Imager::Search::Driver - Abstract imlementation of a Imager::Search driver


  # Create the search
  my $search = Imager::Search::Driver->new(
      driver => 'HTML24',
      big    => $large_imager_object,
      small  => $small_imager_object,
  # Run the search
  my $found = $search->find_first;
  # Handle the result
  print "Found at row " . $found->top . " and column " . $found->left;


Given two images (we'll call them Big and Small), where Small is contained within Big zero or more times, determine the pixel locations of Small within Big.

For example, given a screen shot or a rendered webpage, locate the position of a known icon or picture within the larger image.

The intent is to provide functionality for use in various testing scenarios, or desktop gui automation, and so on.



  my $driver = Imager::Search::Driver->new;

The new constructor takes a new search driver object.

Returns a new Imager::Search::Driver object, or croaks on error.


The image_string method takes a Imager::Search::Image object, and generates the search string for the image.

Returns a reference to a scalar, or dies on error.


Because of the way the regular expression spans scanlines, it requires the width of the target image in order to be fully generated. However, the sub-regexp for each scanline can be (and are) generated in advance.

When a Imager::Search::Pattern object is created, the driver method pattern_lines is called to generate the scanline regexp for the search pattern.

Returns a reference to an ARRAY containing the regexp in string form, or dies on error.


The pattern_regexp method takes a pattern and an image is retruns a fully-generated search regexp for the pattern, when used on that image.

Returns a Regexp object, or dies on error.


Once the regexp engine has located a potential match, the pattern, image and character position are provided to the match_object method.

The match_object will take the raw character position, validate that the character position is at a legimate pixel position, and then return the fully-described match.

Returns a Imager::Search::Match object if the position is valid, or false (undef in scalar context or a null string in list context) if the position is not valid.


See the SUPPORT section of the main Imager::Search module.


Adam Kennedy <>


Copyright 2007 - 2011 Adam Kennedy.

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

The full text of the license can be found in the LICENSE file included with this module.