LIBDMTX(3) LIBDMTX(3)NAME libdmtx - Data Matrix Encoding & Decoding Library 0.7.2SYNOPSIS #include <dmtx.h> cc file.c -ldmtxDESCRIPTION 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.解码 - 读取Data Matrix条码
条码的读取要比条码的生成多一些步骤。主要是因为libdmtx在可以解码之前，必须找到条码区域。然而，
这也只是个相当简单的处理，用到4个主要结构：
DmtxImage 保存着图像的属性以及一个指向像素数据的指针，这些像素数据保存在调用的程序里。
DmtxDecode 保存着控制解码行为和跟踪扫描过程的数值。当扫描一张新的图像，调用的程序需要每次重新
创建新的DmtxDecode结构，而不是重用旧的结构。
DmtxRegion 以像素坐标定义了一个4边形的区域。区域可以从几乎任何方向获得，而且它们的拐角并不需要
形成正确的角度。libdmtx 用它自己的结构来保存潜在条码的位置，程序调用方每调用一次获得一个位置。
DmtxMessage 保存着从条码提取出的解码信息。一个成功解码的区域将精确地产生一个的信息。
使用下面的的函数以寻找并解码Data Matrix条码： 1. 调用 dmtxImageCreate()用程序调用方提供的像素数据创建并初始化一个新的DmtxImage结构。参数包含了一个指向现有像素数组
的指针，图像的宽与高，以及像素封装的格式。
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, DmtxPropBytesPerPixel); 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 ISSBUGS Email bug reports to mike@dragonflylogic.comAUTHOR Copyright (C) 2008, 2009 Mike Laughton September 4, 2009 LIBDMTX(3)
