Image::Similar - find out how similar two images are
use Image::Similar;
This documents version 0.03 of Image::Similar corresponding to git commit 66477f31b284d1f5ab98f1e63cc0342634ab6ff9 released on Tue Feb 23 19:49:50 2016 +0900.
This is an experimental module for comparing images. It uses a simplified form of the algorithm described in "An image signature for any kind of image" to calculate image signatures and distances between images.
The module does not contain its own image-reading facility, so images must be loaded to the module via one of the following supported Perl modules:
All image types are supported. RGB images are combined to greyscale using constants taken from the source code of Imager.
All image types are supported. Unless you only need to compare PNG images, and if you have no prior preference, we suggest using Imager since it is a very well-behaved module. The conversion to greyscale is done using Imager's own routines.
This is used for some internals of Image::Similar related to testing thus it was installed when you installed Image::Similar. However, Image::PNG::Libpng is only for PNG images.
Image::Similar currently supports GRAY, GRAY_ALPHA, RGB, and RGBA Image::PNG::Libpng image types, but not paletted image types. It only supports bit depths of eight.
Image::PNG::Libpng
RGB images are combined to greyscale using constants taken from the source code of Imager. As of this version, there is no handling of the alpha channel (transparent pixels) and the background value is ignored.
Use "load_image" to load the image.
Using Imager:
use Imager; my $img = Imager->new (); $img->read (file => 'my.jpg'); my $is = load_image ($img);
Using Image::PNG::Libpng:
use Image::PNG::Libpng ':all'; my $img = read_png_file ('my.png'); my $is = load_image ($img);
The return value is an Image::Similar object.
my $is = Image::Similar->new (height => 10, width => 10);
Unless you want to change internals, use "load_image" instead of this.
The returned image currently contains a field $is->{image} which you need to use the "set_pixel" method on to set the pixels.
$is->{image}
my $diff = $is1->diff ($is2);
This returns a floating-point number which is the difference between images $is1 and $is2. This is meant to be approximately the same value as given by "vector_euclidean_length()" in Image::Libpuzzle, but no validation has been carried out yet.
$is1
$is2
my $sig = $is->signature ();
Get the signature of the image. This is currently a text string consisting of digits 0-4 which identifies the image. This is liable to change with future versions of the module.
my $diff = $is->sig_diff ($sig);
Get the difference between $sig and the image represented by $is.
$sig
$is
my $is = load_signature ($sig);
Load $is, an Image::Similar object, from $sig.
This section lists the testing and internal methods of the module, for people interested in extending or otherwise improving it. Since these are internal private methods, these are subject to change without notice.
$is->write_png ('test.png');
This is used in conjunction with "png_compare" in Image::PNG::Libpng (version 0.42 or later) to check that Image::Similar has correctly read in the image, by writing out Image::Similar's internal data as a PNG file.
my $is = load_image_gd ($imager, %options);
my $is = load_image_imager ($imager, %options);
This is the internal routine used by "load_image" to load Imager images. The options are
my $is = load_image_imager ($imager, make_grey_png => 'imager.png');
Make the greyscale PNG for comparing to Image::Similar's internal version. See "write_png" for details.
my $is = load_image_libpng ($libpng);
This loads an image from the return value of "read_png_file" in Image::PNG::Libpng.
These methods work on the XS object within an Image::Similar, which is called Image::Similar::Image.
fill_grid ($img);
Calculate the image's signature and store it within $img. This method is called automatically by "load_image", and it does not need to be called by "load_signature", which overrides it with values from the signature, so it should only be used when calling "new", filling the pixels by the user, and then making the signature "by hand" rather than via "load_image".
$img
my $diff = image_diff ($img1, $img2);
Compute the value for "diff".
$img->set_pixel ($x, $y, $grey);
$x and $y need to be integers, and $grey needs to be an integer within 0-255.
$x
$y
$grey
my $rows = $img->get_rows ();
Get the greyscale pixels from $img as an array reference $rows containing strings of bytes, one byte per pixel.
$rows
my $sig = $image->signature ();
if ($image->valid_image ()) { # do something with image data }
This returns a true value only if $image contains valid image data.
$image
The following parts of the original algorithm are unimplemented as of this version:
The 5% and 95% image cropping methods described in the paper are not used.
The soft pixel method is not used.
There is no balancing of the greyscale of the image using a histogram, it only uses the raw pixel values.
This uses a similar algorithm to Image::Similar, but it requires installing a third-party library called libpuzzle, as well as the gd library.
An image signature for any kind of image by H. Chi Wong, Marshall Bern, and David Goldberg, published in Proceedings: 2002 International Conference on Image Processing, Volume 1, date 22-25 September 2002.
Ben Bullock, <bkb@cpan.org>
If you'd like to see this module continued, let me know that you're using it. For example, send an email, write a bug report, star the project's github repository, add a patch, add a ++ on Metacpan.org, or write a rating at CPAN ratings. It really does make a difference. Thanks.
++
This package and associated files are copyright (C) 2016 Ben Bullock.
You can use, copy, modify and redistribute this package and associated files under the Perl Artistic Licence or the GNU General Public Licence.
To install Image::Similar, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Image::Similar
CPAN shell
perl -MCPAN -e shell install Image::Similar
For more information on module installation, please visit the detailed CPAN module installation guide.