.\" $Id: libdmtx.3 528 2008-11-23 21:22:11Z mblaughton $.\".\" Man page for the libdmtx project..\".\" To view: $ groff -man -T ascii libdmtx.3 | less.\" To text: $ groff -man -T ascii libdmtx.3 | col -b | expand.\".TH LIBDMTX 3 "November 23, 2008".SH NAMElibdmtx \- Data Matrix Encoder/Decoder Library 0.6.0.SH SYNOPSIS\fB#include <dmtx.h>\fP\fIENCODING FUNCTIONS\fP\fBDmtxEncode dmtxEncodeStructInit(\fIvoid\fP);\fP\fBint dmtxEncodeDataMatrix(DmtxEncode *\fIenc\fP, int \fIn\fP, unsigned char *\fIs\fP, int \fIsizeIdxRequest\fP);\fP\fBint dmtxEncodeDataMosaic(DmtxEncode *\fIenc\fP, int \fIn\fP, unsigned char *\fIs\fP, int \fIsizeIdxRequest\fP);\fP\fBvoid dmtxEncodeStructDeInit(DmtxEncode *\fIenc\fP);\fP\fIDECODING FUNCTIONS\fP\fBDmtxDecode dmtxDecodeStructInit(DmtxImage *\fIimg\fP);\fP\fBint dmtxDecodeSetProp(DmtxDecode *\fIdec\fP, int \fIprop\fP, int \fIvalue\fP);\fP\fBDmtxRegion dmtxDecodeFindNextRegion(DmtxDecode *\fIdec\fP, DmtxTime *\fItimeout\fP);\fP\fBDmtxMessage *dmtxDecodeMatrixRegion(DmtxImage *\fIimg\fP, DmtxRegion *\fIreg\fP, int \fIfix\fP);\fP\fBDmtxMessage *dmtxDecodeMosaicRegion(DmtxImage *\fIimg\fP, DmtxRegion *\fIreg\fP, int \fIfix\fP);\fP\fBvoid dmtxDecodeStructDeInit(DmtxDecode *\fIdec\fP);\fP\fICOMMON FUNCTIONS\fP\fBDmtxMessage *dmtxMessageMalloc(int \fIsizeIdx\fP);\fP\fBvoid dmtxMessageFree(DmtxMessage **\fImesg\fP);\fP\fBDmtxImage *dmtxImageMalloc(int \fIwidth\fP, int \fIheight\fP);\fP\fBint dmtxImageFree(DmtxImage **\fIimg\fP);\fP\fBint dmtxImageSetProp(DmtxImage *\fIimg\fP, int \fIprop\fP, int \fIvalue\fP);\fP\fBint dmtxImageGetProp(DmtxImage *\fIimg\fP, int \fIprop\fP);\fP\fBDmtxTime dmtxTimeNow(void);\fP\fBDmtxTime dmtxTimeAdd(DmtxTime \fIt\fP, long \fImsec\fP);\fP\fBint dmtxTimeExceeded(DmtxTime \fItimeout\fP);\fP.SH DESCRIPTION\fIlibdmtx\fP is a shared library that enables programs to read and write ECC200 Data Matrix barcodes.  The utility programs \fIdmtxread\fP and \fIdmtxwrite\fP serve as the official interface to libdmtx from the command line, and also provide a good reference for programmers who wish to write their own programs that interact with libdmtx.Data Matrix barcodes are two dimensional patterns that resemble a checkerboard in appearance, and hold a high density of data with built-in error correction.  They can exist in either square or rectangular configurations, and support several different encodation schemes for optimized storage of binary and text data.  The Data Matrix symbology was invented and released into the public domain by RVSI Acuity CiMatrix..SH ENCODING - Generating Data Matrix Barcodeslibdmtx provides a simple set of functions for encoding.  The following steps will produce an image that holds a Data Matrix barcode with the specified message.1. Call \fBdmtxEncodeStructInit()\fPInitializes the internal values of the encoding process.  Must be called before any other encoding functions.2. Call either \fBdmtxEncodeDataMatrix()\fP or \fBdmtxEncodeDataMosaic()\fPDepending on the desired barcode format, the calling program will use one of these functions to generate a barcode image within the \fBDmtxEncode\fP struct.  The calling program is responsible for using this information to create a permanent image file.3. Call \fBdmtxEncodeStructDeInit()\fPResets the internal encoding values and frees memory allocated during the encoding process..SH DECODING - Reading Data Matrix Barcodeslibdmtx provides a number of functions designed to provide maximum control and flexibility in the decoding process.  The following steps first allocate memory for the image data held by the calling application.  After the image data is captured, the remaining steps will find and decode the barcodes present in the image.1. Call \fBdmtxImageMalloc()\fPAllocates memory for received image data.  libdmtx provides its own image structure that the calling program must populate before starting a scan.2. Call \fBdmtxDecodeStructInit()\fPInitializes the \fBDmtxDecode\fP struct, which designates the image to be scanned and resets the grid pattern for a new scan.  This function must be called before any other scanning functions.3. Call \fBdmtxDecodeSetProp()\fPSet internal properties to control decoding behavior. This feature allows applications to tune performance and accuracy for specific image conditions.4. Call \fBdmtxDecodeFindNextRegion()\fPSearches every pixel location in a recursive grid pattern looking for potential barcode edges.  A \fBDmtxRegion\fP is returned whenever A) a potential barcode region is found, or B) the final pixel has been scanned.  Subsequent calls to this function will resume the search where the previous call left off.\fIImportant\fP: This function does not dynamically allocate memory and does not decode the barcode contents.  If the calling program receives a region that it wishes to discard, it can simply continue without freeing or cleaning up the previous \fBDmtxRegion\fP struct.  This can be useful for programs that are selective in choosing which regions should be decoded.5. Call either \fBdmtxDecodeMatrixRegion()\fP or \fBdmtxDecodeMosaicRegion()\fPExtract bit values from the barcode region and decode the underlying message.  \fBDmtxMessage\fP values returned from this function must be freed after use.6. Call \fBdmtxMessageFree()\fPFree the memory held by a \fBDmtxMessage\fP struct.  The complementary function, \fBdmtxMessageMalloc()\fP, is automatically called by \fBdmtxDecodeMatrixRegion()\fP and therefore is not normally used by the calling program.7. Call \fBdmtxDecodeStructDeInit()\fPResets the internal decoding values used during the decoding process.8. Call \fBdmtxImageFree()\fPResets and frees memory held by \fBDmtxImage\fP struct.  This is the complement to \fBdmtxImageMalloc()\fP..SH EXAMPLE PROGRAMThis example program (available as simpletest.c in the source package) demonstrates both directions of \fIlibdmtx\fP functionality, encoding and decoding.  It first creates a Data Matrix barcode and then reads it back and prints the decoded message.  If everything works correctly then the final output message should match the original input string.  #include <stdlib.h>  #include <stdio.h>  #include <string.h>  #include <dmtx.h>  int  main(int argc, char *argv[])  {     unsigned char str[] = "30Q324343430794<OQQ";     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 = dmtxEncodeStructInit();     dmtxEncodeDataMatrix(&enc, strlen(str), str, DMTX_SYMBOL_SQUARE_AUTO);     /* 2) COPY the new image data before freeing encoding memory */     img = dmtxImageMalloc(enc.image->width, enc.image->height);     memcpy(img->pxl, enc.image->pxl, img->width * img->height * sizeof(DmtxRgb));     dmtxEncodeStructDeInit(&enc);     /* 3) DECODE the Data Matrix barcode from the copied image */     dec = dmtxDecodeStructInit(img);     reg = dmtxDecodeFindNextRegion(&dec, NULL);     if(reg.found != DMTX_REGION_FOUND)        exit(0);     msg = dmtxDecodeMatrixRegion(img, &reg, -1);     if(msg != NULL) {        fputs("output: \\"", stdout);        fwrite(msg->output, sizeof(unsigned char), msg->outputIdx, stdout);        fputs("\\"\\n\\n", stdout);        dmtxMessageFree(&msg);     }     dmtxDecodeStructDeInit(&dec);     dmtxImageFree(&img);     exit(0);  }.SH "SEE ALSO"\fIdmtxread\fP(1), \fIdmtxwrite\fP(1).SH STANDARDSISO/IEC 16022:2000.PPANSI/AIM BC11 ISS.SH BUGSEmail bug reports to mike@dragonflylogic.com.SH AUTHORCopyright (c) 2008 Mike Laughton.\" end of man page