Infarondus
/

Klein-marchen_Base

@@ -1,282 +0,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}
-}
-```