Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
NAME
     puzzle_init_cvec,	     puzzle_init_dvec,	     puzzle_fill_dvec_from_file,
     puzzle_fill_cvec_from_file,  puzzle_fill_cvec_from_dvec,  puzzle_free_cvec,
     puzzle_free_dvec, puzzle_init_compressed_cvec, puzzle_free_compressed_cvec,
     puzzle_compress_cvec,				 puzzle_uncompress_cvec,
     puzzle_vector_normalized_distance	--  compute  comparable  signatures   of
     bitmap images.

SYNOPSIS
     #include <puzzle.h>

     int
     puzzle_init_context(PuzzleContext *context);

     int
     puzzle_free_context(PuzzleContext *context);

     int
     puzzle_init_cvec(PuzzleContext *context, PuzzleCvec *cvec);

     int
     puzzle_init_dvec(PuzzleContext *context, PuzzleDvec *cvec);

     void
     puzzle_fill_dvec_from_file(PuzzleContext *context, PuzzleDvec * dvec,
	 const char *file);

     void
     puzzle_fill_cvec_from_file(PuzzleContext *context, PuzzleCvec * cvec,
	 const char *file);

     void
     puzzle_fill_cvec_from_dvec(PuzzleContext *context, PuzzleCvec * cvec,
	 const PuzzleDvec *dvec);

     void
     puzzle_free_cvec(PuzzleContext *context, PuzzleCvec *cvec);

     void
     puzzle_free_dvec(PuzzleContext *context, PuzzleDvec *cvec);

     void
     puzzle_init_compressed_cvec(PuzzleContext *context,
	 PuzzleCompressedCvec * compressed_cvec);

     void
     puzzle_free_compressed_cvec(PuzzleContext *context,
	 PuzzleCompressedCvec * compressed_cvec);

     int
     puzzle_compress_cvec(PuzzleContext *context,
	 PuzzleCompressedCvec * compressed_cvec, const PuzzleCvec * cvec);

     int
     puzzle_uncompress_cvec(PuzzleContext *context,
	 PuzzleCompressedCvec * compressed_cvec, PuzzleCvec * const cvec);

     double
     puzzle_vector_normalized_distance(PuzzleContext *context,
	 const PuzzleCvec * cvec1, const PuzzleCvec * cvec2);, const int
	 fix_for_texts

DESCRIPTION
     The  Puzzle  library  computes a signature out of a bitmap picture.  Signa-
     tures are comparable and similar pictures have similar signatures.

     After a picture has been loaded and uncompressed, featureless parts of  the
     image  are  skipped  (autocrop), unless that step has been explicitely dis-
     abled, see puzzle_set(3)

LIBPUZZLE CONTEXT
     Every public function requires a PuzzleContext object,  that  stores  every
     required tunables.

     Any  application  using  libpuzzle should initialize a PuzzleContext object
     with puzzle_init_context() and free it after use with puzzle_free_context()

     PuzzleContext context;

     puzzle_init_context(&context);
      ...  puzzle_free_context(&context);

DVEC AND CVEC VECTORS
     The next step is to divide the cropped image into a grid and to compute the
     average intensity of soft-edged pixels in every  block.  The  result  is  a
     PuzzleDvec object.

     PuzzleDvec   objects   should   be   initialized	before	use,  with  puz-
     zle_init_dvec() and freed after use with puzzle_free_dvec()

     The PuzzleDvec structure has two important fields: vec is	the  pointer  to
     the  first  element  of  the  array containing the average intensities, and
     sizeof_compressed_vec is the number of elements.

     PuzzleDvec objects are not comparable, so	what  you  usually  want  is  to
     transform these objects into PuzzleCvec objects.

     A	PuzzleCvec object is a vector with relationships between adjacent blocks
     from a PuzzleDvec object.

     The  puzzle_fill_cvec_from_dvec()	fills  a  PuzzleCvec   object	from   a
     PuzzleDvec object.

     But  just	like the other structure, PuzzleCvec objects must be initialized
     and freed with puzzle_init_cvec() and puzzle_free_cvec()

     PuzzleCvec objects have a vector whoose first element is in the vec  field,
     and the number of elements is in the sizeof_vec field

