Architecture Архитектура

Processing pipeline architecture, technology stack, and data flow for the Family Photo Archive. Архитектура конвейера обработки, технологический стек и поток данных семейного фотоархива.

Pipeline Overview Обзор конвейера

The processing pipeline takes raw flatbed scanner scans (600 DPI, 4960x7014) through 10 stages to produce a fully tagged, restored, and browsable photo archive. Конвейер обработки проводит необработанные сканы с планшетного сканера (600 DPI, 4960x7014) через 10 этапов для создания полностью размеченного, восстановленного и доступного для просмотра фотоархива.

Step 1: Scanner Profile Шаг 1: Профиль сканера

Multiple white border scans are averaged to build a scanner profile that detects color cast, vignetting, and dust spots. This profile is used to normalize all subsequent scans. Несколько сканов белых полей усредняются для построения профиля сканера, который определяет цветовой сдвиг, виньетирование и пылинки. Этот профиль используется для нормализации всех последующих сканов.

Step 2: Flat-Field Correction Шаг 2: Коррекция плоского поля

The original scan is divided by the scanner profile to produce a clean scan with uniform lighting and no scanner artifacts. Исходный скан делится на профиль сканера для получения чистого скана с равномерным освещением и без артефактов сканера.

Original Scan / Scanner Profile = Clean Scan

Step 3: Auto-Crop Шаг 3: Автоматическая обрезка

OpenCV detects photo boundaries via grayscale conversion, blur, thresholding, and contour detection. A 1% over-crop removes printed borders and rounded corners. OpenCV определяет границы фотографии с помощью преобразования в градации серого, размытия, пороговой обработки и обнаружения контуров. Перекадрирование в 1% удаляет печатные рамки и закруглённые углы.

Step 4: Color Correction Шаг 4: Цветокоррекция

Subject-weighted correction using saliency maps. Three passes: white balance (subject-weighted gray-world), auto levels (gentle, 0.5% clip), and CLAHE on LAB L-channel (clip=1.5). Коррекция с учётом объекта на основе карт значимости. Три прохода: баланс белого (серый мир с учётом объекта), автоуровни (мягкие, отсечка 0.5%) и CLAHE на L-канале LAB (clip=1.5).

Steps 5-6: AI Restoration & Colorization Шаги 5-6: ИИ-реставрация и колоризация

Face restoration uses GFPGAN/CodeFormer, noise reduction uses Real-ESRGAN (all with MPS acceleration). B&W/sepia photos are auto-detected and colorized with DDColor via Apple Metal. Реставрация лиц использует GFPGAN/CodeFormer, шумоподавление - Real-ESRGAN (всё с ускорением MPS). Чёрно-белые/сепия фотографии автоматически определяются и раскрашиваются с помощью DDColor через Apple Metal.

Step 7: Face Clustering Шаг 7: Кластеризация лиц

InsightFace extracts 512-dimensional face embeddings, then DBSCAN clusters them into identity groups. This enables browsing by person across the entire archive. InsightFace извлекает 512-мерные эмбеддинги лиц, затем DBSCAN кластеризует их в группы по идентичности. Это позволяет просматривать архив по людям.

Steps 8-9: AI Tagging & OCR Шаги 8-9: ИИ-тегирование и ОРТ

Front photos are tagged by GPT-4o/Gemini (description, era, tags, mood, people count, setting). Back photos are processed by Apple Vision for Cyrillic OCR, translation, and date/name extraction. Лицевые стороны фотографий тегируются GPT-4o/Gemini (описание, эпоха, теги, настроение, количество людей, обстановка). Обратные стороны обрабатываются Apple Vision для распознавания кириллического текста, перевода и извлечения дат/имён.

Technology Stack Технологический стек

Data Flow Поток данных

Input photos are processed through the pipeline and output into layered directories, each representing a stage of processing. Входные фотографии проходят через конвейер и сохраняются в многослойные директории, каждая из которых представляет этап обработки.

Metadata Structure Структура метаданных

Each photo produces a JSON metadata file containing processing parameters, AI tags, OCR results, and face data: Для каждой фотографии создаётся JSON-файл метаданных, содержащий параметры обработки, ИИ-теги, результаты ОРТ и данные о лицах:

{
  "source": "photos/Scanned-image...-1.jpg",
  "crop": { "box": [x1, y1, x2, y2], "overcrop": 1.0 },
  "scanner_fix": { "color_cast": [r, g, b], "vignette": true },
  "color_correct": { "white_balance": 0.5, "clahe": 1.5 },
  "tags": {
    "description": "Family gathering outdoors...",
    "estimated_era": "1970s",
    "people_count": 4,
    "tags": ["family", "outdoor", "summer", "park"],
    "mood": "happy"
  },
  "back_text": {
    "original_text": "\u041b\u0435\u0442\u043e 1978, \u0425\u0430\u0439\u0444\u0430",
    "translation": "Summer 1978, Haifa",
    "text_type": "date+location"
  },
  "faces": [
    { "cluster_id": 0, "name": "Boris", "bbox": [x, y, w, h] },
    { "cluster_id": 1, "name": "Marina", "bbox": [x, y, w, h] }
  ]
}

Comparison Slider UX Интерфейс сравнения

The web viewer includes a comparison slider for viewing processing layers side-by-side. Users can compare any two layers (Original, Scanner-fixed, Cropped, Corrected, Restored, Colorized) using a draggable slider, side-by-side view, or blend mode with difference visualization. Веб-просмотрщик включает слайдер сравнения для просмотра слоёв обработки бок о бок. Пользователи могут сравнивать любые два слоя (Оригинал, Исправленный от сканера, Обрезанный, С цветокоррекцией, Восстановленный, Раскрашенный) с помощью перетаскиваемого слайдера, параллельного просмотра или режима смешивания с визуализацией разницы.