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

FreeBSD Manual Pages

  
 
  

home | help
LIBDMTX(3)		   Library Functions Manual		    LIBDMTX(3)

NAME
       libdmtx - Data Matrix Encoding &	Decoding Library 0.7.5

SYNOPSIS
       #include	<dmtx.h>

       cc file.c -ldmtx

DESCRIPTION
       libdmtx	is  a software library that enables programs to	read and write
       Data Matrix barcodes of the modern ECC200 variety. The library runs na-
       tively  on several platforms, and can be	accessed by multiple languages
       using the libdmtx language wrappers. The	utility	programs dmtxread  and
       dmtxwrite  provide a command line interface for libdmtx,	and serve as a
       good reference for developers writing their  own	 libdmtx-enabled  pro-
       grams.

       Data Matrix barcodes store data as a pattern of ON and OFF modules (of-
       ten black on white) in a	grid pattern that  resembles  a	 checkerboard.
       Like  other  2D symbologies, Data Matrix	barcodes have a	large data ca-
       pacity compared to their	traditional 1D cousins,	and  employ  sophisti-
       cated  error  correction	techniques. Data Matrix	barcodes can be	square
       or rectangle in shape, and offer	several	encodation schemes  for	 opti-
       mized storage of	text and/or binary data. The Data Matrix symbology was
       invented	and released into the public domain by RVSI Acuity CiMatrix.

ENCODING - Generating Data Matrix Barcodes
       C/C++ programs can generate a barcode with just a few  basic  calls  to
       libdmtx:

       1. Call dmtxEncodeCreate()

       Creates	a  new	DmtxEncode  structure  and  initializes	 the  encoding
       process.	This function must be called before using the  other  encoding
       functions.

       2. Call dmtxEncodeSetProp() [optional]

       Allows  you  to	control	 specific aspects of the encoding behavior. If
       this function is	not called, libdmtx will use the defaults set by dmtx-
       EncodeCreate()  above. The complementary	function, dmtxEncodeGetProp(),
       allows you to detect the	current	settings.

       3. Call either dmtxEncodeDataMatrix() or	dmtxEncodeDataMosaic()

       Call one	of these functions to generate an image	of the desired barcode
       type.  Your program is responsible for dispatching the resulting	output
       to its destination, whether that	means displaying it on a screen, writ-
       ing an image file, copying it elsewhere,	etc...

       4. Call dmtxEncodeDestroy()

       Releases	memory allocated during	the encoding process.

DECODING - Reading Data	Matrix Barcodes
       Barcode	reading	 takes	more steps than	barcode	generation, mainly be-
       cause libdmtx must find a barcode region	before it can decode the  mes-
       sage. However, this too is a relatively simple process that uses	4 main
       structures:

       DmtxImage holds image properties	and a pointer to pixel	data  held  by
       the calling program.

       DmtxDecode  holds  values  for controlling decode behavior and tracking
       scan progress. When scanning a new image, calling programs  should  al-
       ways create a new DmtxDecode structure instead of reusing an old	one.

       DmtxRegion  defines  a 4-sided region in	pixel coordinates. Regions may
       be found	in almost any orientation, and their corners won't necessarily
       form right angles. libdmtx uses this structure to store the location of
       potential barcodes, which are then returned to the calling program one-
       at-a-time.

       DmtxMessage  holds  the	decoded	message	after being extracted from the
       barcode region. A successfully decoded region will produce exactly  one
       message.

       Use the following functions to find and decode Data Matrix barcodes:

       1. Call dmtxImageCreate()

       Creates and initializes a new DmtxImage structure using pixel data pro-
       vided by	the calling application. Parameters include a pointer  to  the
       existing	 pixel	array, image width, height, and	the pixel packing for-
       mat.

       2. Call dmtxImageSetProp() [optional]

       Sets image properties to	control	the pixel mapping  logic.  These  set-
       tings  allow libdmtx to understand many native in-memory	image layouts,
       thus preventing the extra work of transforming and copying  data	 to  a
       one-size-fits-all format. A dmtxDecodeGetProp() function	is also	avail-
       able for	detecting the current image properties.

       3. Call dmtxDecodeCreate()

       Creates and initializes a new DmtxDecode	struct,	which  designates  the
       image  to  be scanned and initializes the scan grid pattern. This func-
       tion must be called before any other scanning functions.

       4. Call dmtxDecodeSetProp() [optional]

       Sets internal properties	to control decoding behavior. This feature al-
       lows you	to optimize performance	and accuracy for specific image	condi-
       tions. A	dmtxDecodeGetProp() function is	also available.

       5. Call dmtxRegionFindNext()

       Searches	every pixel location in	a grid pattern looking	for  potential
       barcode	regions. A DmtxRegion is returned whenever a potential barcode
       region is found,	or if the final	pixel location has been	scanned.  Sub-
       sequent	calls to this function will resume the search where the	previ-
       ous call	left off.

       6. Call either dmtxDecodeMatrixRegion() or dmtxDecodeMosaicRegion()

       Extracts	raw data from the barcode region and  decodes  the  underlying
       message.

       7. Call dmtxMessageDestroy()

       Releases	 memory	 held by a DmtxMessage struct. The complementary func-
       tion, dmtxMessageCreate(), is  automatically  called  by	 dmtxDecodeMa-
       trixRegion() and	therefore is not normally used by the calling program.

       8. Call dmtxRegionDestroy()

       Releases	 memory	 held  by a DmtxRegion struct. The complementary func-
       tion, dmtxRegionCreate(), is automatically  called  by  dmtxRegionFind-
       Next()  (actually  dmtxRegionScanPixel()) and therefore is not normally
       used by the calling program.

       9. Call dmtxDecodeDestroy()

       Releases	memory held by a DmtxDecode struct. This is the	 complementary
       function	to dmtxDecodeCreate().

       10. Call	dmtxImageDestroy()

       Releases	 memory	 held by a DmtxImage struct, excluding the pixel array
       passed to dmtxImageCreate(). The	calling	program	is responsible for re-
       leasing the pixel array memory, if required.

