libdmtx man page on Mageia

Man page or keyword search:  
man Server   17783 pages
apropos Keyword Search (all sections)
Output format
Mageia logo
[printable version]

LIBDMTX(3)							    LIBDMTX(3)

NAME
       libdmtx - Data Matrix Encoding & Decoding Library 0.7.4

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
       natively	 on  several  platforms,  and can be accessed by multiple lan‐
       guages 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 programs.

       Data  Matrix  barcodes  store  data  as a pattern of ON and OFF modules
       (often black on white) in a grid pattern that resembles a checkerboard.
       Like  other  2D	symbologies,  Data  Matrix  barcodes have a large data
       capacity 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
       because libdmtx must find a barcode region before  it  can  decode  the
       message.	 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
       always 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
       allows you to optimize performance and accuracy for specific image con‐
       ditions. 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
       releasing 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
       decoding.  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(®);
	    }

	    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
       Email bug reports to mike@dragonflylogic.com

AUTHOR
       Copyright (C) 2008, 2009 Mike Laughton

				 June 2, 2011			    LIBDMTX(3)
[top]

List of man pages available for Mageia

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net