1LIBDMTX(3)                 Library Functions Manual                 LIBDMTX(3)
2
3
4

NAME

6       libdmtx - Data Matrix Encoding & Decoding Library 0.7.2
7

SYNOPSIS

9       #include <dmtx.h>
10
11       cc file.c -ldmtx
12
13

DESCRIPTION

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
23       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
32

ENCODING - Generating Data Matrix Barcodes

34       C/C++ programs can generate a barcode with just a few  basic  calls  to
35       libdmtx:
36
37       1. Call dmtxEncodeCreate()
38
39       Creates  a  new  DmtxEncode  structure  and  initializes  the  encoding
40       process. This function must be called before using the  other  encoding
41       functions.
42
43       2. Call dmtxEncodeSetProp() [optional]
44
45       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
50       3. Call either dmtxEncodeDataMatrix() or dmtxEncodeDataMosaic()
51
52       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
57       4. Call dmtxEncodeDestroy()
58
59       Releases memory allocated during the encoding process.
60
61

DECODING - Reading Data Matrix Barcodes

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
68       DmtxImage holds image properties and a pointer to pixel  data  held  by
69       the calling program.
70
71       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
75       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
81       DmtxMessage  holds  the  decoded message after being extracted from the
82       barcode region. A successfully decoded region will produce exactly  one
83       message.
84
85       Use the following functions to find and decode Data Matrix barcodes:
86
87       1. Call dmtxImageCreate()
88
89       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
94       2. Call dmtxImageSetProp() [optional]
95
96       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
102       3. Call dmtxDecodeCreate()
103
104       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
108       4. Call dmtxDecodeSetProp() [optional]
109
110       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
114       5. Call dmtxRegionFindNext()
115
116       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
122       6. Call either dmtxDecodeMatrixRegion() or dmtxDecodeMosaicRegion()
123
124       Extracts raw data from the barcode region and  decodes  the  underlying
125       message.
126
127       7. Call dmtxMessageDestroy()
128
129       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
133       8. Call dmtxRegionDestroy()
134
135       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
140       9. Call dmtxDecodeDestroy()
141
142       Releases memory held by a DmtxDecode struct. This is the  complementary
143       function to dmtxDecodeCreate().
144
145       10. Call dmtxImageDestroy()
146
147       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
151

EXAMPLE PROGRAM

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
159         #include <stdlib.h>
160         #include <stdio.h>
161         #include <string.h>
162         #include <assert.h>
163         #include <dmtx.h>
164
165         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
177            fprintf(stdout, "input:  \"%s\"\n", str);
178
179            /* 1) ENCODE a new Data Matrix barcode image (in memory only) */
180
181            enc = dmtxEncodeCreate();
182            assert(enc != NULL);
183            dmtxEncodeDataMatrix(enc, strlen(str), str);
184
185            /* 2) COPY the new image data before releasing encoding memory */
186
187            width = dmtxImageGetProp(enc->image, DmtxPropWidth);
188            height = dmtxImageGetProp(enc->image, DmtxPropHeight);
189            bytesPerPixel   =  dmtxImageGetProp(enc->image,  DmtxPropBytesPer‐
190       Pixel);
191
192            pxl = (unsigned char *)malloc(width * height * bytesPerPixel);
193            assert(pxl != NULL);
194            memcpy(pxl, enc->image->pxl, width * height * bytesPerPixel);
195
196            dmtxEncodeDestroy(&enc);
197
198            /* 3) DECODE the Data Matrix barcode from the copied image */
199
200            img = dmtxImageCreate(pxl, width, height, DmtxPack24bppRGB);
201            assert(img != NULL);
202
203            dec = dmtxDecodeCreate(img, 1);
204            assert(dec != NULL);
205
206            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(&reg);
217            }
218
219            dmtxDecodeDestroy(&dec);
220            dmtxImageDestroy(&img);
221            free(pxl);
222
223            exit(0);
224         }
225
226

SEE ALSO

228       dmtxread(1), dmtxwrite(1), dmtxquery(1)
229

STANDARDS

231       ISO/IEC 16022:2000
232
233       ANSI/AIM BC11 ISS
234

BUGS

236       Email bug reports to mike@dragonflylogic.com
237

AUTHOR

239       Copyright (C) 2008, 2009 Mike Laughton
240
241
242
243                               September 4, 2009                    LIBDMTX(3)
Impressum