libscanner-dmr 1.0.0__py3-none-win_amd64.whl

dmr/__init__.py

@@ -0,0 +1,68 @@
+"""dmr — чтение кодов DataMatrix (ECC200, ГОСТ Р ИСО/МЭК 16022) из Python.
+
+Обёртка на ctypes поверх плоского C ABI библиотеки (dmr_c, dmr/dmr_c.h,
+FLAT_C_ABI_PLAN.md). Требует собранной и доступной библиотеки dmr_c
+(dmr_c.dll / libdmr_c.so) — см. README.md рядом с этим пакетом.
+
+Быстрый старт::
+
+    import dmr
+
+    img = dmr.Image("кадр.jpg", dmr.LoadAs.GRAY)
+    scanner = dmr.Scanner()                       # поток кадров, умолчание
+    result = scanner.scan(img.view())
+    if result.ok:
+        print(result.text.decode("utf-8"))
+
+Кадр из чужого буфера — без копирования, видом на него (буфер обязан быть
+жив на момент scan())::
+
+    view = dmr.ImageView(buf, width, height, stride, dmr.PixelFormat.BGR8)
+    result = scanner.scan(view)
+
+Лицензия и диагностика — отдельными подмодулями, ``dmr.license`` и
+``dmr.diagnostics``, тем же приёмом, что namespace ``dmr::license`` в C++ API.
+"""
+
+from . import diagnostics, license  # noqa: F401  (публичные подмодули)
+from ._ffi import DmrError
+from .image import Image, ImageView, LoadAs, LoadStatus, PixelFormat, channels_of
+from .scanner import Box, Code, Point, ScanResult, Scanner, Status, scan
+from .settings import Settings
+
+__all__ = [
+    "DmrError",
+    "Image",
+    "ImageView",
+    "LoadAs",
+    "LoadStatus",
+    "PixelFormat",
+    "channels_of",
+    "Box",
+    "Code",
+    "Point",
+    "ScanResult",
+    "Scanner",
+    "Status",
+    "scan",
+    "Settings",
+    "license",
+    "diagnostics",
+    "version",
+    "abi_version",
+]
+
+
+def version() -> str:
+    """Версия СОБРАННОЙ библиотеки dmr_c — как dmr::version() в C++ API."""
+    from . import _ffi
+
+    return _ffi.copy_version(_ffi.lib.dmr_version)
+
+
+def abi_version() -> str:
+    """Версия самой границы C ABI (DMR_C_ABI_VERSION_MAJOR.MINOR) — отдельно
+    от версии алгоритма (см. version()); FLAT_C_ABI_PLAN.md, §5."""
+    from . import _ffi
+
+    return _ffi.copy_version(_ffi.lib.dmr_c_abi_version)

