Hitit Çivi Yazısı OCR Sistemi

Mimari: 2-Aşamalı Pipeline

Aşama 1: İşaret Tespiti (Object Detection)

Model: YOLOv8m (Ultralytics)
Görev: Tablet resminde çivi yazısı işaretlerinin konumlarını tespit et
Çıktı: Bounding box'lar (x, y, w, h)
Multi-GPU: YOLO native DDP (device='0,1,2,3')

Aşama 2: İşaret Sınıflandırma (Classification)

Ana model: ConvNeXt-Small (METHODOLOGY.md §3)
İleri karşılaştırma: DINOv3 ViT-B (frozen + linear head)
Baseline'lar: ResNet50 (Verwimp et al. 2025), EfficientNetV2-S/M
Görev: Tespit edilen her işareti sınıflandır
Çıktı: İşaret adı (195 sınıf, MIN_SIGN_SAMPLES ≥ 20)
Multi-GPU: PyTorch DDP (torchrun) + DistributedWeightedSampler
img_size: 224px

Neden 2-Aşama?

1200+ benzersiz işaret var ama çoğu nadir (long-tail dağılım)
YOLO tek başına bu kadar sınıfla düşük performans verir
2-aşama ile: YOLO sadece "işaret var/yok" tespit eder → sınıflandırıcı tanır

Long-Tail Handling (Literatür-destekli)

Focal Loss + Effective Number Weighting (Cui et al. 2019)
TailMix augmentation (Li et al. 2023 — tail accuracy 18%→46%)
WeightedRandomSampler (sqrt tabanlı)
Macro Accuracy ile model seçimi (Top-1 yerine — long-tail için daha adil)

Değerlendirme

5-Fold Tablet-Bazlı CV (data leak yok — aynı tabletin yüzleri aynı fold'da)
Metrikler: Top-1 Acc, Top-5 Acc, Macro Acc (per-class average)
Not: detection katmanı doğrudan hazırdır; classification tarafında auxiliary unified manifest güçlü pretraining sağlar, fakat Hittite-only final evaluation için hitit_ocr/data/classification/all/ materialization'ının tamamlanmış olması gerekir.

Kurulum & Çalıştırma

# 1. Veri hazırlama (fold_0 default)
python3 src/prepare_data.py --val-fold 0

# 2. YOLO eğitimi — 4 GPU
sbatch scripts/train_yolo_slurm.sh
# veya: python3 src/train_detector.py --gpus 4 --fold 0

# 3. Sınıflandırıcı eğitimi — 4 GPU DDP
sbatch scripts/train_cls_slurm.sh
# veya: torchrun --nproc_per_node=4 src/train_classifier.py --fold 0

# 4. K-Fold CV (tüm fold'lar)
torchrun --nproc_per_node=4 src/train_classifier.py --all-folds

# 5. Inference
python3 src/inference.py --image tablet.jpg

Dosya Yapısı

hitit_ocr/
├── configs/
│   ├── data.yaml            # Veri sabitleri (MIN_SIGN_SAMPLES=20)
│   ├── detection.yaml       # YOLO parametreleri
│   └── classification.yaml  # Classifier parametreleri
├── src/
│   ├── prepare_data.py      # K-Fold veri hazırlama + materialization
│   ├── train_detector.py    # YOLO eğitimi (multi-GPU, K-Fold)
│   ├── train_classifier.py  # Classifier eğitimi (DDP, K-Fold, TailMix)
│   └── inference.py         # Full pipeline inference
├── scripts/
│   ├── train_yolo_slurm.sh  # SLURM: akya-cuda 4xGPU
│   └── train_cls_slurm.sh   # SLURM: akya-cuda 4xGPU DDP
└── data/
    ├── detection/            # YOLO format (all/ + fold_X/)
    └── classification/       # ImageFolder (all/ + train/ + val/)

Referanslar

Verwimp et al. (2025) "Signs of the Past" — ResNet50, Top-1 87.1%, ≥20 instances
Williams et al. (2023) "DeepScribe" — RetinaNet + ResNet, 0.84 mAP
Li et al. (2023) "TailMix" — Oracle bone long-tail, tail acc 18%→46%