/ 
0.01
/ Image::Libpuzzle

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";
    $p1->set_lambdas($i);
    $p1->set_p_ratio($j);
    $sig1 = $p1->fill_cvec_from_file($pic1);
    $p2->set_lambdas($i);
    $p2->set_p_ratio($j);
    $sig2 = $p2->fill_cvec_from_file($pic2);
    my $string1 = $p1->signature_as_string;
    print qq{$string1\n};
    my $string2 = $p2->signature_as_string;
    print qq{$string2\n};
    my $words1_ref = $p1->signature_as_ngrams; # defaults to $ngram size of $Image::Libpuzzle::DEFAULT_NGRAM_SIZE
    print join ' ', @$words1_ref;
    my $words2_ref = $p2->signature_as_ngrams(6); # example overriding $Image::Libpuzzle::DEFAULT_NGRAM_SIZE 
    print join ' ', @$words2_ref;
    # my $d = puzzle_vector_euclidean_distance($cvec1, $cvec2);
    printf("\nEuclidean length: %f",$p1->vector_euclidean_length);
    # my $d = puzzle_vector_normalized_distance($cvec1, $cvec2);
    printf("\nDiff with \$p2: %f", $p1->vector_normalized_distance($p2));
    printf("\nCompare 1: Is %s",($p1->is_most_similar($p2)) ? q{most similar} : q{not most similar});
    print "\n";
    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

...soon

Working With Signatures

...soon

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

...soon

Pure Perl METHODS AND SUBROUTINES

...soon

signature_as_string

Returns a stringified version of the signature. The string is generated by unpack'ing into an array of ASCII characters (C*). Before the array of character codes is joined into a string, they are padded. For example, 1 turns into 001; 25 turns into 025; 211 remains the same.

signature_as_ngrams

Takes the output of signature_as_string and returns an ARRAY ref of words of size $ngram_size. The default, $DEFAULT_NGRAM_SIZE is set to 4. An optional argument may be passed to override this default.

The paragraph of ngrams is constructed in a method consistent with the one described in the following link:

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

ENVIRONMENT

This module assumes that libpuzzle is installed and puzzle.h is able to be found in a default LIBRARY path.

Libpuzzle is available via most Ports/package repos. It also builds easily, though it requires libgd.so.

Also see, http://www.pureftpd.org/project/libpuzzle.

BUGS

Please report them via https://github.com/estrabd/p5-puzzle-xs/issues.

AUTHOR

Brett Estrade <estrabd@gmail.com>

THANKS

My good and ridiculously smart friend, Xantronix, help me patiently while working through n00b XS bits while writing this module.

COPYRIGHT AND LICENSE

Copyright (C) 2015 by Brett Estrade

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.14.4 or, at your option, any later version of Perl 5 you may have available.