ADR-SRV-005. Нормализация изображений (orthocover)

1. Контекст и постановка задачи

Оператор снимает форму ИК камерой рабочего места: кадр перекошен, с фоном и изгибом. Этап «Проверка файлов» показывает переключение «оригинал ↔ обработанное», а распознавание полей идёт по выровненному изображению. Значит нужен шаг нормализации: получить из фото чистое выровненное изображение «как со сканера».

Писать свой пайплайн (сегментация/выравнивание/dewarp) — отдельный ML-проект. Есть готовый внешний сервис orthocover, который это делает и попутно детектит штрихкоды. Нужно зафиксировать, как мы его подключаем, когда запускаем и где храним результат, не завязывая прикладной код на конкретный сервис.

2. Драйверы решения

1. Не строить свой ML — переиспользовать готовый сервис нормализации.
2. Изоляция — прикладной код не должен зависеть от конкретного сервиса (сменяемость).
3. Без фоновой инфраструктуры — очереди/воркеров пока нет; запуск должен работать «здесь и сейчас».
4. Предсказуемое хранение — обработанное лежит рядом с оригиналом, доступно по варианту.

3. Рассмотренные варианты

• A (выбран). Внешний orthocover по HTTP за абстракцией IImageNormalizer; ручной запуск; обработанное — в файловом хранилище, ссылка — на кадре.
• B. Свой пайплайн нормализации (onnx/opencv) в процессе бэка. Тяжело, отдельный проект, дублирует готовый сервис.
• C. Без нормализации, распознавать по оригиналу. Хуже качество, не соответствует этапу «Проверка файлов».

4. Решение

Выбран Вариант A.

4.1. Абстракция и клиент

• IImageNormalizer (в Ban.Icd.Infrastructure, домен-нейтральна) — вход: байты изображения + тип страницы; выход: обработанные изображения + метаданные (флаг качества/режим, штрихкоды).
• OrthocoverImageNormalizer — реализация поверх типизированного HttpClient.

4.2. Контракт сервиса (orthocover)

• POST {Orthocover:Url}/normalize — multipart/form-data: image + type + enhance; заголовок X-API-Key (если сервис требует).
• Ответ multipart/mixed: часть meta (JSON: results[] с mode/flag/side/barcodes[]) + по PNG-части на каждый результат.

4.3. Тип страницы из роли кадра

Роль штрихкода → barcode (только коды, без картинки); остальные роли → text (кроп листа + dewarp).

4.4. Хранение результата

Обработанный PNG — в файловом хранилище под ключом <номер пакета>/<NN>_<роль>_norm.png (схема ключей — ADR-002). Кадр получает ссылку на обработанное, флаг качества и время обработки. Содержимое отдаётся тем же endpoint выдачи кадра с параметром variant=normalized.

4.5. Запуск — ручной

Кнопка «повторить обработку» на предобработке: пер-кадровый вызов POST /api/InputPacket/{id}/frames/{order}/normalize (есть и пакетный .../normalize). Обработка синхронная (≈2–5 с/кадр). Сбой по кадру не валит остальные — фиксируется в сводке.

4.6. Конфигурация

Orthocover:Url — в appsettings (не секрет). Orthocover:ApiKey — секрет: локально в appsettings.Local.json (вне git) или переменной окружения; на стендах — через devops-генератор конфигов (ADR-SRV-004). Пустой Url = интеграция не сконфигурирована (клиент вернёт понятную ошибку).

4.7. Что не делаем сейчас

• Не запускаем нормализацию автоматически при сдаче пакета (нужна очередь — отложено).
• Не сохраняем штрихкоды/атрибуты (извлечение идентификаторов — отдельный этап).
• Не обрабатываем «разворот» (spread) — не встречается в ИК.

5. Положительные следствия

• Готовое качество нормализации без своего ML.
• Прикладной код зависит от IImageNormalizer, а не от orthocover — сервис сменяем.
• Обработанное предсказуемо лежит рядом с оригиналом и доступно по варианту.

6. Отрицательные следствия и компромиссы

• Синхронный ручной запуск блокирует запрос на ≈2–5 с/кадр — до введения очереди это осознанный компромисс.
• Внешняя зависимость: недоступность сервиса → кадр не обработается (ошибка фиксируется, не падение).

7. Проверка

• Живой прогон против стенда: сдача пакета → запуск обработки → обработанный PNG отдаётся по variant=normalized; у кадра выставлен признак «обработан».
• При недоступном сервисе запрос не падает — в сводке по кадру фиксируется ошибка.

8. Открытые вопросы / отложено

• Автозапуск при сдаче — вместе с фоновой очередью обработки.
• Штрихкоды/идентификаторы — сохранение и авто-подстановка на этапе полей/экземпляров.
• Флаги качества (low_quality → пересъёмка) — явный показ и действия оператору.
• Пер-пакетный прогресс — при многокадровых пакетах.

9. Связанные артефакты

• Endpoint NormalizePacket — контракт запуска обработки.
• Handler NormalizePacket — сценарий обработки.
• ImageFrameSpec — поля обработанного изображения на кадре.
• ADR-002 «Идентичность пакета и имена файлов» — ключи файлов (в т.ч. обработанного).
• ADR_SRV_004_AppConfigAndCors — конфигурация/секреты по средам.