<commit_before>.\" $Id: libdmtx.3,v 1.2 2006-09-14 03:49:57 mblaughton Exp $
.\"
.\" Man page for the libdmtx project.
.\"
.\" $Log: not supported by cvs2svn $
.\" Revision 1.1.1.1  2006/09/14 03:22:06  mblaughton
.\" Initial Import
.\"
.\"
.\" $ groff -man -T ascii libdmtx.3
.\"
.TH LIBDMTX 3 "June 11, 2006"
.SH NAME
libdmtx \- Data Matrix Encoder/Decoder Library 0.2.0
.SH SYNOPSIS
\fB#include <dmtx.h>\fP

\fBDmtxEncode *dmtxEncodeCreate(\fIvoid\fP);\fP

\fBvoid dmtxEncodeDestroy(DmtxEncode **\fIencode\fP);\fP

\fBint dmtxEncodeData(DmtxEncode *\fIencode\fP, unsigned char *\fIinputString\fP);\fP

\fBDmtxDecode *dmtxDecodeStructCreate(\fIvoid\fP);\fP

\fBvoid dmtxDecodeStructDestroy(DmtxDecode **\fIdecode\fP);\fP

\fBint dmtxImageInit(DmtxImage *\fIimage\fP);\fP

\fBint dmtxImageDeInit(DmtxImage *\fIimage\fP);\fP

\fBvoid dmtxScanStartNew(DmtxDecode *\fIdecode\fP);\fP

\fBvoid dmtxScanLine(DmtxDecode *\fIdecode\fP, int \fIline\fP, DmtxDirection \fIdirection\fP);\fP

\fBint dmtxDecodeGetMatrixCount(DmtxDecode *\fIdecode\fP);\fP

\fBDmtxMatrixRegion *dmtxDecodeGetMatrix(DmtxDecode *\fIdecode\fP, int \fIindex\fP);\fP

.SH DESCRIPTION
\fIlibdmtx\fP is a shared library for Linux that encodes and decodes ECC200 Data Matrix barcodes.  It is released under the LGPL and can be used and distributed freely under these terms.

Data Matrix barcodes are two-dimensional patterns that hold a high density of data with built-in error correction.  The Data Matrix symbology was invented and released into the public domain by RVSI Acuity CiMatrix.

.SH ENCODING - Generating Data Matrix Barcodes
Version 0.2 of \fIlibdmtx\fP provides a simple set of functions for the encoding process.  More functions will be added later to support other options, such as output format (ASCII, PNG, PNM, etc...) and others.

Currently, the following steps are required to create a Data Matrix barcode using \fIlibdmtx\fP:

1. Call \fBdmtxEncodeCreate()\fP

This function allocates memory for the encoding process and initializes its internal values.  This function must be called before any other encoding functions.

2. Call \fBdmtxEncodeData()\fP

\fBdmtxEncodeData()\fP creates one barcode for each call, and currently writes a PNM image file of the barcode to the current directory.  This is an ugly temporary hack.  Later there will probably be another function after this where you specify what you want done with the barcode image (e.g. Write to STDOUT?  Write to a PNG file?  Keep it in memory? etc...)

3. Call \fBdmtxEncodeDestroy()\fP

This function frees the memory allocated in the \fBdmtxEncodeCreate()\fP and \fBdmtxEncodeData()\fP functions.

.SH DECODING - Reading Data Matrix Barcodes
\fIlibdmtx\fP provides small number of default decoding functions, and provides additional flexibility through parameters and callback functions.

1. Call \fBdmtxDecodeStructCreate()\fP

Creates the \fIlibdmtx\fP information struct.  This struct contains user decoding information and runtime options.  \fBdmtxDecodeStructCreate()\fP must be called before any other scanning functions.

2. Call \fBdmtxImageInit()\fP