dmr/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m dmr ...`` — то же, что команда ``dmr`` (см. _cli.py)."""
+
+import sys
+
+from ._cli import main
+
+sys.exit(main())

dmr/_cli.py

@@ -0,0 +1,50 @@
+"""Команда ``dmr`` и ``python -m dmr`` — собранная утилита-оболочка из колеса.
+
+Колесо поставки (tools/build_wheel.py) кладёт утилиту ``dmr`` (``dmr.exe`` на
+Windows, без DLL MinGW рядом) в ``dmr/_lib/`` — рядом с библиотекой dmr_c, — а
+``pip install`` делает из этой функции команду ``dmr`` в PATH окружения. Всё,
+что умеет утилита, — как у неё: ``dmr снимок.png``, ``dmr --license status``,
+справка — ``dmr --help``; аргументы и код возврата передаются как есть.
+
+Файл ключа ``license.key`` для неё и для библиотеки — один, в ``dmr/_lib/``:
+утилита ищет его рядом с собой, библиотека — рядом с dmr_c.
+"""
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def executable() -> Path:
+    name = "dmr.exe" if sys.platform == "win32" else "dmr"
+    return Path(__file__).resolve().parent / "_lib" / name
+
+
+def main() -> int:
+    exe = executable()
+    if not exe.is_file():
+        sys.stderr.write(
+            f"утилиты dmr нет в пакете ({exe}): она приходит с колесом поставки "
+            "(раздел «Загрузки» личного кабинета); пакет из исходников её не содержит.\n"
+        )
+        return 2
+    if sys.platform != "win32" and not os.access(exe, os.X_OK):
+        # Колесо, где бит исполнения не дошёл до установки (pip берёт его из
+        # режима файла в zip), — чиним на месте, если каталог наш.
+        try:
+            exe.chmod(exe.stat().st_mode | 0o111)
+        except OSError:
+            sys.stderr.write(f"утилита {exe} не исполняемая: chmod +x {exe}\n")
+            return 2
+    args = [str(exe), *sys.argv[1:]]
+    if sys.platform == "win32":
+        # На Windows exec заменяет процесс не так, как в POSIX (консоль и код
+        # возврата теряются) — запускаем дочерним и ждём.
+        return subprocess.call(args)
+    os.execv(args[0], args)
+    return 127  # недостижимо: execv не возвращается
+
+
+if __name__ == "__main__":
+    sys.exit(main())

dmr/_ffi.py

@@ -0,0 +1,261 @@
+"""Сырая граница ctypes поверх dmr_c (include/dmr/dmr_c.h).
+
+Не публичный модуль пакета — сюда не ходят снаружи. Здесь только два дела:
+найти и загрузить dmr_c.dll/libdmr_c.so и объявить сигнатуры (argtypes/
+restype) для каждой функции границы, ничего сверх. Пайтонический слой —
+в остальных модулях пакета (settings.py, image.py, scanner.py, license.py).
+
+ВАЖНОЕ О ТИПАХ, а не только формальность:
+
+- Строки, которые библиотека ВОЗВРАЩАЕТ через dmr_free_string (лицензия),
+  объявлены restype=c_void_p, а не c_char_p. Если объявить их c_char_p,
+  ctypes сам превратит указатель в bytes ПРИ ВЫЗОВЕ и вернёт копию —
+  а исходный указатель, без которого dmr_free_string нечего освобождать,
+  потеряется навсегда. Освобождать нечем — течёт при каждом вызове.
+- dmr_scan_result_code_text — та же ловушка и вдобавок опасная: c_char_p
+  читает строку до первого нулевого байта, а GS1-код может НЕ иметь такого
+  байта там, где заканчивается настоящий текст (0x1D — GS, не 0x00), то
+  есть строка легко читалась бы длиннее или короче настоящей. Отсюда —
+  restype=c_void_p и обязательное чтение через dmr_scan_result_code_text_len,
+  а не через сам указатель.
+- Пути (dmr_load_image и подобные) — bytes, не str: ctypes НЕ кодирует str
+  в bytes для c_char_p сам, и это то самое свойство, которое нужно здесь —
+  кодировка пути системная, не UTF-8 (см. paths.py), и неявное авто-
+  кодирование ctypes её бы просто подменило.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import sys
+from pathlib import Path
+
+
+class DmrError(RuntimeError):
+    """Внутренняя ошибка самой границы: перехваченное на стороне C++
+    исключение (NULL/DMR_STATUS_INTERNAL_ERROR — FLAT_C_ABI_PLAN.md, §4).
+
+    Не путать с обычным отказом операции (например, неверный лицензионный
+    ключ) — тот приходит как {"ok": false, "error": ...} в JSON и исключения
+    не поднимает: это ожидаемый исход, а не поломка границы.
+    """
+
+
+DMR_MAX_WARP_SCALES = 16
+
+
+class DmrImageView(ctypes.Structure):
+    _fields_ = [
+        ("data", ctypes.c_void_p),
+        ("width", ctypes.c_int),
+        ("height", ctypes.c_int),
+        ("stride", ctypes.c_int),
+        ("format", ctypes.c_int),
+    ]
+
+
+class DmrSettings(ctypes.Structure):
+    # ABI 2.0: первым полем — struct_size, sizeof этой структуры у нас
+    # (dmr_c.h). Выставлять его до любого вызова, принимающего настройки, —
+    # settings.py делает это сам (new_settings_struct).
+    _fields_ = [
+        ("struct_size", ctypes.c_uint32),
+        ("max_codes", ctypes.c_int),
+        ("require_gs1", ctypes.c_int),
+        ("forced_rotation", ctypes.c_int),
+        ("budget_ms", ctypes.c_double),
+        ("row_parallel", ctypes.c_int),
+        ("max_size_tries", ctypes.c_int),
+        ("warp_scales", ctypes.c_int * DMR_MAX_WARP_SCALES),
+        ("warp_scales_count", ctypes.c_int),
+        ("max_candidates", ctypes.c_int),
+        ("reader_cache_mb", ctypes.c_double),
+        ("mc_hint_run", ctypes.c_int),
+        ("max_pattern_error", ctypes.c_double),
+        ("lpat_retry_scale", ctypes.c_double),
+        ("direct_sampling", ctypes.c_int),
+        ("use_lpattern_finder", ctypes.c_int),
+        ("use_texture_finder", ctypes.c_int),
+        ("collect_details", ctypes.c_int),
+        # ABI 1.1 — предел размера кадра (dmr::Settings::imageLimits).
+        ("max_image_side", ctypes.c_int),
+        ("max_image_pixels", ctypes.c_int64),
+        # ABI 2.0 — предохранитель (dmr::Settings::timeoutMs).
+        ("timeout_ms", ctypes.c_double),
+    ]
+
+
+def new_settings_struct(**fields) -> DmrSettings:
+    """DmrSettings с выставленным struct_size — иначе библиотека отвергает
+    структуру (пресет вернёт 0, dmr_scanner_create — NULL)."""
+    return DmrSettings(struct_size=ctypes.sizeof(DmrSettings), **fields)
+
+
+# void (*)(const char* line, size_t len, void* user) — line НЕ гарантированно
+# завершена нулём как C-строка "до len", поэтому тип параметра — c_void_p, а
+# не c_char_p: тем, кто ставит приёмник (log_sink.py), передаётся сырой
+# указатель, а не преждевременно и неверно декодированная строка.
+DmrLogSinkFunc = ctypes.CFUNCTYPE(None, ctypes.c_void_p, ctypes.c_size_t, ctypes.c_void_p)
+
+
+def _candidate_names() -> list[str]:
+    if sys.platform == "win32":
+        return ["dmr_c.dll"]
+    if sys.platform == "darwin":
+        return ["libdmr_c.dylib"]
+    return ["libdmr_c.so"]
+
+
+def _load_library() -> ctypes.CDLL:
+    """Библиотека грузится по ПОЛНОМУ пути, а не по имени.
+
+    Поиск по имени (PATH, текущий каталог, пути линковщика) отдаёт выбор
+    файла окружению процесса: подложенная в такой каталог dmr_c.dll
+    исполнялась бы с правами приложения (аудит 2026-10-01, P-17). Поэтому:
+
+    1. dmr/_lib/ внутри пакета — так её кладёт колесо поставки
+       (tools/build_wheel.py). Если она там есть, берётся ТОЛЬКО она:
+       переменная окружения установленный пакет не перенаправляет;
+    2. файл рядом с модулями пакета (dmr/dmr_c.dll) — положили вручную;
+    3. DMR_C_LIBRARY — полный путь к файлу; для разработки (пакет из
+       исходников, где _lib нет) и своей сборки. Относительный путь не
+       принимается: он зависел бы от текущего каталога.
+
+    Системного поиска нет.
+    """
+    names = _candidate_names()
+    here = Path(__file__).resolve().parent
+    for d in (here / "_lib", here):
+        for name in names:
+            p = d / name
+            if p.is_file():
+                return ctypes.CDLL(str(p))
+
+    env = os.environ.get("DMR_C_LIBRARY")
+    if env:
+        p = Path(env)
+        if not p.is_absolute():
+            raise OSError(f"DMR_C_LIBRARY должен быть полным путём к файлу, получено: {env!r}")
+        return ctypes.CDLL(str(p))
+
+    raise OSError(
+        "не найдена библиотека dmr_c (искали: " + ", ".join(names) + " в "
+        + str(here / "_lib") + " и " + str(here) + "). "
+        "Поставьте колесо из поставки (библиотека внутри него) или соберите: "
+        "meson setup build -Dcabi=true && meson compile -C build, и укажите "
+        "полный путь переменной DMR_C_LIBRARY."
+    )
+
+
+lib = _load_library()
+
+
+def _proto(name: str, argtypes: list, restype) -> None:
+    fn = getattr(lib, name)
+    fn.argtypes = argtypes
+    fn.restype = restype
+
+
+_c_void_p = ctypes.c_void_p
+_c_char_p = ctypes.c_char_p
+_c_int = ctypes.c_int
+_c_size_t = ctypes.c_size_t
+_c_double = ctypes.c_double
+_c_float = ctypes.c_float
+_p_settings = ctypes.POINTER(DmrSettings)
+_p_view = ctypes.POINTER(DmrImageView)
+_p_int = ctypes.POINTER(_c_int)
+_p_float = ctypes.POINTER(_c_float)
+_p_voidp = ctypes.POINTER(_c_void_p)
+
+_proto("dmr_c_abi_version", [_c_char_p, _c_size_t], _c_size_t)
+
+# Структуры выше описаны по заголовку ABI 2.x. Библиотека другой старшей
+# версии раскладывает их иначе (1.x — без struct_size): работать с ней значило
+# бы читать и писать поля вкривь, поэтому — отказ при загрузке, а не порча
+# памяти при первом вызове.
+ABI_MAJOR = 2
+
+
+def _check_abi() -> None:
+    buf = ctypes.create_string_buffer(32)
+    lib.dmr_c_abi_version(buf, len(buf))
+    got = buf.value.decode("ascii", errors="replace")
+    major = got.split(".", 1)[0]
+    if major != str(ABI_MAJOR):
+        raise OSError(
+            f"библиотека dmr_c с ABI {got!r}, а пакет dmr написан для ABI {ABI_MAJOR}.x: "
+            "поставьте библиотеку и пакет одной поставки")
+
+
+_check_abi()
+
+_proto("dmr_version", [_c_char_p, _c_size_t], _c_size_t)
+
+_proto("dmr_load_image", [_c_char_p, _c_int, _p_voidp], _c_int)
+_proto("dmr_load_image_ex", [_c_char_p, _c_int, _p_settings, _p_voidp], _c_int)
+_proto("dmr_image_view", [_c_void_p], DmrImageView)
+_proto("dmr_image_free", [_c_void_p], None)
+
+_proto("dmr_settings_stream", [_p_settings], _c_int)
+_proto("dmr_settings_single", [_p_settings], _c_int)
+_proto("dmr_settings_multi", [_p_settings, _c_int], _c_int)
+
+_proto("dmr_scanner_create", [_p_settings], _c_void_p)
+_proto("dmr_scanner_destroy", [_c_void_p], None)
+_proto("dmr_scanner_module_count_hint", [_c_void_p], _c_int)
+_proto("dmr_scanner_reset_stream", [_c_void_p], None)
+
+_proto("dmr_scanner_scan", [_c_void_p, _p_view, _c_int], _c_void_p)
+_proto("dmr_scan_result_free", [_c_void_p], None)
+_proto("dmr_scan_result_status", [_c_void_p], _c_int)
+_proto("dmr_scan_result_timed_out", [_c_void_p], _c_int)
+_proto("dmr_scan_result_elapsed_ms", [_c_void_p], _c_double)
+_proto("dmr_scan_result_code_count", [_c_void_p], _c_int)
+_proto("dmr_scan_result_code_text", [_c_void_p, _c_int], _c_void_p)
+_proto("dmr_scan_result_code_text_len", [_c_void_p, _c_int], _c_size_t)
+_proto("dmr_scan_result_code_box", [_c_void_p, _c_int, _p_int, _p_int, _p_int, _p_int], None)
+_proto("dmr_scan_result_code_corners", [_c_void_p, _c_int, _p_float], None)
+_proto("dmr_scan_result_code_module_count", [_c_void_p, _c_int], _c_int)
+
+_proto("dmr_set_log_sink", [DmrLogSinkFunc, _c_void_p], None)
+_proto("dmr_set_verbose", [_c_int], None)
+_proto("dmr_is_verbose", [], _c_int)
+
+_proto("dmr_license_configure", [_c_char_p, _c_char_p, _c_int, _c_int], None)
+_proto("dmr_license_status_json", [], _c_void_p)
+_proto("dmr_license_activate_json", [_c_char_p], _c_void_p)
+_proto("dmr_license_refresh_json", [], _c_void_p)
+_proto("dmr_license_deactivate_json", [_c_char_p], _c_void_p)
+_proto("dmr_license_deactivate_to_file_json", [_c_char_p, _c_char_p], _c_void_p)
+_proto("dmr_license_write_activation_request_json", [_c_char_p], _c_void_p)
+_proto("dmr_license_import_license_file_json", [_c_char_p], _c_void_p)
+_proto("dmr_license_fingerprint_json", [], _c_void_p)
+_proto("dmr_free_string", [_c_void_p], None)
+
+
+def take_string(ptr: int | None) -> str:
+    """Забрать строку, отданную библиотекой через dmr_free_string
+    (лицензия — там любой непустой результат такой), и освободить её.
+    NULL — DmrError: это внутренняя ошибка границы, не обычный отказ
+    операции (тот приходит валидным JSON с "ok": false)."""
+    if not ptr:
+        raise DmrError("граница вернула NULL вместо строки (внутренняя ошибка)")
+    try:
+        return ctypes.string_at(ptr).decode("utf-8")
+    finally:
+        lib.dmr_free_string(ptr)
+
+
+def copy_version(cfunc) -> str:
+    """snprintf-контракт dmr_version/dmr_c_abi_version: буфер угадан заведомо
+    большим, но если когда-нибудь не хватит — перевызов размером ровно в
+    то, что попросила сама библиотека (её же возврат), а не догадка."""
+    size = 64
+    while True:
+        buf = ctypes.create_string_buffer(size)
+        need = cfunc(buf, size)
+        if need < size:
+            return buf.value.decode("utf-8", errors="replace")
+        size = need + 1

