refactored code

.ai/AI_RULES.md

+# Правила работы AI-агента
+
+Не изменять архитектуру проекта без явного запроса пользователя.
+
+Не добавлять новые зависимости без необходимости.
+
+Не выполнять рефакторинг только ради красоты кода.
+
+Не изменять существующее поведение без требования пользователя.
+
+Не реализовывать функциональность, отсутствующую в техническом задании.
+
+Если существует несколько вариантов реализации:
+
+- выбрать самый простой;
+- если различия существенны — предложить варианты пользователю.
+
+Предпочитать понятный код компактному.
+
+Предпочитать простое решение сложному.
+
+При сомнениях задавать вопрос вместо предположений.

.ai/CODE_STYLE.md

+# Стиль кода
+
+## Язык
+
+Python 3.12+
+
+---
+
+## Типизация
+
+Полная типизация обязательна.
+
+Избегать использования Any.
+
+---
+
+## Размер функций
+
+Желательно не более 40 строк.
+
+Максимум около 80 строк.
+
+Если функция становится длиннее — разделить её.
+
+---
+
+## Размер файлов
+
+Желательно до 300 строк.
+
+Максимум около 500 строк.
+
+---
+
+## Именование
+
+Использовать понятные имена.
+
+Хорошо:
+
+load_image()
+
+split_grid()
+
+rotate_image()
+
+add_border()
+
+Плохо:
+
+proc()
+
+run2()
+
+tmp()
+
+---
+
+## Глобальное состояние
+
+Не использовать глобальные переменные.
+
+Не использовать Singleton.
+
+---
+
+## Магические числа
+
+Все значения должны быть вынесены в именованные константы либо параметры функций.
+
+---
+
+## Ошибки
+
+Использовать исключения.
+
+CLI должен завершаться ненулевым кодом возврата.
+
+Сообщения должны быть понятны пользователю.
+
+---
+
+## Логирование
+
+Использовать logging.
+
+Не использовать print() для отладки.
+
+---
+
+## Качество
+
+Следовать PEP8.
+
+Использовать Ruff.
+
+Не оставлять:
+
+- закомментированный код;
+- неиспользуемый код;
+- TODO без объяснения.

.ai/DEVELOPMENT.md

+# Правила разработки
+
+## Цель проекта
+
+Проект предназначен для полностью офлайн-подготовки документов к OCR.
+
+Главный приоритет — сохранить максимальное качество исходного изображения.
+
+Любое преобразование изображения должно либо улучшать OCR, либо не изменять качество изображения.
+
+---
+
+## Принципы
+
+Приоритеты разработки:
+
+1. Простота.
+2. Предсказуемость.
+3. Читаемость.
+4. Качество изображения.
+5. Производительность.
+
+Не реализовывать функциональность "на будущее".
+
+Реализовывать только то, что требуется текущим техническим заданием.
+
+---
+
+## Поведение
+
+Если требования неоднозначны:
+
+- не делать предположений;
+- не придумывать функциональность самостоятельно;
+- предложить варианты и дождаться решения пользователя.
+
+Не изменять существующее поведение без необходимости.
+
+Новые возможности добавлять как отдельные независимые этапы обработки.
+
+---
+
+## Зависимости
+
+Каждая новая библиотека должна иметь явное обоснование.
+
+Предпочитать стандартную библиотеку Python.
+
+Не добавлять тяжёлые зависимости без необходимости.

.ai/IMAGE_PROCESSING.md

+# Правила обработки изображений
+
+Главная цель — максимально сохранить качество изображения для последующего OCR.
+
+## По умолчанию запрещено
+
+Без явного требования пользователя не выполнять:
+
+- изменение DPI;
+- повторное JPEG-сжатие;
+- изменение цветового пространства;
+- преобразование в grayscale;
+- бинаризацию;
+- изменение контрастности;
+- повышение резкости;
+- шумоподавление;
+- масштабирование.
+
+---
+
+## OpenCV
+
+Использовать OpenCV только там, где это действительно необходимо.
+
+Если задачу проще решить средствами NumPy — использовать NumPy.
+
+Например:
+
+разрезание изображения выполняется исключительно срезами массива NumPy.
+
+---
+
+## Потери качества
+
+Не выполнять преобразований, ухудшающих изображение.
+
+Избегать лишнего копирования изображений.
+
+Предпочитать NumPy views вместо копирования данных.
+
+---
+
+## Форматы
+
+Формат выходного изображения должен совпадать с входным.
+
+Цветовое пространство должно сохраняться.
+
+Все операции должны быть обратимыми либо явно управляться параметрами CLI.

