/ 
Image-Compare-1.03
River stage one • 1 direct dependent • 1 total dependent
/ Image::Compare

NAME

Image::Compare - Compare two images in a variety of ways.

USAGE

use Image::Compare;
use warnings;
use strict;

my($cmp) = Image::Compare->new();
$cmp->set_image1(
    img  => '/path/to/some/file.jpg',
    type => 'jpg',
);
$cmp->set_image2(
    img  => 'http://somesite.com/someimage.gif',
);
$cmp->set_method(
    method => &Image::Compare::THRESHOLD,
    args   => 25,
);
if ($cmp->compare()) {
    # The images are the same, within the threshold
}
else {
    # The images differ beyond the threshold
}

OVERVIEW

This library implements a system by which 2 image files can be compared, using a variety of comparison methods. In general, those methods operate on the images on a pixel-by-pixel basis and reporting statistics or data based on color value comparisons.

Image::Compare makes heavy use of the Imager module, although it's not neccessary to know anything about it in order to make use of the compare functions. However, Imager must be installed in order to use this module, and file import types will be limited to those supported by your installed Imager library.

In general, to do a comparison, you need to provide 3 pieces of information: the first image to compare, the second image to compare, and a comparison method. Some comparison methods also require extra arguments -- in some cases a boolean value, some a number and some require a hash reference with structured data. See the documentation below for information on how to use each comparison method.

Image::Compare provides 3 different ways to invoke its comparison functionality -- you can construct an Image::Compare object and call set_* methods on it to give it the information, then call compare() on that object, or you can construct the Image::Compare with all of the appropriate data right off the bat, or you can simply call compare() with all of the information. In this third case, you can call compare() as a class method, or you can simply invoke the method directly from the Image::Compare namespace. If you'd like, you can also pass the word compare to the module when you use it and the method will be imported to your local namespace.

COMPARISON METHODS

EXACT

The EXACT method simply returns true if every single pixel of one image is exactly the same as every corresponding pixel in the other image, or false otherwise. It takes no arguments.

$cmp->set_method(
    method => &Image::Compare::EXACT,
);
THRESHOLD

The THRESHOLD method returns true if no pixel difference between the two images exceeds a certain threshold, and false if even one does. Note that differences are measured in a sum of squares fashion (vector distance), so the maximum difference is 255 * sqrt(3), or roughly 441.7. Its argument is the difference threshold. (Note: EXACT is the same as THRESHOLD with an argument of 0.)

$cmp->set_method(
    method => &Image::Compare::THRESHOLD,
    args   => 50,
);
THRESHOLD_COUNT

The THRESHOLD_COUNT method works similarly to the THRESHOLD method, but instead of immediately returning a false value as soon as it finds a pixel pair whose difference exceeds the threshold, it simply counts the number of pixels pairs that exceed that threshold in the image pair. It returns that count.

$cmp->set_method(
    method => &Image::Compare::THRESHOLD_COUNT,
    args   => 50,
);
AVG_THRESHOLD

The AVG_THRESHOLD method returns true if the average difference over all pixel pairings between the two images is under a given threshold value. Two different average types are available: MEDIAN and MEAN. Its argument is a hash reference, contains keys "type", indicating the average type, and "value", indicating the threshold value.

$cmp->set_method(
    method => &Image::Compare::AVG_THRESHOLD,
    args   => {
        type  => &Image::Compare::AVG_THRESHOLD::MEAN,
        value => 35,
    },
);
IMAGE

The IMAGE method returns an Imager object of the same dimensions as your input images, with each pixel colored to represent the pixel color difference between the corresponding pixels in the input.

Its only argument accepts 0, 1, or an Imager::Fountain. If the argument is omitted or false, then the output image will be grayscale, with black meaning no change and white meaning maximum change. If the argument is a true value other than an Imager::Fountain, the output will be in color, ramping from pure red at 0 change to pure green at 50% of maximum change, and then to pure blue at maximum change.

