Datamatrix （只翻译解码部分)

LIBDMTX(3)                                                          LIBDMTX(3)



NAME
       libdmtx - Data Matrix Encoding & Decoding Library 0.7.2

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.

解码　-　读取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(&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
       Email bug reports to mike@dragonflylogic.com

AUTHOR
       Copyright (C) 2008, 2009 Mike Laughton



                               September 4, 2009                    LIBDMTX(3)