code/README.md

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