$cmp->set_method(
    method => &Image::Compare::IMAGE,
    args   => 1,   # Output in color
);

You may also pass an Imager::Fountain to choose your own color scale.

use Imager qw/:handy/; # for the NC subroutine
use Imager::Fountain;

$cmp->set_method(
    method => &Image::Compare::IMAGE,
    args   => Imager::Fountain->simple(
        positions => [              0.0,            1.0],
        colors    => [NC(255, 255, 255), NC(240,18,190)]
    )     # scale from white (no change) to fuschia (100% change)
);

MATCHMASKS

In addition to providing the two images which are to be compared, you may also provide a "mask" image which will define a subset of those images to compare. A mask must be an Imager object, with one channel and 8 bit color depth per channel. Image processing will not occur for any pixel in the test images which correspond to any pixel in the mask image with a color value of (255, 255, 255), that is, black.

Put another way, the pure black section of the mask image effectively "hide" that section of the test images, and those pixels will be ignored during processing. What that means will differ from comparator to comparator, but should be obviously predictable in nature.

METHODS

new()
new(image1 => { .. }, image2 => { .. }, method => { .. }, ..)

This is the constructor method for the class. You may optionally pass it any of 3 arguments, each of which takes a hash reference as data, which corresponds exactly to the semantics of the set_* methods, as described below. You may optionally pass in a match mask argument using the "mask" argument, which must be an Imager object, as described above.

$cmp->set_image1(img => $data, type => $type) =item $cmp->set_image2(img => $data, type => $type)

Sets the data for the appropriate image based on the input parameters. The img parameter can either be an Imager object, a file path or a URL. If a URL, it must be of a scheme supported by your LWP install. The type argument is optional, and will be used to override the image type deduced from the input. Again, the image type used must be one supported by your Imager install, and its format is determined entirely by Imager. See the documentation on Imager::Files for a list of image types.

Note that providing images as URLs requires that both LWP and Regexp::Common be available in your kit.

$cmp->get_image1() =item $cmp->get_image2()

Returns the underlying Imager object for the appropriate image, as created inside of $cmp by either of the previous two methods.

$cmp->set_method(method => $method, args => $args)

Sets the comparison method for the object. See the section above for details on different comparison methods.

$cmp->get_method()

Returns a hash describing the method as set by the call previous. In this hash, the key "method" will map to the method, and the key "args" will map to the arguments (if any).

$cmp->set_mask(mask => $mask)

Sets the match mask parameter as described above.

$cmp->get_mask()

Returns the match mask (if any) currently set in this object.

$cmp->compare()
compare(image1 => { .. }, image2 => { .. }, method => { .. })

Actually does the comparison. The return value is determined by the comparison method described in the previous section, so look there to see the details. As described above, this can be called as an instance method, in which case the values set at construction time or through the set_* methods will be used, or it can be called as a class method or as a simple subroutine.

In the latter case, all of the information must be provided as arguments to the function call. Those argument have exactly the same semantics as the arguments for new(), so see that section for details.

Future Work

  • I would like to implement more comparison methods. I will have to use the module myself somewhat before I know which ones would be useful to add, so I'm releasing this initial version now with a limited set of comparisons.

    I also more than welcome suggestions from users as to comparison methods they would find useful, so please let me know if there's anything you'd like to see the module be able to do. This module is meant more to be a framework for image comparison and a collection of systems working within that framework, so the process of adding new comparison methods is reasonably simple and painless.

  • I bet the input processing could be more bulletproof. I am pretty certain of it, in fact.

  • Maybe I could be more lenient with the format for masks. I'll leave it up to user request to see how I could extend that interface.

Known Issues

  • None at this time.

AUTHOR

Avi Finkel <avi@finkel.org>

LICENSE AND COPYRIGHT

Copyright 2008 Avi Finkel <avi@finkel.org>

This package is free software and is provided "as is" without express or implied warranty. It may be used, redistributed and/or modified under the terms of the Perl Artistic License (see http://www.perl.com/perl/misc/Artistic.html)