Initializes an image structure for the calling program to use.  \fIlibdmtx\fP provides its own image structure that must be populated with the raw image information by the calling program before beginning the scan.  An initialized and populated image is required for any scanning activities.

3. Call \fBdmtxScanStartNew()\fP

Resets the counters and lists before a new scan begins.  This is necessary because libdmtx might find multiple Data Matrix barcodes in an image, and therefore maintains a list of barcode regions.  This function clears the lists between reads so the program doesn't exhaust the system memory with already-scanned barcode regions.

4. Call \fBdmtxScanLine()\fP

Performs the actual scan of a row or column (1 pixel wide) from the source image.  It returns number of Data Matrix barcodes that were found, and stores the barcode information in a list from the decode struct.  Multiple calls to \fBdmtxScanLine()\fP can happen between \fBdmtxScanStartNew()\fP (for example, to make the familiar "cross pattern" like in the supermarket checkout lane).

5. Call \fBdmtxDecodeGetMatrixCount()\fP

Returns the number of Data Matrix barcodes that are currently stored in the DmtxDecode list.  If none were found, will return 0.

6. Call \fBdmtxDecodeGetMatrix()\fP

Returns a pointer to the DmtxMatrixRegion struct held by DmtxDecode.  Data Matrix information (geometries, encoded and decoded data) will be stored until next call to \fBdmtxScanStartNew()\fP or \fBdmtxDecodeStructDestroy()\fP.

7. Call \fBdmtxImageDeInit()\fP

Resets and frees memory associated with DmtxImage struct.  This is the complement to \fBdmtxImageInit()\fP.

8. Call \fBdmtxDecodeStructDestroy()\fP

Resets and frees memory associated with DmtxDecode struct.  This is the complement to \fBdmtxDecodeInit()\fP.

.SH EXAMPLE PROGRAM

