NAME

Image::Match - locate an image inside another

DESCRIPTION

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.

SYNOPSIS

  use strict;
  use Image::Match;

  # make screenshot
  my $big = Image::Match-> screenshot;
  # extract 70x70 image
  my $small = $big-> extract( 230, $big-> height - 70 - 230, 70, 70);
  # save
  $small-> save('1.png');
  # load
  $small = Prima::Image-> load('1.png') or die "Can't load: $@";
  # find again
  my ( $x, $y) = $big-> match( $small);
  print defined($x) ? "found at $x:$y\n" : "not found\n";

API

match $IMAGE, $SUBIMAGE, %OPTIONS

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.

screenshot [ $X = 0, $Y = 0, $W = screen width, $H = screen height ]

Returns a new Prima::Image object with a screen shot, taken at given coordinates.

mode $MODE = 'screen'

The module uses Prima for imaging storage and manipulations. Note that Prima uses coordinate system where Y axis grows upwards. This module however can use both geometrical (Y grows upwards, mode('geom')) and screen-based (Y grows downwards, mode('screen')) modes. The latter mode is the default.

NOTES

On unix, Prima by default will start X11. The module changes that behavior, so X11 connection is not needed. If your code though needs X11 connection, change that by adding

   use Prima;

before invoking

   use Image::Match

See Prima::X11 for more information.

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.

SEE ALSO

Prima::Image, OCR::Naive, Win32::GUIRobot

LICENSE AND COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Dmitry Karasik, <dmitry@karasik.eu.org>.