LOADING PICTURES
     PuzzleDvec  and  PuzzleCvec  objects  can be computed from a bitmap picture
     file, with puzzle_fill_dvec_from_file() and puzzle_fill_cvec_from_file()

     GIF , PNG and JPEG files formats are currently supported and  automatically
     recognized.

     Here's a simple example that creates a PuzzleCvec objects out of a file.

     PuzzleContext context; PuzzleCvec cvec;

     puzzle_init_context(&context);   puzzle_init_cvec(&context,   &cvec);  puz-
     zle_fill_cvec_from_file(&context, &cvec, "test-picture.jpg");
      ...  puzzle_free_cvec(&context, &cvec); puzzle_free_context(&context);

COMPARING VECTORS
     In order to check whether two pictures are similar,  you  need  to  compare
     their PuzzleCvec signatures, using puzzle_vector_normalized_distance()

     That  function  returns  a  distance,  between 0.0 and 1.0. The lesser, the
     nearer.

     Tests on common pictures show that a normalized distance of 0.6  (also  de-
     fined  as	PUZZLE_CVEC_SIMILARITY_THRESHOLD  ) means that both pictures are
     visually similar.

     If that threshold is not right for your set of pictures, you can experiment
     with		 PUZZLE_CVEC_SIMILARITY_HIGH_THRESHOLD		       ,
     PUZZLE_CVEC_SIMILARITY_LOW_THRESHOLD				     and
     PUZZLE_CVEC_SIMILARITY_LOWER_THRESHOLD or with your own value.

     If the fix_for_texts of puzzle_vector_normalized_distance() is 1 , a fix is
     applied to the computation in order to deal with bitmap pictures that  con-
     tain  text.  That fix is recommended, as it allows using the same threshold
     for that kind of picture as for generic pictures.

     If fix_for_texts is 0 , that special way of computing the	normalized  dis-
     tance is disabled.

     PuzzleContext context; PuzzleCvec cvec1, cvec2; double d;

     puzzle_init_context(&context);   puzzle_init_cvec(&context,  &cvec1);  puz-
     zle_init_cvec(&context,	&cvec2);    puzzle_fill_cvec_from_file(&context,
     &cvec1, "test-picture-1.jpg"); puzzle_fill_cvec_from_file(&context, &cvec2,
     "test-picture-2.jpg");   d   =  puzzle_vector_normalized_distance(&context,
     &cvec1, &cvec2, 1); if (d < PUZZLE_CVEC_SIMILARITY_THRESHOLD) {
       puts("Pictures are similar"); } puzzle_free_cvec(&context, &cvec2);  puz-
     zle_free_cvec(&context, &cvec1); puzzle_free_context(&context);

CVEC COMPRESSION
     In  order	to reduce storage needs, PuzzleCvec objects can be compressed to
     1/3 of their original size.

     PuzzleCompressedCvec structures hold the compressed data. Before and  after
     use,  these  structures  have to be passed to puzzle_init_compressed_cvec()
     and puzzle_free_compressed_cvec()

     puzzle_compress_cvec()   compresses   a   PuzzleCvec    object    into    a
     PuzzleCompressedCvec object.

     And  puzzle_uncompress_cvec()  uncompresses  a  PuzzleCompressedCvec object
     into a PuzzleCvec object.

     PuzzleContext context; PuzzleCvec cvec; PuzzleCompressedCvec c_cvec;
      ...     puzzle_init_compressed_cvec(&context,    &c_cvec);     puzzle_com-
     press_cvec(&context, &c_cvec, &cvec);
      ...  puzzle_free_compressed_cvec(&context, &c_cvec);
     The  PuzzleCompressedCvec structure has two important fields: vec that is a
     pointer   to   the   first   element   of	 the   compressed   data,    and
     sizeof_compressed_vec that contains the number of elements.

RETURN VALUE
     Functions return 0 on success, and -1 if something went wrong.

AUTHORS
     Frank DENIS libpuzzle at pureftpd dot org

ACKNOWLEDGMENTS
     Xerox  Research  Center  H.  CHI  WONG  Marschall BERN David GOLDBERG Sameh
     SCHAFIK

SEE ALSO
     puzzle_set(3) puzzle-diff(8)

			       September 24, 2007		    LIBPUZZLE(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=libpuzzle&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help