NAME

Image::Match - locate 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 regexp! For all practical reasons, images can be easily treated as byte strings, and regexps are not exception. For example, one needs to locate an image 2x2 in larger 7x7 image. The regexp constructed should be the first scanline of smaller image, 2 bytes, verbatim, then 7 - 2 = 5 of any character, and finally the second scanline, 2 bytes again. Of course there are some quirks, but these explained in 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 50x50 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, $MULTIPLE

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

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.

$Y_GROWS_UPWARDS = 0

The module uses Prima for imaging storage and manipulations. Note that Prima's notion of graphic coordinates is such that Y axis grows upwards. This module can use both mathematical (Y grows upwards) and screen-based (Y grows downwards) modes. The latter is default; set Image::Match::Y_GROWS_UPWARDS to 1 to change that.

NOTES

Prima by default will start X11 session on unix. The module changes that behavior. If your code needs X11 connection, change that by explicitly stating

use Prima;

before invoking

use Image::Match.

See "noX11" in Prima for more.

PREREQUISITES

Prima

SEE ALSO

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