Linux Certif

Toute la documentation sur la certification Linux LPI

libdmtx

NAME

libdmtx - Data Matrix Encoder/Decoder Library 0.6.0

SYNOPSIS

#include <dmtx.h>

ENCODING FUNCTIONS

DmtxEncode dmtxEncodeStructInit(void);

int dmtxEncodeDataMatrix(DmtxEncode *enc, int n, unsigned char *s, int sizeIdxRequest);

int dmtxEncodeDataMosaic(DmtxEncode *enc, int n, unsigned char *s, int sizeIdxRequest);

void dmtxEncodeStructDeInit(DmtxEncode *enc);

DECODING FUNCTIONS

DmtxDecode dmtxDecodeStructInit(DmtxImage *img);

int dmtxDecodeSetProp(DmtxDecode *dec, int prop, int value);

DmtxRegion dmtxDecodeFindNextRegion(DmtxDecode *dec, DmtxTime *timeout);

DmtxMessage *dmtxDecodeMatrixRegion(DmtxImage *img, DmtxRegion *reg, int fix);

DmtxMessage *dmtxDecodeMosaicRegion(DmtxImage *img, DmtxRegion *reg, int fix);

void dmtxDecodeStructDeInit(DmtxDecode *dec);

COMMON FUNCTIONS

DmtxMessage *dmtxMessageMalloc(int sizeIdx);

void dmtxMessageFree(DmtxMessage **mesg);

DmtxImage *dmtxImageMalloc(int width, int height);

int dmtxImageFree(DmtxImage **img);

int dmtxImageSetProp(DmtxImage *img, int prop, int value);

int dmtxImageGetProp(DmtxImage *img, int prop);

DmtxTime dmtxTimeNow(void);

DmtxTime dmtxTimeAdd(DmtxTime t, long msec);

int dmtxTimeExceeded(DmtxTime timeout);

DESCRIPTION

libdmtx is a shared library that enables programs to read and write ECC200 Data Matrix barcodes. The utility programs dmtxread and dmtxwrite serve as the official interface to libdmtx from the command line, and also provide a good reference for programmers who wish to write their own programs that interact with libdmtx.

Data Matrix barcodes are two dimensional patterns that resemble a checkerboard in appearance, and hold a high density of data with built-in error correction. They can exist in either square or rectangular configurations, and support several different encodation schemes for optimized storage of binary and text data. The Data Matrix symbology was invented and released into the public domain by RVSI Acuity CiMatrix.

ENCODING - Generating Data Matrix Barcodes

libdmtx provides a simple set of functions for encoding. The following steps will produce an image that holds a Data Matrix barcode with the specified message.

1. Call dmtxEncodeStructInit()

Initializes the internal values of the encoding process. Must be called before any other encoding functions.

2. Call either dmtxEncodeDataMatrix() or dmtxEncodeDataMosaic()

Depending on the desired barcode format, the calling program will use one of these functions to generate a barcode image within the DmtxEncode struct. The calling program is responsible for using this information to create a permanent image file.

3. Call dmtxEncodeStructDeInit()

Resets the internal encoding values and frees memory allocated during the encoding process.

DECODING - Reading Data Matrix Barcodes

libdmtx provides a number of functions designed to provide maximum control and flexibility in the decoding process. The following steps first allocate memory for the image data held by the calling application. After the image data is captured, the remaining steps will find and decode the barcodes present in the image.

1. Call dmtxImageMalloc()

Allocates memory for received image data. libdmtx provides its own image structure that the calling program must populate before starting a scan.

2. Call dmtxDecodeStructInit()

Initializes the DmtxDecode struct, which designates the image to be scanned and resets the grid pattern for a new scan. This function must be called before any other scanning functions.

3. Call dmtxDecodeSetProp()

Set internal properties to control decoding behavior. This feature allows applications to tune performance and accuracy for specific image conditions.

4. Call dmtxDecodeFindNextRegion()

Searches every pixel location in a recursive grid pattern looking for potential barcode edges. A DmtxRegion is returned whenever A) a potential barcode region is found, or B) the final pixel has been scanned. Subsequent calls to this function will resume the search where the previous call left off.

Important: This function does not dynamically allocate memory and does not decode the barcode contents. If the calling program receives a region that it wishes to discard, it can simply continue without freeing or cleaning up the previous DmtxRegion struct. This can be useful for programs that are selective in choosing which regions should be decoded.

5. Call either dmtxDecodeMatrixRegion() or dmtxDecodeMosaicRegion()

Extract bit values from the barcode region and decode the underlying message. DmtxMessage values returned from this function must be freed after use.

6. Call dmtxMessageFree()

Free the memory held by a DmtxMessage struct. The complementary function, dmtxMessageMalloc(), is automatically called by dmtxDecodeMatrixRegion() and therefore is not normally used by the calling program.

7. Call dmtxDecodeStructDeInit()

Resets the internal decoding values used during the decoding process.

8. Call dmtxImageFree()

Resets and frees memory held by DmtxImage struct. This is the complement to dmtxImageMalloc().

EXAMPLE PROGRAM

This example program (available as simpletest.c in the source package) demonstrates both directions of libdmtx functionality, encoding and decoding. It first creates a Data Matrix barcode and then reads it back and prints the decoded message. If everything works correctly then the final output message should match the original input string.

  #include <stdlib.h>
  #include <stdio.h>
  #include <string.h>
  #include <dmtx.h>

  int
  main(int argc, char *argv[])
  {
     unsigned char str[] = "30Q324343430794<OQQ";
     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 = dmtxEncodeStructInit();
     dmtxEncodeDataMatrix(&enc, strlen(str), str, DMTX_SYMBOL_SQUARE_AUTO);

     /* 2) COPY the new image data before freeing encoding memory */

     img = dmtxImageMalloc(enc.image->width, enc.image->height);
     memcpy(img->pxl, enc.image->pxl, img->width * img->height * sizeof(DmtxRgb));

     dmtxEncodeStructDeInit(&enc);

     /* 3) DECODE the Data Matrix barcode from the copied image */

     dec = dmtxDecodeStructInit(img);

     reg = dmtxDecodeFindNextRegion(&dec, NULL);
     if(reg.found != DMTX_REGION_FOUND)
        exit(0);

     msg = dmtxDecodeMatrixRegion(img, &reg, -1);
     if(msg != NULL) {
        fputs("output: \"", stdout);
        fwrite(msg->output, sizeof(unsigned char), msg->outputIdx, stdout);
        fputs("\"\n\n", stdout);
        dmtxMessageFree(&msg);
     }

     dmtxDecodeStructDeInit(&dec);
     dmtxImageFree(&img);

     exit(0);
  }

SEE ALSO

dmtxread(1), dmtxwrite(1)

STANDARDS

ISO/IEC 16022:2000

ANSI/AIM BC11 ISS

BUGS

Email bug reports to mike@dragonflylogic.com

AUTHOR

Copyright (c) 2008 Mike Laughton