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.
ENCODING - Generating Data Matrix Barcodes
C/C++ programs can generate a barcode with just a few basic calls to
libdmtx:
1. Call dmtxEncodeCreate()
Creates a new DmtxEncode structure and initializes the encoding pro-
cess. This function must be called before using the other encoding
functions.
2. Call dmtxEncodeSetProp() [optional]
Allows you to control specific aspects of the encoding behavior. If
this function is not called, libdmtx will use the defaults set by dmtx-
EncodeCreate() above. The complementary function, dmtxEncodeGetProp(),
allows you to detect the current settings.
3. Call either dmtxEncodeDataMatrix() or dmtxEncodeDataMosaic()
Call one of these functions to generate an image of the desired barcode
type. Your program is responsible for dispatching the resulting output
to its destination, whether that means displaying it on a screen, writ-
ing an image file, copying it elsewhere, etc...
4. Call dmtxEncodeDestroy()
Releases memory allocated during the encoding process.
DECODING - Reading Data Matrix Barcodes
Barcode reading takes more steps than barcode generation, mainly
because libdmtx must find a barcode region before it can decode the
message. However, this too is a relatively simple process that uses 4
main structures:
DmtxImage holds image properties and a pointer to pixel data held by
the calling program.
DmtxDecode holds values for controlling decode behavior and tracking
scan progress. When scanning a new image, calling programs should
always create a new DmtxDecode structure instead of reusing an old one.
DmtxRegion defines a 4-sided region in pixel coordinates. Regions may
be found in almost any orientation, and their corners won't necessarily
form right angles. libdmtx uses this structure to store the location of
potential barcodes, which are then returned to the calling program one-
at-a-time.
DmtxMessage holds the decoded message after being extracted from the
barcode region. A successfully decoded region will produce exactly one
message.
Use the following functions to find and decode Data Matrix barcodes:
1. Call dmtxImageCreate()
Creates and initializes a new DmtxImage structure using pixel data pro-
vided by the calling application. Parameters include a pointer to the
existing pixel array, image width, height, and the pixel packing for-
mat.
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 mike@dragonflylogic.com
AUTHOR
Copyright (C) 2008, 2009 Mike Laughton
September 4, 2009 LIBDMTX(3)
