initial release with base split functionality

.ai/AGENTS.md

@@ -0,0 +1,23 @@
+# Coding rules
+
+Python 3.12
+
+PEP8
+
+Type hints required
+
+ruff
+
+pytest
+
+Никаких глобальных переменных.
+
+CLI через Typer.
+
+OpenCV.
+
+Не использовать магические числа.
+
+Каждая функция менее 40 строк.
+
+Комментарии только если они действительно объясняют алгоритм.

.ai/ARCHITECTURE.md

@@ -0,0 +1,24 @@
+src/
+
+split/
+    разделение изображения
+
+preprocess/
+    deskew
+    crop
+    denoise
+
+ocr/
+    PaddleOCR
+
+html/
+    генерация HTML
+
+cli.py
+
+Этапы:
+1. Input
+2. Split
+3. Preprocess
+4. OCR
+5. HTML

.ai/README.md

@@ -0,0 +1,40 @@
+# Offline Document Pipeline
+
+Назначение проекта
+
+Преобразование больших технических документов,
+полученных после печати и сканирования,
+в структурированный HTML без использования облачных сервисов.
+
+Поддерживается полностью offline работа.
+
+Pipeline
+
+JPEG/TIFF/PDF
+
+↓
+
+Split pages
+
+↓
+
+Deskew
+
+↓
+
+Crop
+
+↓
+
+PaddleOCR
+
+↓
+
+HTML
+
+Вне scope проекта
+
+- LLM
+- RAG
+- поиск
+- анализ документов

.ai/REQUIREMENTS.md

@@ -0,0 +1,55 @@
+# Functional requirements
+
+Проект работает полностью offline.
+
+Linux only.
+
+Python 3.12+
+
+Первый этап проекта
+
+Разделение большого JPEG/TIFF
+на несколько страниц.
+
+Параметры
+
+--rows
+
+--cols
+
+Например
+
+2x2
+
+2x4
+
+3x3
+
+4x4
+
+Страницы сохраняются
+в порядке чтения.
+
+Поддерживаемые входные форматы
+
+JPEG
+
+PNG
+
+TIFF
+
+PDF (позже)
+
+Следующие этапы
+
+Deskew
+
+Crop
+
+PaddleOCR
+
+HTML generation
+
+Никаких GUI.
+
+Только CLI.

.ai/TASKS.md

@@ -0,0 +1,21 @@
+# MVP
+
+[x] Создать структуру проекта
+
+[ ] CLI
+
+[ ] Разрезание изображения
+
+[ ] Автоматические тесты
+
+[ ] Deskew
+
+[ ] Crop
+
+[ ] PaddleOCR
+
+[ ] HTML
+
+[ ] Docker
+
+[ ] Release 0.1

.gitignore

@@ -0,0 +1,18 @@
+# Виртуальное окружение
+.venv/
+venv/
+env/
+
+# Кэш и байт-код Python
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Настройки среды и секреты
+.env
+
+# Системные файлы и редакторы
+.idea/
+.vscode/
+.DS_Store
+

src/cli.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from src.split.slicer import (
+    DEFAULT_BORDER_PX,
+    VALID_ROTATIONS,
+    parse_slice,
+    process_image,
+)
+
+app = typer.Typer(add_completion=False)
+
+
+@app.command()
+def slice_pages(
+    input: Annotated[
+        Path,
+        typer.Option(
+            "--input",
+            "-i",
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            readable=True,
+            help="Путь к входному изображению (JPEG, PNG, TIFF)",
+        ),
+    ],
+    slice: Annotated[
+        str,
+        typer.Option(
+            "--slice",
+            "-s",
+            help="Размер сетки в формате <колонки>:<строки>, например 3:2",
+        ),
+    ],
+    output_dir: Annotated[
+        Path,
+        typer.Option(
+            "--output-dir",
+            "-o",
+            file_okay=False,
+            dir_okay=True,
+            writable=True,
+            help="Каталог для сохранения результатов (по умолчанию — текущий)",
+        ),
+    ] = Path(),
+    pre_rotate: Annotated[
+        int | None,
+        typer.Option(
+            "--pre-rotate",
+            "-r",
+            help="Поворот изображения перед разрезанием: 90, 180 или 270",
+        ),
+    ] = None,
+    border: Annotated[
+        int,
+        typer.Option(
+            "--border",
+            "-b",
+            min=0,
+            help="Отступ в пикселях (белая рамка / отступ при обрезке содержимого, по умолчанию 50)",
+        ),
+    ] = DEFAULT_BORDER_PX,
+    post_crop: Annotated[
+        bool,
+        typer.Option(
+            "--post-crop",
+            "-c",
+            help="Обрезать каждую страницу по границам полезного содержимого",
+        ),
+    ] = False,
+) -> None:
+    """Разрезать отсканированное изображение на отдельные страницы по геометрической сетке."""
+    if pre_rotate is not None and pre_rotate not in VALID_ROTATIONS:
+        raise typer.BadParameter(
+            f"Недопустимый угол: {pre_rotate}. Допустимые: {sorted(VALID_ROTATIONS)}"
+        )
+
+    cols, rows = parse_slice(slice)
+
+    output_paths = process_image(
+        input_path=input.resolve(),
+        rows=rows,
+        cols=cols,
+        output_dir=output_dir.resolve(),
+        pre_rotate=pre_rotate,
+        border_px=border,
+        post_crop=post_crop,
+    )
+
+    typer.echo(f"Сохранено {len(output_paths)} страниц в {output_dir.resolve()}")
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

