CeramicNet

CeramicNet — проект для поиска клейм на старинных керамических изделиях и их сопоставления с каталогом эталонов.

Как это работает

1. Фото изделия: на вход подается обычная фотография тарелки, чашки или вазы (обычно снимок донца с клеймом).
2. Детекция (RT-DETR v2-S): нейросеть находит область клейма и вырезает ее.
3. Предобработка (CLAHE): алгоритм убирает засветы, проявляет затертые линии рельефа и приводит картинку к квадрату $224 \times 224$ px.
4. Векторизация (Энкодер клейм): энкодер превращает изображение клейма в вектор из 384 чисел, описывающий его геометрическую форму.
5. Поиск по базе: вектор сравнивается со всеми эталонами из каталогов по косинусному сходству за пару миллисекунд.
6. Результат: список наиболее похожих клейм из справочников с указанием завода, книги, страницы и процента совпадения.

Модели

• Детектор (RT-DETR v2-S) — локализует клеймо на керамике (weights/detection_weights/rtdetr_v2_s.onnx). Точный безанкорный трансформерный детектор (end-to-end без NMS), обученный находить клейма и устойчивый к фоновым элементам (орнаментам, трещинам, дефектам глазури).
• Энкодер (student_encoder_katya) — извлекает компактные признаки клейма (weights/retrieval_weights/student_encoder_katya.onnx). Дистиллированная модель, обученная сопоставлять реальные фрагменты керамики с эталонными оттисками из книг.
• Индекс эталонов — готовая база клейм из справочников, сохраненная в виде матрицы векторов в файле data/books_index/books_index_student_encoder_katya.npz. Новые клейма можно добавлять в базу без переобучения моделей.

Установка

Требуется Python версии 3.9 или выше.

git clone https://github.com/mmmishaa/CeramicNet
cd CeramicNet

python -m venv .venv
source .venv/bin/activate  # Для Linux/macOS
# .venv\Scripts\activate   # Для Windows

pip install -r requirements.txt

Подготовка к работе

Для первого запуска системы нужно выполнить два простых шага:

Шаг 1. Скачать модели и справочники с Google Drive

По умолчанию скачивается только необходимый рабочий набор: веса актуального детектора (rtdetr_v2_s.onnx), энкодера (student_encoder_katya.onnx) и архив справочников клейм (books.zip):

Для получения доступа к архиву и ID папки на Google Drive обратитесь к авторам репозитория.

python -m scripts.download_artifacts --folder_id <ID_ПАПКИ_GOOGLE_DRIVE>

Скрипт загрузит веса в weights/ и распакует справочники в data/books/.

Шаг 2. Собрать поисковый индекс эталонов

Перед первым запуском необходимо один раз собрать векторный индекс по справочникам (если готовый .npz не был скачан):

python scripts/build_index.py

Скрипт пропустит все эталонные клейма из data/books/ через энкодер и сохранит векторную базу в data/books_index/books_index_student_encoder_katya.npz.

После этого система полностью готова к поиску и распознаванию.

---

Дополнительные режимы загрузки артефактов

• Полная загрузка для разработки (--dev): скачивает все файлы, включая полный датасет обучающих фотографий керамики (ceramic_dataset.zip) и экспериментальные веса:

  python -m scripts.download_artifacts --folder_id <ID_ПАПКИ> --dev

• Выборочная загрузка: можно скачать только отдельные категории артефактов через флаги --detection, --retrieval, --books, --dataset:

  # Скачать только справочники клейм
  python -m scripts.download_artifacts --folder_id <ID_ПАПКИ> --books

• Просмотр файлов в папке без скачивания:

  python -m scripts.download_artifacts --folder_id <ID_ПАПКИ> --list

Использование (main.py)

Вся работа с системой выполняется через скрипт main.py.

Тест на случайном фото из датасета

Запуск пайплайна на случайном снимке с показом окна с результатом:

python main.py --random 1 --show

Проверка своего изображения

python main.py --input path/to/plate.jpg --show

Пакетная обработка папки с фото

python main.py --input path/to/folder/ --top-k 5

Поиск по уже вырезанному клейму (без детектора)

Если у вас уже есть кроп клейма, детектор можно отключить флагом --no-detect:

python main.py --input path/to/stamp.png --no-detect --show

Настройка числа выводимых кандидатов

python main.py --input path/to/plate.jpg --top-k 5 --show

Основные аргументы main.py:

• --input <путь> — путь к файлу изображения или к папке с изображениями.
• --random [N] — взять N случайных снимков из датасета (по умолчанию 1).
• --top-k <число> — сколько похожих клейм выводить в ответе (по умолчанию 10).
• --no-detect — отключить детектор и передать изображение напрямую в энкодер.
• --show — открыть окно с визуализацией: исходное фото, рамка детекции и найденные эталоны.
• --model <имя> — альтернативная модель энкодера из конфига (по умолчанию активная student_encoder_katya).
• --detection-config <путь> — путь к конфигу детектора (по умолчанию configs/detection/detection_config.yaml).
• --retrieval-config <путь> — путь к конфигу ретривала (по умолчанию configs/retrieval/retrieval_config.yaml).

Структура проекта

CeramicNet/
├── configs/                   # Конфигурационные файлы
│   ├── detection/             # Пороги и параметры детектора
│   └── retrieval/             # Параметры энкодеров и каталогов
├── data/                      # Данные (скачиваются скриптом)
│   ├── books/                 # Сканы справочников клейм
│   ├── books_index/           # Векторный индекс эталонов (.npz)
│   └── ceramic_dataset/       # Фотографии керамики (при флаге --dev)
├── notebooks/                 # Ноутбуки обучения (Kaggle / ClearML)
│   ├── detection/yolo/        # Обучение YOLO26s
│   └── retrieval/             # Обучение энкодера DINOv2
├── scripts/                   # Вспомогательные скрипты
│   ├── build_index.py         # Построение векторного индекса эталонов
│   └── download_artifacts.py  # Скачивание весов и данных с Google Drive
├── src/                       # Исходный код системы
│   ├── detection/             # Модуль детекции на ONNX Runtime
│   ├── retrieval/             # Энкодер DINOv2, индекс, книги
│   └── pipeline.py            # Логика сквозного пайплайна
├── weights/                   # Веса моделей ONNX
└── main.py                    # Главная точка входа