EXAMPLE	PROGRAM
       This example program (available as simple_test.c	in the source package)
       demonstrates libdmtx functionality in both directions: encoding and de-
       coding.	It creates a Data Matrix barcode in memory, reads it back, and
       prints the decoded message. The final output message should  match  the
       original	input string.

	 #include <stdlib.h>
	 #include <stdio.h>
	 #include <string.h>
	 #include <assert.h>
	 #include <dmtx.h>

	 int
	 main(int argc,	char *argv[])
	 {
	    size_t	    width, height, bytesPerPixel;
	    unsigned char   str[] = "30Q324343430794<OQQ";
	    unsigned char  *pxl;
	    DmtxEncode	   *enc;
	    DmtxImage	   *img;
	    DmtxDecode	   *dec;
	    DmtxRegion	   *reg;
	    DmtxMessage	   *msg;

	    fprintf(stdout, "input:  \"%s\"\n",	str);

	    /* 1) ENCODE a new Data Matrix barcode image (in memory only) */

	    enc	= dmtxEncodeCreate();
	    assert(enc != NULL);
	    dmtxEncodeDataMatrix(enc, strlen(str), str);

	    /* 2) COPY the new image data before releasing encoding memory */

	    width = dmtxImageGetProp(enc->image, DmtxPropWidth);
	    height = dmtxImageGetProp(enc->image, DmtxPropHeight);
	    bytesPerPixel   =  dmtxImageGetProp(enc->image,  DmtxPropBytesPer-
       Pixel);

	    pxl	= (unsigned char *)malloc(width	* height * bytesPerPixel);
	    assert(pxl != NULL);
	    memcpy(pxl,	enc->image->pxl, width * height	* bytesPerPixel);

	    dmtxEncodeDestroy(&enc);

	    /* 3) DECODE the Data Matrix barcode from the copied image */

	    img	= dmtxImageCreate(pxl, width, height, DmtxPack24bppRGB);
	    assert(img != NULL);

	    dec	= dmtxDecodeCreate(img,	1);
	    assert(dec != NULL);

	    reg	= dmtxRegionFindNext(dec, NULL);
	    if(reg != NULL) {
	       msg = dmtxDecodeMatrixRegion(dec, reg, DmtxUndefined);
	       if(msg != NULL) {
		  fputs("output: \"", stdout);
		  fwrite(msg->output, sizeof(unsigned  char),  msg->outputIdx,
       stdout);
		  fputs("\"\n",	stdout);
		  dmtxMessageDestroy(&msg);
	       }
	       dmtxRegionDestroy(&reg);
	    }

	    dmtxDecodeDestroy(&dec);
	    dmtxImageDestroy(&img);
	    free(pxl);

	    exit(0);
	 }

SEE ALSO
       dmtxread(1), dmtxwrite(1), dmtxquery(1)

STANDARDS
       ISO/IEC 16022:2000

       ANSI/AIM	BC11 ISS

BUGS
       Post  bug  reports  on  GitHub  issue  tracker  or  email them to dmtx-
       bug@mva.name

AUTHOR
       Copyright (C) 2008, 2009	Mike Laughton Copyright	(C) 2012-2016 Vadim A.
       Misbakh-Soloviov

				 June 2, 2011			    LIBDMTX(3)

NAME | SYNOPSIS | DESCRIPTION | ENCODING - Generating Data Matrix Barcodes | DECODING - Reading Data Matrix Barcodes | EXAMPLE PROGRAM | SEE ALSO | STANDARDS | BUGS | AUTHOR

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

home | help