CPAN RT

The module searches for occurencies of an image inside of a larger image.

The interesting stuff here is the image finding itself - it is done by a regex!
For all practical reasons,
regexes operate on strings of bytes,
and images can be easily treated as such.
For example,
one needs to locate an image 2x2 in a larger 7x7 image.
The constructed regex should contain the first scanline of the smaller image,
2 bytes,
verbatim,
then match 7 - 2 = 5 of any byte found,
and finally the second scanline,
2 bytes again.
Of course there are some quirks,
but these explained in the API section.

The original idea was implemented in OCR::Naive and Win32::GUIRobot,
but this module extracts the pure matching logic,
unburdened from wrappers that were needed back then for matters at hand.

Locates a $SUBIMAGE in $IMAGE, returns one or many matches, depending on $OPTIONS{multiple}. If single match is requested, stops on the first match, and returns a single pair of (X,Y) coordinates. If $OPTIONS{multiple} is 1, returns array of (X,Y) pairs. In both modes, returns empty list if nothing was found.

$OPTIONS{mode} overrides global mode().

$OPTIONS{overlap} can be set to one of three values: none, some, all, to determine how the overlapping matches are reported when $OPTIONS{multiple} is set. None will never report overlapping rectanges, and all report all possible occurencies of $SUBIMAGE in $IMAGE. some is similar to all, but is a bit faster, and will not report overlapping rectangles that begin on the same scanline. some is also the default overlapping mode.

If you need to use other image backends than Prima, that can be done too. There is Prima::Image::Magick that brings together Prima and ImageMagick, and there is Prima::Image::PDL, that does the same for PDL. GD, Imglib2, and Imager, those we can't deal much with, except for saving to and loading from png files.