Man Linux: Main Page and Category List


       libdmtx - Data Matrix Encoding & Decoding Library 0.7.2


       #include <dmtx.h>

       cc file.c -ldmtx


       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

ENCODING - Generating Data Matrix Barcodes

       C/C++  programs  can  generate a barcode with just a few basic calls to

       1. Call dmtxEncodeCreate()

       Creates  a  new  DmtxEncode  structure  and  initializes  the  encoding
       process.  This  function must be called before using the other encoding

       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-

       DmtxMessage  holds  the  decoded message after being extracted from the
       barcode region. A successfully decoded region will produce exactly  one

       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

       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

       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.


       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>

         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,

            pxl = (unsigned char *)malloc(width * height * bytesPerPixel);
            assert(pxl != NULL);
            memcpy(pxl, enc->image->pxl, width * height * bytesPerPixel);


            /* 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,
                  fputs("\"\n", stdout);




       dmtxread(1), dmtxwrite(1), dmtxquery(1)


       ISO/IEC 16022:2000

       ANSI/AIM BC11 ISS


       Email bug reports to


       Copyright (C) 2008, 2009 Mike Laughton

                               September 4, 2009