libdatamatrix
================================================================================

libdatamatrix is an embeddable and highly extensible library made to separate
datamatrix (ISO/IEC16022) functionality from image reading/writing since I
needed to make a custom image scanner and couldn't find any libraries that did
error correction (instead of just error checking) and had a modular interface
allowing one to extend functionality easily.

Since it was just written for internal use, it's not very polished.  I'm just
releasing it in hopes that it helps anyone who is also in search of an
embeddable datamatrix solution.

It also comes with a tiff image reading and very simplistic image scanner that
finds and reads matrices.

Caveats
-------

Currently only supports ASCII encoding, square, single region matrices.  Other
functionality will be added as needed (or as patches are submitted).

Requirements
------------

libfec (http://www.ka9q.net/code/fec/) copied or linked to
 <top_level_directory>/fec

for example:
wget http://www.ka9q.net/code/fec/fec-3.0.tar.bz2
bunzip2 -c fec-3.0.tar.bz2 | tar xvf -
cd fec-3.0
./configure
cd ..
ln -sf fec-3.0 fec

How to use
----------

Bundled with this library is a command line utility for accessing it - it also
serves as a good example (src/cli.c).

At the top level, one would just need to use datamatrix_create() and dm_region_read(), however internal functions are exported to allow extending the whole read or write process, for example to use a proprietary encoding method.

Better docs may come with time.

Example of simple region decoding
################################################################################
  char *str;
  dm_region_t *reg;


  if(!(str = dm_region_read(NULL, reg)))
    error("Failed to decode image: %s", strerror(errno));

  printf("decoded to [%s]\n", str);
################################################################################

Example of dm_config
################################################################################

  dm_config_t conf;

# config struct contains:
#  int w, h;
#  dm_enc_t encoding;
#  dm_errcb_t errmsg;

#hard set the datamatrix width and height
# if not set for creating, it uses the smallest size that will fit data
  conf.w = 12;
  conf.h = 12;

# sets the encoding method - currently unimplemented and only uses ASCII
  conf.encoding = DM_AUTOENC;

void errcb(const char *fmt, va_list ap)
{
  fprintf(stderr, "libdatamatrix: ");
  vfprintf(stderr, fmt, ap);
  fprintf(stderr, "\n");
}

# sets a callback function for reporting errors
  conf.errmsg = errcb;

################################################################################


Example of extending to use a custom encoder (in this case for higher density
data encoding).
################################################################################

  #define TS_DM_W 12
  #define TS_DM_H 12

# gets a datamatrix definition based on width and height of matrix
  /* lookup region size definition */
  if(!(def = dm_szdef_wh(TS_DM_W, TS_DM_H)))
    errret(NULL, "Invalid datamatrix region size (%dx%d)", TS_DM_W, TS_DM_H);

  /* create a buf for total size of data and RS codewords */
  if(!(data = dm_buf_new(NULL, def->dcw + def->rscw)))
    errret(NULL, "Failed to alloc for dm buf");

# this is the propietary encoding method
  /* encode slot */
  ts_dm_enc(slot, data);

# padding not needed since the encoding uses the full datacode codeword section

# adds the ECC information to the end of the data buf
  /* append ecc blocks */
  dm_eccenc(data, def->rscw);

# dm_region_new is what actually turns an arbitrary chunk of data into a 
# datamatrix, size based on the definition
  /* reset idx for write */
  data->idx = 0;
  return(dm_region_new(def->w, def->h, data));

################################################################################

To do
-----

* add autoconf / libtool
* embed ecc functionality, optimizing for just datamatrix
* add rectangular
* add multi region
* add "compressor" for finding the smallest encoding method.
* good documentation

Thanks
------

I used the following resources when writing this, thanks!

http://www.libdmtx.org/
http://datamatrixdec.berlios.de/index.php/Main_Page
http://grandzebu.net/informatique/codbar-en/datamatrix.htm
http://packages.qa.debian.org/i/iec16022.html
http://en.wikipedia.org/wiki/Datamatrix

License
-------

libdatamatrix is free software and released under the GNU GPL, see COPYING for
details.

================================================================================

Please send any comments or bugs to matt@devIT.com.

Matt Griswold <matt@devIT.com>
6CF4 A97B 55A5 BBD6 FF06  6F0B F99D 7C86 6B2E 514F