NAME

Image::Compare::Comparator - Base class for comparison methods used by Image::Compare

OVERVIEW

This is essentially an abstract class which defines some basic functionality and outlines some patterns for use of subclasses which will each define a different process for comparing two images. The documentation here is aimed more for those wishing to write their own comparators.

COMPARATORS

See each submodule's documentation for information about how it works.

Image::Compare::AVG_THRESHOLD
Image::Compare::EXACT
Image::Compare::THRESHOLD
Image::Compare::THRESHOLD_COUNT
Image::Compare::IMAGE

CREATING CUSTOM COMPARATORS

OVERVIEW

There are 5 methods that can be overriden by comparator subclasses, and two that must be. Most of the work in creating your owm comparator is in the implementation of your comparison logic, which is out of the purview of this document, so it will be pretty short.

IMPORT

It is optional to override the import() method. If you do, you must call the superclass import(). If your comparator is not in the Image::Compare:: namespace, then you must be sure that the superclass import() is called with an argument called "name", containing a unique name by which the comparator will be referred in the system. If the comparator is in the Image::Compare:: namespace, then the name will be assumed to be the class name, but that can be overriden using the name argument to import(). For example:

 package My::Comparator::FOO

 use base qw/Image::Compare::Comparator/;

 sub import {
         my $class = shift;
         $class->SUPER::import(name => 'FOO');
         # ... Whatever
 }

You should override import if:

You need to do some special logic at class initialization time.
Your class isn't in the Image::Compare:: namespace and you need to provide the comparator name.
You want to provide a different comparator name, even though your comparator is in the Image::Compare:: namespace.

SETUP: It is optional to override the setup() method. If left alone, it will do some very basic input checking. If you have any logic which must run before each comparison run begins, this is where you'd put it. You should put any pre-run sanity checking code here, and die() if there's a problem. You need not call the superclass version of this method if you don't want to, but you may in order to leverage the error checking logic there.
ACCUMULATE: This method must be overriden and it will contain most of your subclass's logic. Its inputs will be:

A reference to an array containing the red, green and blue values of a certain pixel in the first image.
A reference to an array containing the red, green and blue values of a certain pixel in the second image.
The X coordinate whence came the color values from the first image. In most cases, this will be the same as the X coordinate for the second image, but if you've overriden get_second_pixel(), then this may not be true.
The Y coordinate whence came the color values from the first image. The same caveat applies here as for X.
Your logic should do whatever calculations are neccessary with this data and store whatever information must be stored for further processing. If you can determine at any point that further processing is wasteful, you can return any non-undef value from this method and processing will cease. In the usual case, you should simply return undef to allow processing to continue. die() from this method if there's a problem.

GET_RESULT: This method will be called at the end of the comparison run, and must be override by the subclass. This should do any final work that needs to be done for the comparison, and should then return whatever value should be returned to the end user.
GET_SECOND_PIXEL: Overriding this method is optional. By default, if the XxY pixel is read from the first image then the XxY pixel is also read from the second image, and they are then compared. By overriding this method, one can cause the application to compare the XxY pixel from the first image with the X'xY' pixel from the second image.
Note: This functionality is experimental and is subject to change as its use case becomes more clear.

METHODS

new: Constructs a new instance of a comparator. Should not be overridden by subclasses. All this does is the basic perl OO stuff, and copies the second argument for later usage by the subclass.
setup($img1, $img2): Subclasses should override this method to do input checking of their arguments and die if there are any problems. By default, this method only verifies that both images are the same dimensions.
accumulate(\@pixel1, \@pixel2, $x, $y): This method will be called once for each pair of pixels in the two images. The RGB color values for those pixels will be passed in, along with the X and Y coordinates of those pixels. The return value should be undef if processing should continue; this means that the comparator has recorded what it needs to record and sees no reason for things to stop. If, however, the comparator has decided at this point (for whatever reason) that further processing would not change its answer, it can return any non-undef value, and that value will be returned as the result of the comparison. This short-circuiting can be very helpful in speeding up processing for certain types of comparison.
This method must be overridden by subclasses of this class.
color_distance(\@pixel1, \@pixel2): Returns the magnitude of the linear (pythagorean) distance between two pixels in color-space. In the future, this method may be modifiable to use different color distance methodologies, but for now only the simplest is available.
compare_images($img1, $img2): The main entrypoint method for consumers of instances of subclasses of this class. This handles all the "wrapping" for comparing two images. Generally should not be subclassed.
get_args(): Returns the arguments that had been passed to this instance of this comparator at construction. The same as get_representation()->{args}. Included for backwards compatibility.
get_representation(): Returns a hash-representation of the current comparator instance. The hash currently contains two keys: method, which maps to a constant which could be used to construct more instances of this comparator, and args, which maps to the arguments as described in the documentation for get_args().
get_result(): If all of the images' pixels are processed without accumulate() returning a defined value, then this method will be called and its return value will be used as the result of the comparison.
This method must be overridden by subclasses of this class.
get_second_pixel(): Given the second image and the current x, y coordinates on which processing of the first image is currently at, returns the x and y coordinates at which to process the second image. By default, simply returns x and y. Subclasses may override this method in order to change this behavior.

AUTHOR

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)