dmr/diagnostics.py

@@ -0,0 +1,49 @@
+"""Поток отладочных сообщений — dmr_set_log_sink/dmr_set_verbose/dmr_is_verbose
+(dmr/dmr_c.h), соответствует dmr/Diagnostics.h в C++ API.
+
+По умолчанию приёмника нет, и это не "есть, но молчит": без него строки не
+собираются даже внутри библиотеки (isVerbose() ложно) — писать в чужой
+поток библиотека не вправе, она не знает, кто его читает.
+"""
+
+from __future__ import annotations
+
+import ctypes
+from typing import Callable, Optional
+
+from . import _ffi
+
+# CFUNCTYPE-обёртка должна жить не короче, чем она зарегистрирована в
+# библиотеке — ctypes не держит на неё ссылку сам, и без этой переменной
+# сборщик мусора Python освободил бы её первым, а библиотека звала бы уже
+# висячий указатель.
+_current_callback: Optional[ctypes.CFUNCTYPE] = None
+
+
+def set_log_sink(sink: Optional[Callable[[bytes], None]]) -> None:
+    """Поставить приёмник строк лога; None — выключить.
+
+    sink получает СЫРЫЕ байты одной строки (с переводом строки на конце) —
+    не str: сообщения из библиотеки в UTF-8, но решать, как их декодировать
+    (или не декодировать вовсе, если просто пишете в файл), — дело
+    вызывающего.
+    """
+    global _current_callback
+    if sink is None:
+        _ffi.lib.dmr_set_log_sink(None, None)
+        _current_callback = None
+        return
+
+    def _trampoline(line_ptr, length, _user):
+        sink(ctypes.string_at(line_ptr, length))
+
+    _current_callback = _ffi.DmrLogSinkFunc(_trampoline)
+    _ffi.lib.dmr_set_log_sink(_current_callback, None)
+
+
+def set_verbose(on: bool) -> None:
+    _ffi.lib.dmr_set_verbose(int(bool(on)))
+
+
+def is_verbose() -> bool:
+    return bool(_ffi.lib.dmr_is_verbose())

