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(®);
}
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 [email protected]
AUTHOR
Copyright (C) 2008, 2009 Mike Laughton
September 4, 2009 LIBDMTX(3)
