Helpful Tips

Trailing Newline Characters

Command line utilities often print a newline character ('\n') as the final character of text output. For example, this "od" listing shows the newline character at the end of a basic "echo" command:

$ echo 'Hello, world!' | od -c
0000000   H   e   l   l   o   ,       w   o   r   l   d   !  \n

Trailing newline characters are useful when displaying and processing text, but often just waste precious space when stored in barcodes. Fortunately, many versions of "echo" provide the ability to omit the trailing newline by using the '-n' option:

$ echo -n 'Hello, world!' | od -c
0000000   H   e   l   l   o   ,       w   o   r   l   d   !

Another popular syntax uses the '\c' escape sequence:

$ echo 'Hello, world!\c' | od -c
0000000    H   e   l   l   o   ,       w   o   r   l   d   !

When reading the barcode back, the dmtxread utility provides a complementary option ('-n' again) that re-inserts a trailing newline character. The following example shows the process from beginning to end:

$ echo -n 'Hello, world!' | dmtxwrite -o hello.png
$ dmtxread -n hello.png | od -c
0000000   H   e   l   l   o   ,       w   o   r   l   d   !  \n

Note: the "| od -c" syntax is used here for demonstration purposes, and would be omitted during typical use.

Storage Efficiency During Encoding

(content required)

Scanning Performance During Decoding

Scanning Timeout

Applications often need to return quickly even if they did not find a barcode. The "—milliseconds" option in dmtxread forces the program to return after a specified number of milliseconds regardless of success or failure.

-m, --milliseconds=N       Stop scan after N milliseconds (per image)

Square Deviation

Applications like faxing and flatbed scanning should specify a low squareness deviation (5-10 deg) since all right angles in the subject image will appear as right angles in the image. Other applications, like scanning from a cell phone or webcam, may have distortion due to extreme scanning angles, and should be set to allow higher deviations (20-40 deg). The dmtxread utility allows large deviation values by default.

-q, --square-deviation=N   Allowed non-squareness of corners in degrees (0-90)

Internal Image Shrinking / Fast Pixel Skipping

Sometimes provides dramatic performance benefit. Often helps when image is high resolution but blurry focus.

-S, --shrink=N             Internally shrink image by a factor of N

Edge Strength Threshold

Lowering the threshold can increase the number of features to be scanned (thereby slowing performance) but may be necessary if image is blurry or has low contrast. Sometimes lowering the threshold will actually improve performance if it results in the reader seeing a good barcode candidate before it otherwise would have.

-t, --threshold=N          Ignore weak edges below threshold N (1-100)

Scan Portion of Image

If a barcode will always fall within a predictable region of an image then your application need not waste time looking anywhere else. The image range options allow you to specify a rectangular region of the image as small or large as you want.

-x, --x-range-min=N[%]     Do not scan pixels to the left of N (or N%)
-X, --x-range-max=N[%]     Do not scan pixels to the right of N (or N%)
-y, --y-range-min=N[%]     Do not scan pixels above N (or N%)
-Y, --y-range-max=N[%]     Do not scan pixels below N (or N%)

Creating vector output from versions prior to 0.7

At the time of writing, the version of libdmtx in Debian/Ubuntu repositories is 0.6.0 which cannot produce svg or other vector formats. For users who cannot or prefer not to compile their own, the following produces vector format output:

First, install potrace (a bitmap to vector converter). For Debian/Ubuntu do:

sudo apt-get install potrace

For other platforms downloads are available here: Potrace project page

The following will then produce an svg file as output:

echo "test text" | dmtxwrite -f m | potrace -a -1 -s -o test.svg

The following produces an eps file:

echo "test text" | dmtxwrite -f m | potrace -a -1 -o test.eps


potrace --help

will provide a list of all possible output formats and the flags required to generate them. Setting the 'a' flag to a negative number in the above examples is needed to prevent potrace from attempting to 'round' all the edges of the datamatrix squares (dmtxread seems to be capable of dealing with this at the resolutions I tried, but I have no idea how consistently reliable it'd be).

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License