puzzle_set(3)

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

NAME

4     puzzle_set_max_width, puzzle_set_max_height, puzzle_set_lambdas,
5     puzzle_set_p_ratio, puzzle_set_noise_cutoff,
6     puzzle_set_contrast_barrier_for_cropping, puzzle_set_max_cropping_ratio,
7     puzzle_set_autocrop — set tunables for libpuzzle functions.
8

SYNOPSIS

10     #include <puzzle.h>
11
12     int
13     puzzle_set_max_width(PuzzleContext *context, unsigned int width);
14
15     int
16     puzzle_set_max_height(PuzzleContext *context, unsigned int height);
17
18     int
19     puzzle_set_lambdas(PuzzleContext *context, unsigned int lambdas);
20
21     int
22     puzzle_set_p_ratio(PuzzleContext *context, double p_ratio);
23
24     int
25     puzzle_set_noise_cutoff(PuzzleContext *context, double noise_cutoff);
26
27     int
28     puzzle_set_contrast_barrier_for_cropping(PuzzleContext *context,
29         double barrier);
30
31     int
32     puzzle_set_max_cropping_ratio(PuzzleContext *context, double ratio);
33
34     int
35     puzzle_set_autocrop(PuzzleContext *context, int enable);
36

DESCRIPTION

38     While default values have been chosen to be ok for most people, the
39     puzzle_set_*() functions are knobs to fit the algorithm to your set of
40     data and to your applications.
41

LAMBDAS

43     By default, pictures are divided in 9 x 9 blocks.
44
45     9 is the lambdas value, and it can be changed with puzzle_set_lambdas()
46
47     For large databases, for complex images, for images with a lot of text or
48     for sets of near‐similar images, it might be better to raise that value
49     to 11 or even 13
50
51     However, raising that value obviously means that vectors will require
52     more storage space.
53
54     The lambdas value should remain the same in order to get comparable vec‐
55     tors. So if you pick 11 (for instance), you should always use that value
56     for all pictures you will compute a digest for.  puzzle_set_p_ratio()
57
58     The average intensity of each block is based upon a small centered zone.
59
60     The "p ratio" determines the size of that zone. The default is 2.0, and
61     that ratio mimics the behavior that is described in the reference algo‐
62     rithm.
63
64     For very specific cases (complex images) or if you get too many false
65     positives, as an alternative to increasing lambdas, you can try to lower
66     that value, for instance to 1.5.
67
68     The lowest acceptable value is 1.0.
69

MAXIMUM SIZES

71     In order to avoid CPU starvation, pictures won't be processed if their
72     width or height is larger than 3000 pixels.
73
74     These limits are rather large, but if you ever need to change them, the
75     puzzle_set_max_width() and puzzle_set_max_height() are available.
76

NOISE CUTOFF

78     The noise cutoff defaults to 2. If you raise that value, more zones with
79     little difference of intensity will be considered as similar.
80
81     Unless you have very specialized sets of pictures, you probably don't
82     want to change this.
83

AUTOCROP

85     By default, featureless borders of the original image are ignored. The
86     size of each border depends on the sum of absolute values of differences
87     between adjacent pixels, relative to the total sum.
88
89     That feature can be disabled with puzzle_set_autocrop(0) Any other value
90     will enable it.
91
92     puzzle_set_contrast_barrier_for_cropping() changes the tolerance. The
93     default value is 5. Less shaves less, more shaves more.
94
95     puzzle_set_max_cropping_ratio() This is a safe‐guard against unwanted
96     excessive auto‐cropping.
97
98     The default (0.25) means that no more than 25% of the total width (or
99     height) will ever be shaved.
100

RETURN VALUE

102     Functions return 0 on success, and -1 if something went wrong.
103