1LIBDMTX(3) Library Functions Manual LIBDMTX(3)
2
6 libdmtx - Data Matrix Encoding & Decoding Library 0.7.2
7
9 #include <dmtx.h>
10 cc file.c -ldmtx
12
15 libdmtx is a software library that enables programs to read and write
16 Data Matrix barcodes of the modern ECC200 variety. The library runs
17 natively on several platforms, and can be accessed by multiple lan‐
18 guages using the libdmtx language wrappers. The utility programs
19 dmtxread and dmtxwrite provide a command line interface for libdmtx,
20 and serve as a good reference for developers writing their own libdmtx-
21 enabled programs.
22 Data Matrix barcodes store data as a pattern of ON and OFF modules
24 (often black on white) in a grid pattern that resembles a checkerboard.
25 Like other 2D symbologies, Data Matrix barcodes have a large data
26 capacity compared to their traditional 1D cousins, and employ sophisti‐
27 cated error correction techniques. Data Matrix barcodes can be square
28 or rectangle in shape, and offer several encodation schemes for opti‐
29 mized storage of text and/or binary data. The Data Matrix symbology was
30 invented and released into the public domain by RVSI Acuity CiMatrix.
31
34 C/C++ programs can generate a barcode with just a few basic calls to
35 libdmtx:
36 1. Call dmtxEncodeCreate()
38 Creates a new DmtxEncode structure and initializes the encoding
40 process. This function must be called before using the other encoding
41 functions.
42 2. Call dmtxEncodeSetProp() [optional]
44 Allows you to control specific aspects of the encoding behavior. If
46 this function is not called, libdmtx will use the defaults set by dmtx‐
47 EncodeCreate() above. The complementary function, dmtxEncodeGetProp(),
48 allows you to detect the current settings.
49 3. Call either dmtxEncodeDataMatrix() or dmtxEncodeDataMosaic()
51 Call one of these functions to generate an image of the desired barcode
53 type. Your program is responsible for dispatching the resulting output
54 to its destination, whether that means displaying it on a screen, writ‐
55 ing an image file, copying it elsewhere, etc...
56 4. Call dmtxEncodeDestroy()
58 Releases memory allocated during the encoding process.
60
63 Barcode reading takes more steps than barcode generation, mainly
64 because libdmtx must find a barcode region before it can decode the
65 message. However, this too is a relatively simple process that uses 4
66 main structures:
67 DmtxImage holds image properties and a pointer to pixel data held by
69 the calling program.
70 DmtxDecode holds values for controlling decode behavior and tracking
72 scan progress. When scanning a new image, calling programs should
73 always create a new DmtxDecode structure instead of reusing an old one.
74 DmtxRegion defines a 4-sided region in pixel coordinates. Regions may
76 be found in almost any orientation, and their corners won't necessarily
77 form right angles. libdmtx uses this structure to store the location of
78 potential barcodes, which are then returned to the calling program one-
79 at-a-time.
80 DmtxMessage holds the decoded message after being extracted from the
82 barcode region. A successfully decoded region will produce exactly one
83 message.
84 Use the following functions to find and decode Data Matrix barcodes:
86 1. Call dmtxImageCreate()
88 Creates and initializes a new DmtxImage structure using pixel data pro‐
90 vided by the calling application. Parameters include a pointer to the
91 existing pixel array, image width, height, and the pixel packing for‐
92 mat.
93 2. Call dmtxImageSetProp() [optional]
95 Sets image properties to control the pixel mapping logic. These set‐
97 tings allow libdmtx to understand many native in-memory image layouts,
98 thus preventing the extra work of transforming and copying data to a
99 one-size-fits-all format. A dmtxDecodeGetProp() function is also avail‐
100 able for detecting the current image properties.
101 3. Call dmtxDecodeCreate()
103 Creates and initializes a new DmtxDecode struct, which designates the
105 image to be scanned and initializes the scan grid pattern. This func‐
106 tion must be called before any other scanning functions.
107 4. Call dmtxDecodeSetProp() [optional]
109 Sets internal properties to control decoding behavior. This feature
111 allows you to optimize performance and accuracy for specific image con‐
112 ditions. A dmtxDecodeGetProp() function is also available.
113 5. Call dmtxRegionFindNext()
115 Searches every pixel location in a grid pattern looking for potential
117 barcode regions. A DmtxRegion is returned whenever a potential barcode
118 region is found, or if the final pixel location has been scanned. Sub‐
119 sequent calls to this function will resume the search where the previ‐
120 ous call left off.
121 6. Call either dmtxDecodeMatrixRegion() or dmtxDecodeMosaicRegion()
123 Extracts raw data from the barcode region and decodes the underlying
125 message.
126 7. Call dmtxMessageDestroy()
128 Releases memory held by a DmtxMessage struct. The complementary func‐
130 tion, dmtxMessageCreate(), is automatically called by dmtxDecodeMa‐
131 trixRegion() and therefore is not normally used by the calling program.
132 8. Call dmtxRegionDestroy()
134 Releases memory held by a DmtxRegion struct. The complementary func‐
136 tion, dmtxRegionCreate(), is automatically called by dmtxRegionFind‐
137 Next() (actually dmtxRegionScanPixel()) and therefore is not normally
138 used by the calling program.
139 9. Call dmtxDecodeDestroy()
141 Releases memory held by a DmtxDecode struct. This is the complementary
143 function to dmtxDecodeCreate().
144 10. Call dmtxImageDestroy()
146 Releases memory held by a DmtxImage struct, excluding the pixel array
148 passed to dmtxImageCreate(). The calling program is responsible for
149 releasing the pixel array memory, if required.
150
153 This example program (available as simple_test.c in the source package)
154 demonstrates libdmtx functionality in both directions: encoding and
155 decoding. It creates a Data Matrix barcode in memory, reads it back,
156 and prints the decoded message. The final output message should match
157 the original input string.
158 #include <stdlib.h>
160 #include <stdio.h>
161 #include <string.h>
162 #include <assert.h>
163 #include <dmtx.h>
164 int
166 main(int argc, char *argv[])
167 {
168 size_t width, height, bytesPerPixel;
169 unsigned char str[] = "30Q324343430794<OQQ";
170 unsigned char *pxl;
171 DmtxEncode *enc;
172 DmtxImage *img;
173 DmtxDecode *dec;
174 DmtxRegion *reg;
175 DmtxMessage *msg;
176 fprintf(stdout, "input: \"%s\"\n", str);
178 /* 1) ENCODE a new Data Matrix barcode image (in memory only) */
180 enc = dmtxEncodeCreate();
182 assert(enc != NULL);
183 dmtxEncodeDataMatrix(enc, strlen(str), str);
184 /* 2) COPY the new image data before releasing encoding memory */
186 width = dmtxImageGetProp(enc->image, DmtxPropWidth);
188 height = dmtxImageGetProp(enc->image, DmtxPropHeight);
189 bytesPerPixel = dmtxImageGetProp(enc->image, DmtxPropBytesPer‐
190 Pixel);
191 pxl = (unsigned char *)malloc(width * height * bytesPerPixel);
193 assert(pxl != NULL);
194 memcpy(pxl, enc->image->pxl, width * height * bytesPerPixel);
195 dmtxEncodeDestroy(&enc);
197 /* 3) DECODE the Data Matrix barcode from the copied image */
199 img = dmtxImageCreate(pxl, width, height, DmtxPack24bppRGB);
201 assert(img != NULL);
202 dec = dmtxDecodeCreate(img, 1);
204 assert(dec != NULL);
205 reg = dmtxRegionFindNext(dec, NULL);
207 if(reg != NULL) {
208 msg = dmtxDecodeMatrixRegion(dec, reg, DmtxUndefined);
209 if(msg != NULL) {
210 fputs("output: \"", stdout);
211 fwrite(msg->output, sizeof(unsigned char), msg->outputIdx,
212 stdout);
213 fputs("\"\n", stdout);
214 dmtxMessageDestroy(&msg);
215 }
216 dmtxRegionDestroy(®);
217 }
218 dmtxDecodeDestroy(&dec);
220 dmtxImageDestroy(&img);
221 free(pxl);
222 exit(0);
224 }
225
228 dmtxread(1), dmtxwrite(1), dmtxquery(1)
229
231 ISO/IEC 16022:2000
232 ANSI/AIM BC11 ISS
234
236 Email bug reports to mike@dragonflylogic.com
237
239 Copyright (C) 2008, 2009 Mike Laughton
240 September 4, 2009 LIBDMTX(3)