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 languages 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 sophisticated error correction techniques.
Data Matrix barcodes can be square or rectangle in shape, and offer several
encodation schemes for optimized 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 process.
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
dmtxEncodeCreate() 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, writing 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
provided by the calling application. Parameters include a pointer to the
existing pixel array, image width, height, and the pixel packing format.
2. Call
dmtxImageSetProp() [optional]
Sets image properties to control the pixel mapping logic. These settings 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 available 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 function 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 conditions. 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. Subsequent calls to
this function will resume the search where the previous 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 function,
dmtxMessageCreate(), is automatically called by
dmtxDecodeMatrixRegion() and therefore is not normally used by the
calling program.
8. Call
dmtxRegionDestroy()
Releases memory held by a
DmtxRegion struct. The complementary function,
dmtxRegionCreate(), is automatically called by
dmtxRegionFindNext() (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