src/cli.py

 app = typer.Typer(add_completion=False, no_args_is_help=True)
 
 
+def _validate_input(input_path: Path | None) -> Path:
+    if input_path is None:
+        raise typer.BadParameter(
+            "Укажите путь к входному изображению", param_hint="--input"
+        )
+    if not input_path.exists():
+        raise typer.BadParameter(
+            f"Файл не найден: {input_path}", param_hint="--input"
+        )
+    if not input_path.is_file():
+        raise typer.BadParameter(
+            f"Не является файлом: {input_path}", param_hint="--input"
+        )
+    if not os.access(input_path, os.R_OK):
+        raise typer.BadParameter(
+            f"Нет доступа на чтение: {input_path}", param_hint="--input"
+        )
+    return input_path.resolve()
+
+
+def _validate_rotation(degrees: int | None) -> None:
+    if degrees is not None and degrees not in VALID_ROTATIONS:
+        raise typer.BadParameter(
+            f"Недопустимый угол: {degrees}. "
+            f"Допустимые: {sorted(VALID_ROTATIONS)}"
+        )
+
+
+def _resolve_grid(
+    slice_str: str | None,
+    slice_auto: bool,
+    input_path: Path,
+    pre_rotate: int | None,
+) -> tuple[int, int]:
+    if slice_str is not None and slice_auto:
+        raise typer.BadParameter(
+            "Нельзя указывать одновременно --slice и --slice-auto"
+        )
+    if slice_str is None and not slice_auto:
+        raise typer.BadParameter("Укажите --slice или --slice-auto")
+
+    if slice_auto:
+        image = load_image(input_path)
+        if pre_rotate is not None:
+            image = rotate_image(image, pre_rotate)
+        cols, rows = detect_grid(image)
+        typer.echo(f"Определена сетка: {cols}×{rows}")
+        return cols, rows
+
+    assert slice_str is not None
+    return parse_slice(slice_str)
+
+
 @app.command()
 def slice_pages(
     input: Annotated[
     ] = False,
 ) -> None:
     """Разрезать отсканированное изображение на отдельные страницы по геометрической сетке."""