src/split/__init__.py

@@ -0,0 +1,37 @@
+from src.split.slicer import (
+    CONTENT_THRESHOLD,
+    DEFAULT_BORDER_PX,
+    PAGE_NUMBER_WIDTH,
+    SUPPORTED_EXTENSIONS,
+    VALID_ROTATIONS,
+    add_border,
+    crop_to_content,
+    find_content_bounds,
+    generate_output_paths,
+    load_image,
+    parse_slice,
+    process_image,
+    rotate_image,
+    save_page,
+    slice_grid,
+    validate_output_dir,
+)
+
+__all__ = [
+    "CONTENT_THRESHOLD",
+    "DEFAULT_BORDER_PX",
+    "PAGE_NUMBER_WIDTH",
+    "SUPPORTED_EXTENSIONS",
+    "VALID_ROTATIONS",
+    "add_border",
+    "crop_to_content",
+    "find_content_bounds",
+    "generate_output_paths",
+    "load_image",
+    "parse_slice",
+    "process_image",
+    "rotate_image",
+    "save_page",
+    "slice_grid",
+    "validate_output_dir",
+]

src/split/slicer.py

@@ -0,0 +1,201 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+SUPPORTED_EXTENSIONS: frozenset[str] = frozenset({".jpg", ".jpeg", ".png", ".tiff", ".tif"})
+PAGE_NUMBER_WIDTH: int = 2
+DEFAULT_BORDER_PX: int = 50
+BORDER_COLOR: tuple[int, int, int] = (255, 255, 255)
+VALID_ROTATIONS: frozenset[int] = frozenset({90, 180, 270})
+CONTENT_THRESHOLD: int = 200
+DENSITY_RATIO: float = 0.005
+
+
+def load_image(path: Path) -> np.ndarray:
+    if path.suffix.lower() not in SUPPORTED_EXTENSIONS:
+        raise ValueError(
+            f"Неподдерживаемый формат: {path.suffix}. "
+            f"Поддерживаются: {', '.join(sorted(SUPPORTED_EXTENSIONS))}"
+        )
+    if not path.exists():
+        raise FileNotFoundError(f"Файл не найден: {path}")
+    image = cv2.imread(str(path), cv2.IMREAD_UNCHANGED)
+    if image is None:
+        raise ValueError(f"Не удалось загрузить изображение: {path}")
+    return image
+
+
+def rotate_image(image: np.ndarray, degrees: int) -> np.ndarray:
+    if degrees == 90:
+        return cv2.rotate(image, cv2.ROTATE_90_CLOCKWISE)
+    if degrees == 180:
+        return cv2.rotate(image, cv2.ROTATE_180)
+    if degrees == 270:
+        return cv2.rotate(image, cv2.ROTATE_90_COUNTERCLOCKWISE)
+    raise ValueError(f"Недопустимый угол поворота: {degrees}. Допустимые: {sorted(VALID_ROTATIONS)}")
+
+
+def slice_grid(image: np.ndarray, rows: int, cols: int) -> list[np.ndarray]:
+    height, width = image.shape[:2]
+    base_h = height // rows
+    base_w = width // cols
+    extra_h = height % rows
+    extra_w = width % cols
+
+    pages: list[np.ndarray] = []
+    y = 0
+    for row in range(rows):
+        cell_h = base_h + (1 if row >= rows - extra_h else 0)
+        x = 0
+        for col in range(cols):
+            cell_w = base_w + (1 if col >= cols - extra_w else 0)
+            page = image[y : y + cell_h, x : x + cell_w]
+            pages.append(page)
+            x += cell_w
+        y += cell_h
+    return pages
+
+
+def add_border(image: np.ndarray, border_px: int) -> np.ndarray:
+    return cv2.copyMakeBorder(
+        image,
+        top=border_px,
+        bottom=border_px,
+        left=border_px,
+        right=border_px,
+        borderType=cv2.BORDER_CONSTANT,
+        value=BORDER_COLOR,
+    )
+
+
+def save_page(image: np.ndarray, path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    success = cv2.imwrite(str(path), image)
+    if not success:
+        raise OSError(f"Не удалось сохранить изображение: {path}")
+
+
+def generate_output_paths(input_path: Path, page_count: int, output_dir: Path) -> list[Path]:
+    stem = input_path.stem
+    suffix = input_path.suffix.lower()
+    max_digits = max(PAGE_NUMBER_WIDTH, len(str(page_count)))
+    return [
+        output_dir / f"{stem}_{i:0{max_digits}d}{suffix}"
+        for i in range(1, page_count + 1)
+    ]
+
+
+def parse_slice(value: str) -> tuple[int, int]:
+    parts = value.split(":")
+    if len(parts) != 2:
+        raise ValueError(
+            f"Неверный формат --slice: {value}. Ожидается <колонки>:<строки>, например 3:2"
+        )
+    try:
+        cols = int(parts[0])
+        rows = int(parts[1])
+    except ValueError:
+        raise ValueError(
+            f"Неверный формат --slice: {value}. Колонки и строки должны быть целыми числами"
+        )
+    if rows < 1 or cols < 1:
+        raise ValueError(
+            f"Неверное значение --slice: {value}. Строки и столбцы должны быть >= 1"
+        )
+    return cols, rows
+
+
+def validate_output_dir(path: Path) -> Path:
+    path.mkdir(parents=True, exist_ok=True)
+    if not path.is_dir():
+        raise NotADirectoryError(f"Не удалось создать каталог: {path}")
+    return path
+
+
+def find_content_bounds(
+    image: np.ndarray,
+    threshold: int = CONTENT_THRESHOLD,
+) -> tuple[int, int, int, int]:
+    gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+    blurred = cv2.GaussianBlur(gray, (3, 3), 0)
+    otsu_th, binary = cv2.threshold(
+        blurred, 0, 255, cv2.THRESH_BINARY_INV + cv2.THRESH_OTSU,
+    )
+    if otsu_th < 50:
+        binary = cv2.adaptiveThreshold(
+            blurred, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C,
+            cv2.THRESH_BINARY_INV, 31, 10,
+        )
+    kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (3, 3))
+    binary = cv2.morphologyEx(binary, cv2.MORPH_CLOSE, kernel)
+
+    h, w = binary.shape
+    min_density = int(w * DENSITY_RATIO)
+
+    row_density = (binary > 0).sum(axis=1)
+    col_density = (binary > 0).sum(axis=0)
+
+    y1 = 0
+    while y1 < h and row_density[y1] < min_density:
+        y1 += 1
+    y2 = h - 1
+    while y2 >= 0 and row_density[y2] < min_density:
+        y2 -= 1
+    x1 = 0
+    while x1 < w and col_density[x1] < min_density:
+        x1 += 1
+    x2 = w - 1
+    while x2 >= 0 and col_density[x2] < min_density:
+        x2 -= 1
+
+    if y1 > y2 or x1 > x2:
+        return 0, 0, w, h
+    return x1, y1, x2, y2
+
+
+def crop_to_content(image: np.ndarray, border_px: int = DEFAULT_BORDER_PX) -> np.ndarray:
+    h, w = image.shape[:2]
+    x1, y1, x2, y2 = find_content_bounds(image)
+
+    left = min(border_px, x1)
+    top = min(border_px, y1)
+    right = min(border_px, w - 1 - x2)
+    bottom = min(border_px, h - 1 - y2)
+
+    x1_crop = x1 - left
+    y1_crop = y1 - top
+    x2_crop = x2 + right + 1
+    y2_crop = y2 + bottom + 1
+
+    return image[y1_crop:y2_crop, x1_crop:x2_crop]
+
+
+def process_image(
+    input_path: Path,
+    rows: int,
+    cols: int,
+    output_dir: Path,
+    pre_rotate: int | None = None,
+    border_px: int = DEFAULT_BORDER_PX,
+    post_crop: bool = False,
+) -> list[Path]:
+    image = load_image(input_path)
+
+    if pre_rotate is not None:
+        image = rotate_image(image, pre_rotate)
+
+    pages = slice_grid(image, rows, cols)
+
+    if post_crop:
+        pages = [crop_to_content(page, border_px) for page in pages]
+
+    pages_with_border = [add_border(page, border_px) for page in pages]
+
+    output_paths = generate_output_paths(input_path, len(pages_with_border), output_dir)
+    for page, path in zip(pages_with_border, output_paths):
+        save_page(page, path)
+
+    return output_paths

