libpuzzle(3)

1LIBPUZZLE(3)             BSD Library Functions Manual             LIBPUZZLE(3)
2

NAME

4     puzzle_init_cvec, puzzle_init_dvec, puzzle_fill_dvec_from_file,
5     puzzle_fill_cvec_from_file, puzzle_fill_cvec_from_dvec, puzzle_free_cvec,
6     puzzle_free_dvec, puzzle_init_compressed_cvec,
7     puzzle_free_compressed_cvec, puzzle_compress_cvec,
8     puzzle_uncompress_cvec, puzzle_vector_normalized_distance — compute com‐
9     parable signatures of bitmap images.
10

SYNOPSIS

12     #include <puzzle.h>
13
14     int
15     puzzle_init_context(PuzzleContext *context);
16
17     int
18     puzzle_free_context(PuzzleContext *context);
19
20     int
21     puzzle_init_cvec(PuzzleContext *context, PuzzleCvec *cvec);
22
23     int
24     puzzle_init_dvec(PuzzleContext *context, PuzzleDvec *cvec);
25
26     void
27     puzzle_fill_dvec_from_file(PuzzleContext *context, PuzzleDvec * dvec,
28         const char *file);
29
30     void
31     puzzle_fill_cvec_from_file(PuzzleContext *context, PuzzleCvec * cvec,
32         const char *file);
33
34     void
35     puzzle_fill_cvec_from_dvec(PuzzleContext *context, PuzzleCvec * cvec,
36         const PuzzleDvec *dvec);
37
38     void
39     puzzle_free_cvec(PuzzleContext *context, PuzzleCvec *cvec);
40
41     void
42     puzzle_free_dvec(PuzzleContext *context, PuzzleDvec *cvec);
43
44     void
45     puzzle_init_compressed_cvec(PuzzleContext *context,
46         PuzzleCompressedCvec * compressed_cvec);
47
48     void
49     puzzle_free_compressed_cvec(PuzzleContext *context,
50         PuzzleCompressedCvec * compressed_cvec);
51
52     int
53     puzzle_compress_cvec(PuzzleContext *context,
54         PuzzleCompressedCvec * compressed_cvec, const PuzzleCvec * cvec);
55
56     int
57     puzzle_uncompress_cvec(PuzzleContext *context,
58         PuzzleCompressedCvec * compressed_cvec, PuzzleCvec * const cvec);
59
60     double
61     puzzle_vector_normalized_distance(PuzzleContext *context,
62         const PuzzleCvec * cvec1, const PuzzleCvec * cvec2);, const int
63         fix_for_texts
64

DESCRIPTION

66     The Puzzle library computes a signature out of a bitmap picture.  Signa‐
67     tures are comparable and similar pictures have similar signatures.
68
69     After a picture has been loaded and uncompressed, featureless parts of
70     the image are skipped (autocrop), unless that step has been explicitely
71     disabled, see puzzle_set(3)
72

LIBPUZZLE CONTEXT

74     Every public function requires a PuzzleContext object, that stores every
75     required tunables.
76
77     Any application using libpuzzle should initialize a PuzzleContext object
78     with puzzle_init_context() and free it after use with
79     puzzle_free_context()
80
81     PuzzleContext context;
82
83     puzzle_init_context(&context);
84      ...  puzzle_free_context(&context);
85

DVEC AND CVEC VECTORS

87     The next step is to divide the cropped image into a grid and to compute
88     the average intensity of soft‐edged pixels in every block. The result is
89     a PuzzleDvec object.
90
91     PuzzleDvec objects should be initialized before use, with
92     puzzle_init_dvec() and freed after use with puzzle_free_dvec()
93
94     The PuzzleDvec structure has two important fields: vec is the pointer to
95     the first element of the array containing the average intensities, and
96     sizeof_compressed_vec is the number of elements.
97
98     PuzzleDvec objects are not comparable, so what you usually want is to
99     transform these objects into PuzzleCvec objects.
100
101     A PuzzleCvec object is a vector with relationships between adjacent
102     blocks from a PuzzleDvec object.
103
104     The puzzle_fill_cvec_from_dvec() fills a PuzzleCvec object from a
105     PuzzleDvec object.
106
107     But just like the other structure, PuzzleCvec objects must be initialized
108     and freed with puzzle_init_cvec() and puzzle_free_cvec()
109
110     PuzzleCvec objects have a vector whoose first element is in the vec
111     field, and the number of elements is in the sizeof_vec field
112