-    if input is None:
-        raise typer.BadParameter("Укажите путь к входному изображению", param_hint="--input")
-
-    if not input.exists():
-        raise typer.BadParameter(f"Файл не найден: {input}", param_hint="--input")
-    if not input.is_file():
-        raise typer.BadParameter(f"Не является файлом: {input}", param_hint="--input")
-    if not os.access(input, os.R_OK):
-        raise typer.BadParameter(f"Нет доступа на чтение: {input}", param_hint="--input")
-
-    if pre_rotate is not None and pre_rotate not in VALID_ROTATIONS:
-        raise typer.BadParameter(
-            f"Недопустимый угол: {pre_rotate}. Допустимые: {sorted(VALID_ROTATIONS)}"
-        )
-
-    if slice is not None and slice_auto:
-        raise typer.BadParameter(
-            "Нельзя указывать одновременно --slice и --slice-auto"
-        )
-    if slice is None and not slice_auto:
-        raise typer.BadParameter(
-            "Укажите --slice или --slice-auto"
-        )
-
-    if slice_auto:
-        image = load_image(input.resolve())
-        if pre_rotate is not None:
-            image = rotate_image(image, pre_rotate)
-        cols, rows = detect_grid(image)
-        typer.echo(f"Определена сетка: {cols}×{rows}")
-    else:
-        assert slice is not None
-        cols, rows = parse_slice(slice)
+    input_path = _validate_input(input)
+    _validate_rotation(pre_rotate)
+    cols, rows = _resolve_grid(slice, slice_auto, input_path, pre_rotate)
 
     output_paths = process_image(
-        input_path=input.resolve(),
+        input_path=input_path,
         rows=rows,
         cols=cols,
         output_dir=output_dir.resolve(),

src/split/__init__.py

 from src.split.slicer import (
-    CONTENT_THRESHOLD,
     DEFAULT_BORDER_PX,
     PAGE_NUMBER_WIDTH,
     SUPPORTED_EXTENSIONS,
 )
 
 __all__ = [
-    "CONTENT_THRESHOLD",
     "DEFAULT_BORDER_PX",
     "PAGE_NUMBER_WIDTH",
     "SUPPORTED_EXTENSIONS",

src/split/slicer.py

 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
 AUTO_GRID_MAX: int = 4
 
     return max(1, bands)
 
 
-def find_content_bounds(
-    image: np.ndarray,
-    threshold: int = CONTENT_THRESHOLD,
-) -> tuple[int, int, int, int]:
+def find_content_bounds(image: np.ndarray) -> tuple[int, int, int, int]:
     gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
     blurred = cv2.GaussianBlur(gray, (3, 3), 0)
     otsu_th, binary = cv2.threshold(

tests/helpers.py

+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+
+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)

tests/test_detect_grid.py

+from __future__ import annotations
+
+from src.split.slicer import detect_grid
+from tests.helpers import create_test_image
+
+
+class TestDetectGrid:
+    def test_2x2(self) -> None:
+        image = create_test_image(400, 300)
+        image[:, :] = (255, 255, 255)
+        dark = (0, 0, 0)
+        gap = 20
+        bw = (400 - 3 * gap) // 2
+        bh = (300 - 3 * gap) // 2
+        for r in range(2):
+            for c in range(2):
+                y = gap + r * (bh + gap)
+                x = gap + c * (bw + gap)
+                image[y : y + bh, x : x + bw] = dark
+        cols, rows = detect_grid(image)
+        assert cols == 2
+        assert rows == 2
+
+    def test_2x4(self) -> None:
+        image = create_test_image(800, 400)
+        image[:, :] = (255, 255, 255)
+        gap = 15
+        bw = (800 - 5 * gap) // 4
+        bh = (400 - 3 * gap) // 2
+        dark = (0, 0, 0)
+        for r in range(2):
+            for c in range(4):
+                y = gap + r * (bh + gap)
+                x = gap + c * (bw + gap)
+                image[y : y + bh, x : x + bw] = dark
+        cols, rows = detect_grid(image)
+        assert cols == 4
+        assert rows == 2
+
+    def test_1x1(self) -> None:
+        image = create_test_image(200, 200)
+        image[:, :] = (255, 255, 255)
+        image[20:180, 20:180] = (0, 0, 0)
+        cols, rows = detect_grid(image)
+        assert cols == 1
+        assert rows == 1
+
+    def test_3x3(self) -> None:
+        image = create_test_image(600, 450)
+        image[:, :] = (255, 255, 255)
+        dark = (0, 0, 0)
+        gap = 10
+        bw = (600 - 4 * gap) // 3
+        bh = (450 - 4 * gap) // 3
+        for r in range(3):
+            for c in range(3):
+                y = gap + r * (bh + gap)
+                x = gap + c * (bw + gap)
+                image[y : y + bh, x : x + bw] = dark
+        cols, rows = detect_grid(image)
+        assert cols == 3
+        assert rows == 3
+
+    def test_uniform_image(self) -> None:
+        image = create_test_image()
+        cols, rows = detect_grid(image)
+        assert cols == 1
+        assert rows == 1

tests/test_post_crop.py

+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+
+import cv2
+
+from src.split.slicer import crop_to_content, find_content_bounds, process_image
+from tests.helpers import create_test_image, image_to_path
+
+
+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]

tests/test_slicer.py

     SUPPORTED_EXTENSIONS,
     VALID_ROTATIONS,
     add_border,
-    crop_to_content,
-    detect_grid,
-    find_content_bounds,
     generate_output_paths,
     load_image,
     parse_slice,
     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)
+from tests.helpers import create_test_image, image_to_path
 
 
 class TestParseSlice:
 
 class TestSliceGrid:
     def test_2x2_exact(self) -> None:
-        image = _create_test_image(400, 300)
+        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[3].shape == (150, 200, 3)
 
     def test_1x1(self) -> None:
-        image = _create_test_image(100, 100)
+        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)
+        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)
+        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)
+        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)
+        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 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)
+        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 = 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)
         assert pages[3][0, 0].tolist() == [255, 255, 0]
 
     def test_order_2x4(self) -> None:
