Update README.md

README.md

@@ -1,3 +1,285 @@
----
-license: apache-2.0
----
+---
+---
+license: apache-2.0
+language:
+- ru
+- en
+base_model:
+- facebook/convnext-tiny-224
+- facebook/dinov2-small
+pipeline_tag: image-classification
+tags:
+- manuscript
+- bookbinding
+- cultural-heritage
+- digital-humanities
+- convnext
+- fine-tuned
+library_name: timm
+---
+
+# Kleine-Marchen — Binding Detector (ConvNeXt-Tiny)
+
+Модель на базе **ConvNeXt-Tiny (ImageNet-22k)** для определения является ли изображение фотографией переплёта рукописи.
+
+Используется как **первая ступень** в двухэтапном пайплайне классификации переплётов рукописей РГБ.
+
+---
+
+## Назначение
+
+Бинарная классификация:
+
+- **Класс 1 — переплёт**: изображение является фотографией крышки переплёта рукописи
+- **Класс 0 — не переплёт**: страница текста, разворот, предметная съёмка и т.д.
+
+Модель решает задачу фильтрации при массовом скачивании изображений из цифровых архивов рукописей, где первые страницы оцифровки содержат как переплёты, так и текстовые страницы.
+
+---
+
+## Метрики
+
+| Метрика | Значение |
+|---|---|
+| Accuracy (валидация) | **96%** |
+
+---
+
+## Данные
+
+- **Источник**: фотографии из фондов РГБ
+- **Размер**: ~500 изображений на каждый класс
+- **Классы**: переплёт / не переплёт (страницы текста, развороты)
+- **Разрешение при обучении**: 320×320 px
+
+---
+
+## Архитектура
+
+**Базовая модель**: `convnext_tiny.fb_in22k` (ImageNet-22k pretrain, 28M параметров)
+
+**Стратегия обучения**: обучение только классификационной головы при замороженном бэкбоне.
+
+---
+
+## Использование
+
+Готовые скрипты доступны в репозитории:
+
+**[https://github.com/Infarondus/Kleine-marchen](https://github.com/Infarondus/Kleine-marchen)**
+
+### Быстрый старт
+
+```python
+import torch
+import timm
+import numpy as np
+from PIL import Image
+import albumentations as A
+from albumentations.pytorch import ToTensorV2
+
+IMAGE_SIZE = 320
+
+transform = A.Compose([
+    A.LongestMaxSize(max_size=IMAGE_SIZE),
+    A.PadIfNeeded(min_height=IMAGE_SIZE, min_width=IMAGE_SIZE,
+                  border_mode=0, value=[255, 255, 255]),
+    A.Normalize(mean=[0.485, 0.456, 0.406],
+                std=[0.229, 0.224, 0.225]),
+    ToTensorV2(),
+])
+
+device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
+model  = timm.create_model('convnext_tiny_in22k', pretrained=False, num_classes=2)
+ckpt   = torch.load('kleine-marchen_preprocess.pth', map_location=device, weights_only=False)
+model.load_state_dict(ckpt['model_state_dict'])
+model.to(device).eval()
+
+img    = np.array(Image.open('page.jpg').convert('RGB'))
+tensor = transform(image=img)['image'].unsqueeze(0).to(device)
+with torch.no_grad():
+    probs = torch.softmax(model(tensor), dim=1)[0]
+
+print(f"Не переплёт: {probs[0]:.1%} | Переплёт: {probs[1]:.1%}")
+```
+
+---
+
+## Место в пайплайне
+
+Эта модель используется совместно с `binding-srednik-dinov2`:
+
+```
+Изображение → [ConvNeXt: переплёт?] → [DINOv2: есть средник?] → Результат
+```
+
+Скрипт двухступенчатого скрапера `scrape_bindings_v2.py` из репозитория **Kleine-Marchen** реализует этот пайплайн полностью.
+
+---
+
+## Ограничения
+
+- Не предназначена для определения типа переплёта или его элементов — только факт наличия переплёта на снимке
+- При сильно нестандартных условиях съёмки (белый фон, крупный план фрагмента) точность может снижаться
+
+---
+
+# Kleine-Marchen — Binding Srednik Detector (DINOv2 Ensemble)
+
+Ансамбль из 5 моделей на базе **DINOv2 ViT-Small** для классификации переплётов рукописей по наличию **средника** — центрального декоративного элемента крышки переплёта.
+
+Модель разработана в рамках исследования рукописного фонда Российской государственной библиотеки (РГБ).
+
+---
+
+## Назначение
+
+Модель решает задачу бинарной классификации изображений переплётов:
+
+- **Класс 1 — со средником**: на крышке переплёта присутствует средник
+- **Класс 0 — без средника**: средник отсутствует
+
+Модель предназначена для автоматической предварительной сортировки больших коллекций фотографий переплётов рукописей. Окончательная верификация результатов производится специалистом.
+
+---
+
+## Метрики
+
+Оценка проводилась методом 5-fold стратифицированной кросс-валидации.
+
+| Метрика | Значение |
+|---|---|
+| Accuracy (OOF Ensemble) | **94.50%** |
+| F1-macro (OOF Ensemble) | **0.9450** |
+| Precision | 0.9454 |
+| Recall | 0.9450 |
+
+**Confusion Matrix (OOF, все 5 фолдов):**
+
+|  | Предсказано: без средника | Предсказано: со средником |
+|---|---|---|
+| **Реально: без средника** | 471 | 20 |
+| **Реально: со средником** | 34 | 457 |
+
+---
+
+## Данные
+
+- **Источник**: фотографии переплётов рукописей из фондов РГБ
+- **Размер обучающей выборки**: 567 изображений на каждый класс (1134 итого)
+- **Формат**: цветные фотографии переплётов на тёмном фоне
+- **Разрешение при обучении**: 280×280 px
+
+Датасет собирался итеративно: после каждого цикла обучения производился анализ ошибок и доразметка сложных случаев (изношенные переплёты, пограничные экземпляры).
+
+---
+
+## Архитектура
+
+**Базовая модель**: `vit_small_patch14_dinov2.lvd142m` (DINOv2 ViT-Small, 22M параметров)
+
+**Голова классификатора**:
+```
+LayerNorm(384) → Linear(384→256) → GELU → Dropout(0.3) → Linear(256→2)
+```
+
+**Стратегия обучения**: двухфазный fine-tuning
+- Фаза 1 (6 эпох): обучение только головы, LR = 5e-4
+- Фаза 2 (20 эпох): голова + последние 4 блока ViT, дифференциальный LR (голова: 3e-5, бэкбон: 2e-6)
+
+**Ансамбль**: 5 моделей (по одной на каждый фолд) с усреднением вероятностей + TTA (5 аугментаций)
+
+---
+
+## Использование
+
+Готовые скрипты для обучения, оценки и инференса доступны в репозитории:
+
+**[https://github.com/Infarondus/Kleine-marchen](https://github.com/Infarondus/Kleine-marchen)**
+
+### Быстрый старт
+
+```python
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+import timm
+import numpy as np
+from PIL import Image
+import albumentations as A
+from albumentations.pytorch import ToTensorV2
+
+MODEL_NAME   = 'vit_small_patch14_dinov2.lvd142m'
+IMAGE_SIZE   = 280
+DINO_MEAN    = [0.485, 0.456, 0.406]
+DINO_STD     = [0.229, 0.224, 0.225]
+
+def build_model():
+    backbone = timm.create_model(
+        MODEL_NAME, pretrained=False, num_classes=0,
+        img_size=IMAGE_SIZE, dynamic_img_size=True,
+    )
+    head = nn.Sequential(
+        nn.LayerNorm(backbone.embed_dim),
+        nn.Linear(backbone.embed_dim, 256),
+        nn.GELU(),
+        nn.Dropout(0.3),
+        nn.Linear(256, 2),
+    )
+    class DinoClassifier(nn.Module):
+        def __init__(self, b, h):
+            super().__init__()
+            self.backbone, self.head = b, h
+        def forward(self, x):
+            return self.head(self.backbone(x))
+    return DinoClassifier(backbone, head)
+
+transform = A.Compose([
+    A.LongestMaxSize(max_size=IMAGE_SIZE),
+    A.PadIfNeeded(min_height=IMAGE_SIZE, min_width=IMAGE_SIZE,
+                  border_mode=0, value=[255, 255, 255]),
+    A.Normalize(mean=DINO_MEAN, std=DINO_STD),
+    ToTensorV2(),
+])
+
+# Загрузка модели
+device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
+model  = build_model().to(device)
+ckpt   = torch.load('fold_1_km.pth', map_location=device, weights_only=False)
+model.load_state_dict(ckpt['model_state_dict'])
+model.eval()
+
+# Инференс
+img    = np.array(Image.open('binding.jpg').convert('RGB'))
+tensor = transform(image=img)['image'].unsqueeze(0).to(device)
+with torch.no_grad():
+    probs = F.softmax(model(tensor), dim=1)[0]
+
+print(f"Без средника: {probs[0]:.1%} | Со средником: {probs[1]:.1%}")
+```
+
+### Рекомендуемый порог
+
+При использовании ансамбля рекомендуется порог **0.55–0.75** для класса «со средником» в зависимости от допустимого уровня ложных срабатываний.
+
+---
+
+## Ограничения
+
+- Модель обучена на фотографиях переплётов РГБ и может хуже работать на изображениях из других коллекций (domain shift)
+- Сильно изношенные переплёты с плохо читаемым средником являются наиболее сложными случаями
+- Не предназначена для работы с изображениями страниц, не являющихся переплётами — для фильтрации используйте модель `binding-detector-convnext` на первом этапе
+
+---
+## Цитирование
+Если вы используете эту модель в исследовании, пожалуйста, укажите репозиторий:
+```
+@misc{kleine-marchen-binding,
+  author = {Infarondus},
+  title  = {Kleine-Marchen — Binding Detector (ConvNeXt-Tiny)},
+  year   = {2026},
+  url    = {https://github.com/Infarondus/Kleine-marchen}
+}
+```
+
+---