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,
 );

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::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 is a boolean. 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, then 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::IMG,
     args   => 1,   # Output in color
 );

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.

$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.

$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->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.

• I'd like to make it so users can define their own color functions to be used in creating the output for the IMAGE comparison method. I will probably do this using Imager::Color::Fountain objects, but that is kind of tricky, so I'm leaving it out for now.

• I don't think I'm doing the whole required modules thing correctly, and I should probably make it so that it can operate without LWP or Regexp::Common.

Known Issues

• None at this time.

AUTHOR

Copyright 2006 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)