Документация разработчика

Чтение DataMatrix

Распознавание кодов DataMatrix структуры GS1 с кадров промышленной камеры — для конвейеров с маркировкой «Честного знака».

99,6 %кадров корпуса из 8959 снимков производственной линии прочитаны; ложных прочтений нет
7 мсмедианное время чтения кадра по корпусу из 8959 снимков (с декодированием JPEG, одно ядро)
4,5 мсминимальное время чтения кадра по тому же корпусу (с декодированием JPEG, одно ядро)

Для ИИ-ассистентов: эта страница в Markdown · вся документация одним файлом · llms.txt

Версия 1.2

Обзор

Библиотека читает коды DataMatrix (ECC200) с кадров производственной камеры — например, коробки с маркировкой «Честного знака», где символ занимает на кадре около сотни пикселей. Ридер рассчитан на низкое разрешение съёмки — порядка двух пикселей на модуль символа — и проверяет каждую гипотезу геометрии кодовой коррекцией Рида-Соломона. Точность и скорость чтения — вверху страницы; ниже — только устройство интерфейса.

Что нового в 1.2.4: сеть-разведчик внутри dmr быстрее при том же ответе (выход сети побитово прежний, найденные коды те же): кадры 20 Мп — медиана 269 → 243 мс, 40 Мп — 573 → 525 мс (утилита dmr с чтением PNG, 12 потоков). Отказ сервера лицензий на запрос без метки nonce теперь объясняется: устаревшая программа или запрос, искажённый по пути (прокси, антивирус с проверкой HTTPS).

Что нового в 1.2.3: утоньшение тёмного на вырезках сети — только при повторе широким окном, первый узкий проход идёт без него (узкое окно обрезает символ, и такая вырезка платила за утоньшение впустую). Кадры до 8 Мп с десятками кодов — медиана 740 → 642 мс при тех же кодах; кадры 20 Мп с 10 DataMatrix — p90 679 → 339 мс; кадры 24–48 Мп — 943 → 824 мс.

Что нового в 1.2.2: сеть-разведчик видит коды на кадрах камер 20–40 Мп, на очень тёмных и на пересвеченных кадрах; при заданном числе кодов вырезки читаются коротким кругом, а разбор кадра останавливается, как только прочитано нужное число; PNG загружается быстрее. На замере (12 потоков, 10 DataMatrix на кадре): кадры 20 Мп — 785 кодов из 810 вместо 611, медиана 267 мс вместо 673; 40 Мп — 200 из 200 вместо 156; пересвеченные — 200 из 200 вместо 142; тёмные кадры с 50 кодами — 98,9 % DataMatrix вместо 91,1 %. Цена — на кадрах до 8 Мп с десятками кодов разбор дольше на треть (в 1.2.3 — на шестую часть). Режим одного кода не изменился.

Что нового в 1.2.0: сеть-разведчик символов, вкомпилированная в библиотеку, — когда ищется несколько кодов, она находит места символов, и каждое читается вырезкой (netMode); и предел потоков на один вызов scan() (threads). В режиме одного кода ответ и скорость прежние. C ABI — 3.2, совместим с 3.0 и 3.1.

Библиотека статическая, публичный интерфейс — на C++20, восемь заголовков в include/dmr/, плюс плоский интерфейс на C для других языков (dmr_c.h, раздел C ABI). Кадр передаётся видом на чужой буфер (dmr::ImageView) — без копирования, из уже имеющегося буфера камеры или снимка.

Область применения

По умолчанию сканер читает DataMatrix любой структуры. Режим requireGs1 (раздел «Настройки») дополнительно проверяет формат содержимого — AI 01 (GTIN, 14 цифр со сходящейся контрольной суммой), затем AI 21 — и отбраковывает символы, не подходящие под структуру GS1.

Подключение

Библиотека приходит уже собранной — собирать её не нужно, собирается только ваша программа. Подключить её можно двумя способами: статически — C++ API из libdmr.a входит в вашу программу целиком, или динамически — через библиотеку dmr_c с плоским интерфейсом на C (C ABI). Состав поставки одинаковый на обеих ОС:

include\dmr\{Dmr,Diagnostics,Geometry,Image,License,Scanner,Settings,Version}.h   C++ API
include\dmr\dmr_c.h                                                               C ABI
lib\libdmr.a                 статическая библиотека C++
lib\pkgconfig\dmr.pc
bin\dmr_c.dll                библиотека C ABI
lib\dmr_c.dll.a              её библиотека импорта (MinGW)
lib\pkgconfig\dmr_c.pc
bin\dmr.exe                  утилита командной строки
share\doc\dmr\licenses\       лицензии сторонних библиотек
Ваша программаЧто брать
C++, собирается MinGW-w64 GCC (Windows) или GCC (Linux)Статическая линковка — C++ API, libdmr.a
MSVC или другой компилятор; другой язык (C, C#, Delphi, Go…); обновление библиотеки без пересборки программыДинамическая линковка — C ABI, dmr_c
PythonКолесо из «Загрузок» — документация Python

Статическая линковка — C++ API

libdmr.a входит в вашу программу целиком: рядом с ней ничего класть не нужно, кроме файла ключа license.key — он рядом с программой (раздел «Лицензия»). Нужен компилятор C++20. API на C++, в результате возвращаются std::string и std::vector, поэтому компилятор и его стандартная библиотека должны быть теми же, что и у поставки (той же или более новой версии).

Нужен MinGW-w64 GCC, не MSVC

Поставка для Windows собрана MinGW-w64 GCC — libdmr.a в его формате и с его ABI. MSVC такой статический архив не слинкует; вашей программе нужен тот же тулчейн (например, MSYS2/MinGW или CLion с профилем MinGW). Из MSVC — динамически, через dmr_c.

Тулчейн бесплатный: MSYS2 — установщик с сайта, затем в его консоли MINGW64 (поставка собрана именно в этом окружении, не в UCRT64):

pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-pkgconf

Пути включения и строка линковки берутся из dmr.pc. Путь к lib\pkgconfig распакованной поставки — через переменную окружения (PowerShell); пути в .pc считаются от места самого файла, так что каталог распаковки может быть любым:

$env:PKG_CONFIG_PATH = "C:\куда\распакован\lib\pkgconfig"
pkg-config --static --cflags --libs dmr

Системные winhttp, crypt32, shell32 и advapi32 (их использует проверка лицензии) уже прописаны в Libs.private пакета — отдельно подключать не нужно.

Запрос к pkg-config должен быть статическим

Поставка — одна статическая библиотека, а значит вызывающему нужны и те библиотеки, на которых стоит она сама. Без --static их в командной строке не окажется, и линковка упадёт на неразрешённых символах.

В meson — зависимость по имени пакета:

dmr_dep = dependency('dmr', required: true, static: true)
executable('мояпрограмма', 'main.cpp', dependencies: [dmr_dep],
  link_args: ['-static'])   # Windows: рантайм MinGW внутрь программы

Под Windows -static вкомпоновывает в программу и рантайм компилятора: без него она потребует рядом libstdc++-6.dll, libgcc_s_seh-1.dll и libwinpthread-1.dll из MSYS2. Под Linux он не нужен. Полный meson.build — в «Быстром старте».

Динамическая линковка — C ABI

dmr_c — та же библиотека за плоским интерфейсом на C (заголовок dmr/dmr_c.h): функции dmr_* и непрозрачные указатели, без типов C++. Рантайм компилятора вкомпонован в неё статически, поэтому она не зависит ни от компилятора вызывающего, ни от его стандартной библиотеки C++ — годится для MSVC, Clang и любого языка с вызовом функций C. Всё, что библиотека отдаёт (результаты, строки), освобождается её же функциями: dmr_scan_result_free, dmr_image_free, dmr_free_string.

Правила интерфейса, полный пример и все функции — в разделе C ABI.

MinGW-w64 GCC — через dmr_c.pc и библиотеку импорта lib\dmr_c.dll.a, без --static:

$env:PKG_CONFIG_PATH = "C:\куда\распакован\lib\pkgconfig"
pkg-config --cflags --libs dmr_c

Это даёт -I…\include -L…\lib -ldmr_c. Содержимое dmr_c.pc:

prefix=${pcfiledir}/../..
includedir=${prefix}/include
libdir=${prefix}/lib

Name: dmr_c
Version: 1.2.4
Libs: -L${libdir} -ldmr_c
Cflags: -I${includedir}

MSVC — файла .lib в поставке нет, его делают из самой DLL. В консоли MSYS2 — описание экспорта:

gendef dmr_c.dll          # пакет mingw-w64-x86_64-tools; пишет dmr_c.def

затем в Developer Command Prompt for VS (x64) — библиотека импорта и сборка:

lib /def:dmr_c.def /machine:x64 /out:dmr_c.lib
cl /I C:\куда\распакован\include main.c dmr_c.lib

При запуске dmr_c.dll должна лежать рядом с вашим .exe (или в каталоге из PATH), а файл ключа license.key — рядом с dmr_c.dll или рядом с .exe (раздел «Лицензия»).

В meson — так же по имени пакета, без static:

dmr_c_dep = dependency('dmr_c', required: true)
executable('мояпрограмма', 'main.c', dependencies: [dmr_c_dep])

Колесо Python — обёртка как раз над dmr_c, библиотека лежит внутри пакета: документация Python.

Быстрый старт

Минимальная программа: снимок с диска, чтение, вывод текста. Всё, что нужно, — один заголовок:

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

int main() {
    dmr::Image frame;
    if (dmr::loadImage("кадр.jpg", frame) != dmr::LoadStatus::Ok) {
        std::cerr << "не удалось прочитать файл\n";
        return 1;
    }

    dmr::Scanner scanner;                          // поток кадров одной этикетки
    const dmr::ScanResult r = scanner.scan(frame);  // Image неявно приводится к ImageView

    if (r.ok()) {
        std::cout << r.text() << "\n";
    } else if (r.status == dmr::Status::NotFound) {
        std::cout << "символа на кадре нет\n";
    } else {
        std::cout << "символ есть, прочитать не вышло\n";
    }
}

Собрать пример можно Meson. Рядом с main.cpp — распакованная поставка dmr-1.2.4-windows-x64 и файл meson.build:

project('test_dmr', 'cpp',
  version : '0.1.0',
  default_options : ['cpp_std=c++20', 'warning_level=3', 'buildtype=release'])

cxx = meson.get_compiler('cpp')

# Готовая сборка dmr лежит рядом с проектом. Зависимость описываем вручную —
# так pkg-config не нужен вовсе (в архивах 1.0.0, скачанных до 04.10.2026,
# пути в .pc-файлах указывали на машину сборки; способ работает и с ними).
dmr_root = meson.current_source_dir() / 'dmr-1.2.4-windows-x64'

dmr_lib = cxx.find_library('dmr', dirs : dmr_root / 'lib', static : true)

# Libs.private из dmr.pc — нужны при статической компоновке
dmr_private = []
foreach l : ['winhttp', 'crypt32', 'shell32', 'advapi32']
  dmr_private += cxx.find_library(l)
endforeach

dmr_dep = declare_dependency(
  include_directories : include_directories('dmr-1.2.4-windows-x64/include'),
  dependencies : [dmr_lib] + dmr_private)

executable('test_dmr', 'main.cpp',
  dependencies : dmr_dep,
  cpp_args : ['-finput-charset=UTF-8', '-fexec-charset=UTF-8'],
  link_args : ['-static'])

Сборка — в консоли MSYS2 MINGW64:

meson setup build
meson compile -C build

То же через pkg-config: .pc-файлы поставки перемещаемые, поэтому вместо ручного описания хватит одной строки в meson.build — dmr_dep = dependency('dmr', static : true) — и пути к распакованному lib/pkgconfig при настройке:

meson setup build --pkg-config-path="$PWD/dmr-1.2.4-windows-x64/lib/pkgconfig"
meson compile -C build

Для кадра из своего конвейера захвата (SDK камеры, буфер OpenCV, Windows-битмап) диск не участвует — собирается вид на уже имеющийся буфер, без копирования:

const dmr::ImageView view{ m.data, m.cols, m.rows, (int)m.step, dmr::PixelFormat::Bgr8 };
const dmr::ScanResult r = scanner.scan(view);

Заголовки

Публичных заголовков C++ семь, все под include/dmr/; восьмой, dmr/Dmr.h, включает их все разом. Девятый файл, dmr/dmr_c.h, — отдельный интерфейс на C (C ABI).

ЗаголовокЧто в нём
dmr/Dmr.hАгрегат — включает всё нижеперечисленное
dmr/Image.hImageView, Image, PixelFormat, loadImage, пути
dmr/Scanner.hScanner, ScanResult, Code, Status
dmr/Settings.hНастройки и пресеты сканера
dmr/Geometry.hPoint, Box, Quad — где на кадре расположен код
dmr/Diagnostics.hexplain(), приёмник журнала (LogSink)
dmr/License.hПроверка и активация лицензии, пространство dmr::license
dmr/Version.hВерсия заголовка (макросы) и собранной библиотеки (dmr::version())

Заголовки не зависят друг от друга сверх необходимого: Settings.h и Scanner.h тянут за собой <functional> и <vector>, а тому, кто только собирает вид на кадр, достаточно одного Image.h.

Scanner

Scanner — объект, а не функция, и создавать его на каждый кадр не нужно: подсказка размера символа (Settings::mcHintRun) копится по кадрам потока и обязана их пережить, а число потоков пула — настройка процесса. При этом scan() объявлен const и не складывает в объект ничего, кроме этой подсказки: результат зависит от кадра, а не от истории чтений. Кандидаты внутри перебираются параллельно — свой пул потоков поверх scan() заводить не нужно.

class Scanner {
public:
    explicit Scanner(Settings s = Settings::stream());
    ~Scanner();

    Scanner(Scanner&&) noexcept;
    Scanner& operator=(Scanner&&) noexcept;
    Scanner(const Scanner&)            = delete;
    Scanner& operator=(const Scanner&) = delete;

    // Прочитать коды на кадре.
    //   frame        кадр целиком, цветной или полутоновый
    //   moduleCount  сторона символа в модулях; 0 — определять самому
    ScanResult scan(ImageView frame, int moduleCount = 0) const;

    // Снимок с диска и коды на нём под ОДНИМ сроком (budgetMs, timeoutMs):
    // загрузка и разбор вместе. Не загрузился — ImageTooLarge или
    // InvalidImage (при обрыве декодирования по сроку — и timedOut);
    // подробно — в load. С 1.0.10.
    ScanResult scanFile(const std::string& path, int moduleCount = 0,
                        LoadStatus* load = nullptr) const;

    // Размер символа, подсказанный предыдущими кадрами; 0 — подсказки нет.
    int moduleCountHint() const;

    // Забыть подсказку.
    void resetStream();

    const Settings& settings() const;
};

// Разовое чтение без объекта: проба, скрипт, один файл. Подсказка размера
// по потоку кадров здесь не работает — копить её нечему.
ScanResult scan(ImageView frame, const Settings& s = Settings::single());

Когда этикетка на конвейере сменилась, подсказку стоит сбросить явно, не дожидаясь, пока она погаснет сама:

scanner.resetStream();
Ошибки возвращаются, а не бросаются

scan() ловит всё внутри: внутренний сбой (например, нехватка памяти) — это Status::Failed, процесс живёт дальше. loadImage() сообщает о проблемах через LoadStatus. Из конструктора Scanner и функций license:: может выйти только std::bad_alloc — как из любого кода C++, который выделяет память. C ABI не пропускает и его.

Move-only

Scanner можно перемещать (Scanner&&), но не копировать — конструктор и оператор копирования удалены явно.

Результат чтения

Status

enum class Status {
    Ok            = 0,  // прочитан хотя бы один код
    NotFound      = 1,  // символ на кадре не найден
    NotDecoded    = 2,  // символ найден, но не прочитан
    Unlicensed    = 3,  // кадр не разбирался: нет пробного периода и лицензии
    ImageTooLarge = 4,  // кадр больше Settings::imageLimits, не разбирался
    InvalidImage  = 5,  // описание кадра противоречиво: шаг строки меньше
                        // ширины, неизвестный формат пикселя
    Failed        = 6,  // разбор оборван внутренней ошибкой (например, нехватка
                        // памяти); процесс живёт дальше
};

При Status::Unlicensed кадр не разбирался вовсе — причину даёт dmr::license::status() (раздел «Лицензия»). Ok всегда приходит хотя бы с одним кодом в codes; при любом другом статусе codes пуст.

ScanResult

ПолеТипСмысл
statusStatusЧем кончился разбор кадра
codesstd::vector<Code>Прочитанные коды, по одному на символ, в порядке чтения: сверху вниз, при равном верхнем крае — слева направо. Пуст, если status не Ok. При Settings::maxCodes = 1 длина не больше единицы
timedOutboolПеребор оборвался по Settings::budgetMs или Settings::timeoutMs. Взводится, только когда бюджет и правда что-то отсёк — успех при взведённом флаге возможен: код прочитан, но часть гипотез не проверена
elapsedMsdoubleСколько занял разбор кадра, мс, без учёта загрузки снимка с диска
detailsstd::shared_ptr<const Details>Разбор для диагностики; пусто, если не запрошен через Settings::collectDetails

Методы: bool ok() const — сокращение для status == Status::Ok; const std::string& text() const — текст первого кода или пустая строка, чтобы не писать codes.empty() ? "" : codes[0].text на каждом вызове.

Code

ПолеТипСмысл
textstd::stringДекодированная строка. Байты как есть: разделители GS остаются байтом 0x1D, а не подставляются печатным видом
boxBoxГде символ найден на исходном кадре — прямоугольник кандидата
cornersQuadЧетыре угла символа там же, точнее бокса (раздел «Геометрия»)
moduleCountintСторона символа в модулях

Повторы в codes уже слиты: два кандидата с одинаковой строкой и пересекающимися box — один символ, увиденный дважды, он возвращается одним кодом; две одинаковые этикетки, чьи боксы не пересекаются, остаются двумя кодами. Порядок — сверху вниз, затем слева направо.

Несколько кодов на кадре

const dmr::Scanner scanner(dmr::Settings::multi(0));   // 0 — сколько найдётся
for (const dmr::Code& c : scanner.scan(frame).codes)
    use(c.text, c.box, c.moduleCount);

multi(n) — это stream() с maxCodes = n: настроен на поток кадров камеры. Для несвязанных снимков (папка, отдельные файлы) с несколькими кодами добавьте то, что меняет single() — поля независимы:

auto s = dmr::Settings::multi(0);
s.mcHintRun    = 0;    // без подсказки от прошлых кадров
s.maxSizeTries = 24;   // перебор всех размеров на кадре, где ничего не прочитано

Кадр

PixelFormat

enum class PixelFormat {
    Gray8,   // один канал: яркость; для сканера самый дешёвый
    Bgr8,    // три канала, порядок OpenCV
    Rgb8,    // три канала, порядок большинства остальных
    Bgra8,   // четыре канала, порядок OpenCV и Windows
    Rgba8,   // четыре канала
};

Сканер работает с яркостью и цветной кадр первым делом переводит в неё. Для монохромной камеры кадр стоит передавать как Gray8, а не размноженным в три канала — ответ тот же, а кадр обрабатывается быстрее.

ImageView

Вид на чужой буфер: библиотека его не копирует, не освобождает и не переживает — буфер обязан быть жив всё время вызова.

struct ImageView {
    const uint8_t* data   = nullptr;
    int            width  = 0;
    int            height = 0;
    int            stride = 0;              // байт в строке; 0 — плотно
    PixelFormat    format = PixelFormat::Gray8;

    bool empty()    const;
    int  channels() const;
    int  rowBytes() const;                  // stride с уже разобранным нулём
    const uint8_t* row(int y) const;
};

stride = 0 значит «плотно» (width * каналов), а не «ноль байт в строке»: кадр камеры почти никогда не плотный — строки выравнивают, а вырезка наследует длину строки оригинала. Собирается на месте вызова без копирования:

const dmr::ImageView view{ m.data, m.cols, m.rows, (int)m.step, dmr::PixelFormat::Bgr8 };

Image

Кадр, которым библиотека владеет сама — нужен там, где она его создаёт, то есть при чтении с диска. Неявно приводится к ImageView, поэтому передаётся в scan() напрямую, без .view():

class Image {
public:
    Image() = default;
    Image(int width, int height, PixelFormat format);

    void reset(int width, int height, PixelFormat format);  // плотная укладка
    void clear();

    int         width()    const;
    int         height()   const;
    int         stride()   const;
    PixelFormat format()   const;
    int         channels() const;
    bool        empty()    const;

    uint8_t*       data();
    uint8_t*       row(int y);

    ImageView view() const;
    operator ImageView() const;   // неявно — для вызова scan(image)
};

Чтение с диска

enum class LoadStatus {
    Ok,          // снимок прочитан
    NotFound,    // файла нет
    Unreadable,  // файл есть, но это не читаемый снимок
    TooLarge,    // размер из заголовка больше ImageLimits; пиксели не читались
};

enum class LoadAs {
    Color,  // три канала, PixelFormat::Bgr8
    Gray,   // один канал, PixelFormat::Gray8
};

LoadStatus loadImage(const std::string& path, Image& out, LoadAs as = LoadAs::Color,
                     const ImageLimits& limits = ImageLimits{});   // 16384 по стороне, 100 Мп

Форматы: JPEG и PNG — определяются по первым байтам файла, а не по расширению. JPEG обычный и прогрессивный, полутоновый и цветной; CMYK не поддерживается. PNG любой глубины и типа цвета: 16 бит сводятся к 8, палитра и малая глубина разворачиваются, альфа-канал отбрасывается (без наложения на фон). BMP, GIF, TIFF и WebP дают Unreadable — переведите их заранее или передайте уже раскодированные пиксели через ImageView. Обрезанный JPEG читается, насколько хватает данных.

Для сканера Gray — лучший выбор: снимок монохромной камеры (полутон в трёхканальном JPEG) в этом виде читается дешевле, а ответ побайтово тот же, потому что каждый канал Color и есть эта яркость. При отказе out очищается — половина кадра от прошлой попытки хуже пустого.

dmr::Image frame;
switch (dmr::loadImage("кадр.jpg", frame, dmr::LoadAs::Gray)) {
    case dmr::LoadStatus::Ok:         break;
    case dmr::LoadStatus::NotFound:   /* файла нет */ break;
    case dmr::LoadStatus::Unreadable: /* файл есть, но это не снимок */ break;
}
Кодировка пути

loadImage сама разбирается с системной кодировкой пути — каталог с русским именем не роняет чтение. Для собственной работы с путями в заголовке есть toPath(const std::string&), fromPath(const std::filesystem::path&) (обратное преобразование) и printablePath(...) — путь в UTF-8, для журнала.

Геометрия

struct Point {
    float x = 0.0f;
    float y = 0.0f;
};

struct Box {
    int x = 0, y = 0, width = 0, height = 0;
    bool empty() const;
};

struct Quad {
    Point corner[4];
};

Point дробный: углы символа находятся с субмодульной точностью, и округление до целого теряло бы как раз её. Box — прямоугольник кандидата на исходном кадре; Quad — четыре его угла точнее, чем прямоугольником: на конвейере символ снят под углом.

for (const dmr::Point& p : c.corners.corner)
    drawTo(p.x, p.y);
Порядок углов

Углы Quad идут по кругу, и под индексом 3 стоит тот, который детектор принял за угол сплошной L-рамки — решение, принятое по плотности сторон до всякого чтения. Окончательный поворот символа выбирается позже и с ним может не совпасть. Для разметки поверх кадра corner[3] годится, для выводов о содержимом символа — нет.

Настройки

Значения по умолчанию — не выбор наугад, а результат тестирования на большом наборе кадров. Начинать стоит с пресета, а не с отдельных полей — имя пресета уже говорит, под какой сценарий он настроен.

ПресетДля чегоЧем отличается
Settings::stream()Поток кадров одной этикетки — конвейер, камера. УмолчаниеПодсказка размера по предыдущим кадрам включена, перебор размеров выключен
Settings::single()Разовые снимки — папка, ручная проверкаПодсказки нет, перебираются 24 размера символа
Settings::multi(n)Несколько кодов на одном кадреstream() с maxCodes = n (0 — сколько найдётся): подсказка включена, перебора размеров нет. Каждый кадр проходит полный перебор — примерно вчетверо дороже одиночного чтения. С 1.2 здесь сама включается сеть-разведчик
auto s = dmr::Settings::stream();
s.budgetMs   = 120.0;     // 0 — без ограничения
s.requireGs1 = true;      // принимать только коды структуры GS1
const dmr::Scanner scanner(s);
stream() против single()

Разница не стилистическая, а в скорости. single() перебирает до 24 размеров символа, если размер заранее не известен, — на кадре, который так и не удалось прочитать (отказном), это заметно медленнее, чем без перебора, хотя и поднимает долю успешных чтений на несколько процентов. На потоке кадров одной этикетки размер от кадра к кадру не меняется, поэтому перебор не даёт выигрыша в точности вообще — только платит временем на каждом отказе. Именно поэтому в stream() он выключен, а в single() включён: для разрозненных снимков, где размер заранее не знаешь, эта плата оправдана.

Все поля

ПолеУмолчаниеСмысл
maxCodes1Сколько кодов искать: 1 — один, 0 — сколько найдётся, N — не больше N
requireGs1falseПринимать только коды структуры GS1. Сошедшаяся коррекция Рида-Соломона сама по себе не доказывает верного чтения — проверка дополнительно смотрит на формат содержимого (AI 01, 14 цифр GTIN со сходящейся контрольной суммой, затем AI 21)
forcedRotation-1Поворот символа, 0..3 — четверти по часовой; -1 — определять самому
imageLimits16384 по стороне, 100 000 000 пикселейНаибольший кадр, который сканер берётся разбирать (dmr::ImageLimits из dmr/Image.h: maxSide, maxPixels; 0 — жёсткий потолок 65535 и 2^29). Кадр больше сразу получает Status::ImageTooLarge. Те же пределы передайте в loadImage() — там они сверяются с заголовком файла до выделения памяти. Защита, а не настройка качества
budgetMs0.0Бюджет времени на кадр, мс; 0 — без ограничения. Срок мягкий: проверка идёт между стадиями перебора, а не внутри них, поэтому время кадра может превысить бюджет на длительность идущей стадии
timeoutMs10000.0Предохранитель на кадр, мс; 0 и больше 60000 — потолок 60 с: дольше кадр не разбирается никогда. Для снимков из недоверенного источника задавайте и budgetMs. Защита от враждебных кадров (штриховка, текстура во весь кадр), а не настройка задержки: работает как budgetMs — из двух действует меньший, по истечении взводится timedOut, — но не меняет, чем перебор платит за скорость. loadImage() в C++ принимает только пределы размера, а загрузку и разбор под одним сроком даёт Scanner::scanFile(); в C ABI (dmr_load_image_ex → DMR_LOAD_TIMED_OUT) и в Python (dmr.Image(path, settings=…)) срок действует и на декодирование
rowParalleltrueДелить строки ядер изображения между потоками пула, пока кадр идёт одним потоком. Снижает задержку кадра ценой процессорного времени — выключать, если на машине несколько сканеров или важнее пропускная способность, а не задержка
maxSizeTries1Сколько размеров символа пробовать, когда размеру верить нельзя; 1 — не перебирать
warpScalesпустоМасштабы холста выпрямления для последнего прохода, пикселей на модуль; пусто — не перебирать; значения вне 1…32 пропускаются. Разбирается из строки вида "7,8,10" методом setWarpScales()
maxCandidates6Сколько кандидатов брать у детектора по L-паттерну за один проход
thinShare0.0Доля срока кадра, которую оставлять последней попытке — кадру с утоньшенным тёмным (растёкшаяся краска), когда срок короткий; 0 — не оставлять. Нужна вырезкам вокруг найденного символа (так её задаёт сама библиотека при поиске сетью); обычному кадру — не нужна
readerCacheMb64.0Предел памяти, МБ на кадр, под повторное использование работы; 0 — ничего не хранить. На ответ не влияет
mcHintRun5Сколько кадров подряд должны сойтись на одном размере символа, чтобы дальше он проверялся первым; 0 — не подсказывать
maxPatternError0.25Предел доли ошибок в служебных модулях (L-рамка, timing), при котором результат вообще рассматривается
lpatRetryScale0.8Повторный поиск по L-паттерну на точном масштабе, как вторая гипотеза; 0 — не повторять
directSamplingfalseБрать яркости модулей прямо из исходника, минуя холст выпрямления
useLPatternFinder / useTextureFindertrue / trueИсточники кандидатов; выключение нужно для сравнения детекторов на одном корпусе
collectDetailsfalseСобирать разбор прочитанного и отказа в ScanResult::details (около 2 МБ на результат)
netModeNetMode::AutoСеть-разведчик символов (с 1.2). Auto — включена, когда ищется больше одного кода (maxCodes ≠ 1); On — всегда; Off — никогда. Подробно — ниже, «Сеть-разведчик»
threads0Сколько потоков может занять один вызов scan(), считая вызывающий (с 1.2): 0 — все ядра, 1 — только вызывающий, N — не больше N. Ответ от него не зависит, только время. Подробно — ниже, «Потоки»

Сеть-разведчик

Небольшая сеть вкомпилирована в библиотеку — файл модели не нужен. За десятки миллисекунд она находит на кадре места символов; каждое место читается вырезкой, а весь кадр — как без сети — только если сеть ничего не нашла, если вырезки не прочли ни одного символа или если ищется один код и вырезки его не дали.

Включает её netMode. NetMode::Auto (умолчание) — сеть включена, когда ищется больше одного кода (maxCodes ≠ 1, пресет multi()): там полный проход по кадру упирается в предел кандидатов и проходит их всех до конца, а вырезка каждого символа — нет. В режиме одного кода «Авто» сеть не включает — ответ и скорость прежние: на трудных снимках сеть прибавляла чтений, но и 30–80 мс к кадру конвейера, который без неё читается за десятки миллисекунд. Нужна и там — NetMode::On; не нужна совсем — NetMode::Off. Включится ли сеть при данных настройках, отвечает dmr::netEnabled(s).

auto s = dmr::Settings::multi();             // Auto и maxCodes = 0 — сеть включится сама
// s.netMode = dmr::Settings::NetMode::On;    // сеть и в режиме одного кода
// s.netMode = dmr::Settings::NetMode::Off;   // без сети, как до 1.2
const dmr::Scanner scanner(s);

// dmr/Settings.h
bool netEnabled(const Settings& s);          // включена ли сеть при этих настройках

Замер — вырезки настоящих снимков, 16 DataMatrix на кадре: все коды прочитаны на 32 % кадров против 0 % без сети, коды в целом — 79 % против 23 %. Кадр 12 Мп с 16 кодами на 8 ядрах читается за 0,28 с против 0,98 с.

Потоки

threads — сколько потоков может занять один вызов scan(), считая вызывающий: 0 — все ядра машины (умолчание), 1 — только вызывающий, N — не больше N. Пул потоков у библиотеки один на процесс и заводится на все логические ядра; предел ограничивает участие в работе этого сканера — глубокий перебор кандидатов, деление строк (rowParallel), сеть и вырезки. Ответ от него не зависит, только время.

Задавать, когда ядер у процесса меньше, чем видно машине: в контейнере с квотой процессора библиотека видит все ядра хоста, и потоки сверх квоты только ждут её; или когда на машине работает несколько сканеров сразу — тогда ядра разумно поделить между ними.

auto s = dmr::Settings::stream();
s.threads = 2;            // контейнер с квотой в два процессора

Диагностика

Библиотека не пишет в консоль — приёмник журнала передаётся явно, и без него строки даже не собираются (из окружения она читает только язык сообщений, см. ниже):

using LogSink = std::function<void(std::string_view line)>;

void setLogSink(LogSink sink);   // пустой — выключить
void setVerbose(bool on);        // по умолчанию выключена
bool isVerbose();                // включена И есть приёмник
std::ostream& dbg();             // поток выкладки: в приёмник, иначе «в никуда»
dmr::setLogSink([](std::string_view line) { std::cerr << line; });
dmr::setVerbose(true);

Разбор причины конкретного чтения или отказа — отдельно и по запросу, строкой, а не в журнал. Собирается, только если при чтении был включён Settings::collectDetails:

struct ExplainOptions {
    int moduleCount     = 0;      // размер, заданный при чтении; 0 — определялся сам
    int forcedRotation  = -1;     // поворот, заданный при чтении
    bool images         = false;  // сохранять отладочные PNG рядом с рабочим каталогом
    std::string imagePath;        // имя снимка — для подписей отладочных файлов
};

std::string explain(const Details& details, const ExplainOptions& opt = {});
auto s = dmr::Settings::stream();
s.collectDetails = true;                 // около 2 МБ на результат
const dmr::ScanResult r = dmr::Scanner(s).scan(frame);
if (r.details) std::cerr << dmr::explain(*r.details);
explain() не выносит вердикт

Статус кадра уже объявил сканер. Когда символ найден, но не прочитан, разбирать нечего — тогда вырезка заново выпрямляется и декодируется, чтобы отказу было чем объясниться, и это стоит примерно столько же, сколько само чтение кадра.

Язык сообщений

Тексты для человека — состояние лицензии (status().message), сообщения об ошибках, выкладка — на русском или английском. По умолчанию язык берётся из переменной окружения LIBSCANNER_LANG (ru или en), без неё — из языка системы: русская система — русский, любая другая (и локаль C в контейнере) — английский. Машиночитаемые поля и коды не переводятся.

bool setMessageLanguage(std::string_view lang);   // "ru" или "en"; иначе false
std::string_view messageLanguage();               // "ru" или "en"
dmr::setMessageLanguage("en");   // на весь процесс

Версия библиотеки

#define DMR_VERSION_MAJOR 1
#define DMR_VERSION_MINOR 2
#define DMR_VERSION_PATCH 4
#define DMR_VERSION_STRING "1.2.4"

#define DMR_VERSION_AT(ma, mi, pa) ((ma) * 10000 + (mi) * 100 + (pa))
#define DMR_VERSION DMR_VERSION_AT(DMR_VERSION_MAJOR, DMR_VERSION_MINOR, DMR_VERSION_PATCH)

namespace dmr { std::string version(); }

Макросы говорят про заголовок, с которым скомпилировались; dmr::version() — про библиотеку, с которой слинковались. Разойтись они могут: библиотека ставится в префикс и живёт там дольше, чем помнит собиравший.

#if DMR_VERSION >= DMR_VERSION_AT(1, 1, 0)
    // код под заголовок 1.1.0 и новее
#endif

Лицензия

Сканер читает кадры, пока действует пробный период (месяц с первого запуска на машине, без сети и регистрации) или лицензия. Иначе Scanner::scan() сразу отвечает Status::Unlicensed и кадр не разбирает. Лицензия привязана к оборудованию (материнская плата, процессор, системный диск), а не к установке ОС.

#include <dmr/License.h>

const dmr::LicenseStatus s = dmr::license::status();
if (!s.canScan()) show(s.message);   // «Пробный период закончился. Нужна лицензия»

dmr::LicenseResult r = dmr::license::activate(keyFromUser);   // «DMR-XXXXX-XXXXX-XXXXX-XXXXX»
if (!r.ok) show(r.message);

Файл ключа license.key

Вместо вызова activate() из своей программы ключ можно положить в текстовый файл license.key. Библиотека ищет его, берётся первый найденный:

  1. рядом с модулем, где живёт библиотека: dmr_c.dll / libdmr_c.so для C ABI и Python (dmr/_lib/), сама программа — для статической libdmr.a;
  2. рядом с исполняемым файлом программы.

Текущий каталог и переменные окружения не просматриваются. Формат: ключ — первая строка, которая не пуста и не комментарий #, в том виде, в каком выдан — DMR-XXXXX-XXXXX-XXXXX-XXXXX (регистр, пробелы и дефисы не важны; BOM UTF-8 допустим; файлы больше 4 КБ не читаются). Файл читается при старте библиотеки (первый Scanner или вызов license:: — этот вызов один раз ждёт сервер) и снова фоновой проверкой примерно раз в час: ключ, положенный при работающей программе, подхватится в течение часа. Действующую лицензию файл с другим ключом не заменяет; ключ, отвязанный deactivate(), из файла снова не активируется. Если ключ не принят, об этом скажет status().message.

LicenseState

ЗначениеСмысл
TrialИдёт пробный период
ActiveЛицензия действует
RefreshDueДействует, но связи с сервером давно не было; автосверка повторяет попытки раз в час
TrialExpiredПробный период кончился, лицензии нет
ExpiredОплаченный срок лицензии кончился; продление в личном кабинете автосверка подхватит сама
NetworkRequiredБез связи с сервером дальше нельзя; как только сервер ответит, автосверка вернёт лицензию
WrongMachineЛицензия выдана другой машине
InvalidЗапись лицензии не проходит проверку подписи

LicenseStatus

ПолеСмысл
stateLicenseState
canScan()Читает ли сейчас сканер — true при Trial, Active или RefreshDue
validUntilКонец пробного периода или оплаченного срока, unix-секунды UTC
refreshAfterС какого момента токен считается устаревшим и лицензия переходит в RefreshDue; 0 — не устаревает
offlineUntilДольше этого без связи с сервером лицензия не работает; 0 — без ограничения
daysLeftЦелых суток до ближайшей из границ выше; 0 — граница пройдена
licenseId / activationIdИдентификаторы лицензии и конкретной активации
offlineModelimited | extended | full | instances; пусто без лицензии
clockRollbackСистемные часы отстают от времени, которое машина уже видела — откат часов срок не продлевает
messageСостояние словами, для показа пользователю — на языке сообщений (ниже)

Активация: онлайн и офлайн

Онлайн — ключ из личного кабинета, машина сама идёт на сервер лицензий:

dmr::LicenseResult r = dmr::license::activate("DMR-XXXXX-XXXXX-XXXXX-XXXXX");

Офлайн — для машины без интернета: файл запроса переносится на машину с сетью и загружается в личный кабинет, в ответ приходит license.lic:

dmr::license::writeActivationRequest("request.json");   // → загрузить в кабинет, получить license.lic
dmr::license::importLicenseFile("license.lic");          // тем же вызовом продлевается: новый файл заменяет старый

Активированная по сети лицензия раз в сутки сама сверяется с сервером в фоновом потоке — обновляет токен, приносит отзыв и продление срока. Вызывать для этого ничего не нужно, а чтение кадра сеть не ждёт никогда; сервер недоступен — повтор через час, лицензия работает, пока не выйдет срок работы без связи.

Отвязка и остальные функции

namespace dmr::license {
    void configure(const LicenseOptions& options);   // до первого сетевого вызова; можно не звать
    LicenseStatus status();
    LicenseResult activate(const std::string& licenseKey);
    LicenseResult refresh();                                    // сверить сейчас, не дожидаясь суток
    LicenseResult deactivate(const std::string& reason = {});    // расписка уходит на сервер
    LicenseResult deactivateToFile(const std::string& receiptPath, const std::string& reason = {});
    LicenseResult writeActivationRequest(const std::string& path);
    LicenseResult importLicenseFile(const std::string& path);
    std::string machineFingerprint();                           // для обращений в поддержку
}

Переезд на другую машину — deactivate() на старой: место освобождается на сервере распиской, подписанной секретом этой машины. Без сети — deactivateToFile(): расписка ложится в файл, отправить его можно с любой машины. Все функции потокобезопасны; функции с сетью блокируют вызывающего до ответа или до истечения LicenseOptions::timeoutMs (по умолчанию 15000 мс).

Каждый ответ сервера лицензий привязан к своему запросу: библиотека отправляет случайное одноразовое число, сервер возвращает его в подписанном ответе, и записанный раньше ответ повторно не примется. Расписка о сдаче места тоже одноразовая — в ней номер из последнего полученного от сервера ответа, поэтому расписку из восстановленной копии старого состояния машины сервер не примет. Секрет для подписи расписок сервер выдаёт только при первой активации машины. У лицензий с полной автономией (full) сдача места расходует лимит переносов; когда он исчерпан, перенос делает поддержка. Самостоятельно освободить место по лицензии можно не больше двух раз за 30 дней в режиме limited и не больше одного раза — в extended; дальше перенос делает поддержка.

Ключ активации

Ключ активации для activate() выдаётся из личного кабинета после оформления тарифа в каталоге.

Контейнеры: Docker, Kubernetes

С версии 1.1 в контейнере библиотека работает по лицензии «на экземпляры»: ключ передаётся переменной окружения DMR_LICENSE_KEY или секретом — файлом/run/secrets/license.key (сначала проверяется переменная, затем секрет, затем файл ключа рядом с библиотекой и программой). Активировать и отвязывать ничего не нужно: экземпляр занимает место при старте, раз в 30 минут в фоне отчитывается серверу лицензий и освобождает место при выходе программы. Пробного периода без ключа в контейнере нет — пробный ключ для контейнеров (2 экземпляра на 30 дней) выдаётся в личном кабинете. Ключ лицензии «на машины» в контейнере не активируется.Подробнее о лицензии на экземпляры.

Каждый процесс — отдельный экземпляр. Если программа запускает рабочие процессы через fork уже после загрузки библиотеки (gunicorn с --preload, multiprocessing, uWSGI без lazy-apps), каждый рабочий процесс занимает своё место при первом разборе кадра, а главный процесс, который сам кадров не разбирает, освобождает своё в течение 30 минут. Мест нужно столько, сколько процессов работает одновременно. Процесс, завершённый без штатного выхода (os._exit, kill -9), освобождает место через час.

Лицензия на экземпляры файлом не активируется: экземпляру нужна связь с сервером лицензий, без неё он работает 7 дней с последнего отчёта. Обычную машину без интернета (лицензия на машины) можно активировать файлом на весь оплаченный срок: при загрузке запроса в личном кабинете отметьте «Машина без интернета — работать весь срок без связи».

C ABI

Та же библиотека за плоским интерфейсом на C99 — заголовок dmr/dmr_c.h, библиотека dmr_c.dll / libdmr_c.so (как подключить — «Подключение»). Для C, MSVC и любого языка с вызовом функций C (C#, Go, Delphi, Rust…). Правила границы:

  • Через неё ходят только простые типы C: целые, double, указатели на буферы известного размера, перечисления как int и непрозрачные дескрипторы. Исключение C++ границу не пересекает — внутренний сбой превращается в NULLили код ошибки.
  • Владение: всё, что функция возвращает (дескриптор, строка), принадлежит вызывающему и освобождается своей функцией (dmr_image_free,dmr_scan_result_free, dmr_free_string; сканер — dmr_scanner_destroy). Указатели из функций-доступа (dmr_scan_result_code_text и подобных) живут не дольше объекта, из которого взяты, и отдельно не освобождаются.
  • dmr_settings_t начинается с struct_size и метки abi_tag: их выставляет вызывающий до пресета — в C проще всего dmr_settings_t s = DMR_SETTINGS_INIT;, в C++ — dmr_settings_prepare(&s). Пресет пишет не дальше struct_size; поля, которых вызывающий не знает (более новая библиотека), остаются по умолчанию. Чужая метка или размер вне допустимого — отказ: пресет вернёт 0, dmr_scanner_create — NULL. Программу, собранную с заголовком ABI 1.x или 2.0 (dmr до 1.0.8), нужно пересобрать. Программа с заголовком 3.0–3.1 полей ABI 3.2 — net_mode и threads — не передаёт и получает умолчания: сеть по задаче, все ядра.
  • Прочитанный текст хранит разделитель GS байтом 0x1D (в отличие от утилитыdmr, которая печатает <GS>) и может содержать нулевой байт — длину брать у dmr_scan_result_code_text_len, а неstrlen().
  • Пути — в системной кодировке процесса, как argv (в Windows это не UTF-8, если кодовая страница процесса не переключена на UTF-8).
  • Статусы — те же, что dmr::Status (раздел «Результат чтения»), плюсDMR_STATUS_INTERNAL_ERROR = -1 на сбой самого слоя C.dmr_scanner_scan возвращает NULL только при внутренней ошибке; «кода нет» — это результат со статусом DMR_STATUS_NOT_FOUND.
  • Функции лицензии возвращают тот же JSON, что dmr --license … --json (раздел «Командная строка»): один контракт для оболочки, C ABI и Python.

Полный пример: все коды со снимка

#include <dmr/dmr_c.h>
#include <stdio.h>

/* Все коды со снимка: 0 — прочитаны, 1 — нет кода, 2 — ошибка. */
int main(int argc, char** argv) {
    if (argc < 2) return 2;

    dmr_settings_t settings = DMR_SETTINGS_INIT;   /* размер и метка — до пресета */
    dmr_settings_multi(&settings, 0);         /* все коды на снимке */
    settings.mc_hint_run    = 0;              /* отдельный файл: без подсказки прошлых кадров, */
    settings.max_size_tries = 24;             /* все размеры — как single() */

    dmr_image_t* image = NULL;
    if (dmr_load_image_ex(argv[1], DMR_LOAD_GRAY, &settings, &image) != DMR_LOAD_OK)
        return 2;                             /* нет файла, не снимок, слишком большой */

    dmr_scanner_t* scanner = dmr_scanner_create(&settings);
    if (!scanner) { dmr_image_free(image); return 2; }

    dmr_image_view_t view = dmr_image_view(image);
    dmr_scan_result_t* r = dmr_scanner_scan(scanner, &view, 0);   /* 0 — размер сам */
    int rc = 2;
    if (r) {                                  /* NULL — внутренняя ошибка */
        dmr_status_t st = dmr_scan_result_status(r);
        if (st == DMR_STATUS_OK) {
            for (int i = 0; i < dmr_scan_result_code_count(r); ++i) {
                /* в тексте бывают 0x1D (GS) и даже 0x00 — длина, а не strlen() */
                fwrite(dmr_scan_result_code_text(r, i), 1, dmr_scan_result_code_text_len(r, i), stdout);
                putchar('\n');
            }
            rc = 0;
        } else if (st == DMR_STATUS_NOT_FOUND || st == DMR_STATUS_NOT_DECODED) {
            rc = 1;
        } else if (st == DMR_STATUS_UNLICENSED) {
            char* why = dmr_license_status_json();    /* {"state":"trial_expired",...} */
            fprintf(stderr, "%s\n", why ? why : "unlicensed");
            dmr_free_string(why);
        }
        dmr_scan_result_free(r);
    }
    dmr_scanner_destroy(scanner);
    dmr_image_free(image);
    return rc;
}

В Linux: cc main.c -o read $(pkg-config --cflags --libs dmr_c), запуск —LD_LIBRARY_PATH=/куда/распакован/lib ./read этикетка.png. На коде с пачки «Честного знака» печатает строку с настоящими байтами 0x1D между элементами.

Справочник

Все объявления dmr_c.h (ABI 3.2, библиотека 1.2.4); комментарии сокращены — полные в самом заголовке.

/* ── версии ── */
#define DMR_C_ABI_VERSION_MAJOR 3
#define DMR_C_ABI_VERSION_MINOR 2
size_t dmr_c_abi_version(char* buf, size_t buf_size);   /* "3.2" */
size_t dmr_version(char* buf, size_t buf_size);         /* версия библиотеки, "1.2.4" */

/* ── кадр ── */
typedef enum { DMR_PIXEL_GRAY8 = 0, DMR_PIXEL_BGR8 = 1, DMR_PIXEL_RGB8 = 2,
               DMR_PIXEL_BGRA8 = 3, DMR_PIXEL_RGBA8 = 4 } dmr_pixel_format_t;
typedef struct {
    const uint8_t*     data;     /* буфер вызывающего, жив весь вызов scan */
    int                width;
    int                height;
    int                stride;   /* байт на строку; 0 — плотно */
    dmr_pixel_format_t format;
} dmr_image_view_t;

typedef struct dmr_image dmr_image_t;                   /* непрозрачный, буфер библиотеки */
typedef struct dmr_settings dmr_settings_t;             /* определена ниже */
typedef enum { DMR_LOAD_COLOR = 0, DMR_LOAD_GRAY = 1 } dmr_load_as_t;
typedef enum { DMR_LOAD_OK = 0, DMR_LOAD_NOT_FOUND = 1, DMR_LOAD_UNREADABLE = 2,
               DMR_LOAD_TOO_LARGE = 3, DMR_LOAD_TIMED_OUT = 4,
               DMR_LOAD_INVALID_ARGUMENT = 5 } dmr_load_status_t;
dmr_load_status_t dmr_load_image(const char* path, dmr_load_as_t as, dmr_image_t** out);
dmr_load_status_t dmr_load_image_ex(const char* path, dmr_load_as_t as,
                                    const dmr_settings_t* settings,   /* NULL — по умолчанию */
                                    dmr_image_t** out);
dmr_image_view_t  dmr_image_view(const dmr_image_t* image);
void              dmr_image_free(dmr_image_t* image);

/* ── настройки: те же поля и умолчания, что dmr::Settings ── */
struct dmr_settings {
    uint32_t struct_size;        /* sizeof(dmr_settings_t), ставит вызывающий ПЕРВЫМ */
    uint32_t abi_tag;            /* DMR_SETTINGS_TAG, тоже до пресета */
    int    max_codes;            /* 1 — один, 0 — все, N — не больше N */
    int    require_gs1;          /* 0/1 */
    int    forced_rotation;      /* -1 — сам */
    double budget_ms;            /* 0 — без ограничения */
    int    row_parallel;         /* 0/1 */
    int    max_size_tries;
    int    warp_scales[16];      /* DMR_MAX_WARP_SCALES */
    int    warp_scales_count;    /* значения вне 1..32 пропускаются */
    int    max_candidates;
    double reader_cache_mb;
    int    mc_hint_run;
    double max_pattern_error;
    double lpat_retry_scale;
    int    direct_sampling;      /* 0/1 */
    int    use_lpattern_finder;  /* 0/1 */
    int    use_texture_finder;   /* 0/1 */
    int    collect_details;      /* 0/1 */
    int     max_image_side;      /* 0 — потолок 65535; в пресетах 16384 */
    int64_t max_image_pixels;    /* 0 — потолок 2^29; в пресетах 100 000 000 */
    double  timeout_ms;          /* предохранитель, в пресетах 10000; 0 — потолок 60 с */
    /* ── ABI 3.2 (dmr 1.2.0) ── */
    int     net_mode;            /* сеть-разведчик (вкомпилирована): 0 — по задаче (включена при
                                  * max_codes ≠ 1), 1 — всегда, -1 — никогда */
    int     threads;             /* потоков на один вызов scan, считая вызывающий: 0 — все ядра,
                                  * 1 — только вызывающий. Со старым заголовком оба поля — 0 */
};
#define DMR_SETTINGS_TAG 0x33524D44u                   /* 'D' 'M' 'R' '3' */
#define DMR_SETTINGS_INIT { .struct_size = (uint32_t)sizeof(dmr_settings_t), .abi_tag = DMR_SETTINGS_TAG }
#define DMR_SETTINGS_MAX_SIZE 4096u
static inline void dmr_settings_prepare(dmr_settings_t* s);   /* обнуляет, ставит размер и метку */
int dmr_settings_stream(dmr_settings_t* out);           /* 1 — заполнено; 0 — NULL, чужая */
int dmr_settings_single(dmr_settings_t* out);           /*   метка или размер         */
int dmr_settings_multi(dmr_settings_t* out, int max_codes);

/* ── сканер ── */
typedef struct dmr_scanner dmr_scanner_t;               /* непрозрачный */
dmr_scanner_t* dmr_scanner_create(const dmr_settings_t* settings);   /* NULL — stream() */
void           dmr_scanner_destroy(dmr_scanner_t* scanner);
int            dmr_scanner_module_count_hint(const dmr_scanner_t* scanner);
void           dmr_scanner_reset_stream(dmr_scanner_t* scanner);

/* ── результат ── */
typedef enum { DMR_STATUS_OK = 0, DMR_STATUS_NOT_FOUND = 1, DMR_STATUS_NOT_DECODED = 2,
               DMR_STATUS_UNLICENSED = 3, DMR_STATUS_IMAGE_TOO_LARGE = 4,
               DMR_STATUS_INVALID = 5, DMR_STATUS_FAILED = 6,
               DMR_STATUS_INTERNAL_ERROR = -1 } dmr_status_t;
typedef struct dmr_scan_result dmr_scan_result_t;       /* непрозрачный */
dmr_scan_result_t* dmr_scanner_scan(dmr_scanner_t* scanner, const dmr_image_view_t* frame,
                                    int module_count);  /* 0 — сам; NULL — внутренняя ошибка */
/* ABI 3.1: снимок с диска и коды на нём под одним сроком сканера; итог
 * загрузки — в *load_status (NULL — не нужен) */
dmr_scan_result_t* dmr_scanner_scan_file(dmr_scanner_t* scanner, const char* path,
                                         int module_count, dmr_load_status_t* load_status);
void         dmr_scan_result_free(dmr_scan_result_t* result);
dmr_status_t dmr_scan_result_status(const dmr_scan_result_t* result);
int          dmr_scan_result_timed_out(const dmr_scan_result_t* result);
double       dmr_scan_result_elapsed_ms(const dmr_scan_result_t* result);
int          dmr_scan_result_code_count(const dmr_scan_result_t* result);
const char*  dmr_scan_result_code_text(const dmr_scan_result_t* result, int index);
size_t       dmr_scan_result_code_text_len(const dmr_scan_result_t* result, int index);
void         dmr_scan_result_code_box(const dmr_scan_result_t* result, int index,
                                      int* x, int* y, int* width, int* height);
void         dmr_scan_result_code_corners(const dmr_scan_result_t* result, int index,
                                          float corners_xy[8]);   /* x0,y0 … x3,y3 */
int          dmr_scan_result_code_module_count(const dmr_scan_result_t* result, int index);

/* ── диагностика ── */
typedef void (*dmr_log_sink_t)(const char* line, size_t len, void* user);   /* line без завершающего нуля */
void dmr_set_log_sink(dmr_log_sink_t sink, void* user);
void dmr_set_verbose(int on);
int  dmr_is_verbose(void);

/* ── лицензия: JSON как у "dmr --license … --json"; освобождать dmr_free_string, NULL — внутренняя ошибка ── */
void  dmr_license_configure(const char* server_url, const char* app_version,
                            int timeout_ms, int auto_check);
char* dmr_license_status_json(void);
char* dmr_license_activate_json(const char* key);
char* dmr_license_refresh_json(void);
char* dmr_license_deactivate_json(const char* reason);           /* reason может быть NULL */
char* dmr_license_deactivate_to_file_json(const char* path, const char* reason);
char* dmr_license_write_activation_request_json(const char* path);
char* dmr_license_import_license_file_json(const char* path);
char* dmr_license_fingerprint_json(void);
void  dmr_free_string(char* s);

Командная строка

В поставку вместе с библиотекой входит готовая утилита командной строки dmr (bin/dmr) — для быстрой проверки без своего кода: разовый снимок, папка, список путей, поток для внешнего сервиса, лицензия. Её ключи, вывод и коды возврата описаны в отдельной вкладке «Командная строка».

Нужной функции нет в библиотеке или ваш случай за её границами — доработаем под вашу задачу. Напишите нам →