← Articles

Reading DataMatrix in C++: zxing-cpp, libdmtx or dmr — building and camera frames

A C++ program receives a camera frame or an image from disk and needs to extract the DataMatrix code string from it — for example, a GS1 code with its GS separators. Below: what to choose from, how to build and use our dmr library, and what to watch so you do not lose the separator or fall behind the line.

What to choose from

LibraryLicenseWhen to use
zxing-cppApache 2.0clean codes from photos and scans, many symbologies, CMake and MSVC builds; take the GS string from bytes(), not text()
libdmtxBSDDataMatrix only, a simple C API; slower than zxing-cpp (12 ms per frame vs 2 ms in our benchmark)
dmr (libscanner)commercialindustrial camera frames on a line: small modules, blur, glare; zero false reads; a deadline per frame

Numbers on open image sets are in the library benchmark. On a corpus of 8,959 production-line frames dmr read 99.6% of frames with no false reads, with a median of 7 ms per frame on one core including JPEG decoding.

dmr: an image from disk

The package is an archive for Windows (MinGW-w64) or Linux (x86-64, ARM64, ARMv7) from the Downloads section of your account: headers, a static C++ library, a dynamic C ABI library and a command-line tool. A minimal program needs one header:

#include <dmr/Dmr.h>
#include <iostream>

int main() {
    dmr::Image frame;
    if (dmr::loadImage("frame.jpg", frame) != dmr::LoadStatus::Ok) {
        std::cerr << "cannot read the file\n";
        return 1;
    }

    dmr::Scanner scanner;                          // a stream of frames of one label
    const dmr::ScanResult r = scanner.scan(frame);

    if (r.ok())
        std::cout << r.text() << "\n";            // the string with a real GS (0x1D)
    else if (r.status == dmr::Status::NotFound)
        std::cout << "no symbol in the frame\n";
    else
        std::cout << "symbol found but not decoded\n";
}

Building on Linux (GCC 12 or newer):

g++ -std=c++20 main.cpp -o read -I/opt/dmr/include /opt/dmr/lib/libdmr.a -pthread -ldl
# or with pkg-config:
export PKG_CONFIG_PATH=/opt/dmr/lib/pkgconfig
g++ -std=c++20 main.cpp -o read $(pkg-config --static --cflags --libs dmr)

On Windows the static library is built with MinGW-w64 GCC, and your program is built with the same toolchain (MSYS2, CLion with a MinGW profile). A Meson example is in the documentation.

A camera frame, no copy

The camera SDK gives you a buffer in memory — there is no need to save it to a file. ImageView is a view of someone else's buffer: the library neither copies nor frees it.

// buf, width, height, stride come from the camera SDK; a mono camera is Gray8
const dmr::ImageView view{ buf, width, height, stride, dmr::PixelFormat::Gray8 };

auto s = dmr::Settings::stream();   // frame stream: a hint from the previous frame
s.budgetMs = 120.0;                 // deadline per frame matched to the line
const dmr::Scanner scanner(s);      // create once, not per frame

const dmr::ScanResult r = scanner.scan(view);

Pass the row stride the camera gives you: frame rows are almost always padded, and zero (“tightly packed”) is a mistake here. For a mono camera pass the frame as Gray8, not replicated into three channels — the answer is the same and it runs faster. An OpenCV frame is passed the same way: { m.data, m.cols, m.rows, (int)m.step, dmr::PixelFormat::Bgr8 }.

MSVC, C#, Delphi: the C ABI

If your program is built with MSVC or is not written in C++, use the dynamic library with a C interface (dmr_c): it depends neither on the compiler nor on the C++ standard library. The code text comes with a length rather than as a null-terminated string: a code can contain 0x1D bytes and even 0x00, so strlen() is wrong here. A full C example is in the documentation, C ABI section.

What to watch

  • The GS separator. A GS1 code without GS fails validation. Do not cut the string at a null byte and do not print it through functions that replace control characters. More in the article on the GS separator.
  • One scanner per frame stream. Create the scanner once: in stream mode it keeps a hint from previous frames, so the next frames of the same label read faster. For parallel processing, use one scanner per thread.
  • Several codes. dmr::Settings::multi(0) reads every code in the frame; for DataMatrix, QR and barcodes in one frame there is unir. More in the article on multiple codes in one image.
  • License. For the first month the library works on a machine without a license and without internet; after that, a key — also for offline machines and containers.

Try it

Full C++ documentation: dmr and unir. Test your own image without installing anything in the online decoder. If the library does not fit your constraints (MSVC without the C ABI, macOS, mobile platforms, open source), an honest list of alternatives is in the article on when we are not the right choice.

Chestny ZNAK is a trademark of CRPT LLC (ООО «Оператор-ЦРПТ»); GS1 is a trademark of GS1 AISBL. The product is not affiliated with or certified by their owners.