view release on metacpan or  search on metacpan

lib/Image/Match.pm  view on Meta::CPAN

  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";

=head1 API

=over

=item match $IMAGE, $SUBIMAGE, %OPTIONS

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

C<$OPTIONS{mode}> overrides global C<mode()>.

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

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

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

=item mode $MODE = 'screen'

The module uses L<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, C<mode('geom')>) and screen-based (Y grows
downwards, C<mode('screen')>) modes. The latter mode is the default.

=back

=head1 NOTES

On unix, C<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 L<Prima::X11> for more information.

If you need to use other image backends than Prima, that can be done too.
There is L<Prima::Image::Magick> that brings together Prima and ImageMagick,
and there is L<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.

=head1 SEE ALSO

L<Prima::Image>, L<OCR::Naive>, L<Win32::GUIRobot>

=head1 LICENSE AND COPYRIGHT

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

=head1 AUTHOR

Dmitry Karasik, E<lt>dmitry@karasik.eu.orgE<gt>.

=cut