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

FreeBSD Manual Pages

  
 
  

home | help
LIBPUZZLE(3)	       FreeBSD Library Functions Manual		  LIBPUZZLE(3)

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 com-
     parable 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
     disabled, 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
     puzzle_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 automati-
     cally 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 experi-
     ment 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
     contain 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_dis-
     tance(&context, &cvec1, &cvec2, 1); if (d < PUZZLE_CVEC_SIMILAR-
     ITY_THRESHOLD) {
       puts("Pictures are similar"); } puzzle_free_cvec(&context, &cvec2);
     puzzle_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 af-
     ter 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

NAME | SYNOPSIS | DESCRIPTION | LIBPUZZLE CONTEXT | DVEC AND CVEC VECTORS | LOADING PICTURES | COMPARING VECTORS | CVEC COMPRESSION | RETURN VALUE | AUTHORS | ACKNOWLEDGMENTS | SEE ALSO

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

home | help