NAME

Image::Libpuzzle - Perl interface to libpuzzle.

SYNOPSIS

use Image::Libpuzzle; 

my $pic1 = q{pics/luxmarket_tshirt01.jpg};
my $pic2 = q{pics/luxmarket_tshirt01_sal.jpg};

my $p1 = Image::Libpuzzle->new;
my $p2 = Image::Libpuzzle->new;

my $sig1 = $p1->fill_cvec_from_file($pic1);
my $sig2 = $p2->fill_cvec_from_file($pic2);

# contrived example to show the setting of some parameters that affect the signature

foreach my $i ( 11, 9, 7, 5 ) {
  foreach my $j ( 2.0, 1.0, 0.5 ) {
    print "Lambda: $i, p ratio: $j\n";

    # set some params for sig1
    $p1->set_lambdas($i);
    $p1->set_p_ratio($j);

    # get signature for pic1
    $sig1 = $p1->fill_cvec_from_file($pic1);

    # set same params for sig2
    $p2->set_lambdas($i);
    $p2->set_p_ratio($j);

    # get signature for pic2
    $sig2 = $p2->fill_cvec_from_file($pic2);

    # stringify sig1
    my $string1 = $p1->signature_as_string;
    print qq{$string1\n};

    # stringify sig2
    my $string2 = $p2->signature_as_string;
    print qq{$string2\n};

    # generate a "document" of ngrams from sig1
    my $words1_ref = $p1->signature_as_ngrams; # defaults to $ngram size of $Image::Libpuzzle::DEFAULT_NGRAM_SIZE
    print join ' ', @$words1_ref;

    # generate a "document" of ngrams from sig2
    my $words2_ref = $p2->signature_as_ngrams(6); # example overriding $Image::Libpuzzle::DEFAULT_NGRAM_SIZE 
    print join ' ', @$words2_ref;

    # print Euclidean length of sig1
    printf("\nEuclidean length: %f",$p1->vector_euclidean_length);

    # print Euclidean length of sig2
    printf("\nDiff with \$p2: %f", $p1->vector_normalized_distance($p2));

    # compare images with a helper method
    printf("\nCompare 1: Is %s",($p1->is_most_similar($p2)) ? q{most similar} : q{not most similar});
    print "\n";

    # compare images directly
    printf("\nCompare 2: Is %s",( $p1->vector_normalized_distance($p2) < $Image::Libpuzzle::PUZZLE_CVEC_SIMILARITY_LOWER_THRESHOLD ) ? q{most similar} : q{not most similar});
    print "\n";
    print "\n\n";
  }
}

DESCRIPTION

This XS module provdes access to the most common functionality provided by Libpuzzle, http://www.pureftpd.org/project/libpuzzle.

It also includes some pure Perl helper methods users of Libpuzzle might find helpful when creating applications based on it.

This module is in its very early form. It may change without notice. If a feature is missing, please request it at https://github.com/estrabd/p5-puzzle-xs/issues.

NOTES ON USING LIBPUZZLE

Below are some brief notes on how to use this module in order to get the most out of the underlying Libpuzzle library.

Comparing Images

Libpuzzle presents a robust, fuzzy way to compare the similarity of images. Read more about the technique in the paper that describes it,

http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.104.2585&rep=rep1&type=pdf

Working With Signatures

Signatures are typically not printable date, so one may either use the native Libpuzzle methods to work with them, such as vector_euclidean_length and vector_normalized_distance.

Image::Libpuzzle provides two methods for generating signatures in a printable form that may be used to deal with signatures in a more printable way, signature_as_string and signature_as_ngrans. See below for more details.

Comparing Millions of Images

This Stack Overflow URL seems to be the best resources for addressing this question:

http://stackoverflow.com/questions/9703762/libpuzzle-indexing-millions-of-pictures

The Image::Libpuzzle::signature_as_ngrams methods may be used to generate ngrams (words of size N) for use with the oft suggested approach to searching for similar images in a database of signatures.

Working With Compressed Signatures

Working with compressed signatures is not currently supported in this module, but may be added in the future if there is demand.

XS METHODS AND SUBROUTINES

new

Constructor, returns a Image::Libpuzzle reference.

get_cvec

Returns a Image::Libpuzzle::Cvec reference, currently one can't do much with this.

fill_cvec_from_file(q{./path/to/image})

Generates the signature for the given file.

get_signature

Returns the signature in an unprintable form.

set_lambdas

Wrapper around Libpuzzle's function. Sets the number of samples taken for each image.

set_p_ratio

Wrapper around Libpuzzle's function. Sets the size of the samples. Used in conjunction with set_lambdas to get more or less precise signatures.