dmr/image.py

@@ -0,0 +1,227 @@
+"""Кадр: вид на чужой буфер (ImageView) и владеющий кадр, прочитанный с диска
+(Image). Соответствует dmr/Image.h в C++ API и §2.1/§2.6 FLAT_C_ABI_PLAN.md.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import enum
+import weakref
+from pathlib import Path
+from typing import Optional, Union
+
+from . import _ffi
+from .paths import encode_path
+
+
+class PixelFormat(enum.IntEnum):
+    """Укладка байт пикселя. Сканер работает с яркостью и переводит в неё
+    цветной кадр сам — если камера монохромная, отдавайте GRAY8, а не
+    размноженный в три канала полутон: ответ тот же, но дороже."""
+
+    GRAY8 = 0
+    BGR8 = 1
+    RGB8 = 2
+    BGRA8 = 3
+    RGBA8 = 4
+
+
+_CHANNELS = {
+    PixelFormat.GRAY8: 1,
+    PixelFormat.BGR8: 3,
+    PixelFormat.RGB8: 3,
+    PixelFormat.BGRA8: 4,
+    PixelFormat.RGBA8: 4,
+}
+
+
+class LoadAs(enum.IntEnum):
+    COLOR = 0
+    GRAY = 1
+
+
+class LoadStatus(enum.IntEnum):
+    OK = 0
+    NOT_FOUND = 1
+    UNREADABLE = 2
+    TOO_LARGE = 3
+    TIMED_OUT = 4          # декодирование не уложилось в срок (budget_ms/timeout_ms)
+    INVALID_ARGUMENT = 5   # настройки отвергнуты границей (struct_size)
+
+
+def channels_of(fmt: PixelFormat) -> int:
+    return _CHANNELS[PixelFormat(fmt)]
+
+
+def _required_bytes(width: int, height: int, stride: int, fmt: PixelFormat) -> int:
+    """Сколько байт прочитает сканер: (height-1) строк по stride и последняя
+    строка по width*каналов. Ровно столько, не больше, — последняя строка
+    вырезки из большего кадра не обязана иметь хвост до stride."""
+    if width <= 0 or height <= 0:
+        return 0
+    row = width * channels_of(fmt)
+    step = stride if stride > 0 else row
+    return (height - 1) * step + row
+
+
+_INT_MAX = 2**31 - 1
+
+
+def _address_of(buf) -> tuple[int, object]:
+    """Адрес начала буфера без копирования — для писабельных буферов
+    (bytearray, numpy-массив, mmap и подобное через buffer-протокол).
+    Для НЕПИСАБЕЛЬНЫХ буферов (bytes, read-only memoryview) ctypes не
+    может получить писабельный вид без копии — тогда копия делается ОДИН
+    раз здесь, явно, а не молча где-то внутри библиотеки. Возвращает и
+    объект, который нужно живым держать не короче самого ImageView — тот
+    же буфер, что описан в dmr::ImageView (C++ API): библиотека кадр не
+    копирует и не переживает, поэтому переживать его обязан вызывающий.
+
+    Держится сам ctypes-массив, а не буфер (аудит 2026-10-02, R-13):
+    from_buffer держит ЭКСПОРТ буфера, и пока он жив, bytearray нельзя
+    растянуть или укоротить (BufferError), а mmap — закрыть. Ссылка на сам
+    bytearray от этого не спасала: после ba.extend(...) данные переезжали,
+    адрес в виде указывал в освобождённую память, и scan() читал её."""
+    # Длина — в БАЙТАХ: len() у numpy-массива 480x640 — 480, а не 307200.
+    nbytes = memoryview(buf).nbytes
+    if nbytes == 0:
+        return 0, buf
+    try:
+        arr = (ctypes.c_uint8 * nbytes).from_buffer(buf)
+        return ctypes.addressof(arr), arr
+    except TypeError:
+        copy = bytearray(memoryview(buf).tobytes())
+        arr = (ctypes.c_uint8 * len(copy)).from_buffer(copy)
+        return ctypes.addressof(arr), arr
+
+
+class ImageView:
+    """Вид на ЧУЖОЙ буфер — как dmr::ImageView в C++ API. Буфер, на который
+    смотрит view, обязан быть жив всё время вызова Scanner.scan(); сам
+    ImageView держит на него ссылку ради этого же (keepalive), но не копирует
+    его данные."""
+
+    __slots__ = ("_struct", "_keepalive", "__weakref__")
+
+    def __init__(self, buf, width: int, height: int, stride: int, format: PixelFormat):
+        # Проверка ДО того, как адрес уйдёт в библиотеку: сканер читает
+        # (height-1)*stride + width*каналов байт, и буфер короче — чтение за
+        # его концом (аудит 2026-10-01, P-12). Размеры — в пределах int поля
+        # C-структуры: ctypes молча обрезал бы старшие разряды.
+        fmt = PixelFormat(format)
+        width, height, stride = int(width), int(height), int(stride)
+        for name, v in (("width", width), ("height", height), ("stride", stride)):
+            if not 0 <= v <= _INT_MAX:
+                raise ValueError(f"{name}: {v} вне диапазона [0, {_INT_MAX}]")
+        if stride and stride < width * channels_of(fmt):
+            raise ValueError(
+                f"stride {stride} меньше width*каналов = {width * channels_of(fmt)}")
+        need = _required_bytes(width, height, stride, fmt)
+        have = memoryview(buf).nbytes
+        if have < need:
+            raise ValueError(
+                f"буфер {have} байт короче кадра {width}x{height}, stride {stride}, "
+                f"{fmt.name}: нужно не меньше {need}")
+        address, keepalive = _address_of(buf)
+        self._keepalive = keepalive
+        self._struct = _ffi.DmrImageView(
+            ctypes.c_void_p(address), width, height, stride, int(fmt)
+        )
+
+    @classmethod
+    def _from_struct(cls, struct: "_ffi.DmrImageView", keepalive: object) -> "ImageView":
+        # Для Image.view(): структура уже готова (dmr_image_view() отдал её
+        # по значению), пересобирать её из адреса заново незачем.
+        self = cls.__new__(cls)
+        self._struct = struct
+        self._keepalive = keepalive
+        return self
+
+    @property
+    def width(self) -> int:
+        return self._struct.width
+
+    @property
+    def height(self) -> int:
+        return self._struct.height
+
+    @property
+    def stride(self) -> int:
+        return self._struct.stride
+
+    @property
+    def format(self) -> PixelFormat:
+        return PixelFormat(self._struct.format)
+
+    def __repr__(self) -> str:
+        return (
+            f"ImageView(width={self.width}, height={self.height}, "
+            f"stride={self.stride}, format={self.format.name})"
+        )
+
+
+class Image:
+    """Кадр, прочитанный с диска, — библиотека владеет буфером сама
+    (dmr_image_t). Освобождается при close()/выходе из `with`/сборке мусора;
+    явный close() надёжнее — __del__ не гарантирован по времени."""
+
+    def __init__(self, path: Union[str, "Path", bytes], as_: LoadAs = LoadAs.GRAY,
+                 settings=None):
+        """settings — dmr.Settings: берётся предел размера кадра
+        (max_image_side, max_image_pixels) и срок (budget_ms, timeout_ms).
+        None — умолчания библиотеки (в том числе timeout_ms 10 с). Кадр
+        больше предела не декодируется: status == LoadStatus.TOO_LARGE;
+        декодирование дольше срока бросается: LoadStatus.TIMED_OUT."""
+        out = ctypes.c_void_p()
+        c_settings = settings.to_struct() if settings is not None else None
+        status = _ffi.lib.dmr_load_image_ex(
+            encode_path(path), int(as_),
+            ctypes.byref(c_settings) if c_settings is not None else None,
+            ctypes.byref(out))
+        self._ptr: Optional[ctypes.c_void_p] = out if out else None
+        self._views = weakref.WeakSet()
+        self.status = LoadStatus(status)
+        if self.status != LoadStatus.OK:
+            # *out гарантированно NULL при отказе (dmr_load_image, §2.6) —
+            # но проверка на всякий случай ничего не стоит и не лжёт молча.
+            self._ptr = None
+
+    def __bool__(self) -> bool:
+        return self._ptr is not None
+
+    def view(self) -> ImageView:
+        if self._ptr is None:
+            raise ValueError("Image не загружен (проверьте .status перед .view())")
+        struct = _ffi.lib.dmr_image_view(self._ptr)
+        # keepalive — сам Image: буфер живёт в dmr_image_t, а не в Python,
+        # и должен пережить любой scan() через этот view.
+        view = ImageView._from_struct(struct, self)
+        self._views.add(view)
+        return view
+
+    def close(self) -> None:
+        """Освободить кадр. Пока жив хоть один ImageView от view(), —
+        RuntimeError: вид указывает в эту память, и scan() по нему после
+        освобождения читал бы освобождённую память (аудит 2026-10-01, P-12).
+        Удалите виды (del view) и закройте снова."""
+        if self._ptr is not None:
+            if len(self._views):
+                raise RuntimeError(
+                    "Image.close(): жив ImageView этого кадра — освободить нельзя, "
+                    "сначала удалите вид (del view)")
+            _ffi.lib.dmr_image_free(self._ptr)
+            self._ptr = None
+
+    def __enter__(self) -> "Image":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        # Сюда доходит только объект без ссылок, а вид держит ссылку на свой
+        # Image — значит живых видов уже нет. Исключение из __del__ всё
+        # равно гасится, поэтому освобождаем без проверки.
+        if getattr(self, "_ptr", None) is not None:
+            _ffi.lib.dmr_image_free(self._ptr)
+            self._ptr = None