Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Image::Compare::ComparUser(Contributed Perl DocumImage::Compare::Comparator(3)

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

       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

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

       o   Image::Compare::AVG_THRESHOLD

       o   Image::Compare::EXACT

       o   Image::Compare::THRESHOLD

       o   Image::Compare::THRESHOLD_COUNT

       o   Image::Compare::IMAGE

	   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.

	   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

	    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:

	   o   You need	to do some special logic at class initialization time.

	   o   Your class isn't	in the Image::Compare::	namespace and you need
	       to provide the comparator name.

	   o   You want	to provide a different comparator name,	even though
	       your comparator is in the Image::Compare:: namespace.

	   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.

	   This	method must be overriden and it	will contain most of your
	   subclass's logic.  Its inputs will be:

	   o   A reference to an array containing the red, green and blue
	       values of a certain pixel in the	first image.

	   o   A reference to an array containing the red, green and blue
	       values of a certain pixel in the	second image.

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

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

	   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.

	   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.

       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

       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.

	   Returns the arguments that had been passed to this instance of this
	   comparator at construction.	The same as
	   get_representation()->{args}.  Included for backwards

	   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().

	   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.

	   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.

       Copyright 2008 Avi Finkel <>

       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

perl v5.24.1			  2017-02-10	 Image::Compare::Comparator(3)


Want to link to this manual page? Use this URL:

home | help