scan4llm/stage1.md

Техническое задание

Проект

Утилита является первым этапом конвейера офлайн-обработки документов.

Назначение утилиты — разрезание отсканированного изображения, содержащего несколько страниц документа, напечатанных на одном листе A4 с использованием функции Microsoft Word «Несколько страниц на листе».

На данном этапе OCR не выполняется.

---

Предпосылки

Предполагается, что:

• документ распечатан из Microsoft Word;
• использована функция «Несколько страниц на листе»;
• все страницы имеют одинаковый размер;
• страницы расположены в правильной прямоугольной сетке;
• изображение получено качественным сканером;
• поиск границ страниц не требуется.

Разрезание выполняется исключительно по геометрической сетке.

Использование OpenCV для поиска страниц, контуров или линий не требуется.

---

Важно!

Главный приоритет проекта — максимально сохранить качество исходного изображения для последующего OCR. Любые преобразования, способные ухудшить распознавание, должны выполняться только при наличии явного параметра командной строки или быть реализованы на последующих этапах конвейера.

---

Поддерживаемые форматы

Входные изображения:

• JPEG
• PNG
• TIFF

Формат выходных файлов должен совпадать с форматом входного файла.

Цветовое пространство сохраняется без изменений.

Не выполнять:

• перевод в оттенки серого;
• бинаризацию;
• изменение цветовой модели;
• сжатие с потерями сверх уже имеющегося.

---

Интерфейс командной строки

Обязательные параметры

--input <путь_к_файлу>

Путь к входному изображению.

--slice <строки:столбцы>

Размер сетки.

Поддерживаются любые положительные значения.

Примеры:

1:2
2:2
2:4
3:3
4:4

Практический максимум — 4×4.

---

Необязательные параметры

--output-dir <каталог>

Каталог сохранения результатов.

По умолчанию — текущий каталог.

---

--pre-rotate 90|180|270

Повернуть изображение перед разрезанием.

---

--border <пикселей>

Добавить белую рамку вокруг каждой страницы.

По умолчанию:

20

---

Разрезание

Изображение делится на равномерную прямоугольную сетку.

Не использовать:

• поиск страниц;
• поиск контуров;
• поиск линий;
• Hough Transform;
• распознавание структуры изображения;
• любые алгоритмы компьютерного зрения для определения координат страниц.

Координаты вычисляются исключительно на основании размеров изображения и параметра:

--slice

---

Порядок страниц

Порядок должен полностью соответствовать порядку печати Microsoft Word.

Пример для 2×2:

01 02
03 04

Пример для 2×4:

01 02
03 04
05 06
07 08

Используется порядок row-major (слева направо, сверху вниз).

---

Размеры частей

Если размеры изображения не делятся без остатка на количество строк или столбцов, остаток пикселей должен быть добавлен к последней строке и/или последнему столбцу.

Потеря пикселей недопустима.

---

Имена выходных файлов

Входной файл:

scan001.jpg

Результат:

scan001_01.jpg
scan001_02.jpg
scan001_03.jpg
...

Использовать двузначную нумерацию.

---

Постобработка

После разрезания для каждой страницы выполнить:

1. Добавление белой рамки (--border).
2. Сохранение результата.

Белая рамка необходима для повышения качества последующего OCR.

---

Архитектура

Обработка должна состоять из независимых этапов:

Загрузка изображения
        ↓
Опциональный поворот
        ↓
Разрезание на страницы
        ↓
Добавление белой рамки
        ↓
Сохранение результата

Каждый этап должен быть реализован отдельной функцией.

Это необходимо для последующего расширения конвейера.

---

Не входит в MVP

На данном этапе НЕ реализовывать:

• OCR;
• PaddleOCR;
• генерацию HTML;
• поддержку PDF;
• GUI;
• Docker;
• многопоточность;
• автоматическое определение сетки;
• поиск страниц;
• deskew;
• автоматическую обрезку полей;
• удаление шума;
• повышение контрастности;
• бинаризацию.

Все перечисленные возможности будут реализованы на следующих этапах проекта.

---

Требования к реализации

Использовать:

• Python 3.12+
• OpenCV
• NumPy

Для разрезания изображения использовать срезы массива NumPy.

OpenCV использовать только для:

• загрузки изображения;
• поворота;
• добавления белой рамки;
• сохранения результата.

Не использовать OpenCV для вычисления координат разрезания.

---

Требования к качеству кода

• Полная типизация (type hints).
• Отсутствие глобальных переменных.
• Отсутствие дублирования кода.
• Каждая функция должна выполнять одну логическую задачу.
• Проверка всех параметров командной строки.
• Понятные сообщения об ошибках.
• Ненулевой код завершения при ошибках.
• Соответствие PEP 8.

Код должен стать основой для последующих этапов конвейера подготовки документов к OCR.