This program demonstrates both directions of \fIlibdmtx\fP functionality by first creating a Data Matrix barcode with its encoding functionality and then reading it back with the decoding functionality.  If everything works correctly then the original input data should match the final output data.

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

  int
  main(int argc, char **argv)
  {
     int count = 0;
     unsigned char testString[] = "30Q324343430794<OQQ";
     DmtxImage image;
     DmtxEncode *encode;
     DmtxDecode *decode;

     /*
      * 1) Write a new Data Matrix barcode (in memory)
      */

     encode = dmtxEncodeCreate();
     dmtxEncodeData(encode, testString);

     // Take copy of new image before freeing DmtxEncode struct
     image = encode->image;
     image.pxl = (DmtxPixel *)malloc(image.width * image.height *
           sizeof(DmtxPixel));
     if(image.pxl == NULL) {
        perror("Malloc error");
        exit(1);
     }
     memcpy(image.pxl, encode->image.pxl, image.width * image.height *
           sizeof(DmtxPixel));
     dmtxEncodeDestroy(&encode);

     /*
      * 2) Read the Data Matrix barcode from above
      */

     decode = dmtxDecodeStructCreate();
     decode->option = DmtxSingleScanOnly;
     decode->image = image;

     count += dmtxScanLine(decode, DmtxDirUp, decode->image.width/2);
     count += dmtxScanLine(decode, DmtxDirRight, decode->image.height/2);

     if(count > 0) {
        fprintf(stdout, "output: \\"");
        fwrite(decode->matrix[0].output, sizeof(unsigned char),
              decode->matrix[0].outputIdx, stdout);
        fprintf(stdout, "\\"\\n\\n");
     }

     dmtxDecodeStructDestroy(&decode);

     exit(0);
  }

.SH "SEE ALSO"
libpng(3)

.SH STANDARDS
ISO/IEC 16022:2000

ANSI/AIM BC11 ISS

.SH BUGS
Email bug reports to mi<EMAIL>

.SH AUTHOR
Copyright (C) 2006 <NAME>

.\" end of man page
<commit_msg>Updated in preparation for v0.3 release.<commit_after>.\" $Id: libdmtx.3,v 1.3 2006-10-15 19:42:52 mblaughton Exp $
.\"
.\" Man page for the libdmtx project.
.\"
.\" $ groff -man -T ascii libdmtx.3
.\"
.TH LIBDMTX 3 "October 15, 2006"
.SH NAME
libdmtx \- Data Matrix Encoder/Decoder Library 0.3.0
.SH SYNOPSIS
\fB#include <dmtx.h>\fP

\fBDmtxEncode *dmtxEncodeCreate(\fIvoid\fP);\fP

\fBvoid dmtxEncodeDestroy(DmtxEncode **\fIencode\fP);\fP

\fBint dmtxEncodeData(DmtxEncode *\fIencode\fP, unsigned char *\fIinputString\fP);\fP

\fBDmtxDecode *dmtxDecodeStructCreate(\fIvoid\fP);\fP

\fBvoid dmtxDecodeStructDestroy(DmtxDecode **\fIdecode\fP);\fP

\fBint dmtxImageInit(DmtxImage *\fIimage\fP);\fP

\fBint dmtxImageDeInit(DmtxImage *\fIimage\fP);\fP

\fBvoid dmtxScanStartNew(DmtxDecode *\fIdecode\fP);\fP

\fBvoid dmtxScanLine(DmtxDecode *\fIdecode\fP, int \fIline\fP, DmtxDirection \fIdirection\fP);\fP

\fBint dmtxDecodeGetMatrixCount(DmtxDecode *\fIdecode\fP);\fP

\fBDmtxMatrixRegion *dmtxDecodeGetMatrix(DmtxDecode *\fIdecode\fP, int \fIindex\fP);\fP

.SH DESCRIPTION
\fIlibdmtx\fP is a shared library for Linux that encodes and decodes ECC200 Data Matrix barcodes.  Data Matrix barcodes are two-dimensional patterns that hold a high density of data with built-in error correction.  The Data Matrix symbology was invented and released into the public domain by RVSI Acuity CiMatrix.

.SH ENCODING - Generating Data Matrix Barcodes
Version 0.2 of \fIlibdmtx\fP provides a simple set of functions for the encoding process.  More functions will be added later to support other options, such as output format (ASCII, PNG, PNM, etc...) and others.

Currently, the following steps are required to create a Data Matrix barcode using \fIlibdmtx\fP:

1. Call \fBdmtxEncodeCreate()\fP

This function allocates memory for the encoding process and initializes its internal values.  This function must be called before any other encoding functions.

2. Call \fBdmtxEncodeData()\fP

\fBdmtxEncodeData()\fP creates one barcode for each call, and currently writes a PNM image file of the barcode to the current directory.  This is an ugly temporary hack.  Later there will probably be another function after this where you specify what you want done with the barcode image (e.g. Write to STDOUT?  Write to a PNG file?  Keep it in memory? etc...)

3. Call \fBdmtxEncodeDestroy()\fP

This function frees the memory allocated in the \fBdmtxEncodeCreate()\fP and \fBdmtxEncodeData()\fP functions.

.SH DECODING - Reading Data Matrix Barcodes
\fIlibdmtx\fP provides small number of default decoding functions, and provides additional flexibility through parameters and callback functions.

1. Call \fBdmtxDecodeStructCreate()\fP

Creates the \fIlibdmtx\fP information struct.  This struct contains user decoding information and runtime options.  \fBdmtxDecodeStructCreate()\fP must be called before any other scanning functions.

2. Call \fBdmtxImageInit()\fP

Initializes an image structure for the calling program to use.  \fIlibdmtx\fP provides its own image structure that must be populated with the raw image information by the calling program before beginning the scan.  An initialized and populated image is required for any scanning activities.

3. Call \fBdmtxScanStartNew()\fP

Resets the counters and lists before a new scan begins.  This is necessary because libdmtx might find multiple Data Matrix barcodes in an image, and therefore maintains a list of barcode regions.  This function clears the lists between reads so the program doesn't exhaust the system memory with already-scanned barcode regions.

4. Call \fBdmtxScanLine()\fP

Performs the actual scan of a row or column (1 pixel wide) from the source image.  It returns number of Data Matrix barcodes that were found, and stores the barcode information in a list from the decode struct.  Multiple calls to \fBdmtxScanLine()\fP can happen between \fBdmtxScanStartNew()\fP (for example, to make the familiar "cross pattern" like in the supermarket checkout lane).

5. Call \fBdmtxDecodeGetMatrixCount()\fP

Returns the number of Data Matrix barcodes that are currently stored in the DmtxDecode list.  If none were found, will return 0.

6. Call \fBdmtxDecodeGetMatrix()\fP

Returns a pointer to the DmtxMatrixRegion struct held by DmtxDecode.  Data Matrix information (geometries, encoded and decoded data) will be stored until next call to \fBdmtxScanStartNew()\fP or \fBdmtxDecodeStructDestroy()\fP.

7. Call \fBdmtxImageDeInit()\fP

Resets and frees memory associated with DmtxImage struct.  This is the complement to \fBdmtxImageInit()\fP.

8. Call \fBdmtxDecodeStructDestroy()\fP

Resets and frees memory associated with DmtxDecode struct.  This is the complement to \fBdmtxDecodeInit()\fP.

.SH EXAMPLE PROGRAM

This program demonstrates both directions of \fIlibdmtx\fP functionality by first creating a Data Matrix barcode with its encoding functionality and then reading it back with the decoding functionality.  If everything works correctly then the original input data should match the final output data.

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

  int
  main(int argc, char **argv)
  {
     int count = 0;
     unsigned char testString[] = "30Q324343430794<OQQ";
     DmtxImage image;
     DmtxEncode *encode;
     DmtxDecode *decode;

     /*
      * 1) Write a new Data Matrix barcode (in memory)
      */

     encode = dmtxEncodeCreate();
     dmtxEncodeData(encode, testString);

     // Take copy of new image before freeing DmtxEncode struct
     image = encode->image;
     image.pxl = (DmtxPixel *)malloc(image.width * image.height *
           sizeof(DmtxPixel));
     if(image.pxl == NULL) {
        perror("Malloc error");
        exit(1);
     }
     memcpy(image.pxl, encode->image.pxl, image.width * image.height *
           sizeof(DmtxPixel));
     dmtxEncodeDestroy(&encode);

     /*
      * 2) Read the Data Matrix barcode from above
      */

     decode = dmtxDecodeStructCreate();
     decode->option = DmtxSingleScanOnly;
     decode->image = image;

     count += dmtxScanLine(decode, DmtxDirUp, decode->image.width/2);
     count += dmtxScanLine(decode, DmtxDirRight, decode->image.height/2);

     if(count > 0) {
        fprintf(stdout, "output: \\"");
        fwrite(decode->matrix[0].output, sizeof(unsigned char),
              decode->matrix[0].outputIdx, stdout);
        fprintf(stdout, "\\"\\n\\n");
     }

     dmtxDecodeStructDestroy(&decode);

     exit(0);
  }

.SH "SEE ALSO"
libpng(3)

.SH STANDARDS
ISO/IEC 16022:2000

ANSI/AIM BC11 ISS

.SH BUGS
Email bug reports to <EMAIL>

.SH AUTHOR
Copyright (C) 2006 <NAME>

.\" end of man page

{'fraction_non_alphanumeric': 0.08586341248254062, 'fraction_numerical': 0.014188046754392414, 'mean_word_length': 3.8326820603907636, 'pattern_counts': {'":': 0, '<': 21, '<?xml version=': 0, '>': 37, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 1, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2040965', 'n_tokens_mistral': 4604, 'n_tokens_neox': 4366, 'n_words': 1565}