stage1.md

@@ -0,0 +1,285 @@
+# Техническое задание
+
+## Проект
+
+Утилита является первым этапом конвейера офлайн-обработки документов.
+
+Назначение утилиты — разрезание отсканированного изображения, содержащего несколько страниц документа, напечатанных на одном листе A4 с использованием функции Microsoft Word **«Несколько страниц на листе»**.
+
+На данном этапе OCR не выполняется.
+
+---
+
+# Предпосылки
+
+Предполагается, что:
+
+- документ распечатан из Microsoft Word;
+- использована функция «Несколько страниц на листе»;
+- все страницы имеют одинаковый размер;
+- страницы расположены в правильной прямоугольной сетке;
+- изображение получено качественным сканером;
+- поиск границ страниц не требуется.
+
+Разрезание выполняется исключительно по геометрической сетке.
+
+Использование OpenCV для поиска страниц, контуров или линий не требуется.
+
+---
+
+# Важно!
+
+Главный приоритет проекта — максимально сохранить качество исходного изображения для последующего OCR. Любые преобразования, способные ухудшить распознавание, должны выполняться только при наличии явного параметра командной строки или быть реализованы на последующих этапах конвейера.
+
+---
+
+# Поддерживаемые форматы
+
+Входные изображения:
+
+- JPEG
+- PNG
+- TIFF
+
+Формат выходных файлов должен совпадать с форматом входного файла.
+
+Цветовое пространство сохраняется без изменений.
+
+Не выполнять:
+
+- перевод в оттенки серого;
+- бинаризацию;
+- изменение цветовой модели;
+- сжатие с потерями сверх уже имеющегося.
+
+---
+
+# Интерфейс командной строки
+
+## Обязательные параметры
+
+```text
+--input <путь_к_файлу>
+```
+
+Путь к входному изображению.
+
+```text
+--slice <строки:столбцы>
+```
+
+Размер сетки.
+
+Поддерживаются любые положительные значения.
+
+Примеры:
+
+```text
+1:2
+2:2
+2:4
+3:3
+4:4
+```
+
+Практический максимум — 4×4.
+
+---
+
+## Необязательные параметры
+
+```text
+--output-dir <каталог>
+```
+
+Каталог сохранения результатов.
+
+По умолчанию — текущий каталог.
+
+---
+
+```text
+--pre-rotate 90|180|270
+```
+
+Повернуть изображение перед разрезанием.
+
+---
+
+```text
+--border <пикселей>
+```
+
+Добавить белую рамку вокруг каждой страницы.
+
+По умолчанию:
+
+```text
+20
+```
+
+---
+
+# Разрезание
+
+Изображение делится на равномерную прямоугольную сетку.
+
+Не использовать:
+
+- поиск страниц;
+- поиск контуров;
+- поиск линий;
+- Hough Transform;
+- распознавание структуры изображения;
+- любые алгоритмы компьютерного зрения для определения координат страниц.
+
+Координаты вычисляются исключительно на основании размеров изображения и параметра:
+
+```text
+--slice
+```
+
+---
+
+# Порядок страниц
+
+Порядок должен полностью соответствовать порядку печати Microsoft Word.
+
+Пример для 2×2:
+
+```text
+01 02
+03 04
+```
+
+Пример для 2×4:
+
+```text
+01 02
+03 04
+05 06
+07 08
+```
+
+Используется порядок **row-major** (слева направо, сверху вниз).
+
+---
+
+# Размеры частей
+
+Если размеры изображения не делятся без остатка на количество строк или столбцов, остаток пикселей должен быть добавлен к последней строке и/или последнему столбцу.
+
+Потеря пикселей недопустима.
+
+---
+
+# Имена выходных файлов
+
+Входной файл:
+
+```text
+scan001.jpg
+```
+
+Результат:
+
+```text
+scan001_01.jpg
+scan001_02.jpg
+scan001_03.jpg
+...
+```
+
+Использовать двузначную нумерацию.
+
+---
+
+# Постобработка
+
+После разрезания для каждой страницы выполнить:
+
+1. Добавление белой рамки (`--border`).
+2. Сохранение результата.
+
+Белая рамка необходима для повышения качества последующего OCR.
+
+---
+
+# Архитектура
+
+Обработка должна состоять из независимых этапов:
+
+```text
+Загрузка изображения
+        ↓
+Опциональный поворот
+        ↓
+Разрезание на страницы
+        ↓
+Добавление белой рамки
+        ↓
+Сохранение результата
+```
+
+Каждый этап должен быть реализован отдельной функцией.
+
+Это необходимо для последующего расширения конвейера.
+
+---
+
+# Не входит в MVP
+
+На данном этапе НЕ реализовывать:
+
+- OCR;
+- PaddleOCR;
+- генерацию HTML;
+- поддержку PDF;
+- GUI;
+- Docker;
+- многопоточность;
+- автоматическое определение сетки;
+- поиск страниц;
+- deskew;
+- автоматическую обрезку полей;
+- удаление шума;
+- повышение контрастности;
+- бинаризацию.
+
+Все перечисленные возможности будут реализованы на следующих этапах проекта.
+
+---
+
+# Требования к реализации
+
+Использовать:
+
+- Python 3.12+
+- OpenCV
+- NumPy
+
+Для разрезания изображения использовать срезы массива NumPy.
+
+OpenCV использовать только для:
+
+- загрузки изображения;
+- поворота;
+- добавления белой рамки;
+- сохранения результата.
+
+Не использовать OpenCV для вычисления координат разрезания.
+
+---
+
+# Требования к качеству кода
+
+- Полная типизация (type hints).
+- Отсутствие глобальных переменных.
+- Отсутствие дублирования кода.
+- Каждая функция должна выполнять одну логическую задачу.
+- Проверка всех параметров командной строки.
+- Понятные сообщения об ошибках.
+- Ненулевой код завершения при ошибках.
+- Соответствие PEP 8.
+
+Код должен стать основой для последующих этапов конвейера подготовки документов к OCR.

tests/test_slicer.py

@@ -0,0 +1,485 @@
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+
+import cv2
+import numpy as np
+import pytest
+
+from src.split.slicer import (
+    SUPPORTED_EXTENSIONS,
+    VALID_ROTATIONS,
+    add_border,
+    crop_to_content,
+    find_content_bounds,
+    generate_output_paths,
+    load_image,
+    parse_slice,
+    process_image,
+    rotate_image,
+    save_page,
+    slice_grid,
+)
+
+
+def _create_test_image(width: int = 400, height: int = 300) -> np.ndarray:
+    image = np.zeros((height, width, 3), dtype=np.uint8)
+    image[:, :] = (200, 200, 200)
+    return image
+
+
+def _image_to_path(image: np.ndarray, suffix: str = ".png") -> Path:
+    with tempfile.NamedTemporaryFile(suffix=suffix, delete=False) as tmp:
+        cv2.imwrite(tmp.name, image)
+        return Path(tmp.name)
+
+
+class TestParseSlice:
+    def test_simple_2x2(self) -> None:
+        assert parse_slice("2:2") == (2, 2)
+
+    def test_2x4(self) -> None:
+        assert parse_slice("2:4") == (2, 4)
+
+    def test_1x1(self) -> None:
+        assert parse_slice("1:1") == (1, 1)
+
+    def test_large(self) -> None:
+        assert parse_slice("10:10") == (10, 10)
+
+    def test_invalid_format_missing_colon(self) -> None:
+        with pytest.raises(ValueError, match="Неверный формат --slice"):
+            parse_slice("22")
+
+    def test_invalid_format_extra_colon(self) -> None:
+        with pytest.raises(ValueError, match="Неверный формат --slice"):
+            parse_slice("2:3:4")
+
+    def test_non_integer_value(self) -> None:
+        with pytest.raises(ValueError, match="Неверный формат --slice"):
+            parse_slice("a:b")
+
+    def test_non_integer_col(self) -> None:
+        with pytest.raises(ValueError, match="Неверный формат --slice"):
+            parse_slice("x:2")
+
+    def test_zero_cols(self) -> None:
+        with pytest.raises(ValueError, match="Неверное значение --slice"):
+            parse_slice("0:2")
+
+    def test_zero_rows(self) -> None:
+        with pytest.raises(ValueError, match="Неверное значение --slice"):
+            parse_slice("2:0")
+
+    def test_negative_cols(self) -> None:
+        with pytest.raises(ValueError, match="Неверное значение --slice"):
+            parse_slice("-1:2")
+
+    def test_blank_string(self) -> None:
+        with pytest.raises(ValueError):
+            parse_slice("")
+
+
+class TestSliceGrid:
+    def test_2x2_exact(self) -> None:
+        image = _create_test_image(400, 300)
+        pages = slice_grid(image, 2, 2)
+        assert len(pages) == 4
+        assert pages[0].shape == (150, 200, 3)
+        assert pages[1].shape == (150, 200, 3)
+        assert pages[2].shape == (150, 200, 3)
+        assert pages[3].shape == (150, 200, 3)
+
+    def test_1x1(self) -> None:
+        image = _create_test_image(100, 100)
+        pages = slice_grid(image, 1, 1)
+        assert len(pages) == 1
+        assert pages[0].shape == (100, 100, 3)
+
+    def test_2x3(self) -> None:
+        image = _create_test_image(300, 200)
+        pages = slice_grid(image, 2, 3)
+        assert len(pages) == 6
+        for page in pages:
+            assert page.shape == (100, 100, 3)
+
+    def test_uneven_division_width(self) -> None:
+        image = _create_test_image(width=403, height=300)
+        pages = slice_grid(image, 1, 2)
+        assert len(pages) == 2
+        assert pages[0].shape == (300, 201, 3)
+        assert pages[1].shape == (300, 202, 3)
+
+    def test_uneven_division_height(self) -> None:
+        image = _create_test_image(width=400, height=301)
+        pages = slice_grid(image, 2, 1)
+        assert len(pages) == 2
+        assert pages[0].shape == (150, 400, 3)
+        assert pages[1].shape == (151, 400, 3)
+
+    def test_uneven_both(self) -> None:
+        image = _create_test_image(width=401, height=301)
+        pages = slice_grid(image, 2, 2)
+        assert len(pages) == 4
+        assert pages[0].shape == (150, 200, 3)
+        assert pages[1].shape == (150, 201, 3)
+        assert pages[2].shape == (151, 200, 3)
+        assert pages[3].shape == (151, 201, 3)
+
+    def test_pixel_content_preserved(self) -> None:
+        image = np.random.randint(0, 255, (100, 100, 3), dtype=np.uint8)
+        pages = slice_grid(image, 2, 2)
+        assert np.array_equal(image[0:50, 0:50], pages[0])
+        assert np.array_equal(image[0:50, 50:100], pages[1])
+        assert np.array_equal(image[50:100, 0:50], pages[2])
+        assert np.array_equal(image[50:100, 50:100], pages[3])
+
+    def test_total_pixels_preserved(self) -> None:
+        image = _create_test_image(width=401, height=301)
+        pages = slice_grid(image, 3, 3)
+        total = sum(page.shape[0] * page.shape[1] for page in pages)
+        assert total == 401 * 301
+
+    def test_order_2x2(self) -> None:
+        image = _create_test_image(200, 200)
+        image[0:100, 0:100] = (255, 0, 0)
+        image[0:100, 100:200] = (0, 255, 0)
+        image[100:200, 0:100] = (0, 0, 255)
+        image[100:200, 100:200] = (255, 255, 0)
+        pages = slice_grid(image, 2, 2)
+        assert pages[0][0, 0].tolist() == [255, 0, 0]
+        assert pages[1][0, 0].tolist() == [0, 255, 0]
+        assert pages[2][0, 0].tolist() == [0, 0, 255]
+        assert pages[3][0, 0].tolist() == [255, 255, 0]
+
+    def test_order_2x4(self) -> None:
+        image = _create_test_image(400, 200)
+        pages = slice_grid(image, 2, 4)
+        assert len(pages) == 8
+        assert pages[0].shape == (100, 100, 3)
+        assert pages[7].shape == (100, 100, 3)
+
+    def test_4x4(self) -> None:
+        image = _create_test_image(400, 400)
+        pages = slice_grid(image, 4, 4)
+        assert len(pages) == 16
+        for page in pages:
+            assert page.shape == (100, 100, 3)
+
+
+class TestAddBorder:
+    def test_default_border(self) -> None:
+        image = _create_test_image(100, 100)
+        result = add_border(image, 20)
+        assert result.shape == (140, 140, 3)
+
+    def test_zero_border(self) -> None:
+        image = _create_test_image(100, 100)
+        result = add_border(image, 0)
+        assert np.array_equal(result, image)
+
+    def test_border_is_white(self) -> None:
+        image = _create_test_image(100, 100)
+        border = 10
+        result = add_border(image, border)
+        assert np.all(result[0:border, :] == 255)
+        assert np.all(result[-border:, :] == 255)
+        assert np.all(result[:, 0:border] == 255)
+        assert np.all(result[:, -border:] == 255)
+
+    def test_large_border(self) -> None:
+        image = _create_test_image(10, 10)
+        result = add_border(image, 50)
+        assert result.shape == (110, 110, 3)
+
+
+class TestRotateImage:
+    def test_rotate_90(self) -> None:
+        image = _create_test_image(200, 100)
+        result = rotate_image(image, 90)
+        assert result.shape == (200, 100, 3)
+
+    def test_rotate_180(self) -> None:
+        image = _create_test_image(200, 100)
+        result = rotate_image(image, 180)
+        assert result.shape == (100, 200, 3)
+
+    def test_rotate_270(self) -> None:
+        image = _create_test_image(200, 100)
+        result = rotate_image(image, 270)
+        assert result.shape == (200, 100, 3)
+
+    def test_invalid_angle(self) -> None:
+        image = _create_test_image()
+        with pytest.raises(ValueError, match="Недопустимый угол поворота"):
+            rotate_image(image, 45)
+
+    def test_invalid_angle_zero(self) -> None:
+        image = _create_test_image()
+        with pytest.raises(ValueError):
+            rotate_image(image, 0)
+
+    def test_valid_rotations_set(self) -> None:
+        assert VALID_ROTATIONS == frozenset({90, 180, 270})
+
+
+class TestGenerateOutputPaths:
+    def test_simple(self) -> None:
+        paths = generate_output_paths(Path("scan001.jpg"), 2, Path("/tmp"))
+        assert paths == [Path("/tmp/scan001_01.jpg"), Path("/tmp/scan001_02.jpg")]
+
+    def test_tiff_extension(self) -> None:
+        paths = generate_output_paths(Path("doc.tiff"), 3, Path("out"))
+        assert paths == [
+            Path("out/doc_01.tiff"),
+            Path("out/doc_02.tiff"),
+            Path("out/doc_03.tiff"),
+        ]
+
+    def test_png_extension(self) -> None:
+        paths = generate_output_paths(Path("img.PNG"), 1, Path("out"))
+        assert paths == [Path("out/img_01.png")]
+
+    def test_zero_padding(self) -> None:
+        paths = generate_output_paths(Path("scan.jpg"), 12, Path("out"))
+        assert paths[0] == Path("out/scan_01.jpg")
+        assert paths[9] == Path("out/scan_10.jpg")
+        assert paths[11] == Path("out/scan_12.jpg")
+
+    def test_many_pages(self) -> None:
+        paths = generate_output_paths(Path("scan.jpg"), 100, Path("out"))
+        assert paths[0] == Path("out/scan_001.jpg")
+        assert paths[99] == Path("out/scan_100.jpg")
+
+    def test_dot_in_filename(self) -> None:
+        paths = generate_output_paths(Path("scan.001.jpg"), 2, Path("out"))
+        assert paths == [Path("out/scan.001_01.jpg"), Path("out/scan.001_02.jpg")]
+
+
+class TestLoadImage:
+    def test_valid_jpeg(self) -> None:
+        image = _create_test_image()
+        path = _image_to_path(image, ".jpg")
+        loaded = load_image(path)
+        assert loaded.shape == (300, 400, 3)
+
+    def test_valid_png(self) -> None:
+        image = _create_test_image()
+        path = _image_to_path(image, ".png")
+        loaded = load_image(path)
+        assert loaded.shape == (300, 400, 3)
+
+    def test_valid_tiff(self) -> None:
+        image = _create_test_image()
+        path = _image_to_path(image, ".tiff")
+        loaded = load_image(path)
+        assert loaded.shape == (300, 400, 3)
+
+    def test_file_not_found(self) -> None:
+        with pytest.raises(FileNotFoundError, match="Файл не найден"):
+            load_image(Path("/tmp/nonexistent_scan2html_test.jpg"))
+
+    def test_unsupported_extension(self) -> None:
+        path = Path("/tmp/test.bmp")
+        with pytest.raises(ValueError, match="Неподдерживаемый формат"):
+            load_image(path)
+
+    def test_unsupported_extension_no_dot(self) -> None:
+        path = Path("/tmp/test")
+        with pytest.raises(ValueError, match="Неподдерживаемый формат"):
+            load_image(path)
+
+    def test_supported_extensions_set(self) -> None:
+        assert SUPPORTED_EXTENSIONS == frozenset({".jpg", ".jpeg", ".png", ".tiff", ".tif"})
+
+
+class TestSavePage:
+    def test_saves_file(self) -> None:
+        image = _create_test_image()
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "test.png"
+            save_page(image, path)
+            assert path.exists()
+            loaded = cv2.imread(str(path))
+            assert loaded is not None
+            assert loaded.shape == (300, 400, 3)
+
+    def test_creates_parent_dir(self) -> None:
+        image = _create_test_image()
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "subdir" / "test.png"
+            save_page(image, path)
+            assert path.exists()
+
+
+class TestProcessImage:
+    def test_end_to_end_2x2(self) -> None:
+        image = _create_test_image(400, 300)
+        path = _image_to_path(image, ".jpg")
+        with tempfile.TemporaryDirectory() as tmp:
+            result = process_image(Path(path), 2, 2, Path(tmp))
+            assert len(result) == 4
+            for p in result:
+                assert p.exists()
+                loaded = cv2.imread(str(p))
+                assert loaded.shape == (250, 300, 3)
+
+    def test_end_to_end_with_border(self) -> None:
+        image = _create_test_image(200, 200)
+        path = _image_to_path(image, ".png")
+        with tempfile.TemporaryDirectory() as tmp:
+            result = process_image(Path(path), 2, 2, Path(tmp), border_px=10)
+            assert len(result) == 4
+            for p in result:
+                assert p.exists()
+                loaded = cv2.imread(str(p))
+                assert loaded.shape == (120, 120, 3)
+
+    def test_end_to_end_tiff(self) -> None:
+        image = _create_test_image(400, 400)
+        path = _image_to_path(image, ".tiff")
+        with tempfile.TemporaryDirectory() as tmp:
+            result = process_image(Path(path), 2, 2, Path(tmp))
+            assert len(result) == 4
+            for p in result:
+                assert p.suffix.lower() == ".tiff"
+                assert p.exists()
+
+    def test_end_to_end_with_rotation(self) -> None:
+        image = _create_test_image(200, 400)
+        path = _image_to_path(image, ".png")
+        with tempfile.TemporaryDirectory() as tmp:
+            result = process_image(Path(path), 2, 2, Path(tmp), pre_rotate=90)
+            assert len(result) == 4
+            for p in result:
+                assert p.exists()
+            loaded = cv2.imread(str(result[0]))
+            assert loaded.shape[0] > 0
+
+
+class TestFindContentBounds:
+    def test_uniform_image(self) -> None:
+        image = _create_test_image(200, 150)
+        image[:, :] = (255, 255, 255)
+        x1, y1, x2, y2 = find_content_bounds(image)
+        assert (x1, y1, x2, y2) == (0, 0, 200, 150)
+
+    def test_single_dot_center(self) -> None:
+        image = _create_test_image(200, 150)
+        image[:, :] = (255, 255, 255)
+        image[75, 100] = (0, 0, 0)
+        x1, y1, x2, y2 = find_content_bounds(image)
+        assert abs(x1 - 100) <= 1 and abs(x2 - 100) <= 1
+        assert abs(y1 - 75) <= 1 and abs(y2 - 75) <= 1
+
+    def test_rectangle_content(self) -> None:
+        image = _create_test_image(200, 150)
+        image[:, :] = (255, 255, 255)
+        image[30:100, 50:140] = (0, 0, 0)
+        x1, y1, x2, y2 = find_content_bounds(image)
+        assert x1 == 50
+        assert y1 == 30
+        assert x2 == 139
+        assert y2 == 99
+
+    def test_content_at_edges(self) -> None:
+        image = _create_test_image(200, 150)
+        image[:, :] = (255, 255, 255)
+        image[0:10, :] = (0, 0, 0)
+        image[:, 0:10] = (0, 0, 0)
+        x1, y1, _x2, _y2 = find_content_bounds(image)
+        assert y1 == 0
+        assert x1 == 0
+
+    def test_grayscale_content(self) -> None:
+        image = _create_test_image(100, 100)
+        image[:, :] = (255, 255, 255)
+        image[20:30, 20:30] = (128, 128, 128)
+        x1, y1, x2, y2 = find_content_bounds(image)
+        assert x1 <= 29 and x2 >= 20
+        assert y1 <= 29 and y2 >= 20
+
+
+class TestCropToContent:
+    def test_crop_centered_content(self) -> None:
+        image = _create_test_image(200, 150)
+        image[:, :] = (255, 255, 255)
+        image[30:50, 40:60] = (0, 0, 0)
+        result = crop_to_content(image, border_px=10)
+        assert result.shape[0] >= 20
+        assert result.shape[1] >= 20
+
+    def test_crop_uniform_image_no_change(self) -> None:
+        image = _create_test_image(100, 100)
+        image[:, :] = (255, 255, 255)
+        result = crop_to_content(image, border_px=10)
+        assert result.shape == (100, 100, 3)
+
+    def test_border_capped_by_image_edge(self) -> None:
+        image = _create_test_image(100, 100)
+        image[:, :] = (255, 255, 255)
+        image[10:30, 10:30] = (0, 0, 0)
+        result = crop_to_content(image, border_px=200)
+        assert result.shape == (100, 100, 3)
+
+    def test_border_equals_distance_to_edge(self) -> None:
+        image = _create_test_image(100, 100)
+        image[:, :] = (255, 255, 255)
+        image[40:60, 30:70] = (0, 0, 0)
+        result = crop_to_content(image, border_px=50)
+        assert result.shape[1] <= 100
+        assert result.shape[0] <= 100
+
+    def test_dark_bg_no_crop_uniform(self) -> None:
+        image = _create_test_image(100, 100)
+        image[:, :] = (0, 0, 0)
+        result = crop_to_content(image, border_px=0)
+        assert result.shape == (100, 100, 3)
+
+    def test_zero_border_exact_crop(self) -> None:
+        image = _create_test_image(200, 150)
+        image[:, :] = (255, 255, 255)
+        image[20:100, 30:170] = (0, 0, 0)
+        result = crop_to_content(image, border_px=0)
+        assert result.shape == (80, 140, 3)
+
+
+class TestProcessImagePostCrop:
+    def test_post_crop_reduces_size(self) -> None:
+        image = _create_test_image(400, 400)
+        image[:, :] = (255, 255, 255)
+        image[100:200, 100:200] = (0, 0, 0)
+        path = _image_to_path(image, ".png")
+        with tempfile.TemporaryDirectory() as tmp:
+            result = process_image(Path(path), 1, 1, Path(tmp), border_px=30, post_crop=True)
+            assert len(result) == 1
+            loaded = cv2.imread(str(result[0]))
+            assert loaded.shape[0] < 400 or loaded.shape[1] < 400
+
+    def test_post_crop_off_no_crop(self) -> None:
+        image = _create_test_image(400, 300)
+        path = _image_to_path(image, ".png")
+        with tempfile.TemporaryDirectory() as tmp:
+            result = process_image(Path(path), 1, 1, Path(tmp), post_crop=False)
+            assert len(result) == 1
+            loaded = cv2.imread(str(result[0]))
+            assert loaded.shape == (400, 500, 3)
+
+    def test_post_crop_e2e_2x2(self) -> None:
+        image = _create_test_image(400, 400)
+        image[:, :] = (255, 255, 255)
+        image[50:150, 50:150] = (0, 0, 0)
+        image[50:150, 250:350] = (0, 0, 0)
+        image[250:350, 50:150] = (0, 0, 0)
+        image[250:350, 250:350] = (0, 0, 0)
+        path = _image_to_path(image, ".png")
+        with tempfile.TemporaryDirectory() as tmp:
+            result_crop = process_image(Path(path), 2, 2, Path(tmp) / "crop", border_px=30, post_crop=True)
+            result_no = process_image(Path(path), 2, 2, Path(tmp) / "no", border_px=30, post_crop=False)
+            assert len(result_crop) == 4
+            for cp, np in zip(result_crop, result_no):
+                c = cv2.imread(str(cp))
+                n = cv2.imread(str(np))
+                assert c.shape[0] < n.shape[0]
+                assert c.shape[1] < n.shape[1]