LOADING PICTURES

114     PuzzleDvec and PuzzleCvec objects can be computed from a bitmap picture
115     file, with puzzle_fill_dvec_from_file() and puzzle_fill_cvec_from_file()
116
117     GIF , PNG and JPEG files formats are currently supported and automati‐
118     cally recognized.
119
120     Here's a simple example that creates a PuzzleCvec objects out of a file.
121
122     PuzzleContext context; PuzzleCvec cvec;
123
124     puzzle_init_context(&context); puzzle_init_cvec(&context, &cvec); puz‐
125     zle_fill_cvec_from_file(&context, &cvec, "test-picture.jpg");
126      ...  puzzle_free_cvec(&context, &cvec); puzzle_free_context(&context);
127

COMPARING VECTORS

129     In order to check whether two pictures are similar, you need to compare
130     their PuzzleCvec signatures, using puzzle_vector_normalized_distance()
131
132     That function returns a distance, between 0.0 and 1.0. The lesser, the
133     nearer.
134
135     Tests on common pictures show that a normalized distance of 0.6 (also
136     defined as PUZZLE_CVEC_SIMILARITY_THRESHOLD ) means that both pictures
137     are visually similar.
138
139     If that threshold is not right for your set of pictures, you can experi‐
140     ment with PUZZLE_CVEC_SIMILARITY_HIGH_THRESHOLD ,
141     PUZZLE_CVEC_SIMILARITY_LOW_THRESHOLD and
142     PUZZLE_CVEC_SIMILARITY_LOWER_THRESHOLD or with your own value.
143
144     If the fix_for_texts of puzzle_vector_normalized_distance() is 1 , a fix
145     is applied to the computation in order to deal with bitmap pictures that
146     contain text. That fix is recommended, as it allows using the same
147     threshold for that kind of picture as for generic pictures.
148
149     If fix_for_texts is 0 , that special way of computing the normalized dis‐
150     tance is disabled.
151
152     PuzzleContext context; PuzzleCvec cvec1, cvec2; double d;
153
154     puzzle_init_context(&context); puzzle_init_cvec(&context, &cvec1); puz‐
155     zle_init_cvec(&context, &cvec2); puzzle_fill_cvec_from_file(&context,
156     &cvec1, "test-picture-1.jpg"); puzzle_fill_cvec_from_file(&context,
157     &cvec2, "test-picture-2.jpg"); d = puzzle_vector_normalized_dis‐
158     tance(&context, &cvec1, &cvec2, 1); if (d < PUZZLE_CVEC_SIMILAR‐
159     ITY_THRESHOLD) {
160       puts("Pictures are similar"); } puzzle_free_cvec(&context, &cvec2);
161     puzzle_free_cvec(&context, &cvec1); puzzle_free_context(&context);
162

CVEC COMPRESSION

164     In order to reduce storage needs, PuzzleCvec objects can be compressed to
165     1/3 of their original size.
166
167     PuzzleCompressedCvec structures hold the compressed data. Before and
168     after use, these structures have to be passed to
169     puzzle_init_compressed_cvec() and puzzle_free_compressed_cvec()
170
171     puzzle_compress_cvec() compresses a PuzzleCvec object into a
172     PuzzleCompressedCvec object.
173
174     And puzzle_uncompress_cvec() uncompresses a PuzzleCompressedCvec object
175     into a PuzzleCvec object.
176
177     PuzzleContext context; PuzzleCvec cvec; PuzzleCompressedCvec c_cvec;
178      ...  puzzle_init_compressed_cvec(&context, &c_cvec); puzzle_com‐
179     press_cvec(&context, &c_cvec, &cvec);
180      ...  puzzle_free_compressed_cvec(&context, &c_cvec);
181     The PuzzleCompressedCvec structure has two important fields: vec that is
182     a pointer to the first element of the compressed data, and
183     sizeof_compressed_vec that contains the number of elements.
184

RETURN VALUE

186     Functions return 0 on success, and -1 if something went wrong.
187

AUTHORS

189     Frank DENIS libpuzzle at pureftpd dot org
190

ACKNOWLEDGMENTS

192     Xerox Research Center H. CHI WONG Marschall BERN David GOLDBERG Sameh
193     SCHAFIK
194