The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


Image::SubImageFind - Perl extension for locating a sub-image within an image


  use Image::SubImageFind qw/FindSubImage/;

  #  First parameter is the larger image file (HayStack)
  #  Second parameter is the sub-image file to locate within the larger image (Needle)
  my ($x, $y) = FindSubImage("./haystackfile.png", "./needlefile.jpg");
  if ($x > 0 || $y > 0) {
      print "Found sub-image at: $x X $y\n";
  } else {
      print "Could not find sub-image.\n";

  #  Alternatively, you can use the emerging object oriented syntax.
  my $finder = new Image::SubImageFind("./haystackfile.png", "./needlefile.png");
  my ($x, $y) = $finder->GetCoordinates();
  print "$x X $yn";

  #  Another example; which may allow for more flexibility.
  my $finder = new Image::SubImageFind("./haystackfile.png");
  my ($x, $y) = $finder->GetCoordinates("./needlefile.png");
  print "$x X $yn";

  #  You can also specify an alternate comparison method.  The default is DWVB; which
  #  uses an adaptive filter for the correct localization of subimages.  
  #  Another is called GPC; which is just a generic pixel compare, but also supports a
  #  delta threshold (using GetMaxDelta and SetMaxDelta).
  use Image::SubImageFind qw/:CONST/;

  my $finder = new Image::SubImageFind("./haystackfile.png", "./needlefile.png", CM_DWVB);
  # OR
  my $finder = new Image::SubImageFind("./haystackfile.png", "./needlefile.png", CM_GPC);
  # $finder->GetMaxDelta();
  # $finder->SetMaxDelta([DeltaValue]);   # 0 or greater, where 0 means no pixel difference


Perl module to aide in locating a sub-image within an image.


None by default.


One of the underlying algorithms and originating code by Dr. Werner Van Belle (


Dennis K. Paulsen, <>


Copyright (C) 2010-2011 by Dennis K. Paulsen

Other portions are copyright their respective owners.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 of the License.