| # 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 |
| |
| ```bash |
| # 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% |
| |
