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
| Library | License | When to use |
|---|---|---|
| zxing-cpp | Apache 2.0 | clean codes from photos and scans, many symbologies, CMake and MSVC builds; take the GS string from bytes(), not text() |
| libdmtx | BSD | DataMatrix only, a simple C API; slower than zxing-cpp (12 ms per frame vs 2 ms in our benchmark) |
| dmr (libscanner) | commercial | industrial 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.