-        image = _create_test_image(400, 200)
+        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)
+        image = create_test_image(400, 400)
         pages = slice_grid(image, 4, 4)
         assert len(pages) == 16
         for page in pages:
 
 class TestAddBorder:
     def test_default_border(self) -> None:
-        image = _create_test_image(100, 100)
+        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)
+        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)
+        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)
 
     def test_large_border(self) -> None:
-        image = _create_test_image(10, 10)
+        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)
+        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)
+        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)
+        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()
+        image = create_test_image()
         with pytest.raises(ValueError, match="Недопустимый угол поворота"):
             rotate_image(image, 45)
 
     def test_invalid_angle_zero(self) -> None:
-        image = _create_test_image()
+        image = create_test_image()
         with pytest.raises(ValueError):
             rotate_image(image, 0)
 
 
 class TestLoadImage:
     def test_valid_jpeg(self) -> None:
-        image = _create_test_image()
-        path = _image_to_path(image, ".jpg")
+        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")
+        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")
+        image = create_test_image()
+        path = image_to_path(image, ".tiff")
         loaded = load_image(path)
         assert loaded.shape == (300, 400, 3)
 
 
 class TestSavePage:
     def test_saves_file(self) -> None:
-        image = _create_test_image()
+        image = create_test_image()
         with tempfile.TemporaryDirectory() as tmp:
             path = Path(tmp) / "test.png"
             save_page(image, path)
             assert loaded.shape == (300, 400, 3)
 
     def test_creates_parent_dir(self) -> None:
-        image = _create_test_image()
+        image = create_test_image()
         with tempfile.TemporaryDirectory() as tmp:
             path = Path(tmp) / "subdir" / "test.png"
             save_page(image, path)
 
 class TestProcessImage:
     def test_end_to_end_2x2(self) -> None:
-        image = _create_test_image(400, 300)
-        path = _image_to_path(image, ".jpg")
+        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
                 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")
+        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
                 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")
+        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
                 assert p.exists()
 
     def test_end_to_end_with_rotation(self) -> None:
-        image = _create_test_image(200, 400)
-        path = _image_to_path(image, ".png")
+        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
                 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]
-
-
-class TestDetectGrid:
-    def test_2x2(self) -> None:
-        image = _create_test_image(400, 300)
-        image[:, :] = (255, 255, 255)
-        dark = (0, 0, 0)
-        gap = 20
-        bw = (400 - 3 * gap) // 2
-        bh = (300 - 3 * gap) // 2
-        for r in range(2):
-            for c in range(2):
-                y = gap + r * (bh + gap)
-                x = gap + c * (bw + gap)
-                image[y:y + bh, x:x + bw] = dark
-        cols, rows = detect_grid(image)
-        assert cols == 2
-        assert rows == 2
-
-    def test_2x4(self) -> None:
-        image = _create_test_image(800, 400)
-        image[:, :] = (255, 255, 255)
-        gap = 15
-        bw = (800 - 5 * gap) // 4
-        bh = (400 - 3 * gap) // 2
-        dark = (0, 0, 0)
-        for r in range(2):
-            for c in range(4):
-                y = gap + r * (bh + gap)
-                x = gap + c * (bw + gap)
-                image[y:y + bh, x:x + bw] = dark
-        cols, rows = detect_grid(image)
-        assert cols == 4
-        assert rows == 2
-
-    def test_1x1(self) -> None:
-        image = _create_test_image(200, 200)
-        image[:, :] = (255, 255, 255)
-        image[20:180, 20:180] = (0, 0, 0)
-        cols, rows = detect_grid(image)
-        assert cols == 1
-        assert rows == 1
-
-    def test_3x3(self) -> None:
-        image = _create_test_image(600, 450)
-        image[:, :] = (255, 255, 255)
-        dark = (0, 0, 0)
-        gap = 10
-        bw = (600 - 4 * gap) // 3
-        bh = (450 - 4 * gap) // 3
-        for r in range(3):
-            for c in range(3):
-                y = gap + r * (bh + gap)
-                x = gap + c * (bw + gap)
-                image[y:y + bh, x:x + bw] = dark
-        cols, rows = detect_grid(image)
-        assert cols == 3
-        assert rows == 3
-
-    def test_uniform_image(self) -> None:
-        image = _create_test_image()
-        cols, rows = detect_grid(image)
-        assert cols == 1
-        assert rows == 1