.\" $Id: libdmtx.3,v 1.4 2006/10/15 22:08:14 mblaughton Exp $.\".\" Man page for the libdmtx project..\".\" $ groff -man -T ascii libdmtx.3.\".TH LIBDMTX 3 "October 15, 2006".SH NAMElibdmtx \- Data Matrix Encoder/Decoder Library 0.3.0.SH SYNOPSIS\fB#include <dmtx.h>\fP\fBDmtxEncode *dmtxEncodeCreate(\fIvoid\fP);\fP\fBvoid dmtxEncodeDestroy(DmtxEncode **\fIencode\fP);\fP\fBint dmtxEncodeData(DmtxEncode *\fIencode\fP, unsigned char *\fIinputString\fP);\fP\fBDmtxDecode *dmtxDecodeStructCreate(\fIvoid\fP);\fP\fBvoid dmtxDecodeStructDestroy(DmtxDecode **\fIdecode\fP);\fP\fBint dmtxImageInit(DmtxImage *\fIimage\fP);\fP\fBint dmtxImageDeInit(DmtxImage *\fIimage\fP);\fP\fBvoid dmtxScanStartNew(DmtxDecode *\fIdecode\fP);\fP\fBvoid dmtxScanLine(DmtxDecode *\fIdecode\fP, int \fIline\fP, DmtxDirection \fIdirection\fP);\fP\fBint dmtxDecodeGetMatrixCount(DmtxDecode *\fIdecode\fP);\fP\fBDmtxMatrixRegion *dmtxDecodeGetMatrix(DmtxDecode *\fIdecode\fP, int \fIindex\fP);\fP.SH DESCRIPTION\fIlibdmtx\fP is a shared library for Linux that encodes and decodes ECC200 Data Matrix barcodes.  Data Matrix barcodes are two-dimensional patterns that hold a high density of data with built-in error correction.  The Data Matrix symbology was invented and released into the public domain by RVSI Acuity CiMatrix..SH ENCODING - Generating Data Matrix Barcodes\fIlibdmtx\fP provides a simple set of functions for the encoding process.  More functions will be added later to support other options, such as output format (ASCII, PNG, PNM, etc...) and others.Currently, the following steps are required to create a Data Matrix barcode using \fIlibdmtx\fP:1. Call \fBdmtxEncodeCreate()\fPThis function allocates memory for the encoding process and initializes its internal values.  This function must be called before any other encoding functions.2. Call \fBdmtxEncodeData()\fP\fBdmtxEncodeData()\fP creates one barcode for each call, and currently writes a PNM image file of the barcode to the current directory.  This is an ugly temporary hack.  Later there will probably be another function after this where you specify what you want done with the barcode image (e.g. Write to STDOUT?  Write to a PNG file?  Keep it in memory? etc...)3. Call \fBdmtxEncodeDestroy()\fPThis function frees the memory allocated in the \fBdmtxEncodeCreate()\fP and \fBdmtxEncodeData()\fP functions..SH DECODING - Reading Data Matrix Barcodes\fIlibdmtx\fP provides small number of default decoding functions, and provides additional flexibility through parameters and callback functions.1. Call \fBdmtxDecodeStructCreate()\fPCreates the \fIlibdmtx\fP information struct.  This struct contains user decoding information and runtime options.  \fBdmtxDecodeStructCreate()\fP must be called before any other scanning functions.2. Call \fBdmtxImageInit()\fPInitializes an image structure for the calling program to use.  \fIlibdmtx\fP provides its own image structure that must be populated with the raw image information by the calling program before beginning the scan.  An initialized and populated image is required for any scanning activities.3. Call \fBdmtxScanStartNew()\fPResets the counters and lists before a new scan begins.  This is necessary because libdmtx might find multiple Data Matrix barcodes in an image, and therefore maintains a list of barcode regions.  This function clears the lists between reads so the program doesn't exhaust the system memory with already-scanned barcode regions.4. Call \fBdmtxScanLine()\fPPerforms the actual scan of a row or column (1 pixel wide) from the source image.  It returns number of Data Matrix barcodes that were found, and stores the barcode information in a list from the decode struct.  Multiple calls to \fBdmtxScanLine()\fP can happen between \fBdmtxScanStartNew()\fP (for example, to make the familiar "cross pattern" like in the supermarket checkout lane).5. Call \fBdmtxDecodeGetMatrixCount()\fPReturns the number of Data Matrix barcodes that are currently stored in the DmtxDecode list.  If none were found, will return 0.6. Call \fBdmtxDecodeGetMatrix()\fPReturns a pointer to the DmtxMatrixRegion struct held by DmtxDecode.  Data Matrix information (geometries, encoded and decoded data) will be stored until next call to \fBdmtxScanStartNew()\fP or \fBdmtxDecodeStructDestroy()\fP.7. Call \fBdmtxImageDeInit()\fPResets and frees memory associated with DmtxImage struct.  This is the complement to \fBdmtxImageInit()\fP.8. Call \fBdmtxDecodeStructDestroy()\fPResets and frees memory associated with DmtxDecode struct.  This is the complement to \fBdmtxDecodeInit()\fP..SH EXAMPLE PROGRAMThis program demonstrates both directions of \fIlibdmtx\fP functionality by first creating a Data Matrix barcode with its encoding functionality and then reading it back with the decoding functionality.  If everything works correctly then the original input data should match the final output data.  #include <stdlib.h>  #include <stdio.h>  #include <string.h>  #include <unistd.h>  #include <dmtx.h>  int  main(int argc, char **argv)  {     int count = 0;     unsigned char testString[] = "30Q324343430794<OQQ";     DmtxImage image;     DmtxEncode *encode;     DmtxDecode *decode;     /*      * 1) Write a new Data Matrix barcode (in memory)      */     encode = dmtxEncodeCreate();     dmtxEncodeData(encode, testString);     // Take copy of new image before freeing DmtxEncode struct     image = encode->image;     image.pxl = (DmtxPixel *)malloc(image.width * image.height *           sizeof(DmtxPixel));     if(image.pxl == NULL) {        perror("Malloc error");        exit(1);     }     memcpy(image.pxl, encode->image.pxl, image.width * image.height *           sizeof(DmtxPixel));     dmtxEncodeDestroy(&encode);     /*      * 2) Read the Data Matrix barcode from above      */     decode = dmtxDecodeStructCreate();     decode->option = DmtxSingleScanOnly;     decode->image = image;     count += dmtxScanLine(decode, DmtxDirUp, decode->image.width/2);     count += dmtxScanLine(decode, DmtxDirRight, decode->image.height/2);     if(count > 0) {        fprintf(stdout, "output: \\"");        fwrite(decode->matrix[0].output, sizeof(unsigned char),              decode->matrix[0].outputIdx, stdout);        fprintf(stdout, "\\"\\n\\n");     }     dmtxDecodeStructDestroy(&decode);     exit(0);  }.SH "SEE ALSO"libpng(3).SH STANDARDSISO/IEC 16022:2000ANSI/AIM BC11 ISS.SH BUGSEmail bug reports to mike@dragonflylogic.com.SH AUTHORCopyright (C) 2006 Mike Laughton.\" end of man page