view release on metacpan or  search on metacpan

lib/Image/Similar.pod  view on Meta::CPAN

All image types are supported. RGB images are combined to greyscale
using constants taken from the source code of L<Imager>.

=item L<Image::Imlib2>

All image types are supported. RGB images are combined to greyscale
using constants taken from the source code of L<Imager>.

=item L<Image::PNG::Libpng>

This module 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 supports all PNG image types. It currently only
supports bit depths of eight.

RGB images are combined to greyscale using constants taken from the
source code of L<Imager>. As of this version, there is no handling of
the alpha channel (transparent pixels) and the background value is
ignored.

=back

Use L</load_image> to load the image.

=head1 FUNCTIONS

=head2 load_image

This loads image data from various modules into an Image::Similar
object. The return value is the Image::Similar object.

Using L<Imager>:

    
    use Imager;
    my $img = Imager->new ();
    $img->read (file => 'my.jpg');
    my $is = load_image ($img);
    


Using L<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.

Using L<GD>:

    
    use Image::Similar 'load_image';
    use GD;
    my $gd = GD::Image->newFromPng ("t/images/chess/chess-100.png");
    my $is = load_image ($gd);


Using L<Image::Imlib2>:

    
    use Image::Similar 'load_image';
    use Image::Imlib2;
    my $imlib2 = Image::Imlib2->load ("t/images/chess/chess-100.png");
    my $is = load_image ($imlib2);


=head1 METHODS

=head2 new

    my $is = Image::Similar->new (height => 10, width => 10);

Unless you want to change internals, use L</load_image> instead of
this.

The returned image currently contains a field C<< $is->{image} >>
which you need to use the L</set_pixel> method on to set the pixels.

=head2 diff

    my $diff = $is1->diff ($is2);

This returns a floating-point number which is the difference between
images C<$is1> and C<$is2>. This is meant to be approximately the same
value as given by L<Image::Libpuzzle/vector_euclidean_length()>, but
no validation has been carried out. Both C<$is1> and C<$is2> are
Image::Similar objects created using L</load_image>.

=head2 signature

    my $sig = $is->signature ();

Get the signature of the image. This is a text string
consisting of digits 0-4 which identifies the image. The following example demonstrates getting the signature of two similar images.

    
    use FindBin '$Bin';
    use Image::Similar 'load_image';
    use Imager;
    for my $n (100, 1000) {
        my $image = "$Bin/../t/images/lenagercke/lena-$n.png";
        my $imager = Imager->new ();
        $imager->read (file => $image);
        my $is = load_image ($imager);
        print $is->signature (), "\n";
    }
    


(This example is included as L<F<show-hash.pl>|https://fastapi.metacpan.org/source/BKB/Image-Similar-0.07/examples/show-hash.pl> in the distribution.)


Its output looks like this:

    133333331133333333133331231123111131131131223311221331112333131121311111211111132311113323321333213113111121222311221331332333331321113333232333322223313322331313213133121131222311221231332333131121313111211111112311113323333313213133111122232311...
    133333331133333333133321131133111131131131223311222332112233231121312111211111232311113323332333213113111121222211221231232333331321122333233333312113313323231313223123121132222321221231322323131122313111211211112311113323333313213133111122232311...


=head2 sig_diff

    my $diff = $is->sig_diff ($sig);

Get the difference between C<$sig> and the image represented by
C<$is>.

=head2 load_signature

    my $is = load_signature ($sig);

Load C<$is>, an Image::Similar object, from C<$sig>.

=head1 TESTING AND INTERNAL METHODS

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.

=head2 write_png

    $is->write_png ('test.png');

This is used in conjunction with L<Image::PNG::Libpng/png_compare>
(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.

=head2 load_image_gd

    
    use Image::Similar 'load_image';
    use GD;
    my $gd = GD::Image->newFromPng ("t/images/chess/chess-100.png");
    my $is = load_image ($gd);


This is the internal routine used by L</load_image> to load L<GD>
images.

=head2 load_image_imlib2

This is the internal routine used by L</load_image> to load
L<Image::Imlib2> images.

=head2 load_image_imager

    my $is = load_image_imager ($imager, %options);

This is the internal routine used by L</load_image> to load L<Imager>
images.  It is not exported. The options are

=over

=item make_grey_png

    my $is = load_image_imager ($imager, make_grey_png => 'imager.png');

Make the greyscale PNG for comparing to Image::Similar's internal
version. See L</write_png> for how to extract Image::Similar's
internal version.

=back

=head2 load_image_libpng

    my $is = load_image_libpng ($libpng);

This loads an image from the return value of
L<Image::PNG::Libpng/read_png_file>.

=head2 Image::Similar::Image methods

These methods work on the XS object within an Image::Similar, which is
called Image::Similar::Image.

=head3 fill_grid

    fill_grid ($img);

Calculate the image's signature and store it within C<$img>. All the
pixel values should have been set with L</set_pixel> before calling
this. This method is called automatically by
L</load_image>. L</load_signature> overrides it with values from the
signature, so this method should only be used when calling L</new>,
filling the pixels by the user, and then making the signature "by
hand" rather than via L</load_image>.

=head3 image_diff

    my $diff = image_diff ($img1, $img2);

This computes the value of L</diff> from the signatures within
C<$img1> and C<$img2>.