Dmitry Karasik > Image-Match-1.02 > Image::Match

Download:
Image-Match-1.02.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 1.02   Source  

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

syntax highlighting: