# Чтение DataMatrix 1.2 — C++ и C ABI

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

Страница на сайте: https://libscanner.com/docs/datamatrix-gs1/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). Состав поставки одинаковый на обеих ОС:

**Windows:**

```
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\       лицензии сторонних библиотек
```

**Linux:**

```
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
lib/libdmr_c.so               библиотека C ABI
lib/pkgconfig/dmr_c.pc
bin/dmr                       утилита командной строки
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](https://libscanner.com/docs/datamatrix-gs1/1.2/python.md) |

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

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

**Windows:**

> **Нужен MinGW-w64 GCC, не MSVC.** Поставка для Windows собрана MinGW-w64 GCC — `libdmr.a` в его формате и с его ABI. MSVC такой статический архив не слинкует; вашей программе нужен тот же тулчейн (например, MSYS2/MinGW или CLion с профилем MinGW). Из MSVC — динамически, через dmr_c.
>
> Тулчейн бесплатный: [MSYS2](https://www.msys2.org/) — установщик с сайта, затем в его консоли **MINGW64** (поставка собрана именно в этом окружении, не в UCRT64):
>
> ```bash
> pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-pkgconf
> ```

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

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

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

**Linux:**

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

```bash
PKG_CONFIG_PATH=/куда/распакован/lib/pkgconfig pkg-config --static --cflags --libs dmr
```

Нужны `-pthread -ldl` — они уже в пакете. `-std=c++20` файл `.pc` не добавляет — укажите сами (у GCC 12 по умолчанию C++17). Без pkg-config та же строка вручную:

```bash
g++ -std=c++20 main.cpp -o мояпрограмма -I/куда/распакован/include /куда/распакован/lib/libdmr.a -pthread -ldl
```

OpenSSL в линковке не нужен: для `https://` сервера лицензий библиотека сама загружает `libssl.so.3` (или `.so.1.1`) при работе.

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

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

```cpp
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.

**Windows:**

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

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

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

```cpp
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 — описание экспорта:

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

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

```bash
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` (раздел «Лицензия»).

**Linux:**

```bash
PKG_CONFIG_PATH=/куда/распакован/lib/pkgconfig pkg-config --cflags --libs dmr_c
```

Это даёт `-I…/include -L…/lib -ldmr_c`. При запуске загрузчик должен найти `libdmr_c.so`: либо через `LD_LIBRARY_PATH`, либо положите её рядом с программой и пропишите путь поиска при линковке:

```bash
LD_LIBRARY_PATH=/куда/распакован/lib ./мояпрограмма

# или: libdmr_c.so рядом с программой
cc main.c -o мояпрограмма $(pkg-config --cflags --libs dmr_c) -Wl,-rpath,'$ORIGIN'
cp /куда/распакован/lib/libdmr_c.so .
```

Файл ключа `license.key` — рядом с `libdmr_c.so` или рядом с программой (раздел «Лицензия»). Версии в SONAME у библиотеки нет — файл называется просто `libdmr_c.so`.

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

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

Колесо Python — обёртка как раз над `dmr_c`, библиотека лежит внутри пакета: [документация Python](https://libscanner.com/docs/datamatrix-gs1/1.2/python.md).

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

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

```cpp
#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`:

```cpp
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:

```bash
meson setup build
meson compile -C build
```

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

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

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

```cpp
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.h` | `ImageView`, `Image`, `PixelFormat`, `loadImage`, пути |
| `dmr/Scanner.h` | `Scanner`, `ScanResult`, `Code`, `Status` |
| `dmr/Settings.h` | Настройки и пресеты сканера |
| `dmr/Geometry.h` | `Point`, `Box`, `Quad` — где на кадре расположен код |
| `dmr/Diagnostics.h` | `explain()`, приёмник журнала (`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()` заводить не нужно.

```cpp
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());
```

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

```cpp
scanner.resetStream();
```

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

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

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

### Status

```cpp
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

| Поле | Тип | Смысл |
| --- | --- | --- |
| `status` | `Status` | Чем кончился разбор кадра |
| `codes` | `std::vector<Code>` | Прочитанные коды, по одному на символ, в порядке чтения: сверху вниз, при равном верхнем крае — слева направо. Пуст, если `status` не `Ok`. При `Settings::maxCodes = 1` длина не больше единицы |
| `timedOut` | `bool` | Перебор оборвался по `Settings::budgetMs` или `Settings::timeoutMs`. Взводится, только когда бюджет и правда что-то отсёк — успех при взведённом флаге возможен: код прочитан, но часть гипотез не проверена |
| `elapsedMs` | `double` | Сколько занял разбор кадра, мс, без учёта загрузки снимка с диска |
| `details` | `std::shared_ptr<const Details>` | Разбор для диагностики; пусто, если не запрошен через `Settings::collectDetails` |

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

### Code

| Поле | Тип | Смысл |
| --- | --- | --- |
| `text` | `std::string` | Декодированная строка. Байты как есть: разделители GS остаются байтом `0x1D`, а не подставляются печатным видом |
| `box` | `Box` | Где символ найден на исходном кадре — прямоугольник кандидата |
| `corners` | `Quad` | Четыре угла символа там же, точнее бокса (раздел «Геометрия») |
| `moduleCount` | `int` | Сторона символа в модулях |

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

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

```cpp
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()` — поля независимы:

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

## Кадр

### PixelFormat

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

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

### ImageView

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

```cpp
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 * каналов`), а не «ноль байт в строке»: кадр камеры почти никогда не плотный — строки выравнивают, а вырезка наследует длину строки оригинала. Собирается на месте вызова без копирования:

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

### Image

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

```cpp
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)
};
```

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

```cpp
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` очищается — половина кадра от прошлой попытки хуже пустого.

```cpp
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, для журнала.

## Геометрия

```cpp
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` — четыре его угла точнее, чем прямоугольником: на конвейере символ снят под углом.

```cpp
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 здесь сама включается сеть-разведчик |

```cpp
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()` включён: для разрозненных снимков, где размер заранее не знаешь, эта плата оправдана.

### Все поля

| Поле | Умолчание | Смысл |
| --- | --- | --- |
| `maxCodes` | 1 | Сколько кодов искать: 1 — один, 0 — сколько найдётся, N — не больше N |
| `requireGs1` | false | Принимать только коды структуры GS1. Сошедшаяся коррекция Рида-Соломона сама по себе не доказывает верного чтения — проверка дополнительно смотрит на формат содержимого (AI 01, 14 цифр GTIN со сходящейся контрольной суммой, затем AI 21) |
| `forcedRotation` | -1 | Поворот символа, 0..3 — четверти по часовой; -1 — определять самому |
| `imageLimits` | 16384 по стороне, 100 000 000 пикселей | Наибольший кадр, который сканер берётся разбирать (`dmr::ImageLimits` из `dmr/Image.h`: `maxSide`, `maxPixels`; 0 — жёсткий потолок 65535 и 2^29). Кадр больше сразу получает `Status::ImageTooLarge`. Те же пределы передайте в `loadImage()` — там они сверяются с заголовком файла до выделения памяти. Защита, а не настройка качества |
| `budgetMs` | 0.0 | Бюджет времени на кадр, мс; 0 — без ограничения. Срок мягкий: проверка идёт между стадиями перебора, а не внутри них, поэтому время кадра может превысить бюджет на длительность идущей стадии |
| `timeoutMs` | 10000.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=…)`) срок действует и на декодирование |
| `rowParallel` | true | Делить строки ядер изображения между потоками пула, пока кадр идёт одним потоком. Снижает задержку кадра ценой процессорного времени — выключать, если на машине несколько сканеров или важнее пропускная способность, а не задержка |
| `maxSizeTries` | 1 | Сколько размеров символа пробовать, когда размеру верить нельзя; 1 — не перебирать |
| `warpScales` | пусто | Масштабы холста выпрямления для последнего прохода, пикселей на модуль; пусто — не перебирать; значения вне 1…32 пропускаются. Разбирается из строки вида `"7,8,10"` методом `setWarpScales()` |
| `maxCandidates` | 6 | Сколько кандидатов брать у детектора по L-паттерну за один проход |
| `thinShare` | 0.0 | Доля срока кадра, которую оставлять последней попытке — кадру с утоньшенным тёмным (растёкшаяся краска), когда срок короткий; 0 — не оставлять. Нужна вырезкам вокруг найденного символа (так её задаёт сама библиотека при поиске сетью); обычному кадру — не нужна |
| `readerCacheMb` | 64.0 | Предел памяти, МБ на кадр, под повторное использование работы; 0 — ничего не хранить. На ответ не влияет |
| `mcHintRun` | 5 | Сколько кадров подряд должны сойтись на одном размере символа, чтобы дальше он проверялся первым; 0 — не подсказывать |
| `maxPatternError` | 0.25 | Предел доли ошибок в служебных модулях (L-рамка, timing), при котором результат вообще рассматривается |
| `lpatRetryScale` | 0.8 | Повторный поиск по L-паттерну на точном масштабе, как вторая гипотеза; 0 — не повторять |
| `directSampling` | false | Брать яркости модулей прямо из исходника, минуя холст выпрямления |
| `useLPatternFinder` / `useTextureFinder` | true / true | Источники кандидатов; выключение нужно для сравнения детекторов на одном корпусе |
| `collectDetails` | false | Собирать разбор прочитанного и отказа в `ScanResult::details` (около 2 МБ на результат) |
| `netMode` | `NetMode::Auto` | Сеть-разведчик символов (с 1.2). `Auto` — включена, когда ищется больше одного кода (`maxCodes` ≠ 1); `On` — всегда; `Off` — никогда. Подробно — ниже, «Сеть-разведчик» |
| `threads` | 0 | Сколько потоков может занять один вызов `scan()`, считая вызывающий (с 1.2): 0 — все ядра, 1 — только вызывающий, N — не больше N. Ответ от него не зависит, только время. Подробно — ниже, «Потоки» |

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

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

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

```cpp
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`), сеть и вырезки. Ответ от него не зависит, только время.

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

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

## Диагностика

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

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

void setLogSink(LogSink sink);   // пустой — выключить
void setVerbose(bool on);        // по умолчанию выключена
bool isVerbose();                // включена И есть приёмник
std::ostream& dbg();             // поток выкладки: в приёмник, иначе «в никуда»
```

```cpp
dmr::setLogSink([](std::string_view line) { std::cerr << line; });
dmr::setVerbose(true);
```

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

```cpp
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 = {});
```

```cpp
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` в контейнере) — английский. Машиночитаемые поля и коды не переводятся.

```cpp
bool setMessageLanguage(std::string_view lang);   // "ru" или "en"; иначе false
std::string_view messageLanguage();               // "ru" или "en"
```

```cpp
dmr::setMessageLanguage("en");   // на весь процесс
```

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

```cpp
#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()` — про библиотеку, с которой слинковались. Разойтись они могут: библиотека ставится в префикс и живёт там дольше, чем помнит собиравший.

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

## Лицензия

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

```cpp
#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

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

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

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

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

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

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

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

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

```cpp
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()` выдаётся из личного кабинета после оформления тарифа в [каталоге](https://libscanner.com/).

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

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

Каждый процесс — отдельный экземпляр. Если программа запускает рабочие процессы через 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.

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

```cpp
#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); комментарии сокращены — полные в самом заголовке.

```cpp
/* ── версии ── */
#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`) — для быстрой проверки без своего кода: разовый снимок, папка, список путей, поток для внешнего сервиса, лицензия. Её ключи, вывод и коды возврата описаны в отдельной вкладке [«Командная строка»](https://libscanner.com/docs/datamatrix-gs1/1.2/cli.md).
