# Session notes

Oturumlar arası bağlam aktarımı için tutuluyor. Silinebilir.

---

## Bölüm 1 — ÇÖZÜLDÜ: segmentasyon (animasyon strip'leri + tileset)

Önceki oturumdan kalan iki problem de kapandı. Detay `README.md` §2'de;
burada neyin neden değiştiği özetleniyor.

### Problem 1 — animasyon strip'leri parçalanıyordu

`spritesheet.png` gibi sheet'lerde her kare tek sprite yerine düzinelerce
parçaya bölünüyordu. İki ayrı sebep vardı:

1. Bir karenin parçaları gap-tabanlı birleştirme yarıçapından uzakta.
2. Daha kötüsü: bu parçacıkların çoğu 1-2px olduğu için `find_components`
   onları `MIN_SPRITE_SIZE_PX` altı speckle sayıp ATIYORDU. Kareler
   sadece bölünmüyor, KAYBOLUYORDU (8 karenin 2'si hiç görünmüyordu).
   "Klon" sorunu da buradan geliyordu — kalan özdeş küçük parçaları
   duplicate detector haklı olarak klon işaretliyordu.

**Çözüm:** `detect_separator_grid()` — her kesim çizgisinin tamamen arka
plan olduğu bir periyot+faz arıyor. Böyle bir çizgi hiçbir piksel bloğunu
kesemez. Önceki oturumda takılınan nokta buydu: `_grid_candidate_divisors`
hücre boyutunun sheet boyutunu tam bölmesini şart koşuyordu ve skorlama
iki gerçek sheet arasında çelişiyordu. Yeni dedektör ikisine de ihtiyaç
duymuyor; kesimin doğruluğu içerik istatistiğinden ÇIKARILMIYOR, doğrudan
DOĞRULANIYOR.

İki incelik: **faz da aranmalı** (11px adımlı kafeste boşluklar 8, 19,
30... konumlarında), ve **"en küçük yasal periyot" yetmiyor** (parçacıklı
bir karenin içindeki tesadüfi boş satırdan geçen kesim yasal ama kareyi
ikiye böler; adaylar `hücre sayısı × en dar boşluk` ile puanlanıyor).

`regroup_by_grid()` gap sonucunu bu hücrelere topluyor ve **sadece
birleştirme** yapıyor: gap aşamasının zaten birleştirdiği bir sprite
(yaprak+sap) hücreleri union'lıyor, asla bölünmüyor.

### Problem 2 — `Dungeon_Tileset.png` tek dev blok oluyordu

Grid fallback devreye girmiyordu (eski koşul "en fazla 6 bölge" istiyordu,
sheet'te 21 bölge vardı).

**Çözüm:** aşırı-birleşme koşuluna alan tabanlı dal (bir ekseni baştan
sona kaplayan VE alanın ≥%25'ini yutan bölge) + `detect_tile_grid()` —
hücre adımını sheet'in kendi **kenar periyodikliğinden** okuyor. Kritik
nokta: gerçek adımın her KATI da gerçek tile sınırlarına denk gelir, o
yüzden en yüksek puanı hep en büyük kat alır (16px tileset 32/80 okunur);
bu yüzden "en iyi puana yakın EN KÜÇÜK adım" seçiliyor. İki eksenin aynı
kare hücrede anlaşması da şart — bu, tek eksende periyodik animasyon
sheet'lerini bu yoldan uzak tutuyor.

### Sonuçlar

| sheet | önce | sonra | doğrusu |
|---|---|---|---|
| `spritesheet.png` 128×128 | 7 (2 kare kayıp) | 8 | 8 kare |
| `spritesheet (1).png` 512×256 | 54 | 27 | 27 kare |
| `spritesheet (2).png` 256×256 | 71 | 24 | 24 kare |
| `Dungeon_Tileset.png` 160×160 | 21 (dev blok) | 100 | 100 tile |
| `Dungeon_Tiles.png` 400×400 | 300 | 297 | 300 tile* |

\* 297 = 300 tile, biri 4 hücrelik kompozit obje olarak birleştirildi
(aşağıya bak). Beş sheet'te de kutular tüm ön plan piksellerini kapsıyor
(coverage 1.000).

### Ayrıca: O(n²) ölçeklenme

`merge_related_components` ve güven skorundaki en-yakın-komşu taraması
her çifti karşılaştırıyordu. İkisi de uzamsal indekse alındı; aday
kümeleri kesin testlerin dikkate alacağı çiftlerin üst kümesi olduğu için
**sonuçlar birebir aynı** (brute-force referansa karşı doğrulandı).
2048×2048'lik, ~16k sprite'a bölünen bir sheet: dakikalar → ~2s.

---

## Bölüm 2 — Kompozit objeler (çok hücreye yayılan tek obje)

Grid kesimi karolar için doğru, çok hücreye yayılan objeler için yanlış.
Üç hücreye inen bir merdiven tek şeydir; hücre hücre kesilince tek
başlarına anlamsız üç parça olur ve tekrar eden orta bölümü kendi diğer
yarısının duplicate'i sayılır.

`_composite_cell_groups()` grid kesiminden sonra **tek bir bağlı çizim
parçasına** ait hücreleri tekrar birleştiriyor. İki incelik:

- Test **bağlı-bileşen kimliği**, "iki komşu hücre sınırda değiyor mu"
  DEĞİL. Bunlar eşdeğer görünür ama değildir: iki düz dolgu karosu tüm
  ortak kenarları boyunca değer ve saçma bir sprite'a kaynaşır. (Önce
  bunu denedim, `Dungeon_Tileset.png`'de tam olarak bunu yaptı.)
- Kimlik de tek başına yetmiyor: zindanın zemini ve duvarları da tek
  devasa bağlı bölge. Ayıran şey büyüklük — kompozit obje birkaç hücre
  (`GRID_COMPOSITE_MAX_CELLS`, varsayılan 6), arazi düzinelerce.

**Bilinen sınır (açıkça yazıyorum):** bu sadece obje kendi başına bir
çizim adasıysa çalışıyor. `Dungeon_Tileset.png`'de sütunlar ve kapı
çevredeki araziye DEĞECEK şekilde çizilmiş — üst bölge tamamı 17.399
piksellik tek opak ada, sheet'in %68'i — yani hiçbir yerel kural bunları
zemini de kaynaştırmadan ayıramaz. Onlar için elle **Merge** aracı var.
Kendi arka planı üzerinde duran objeler (yaygın durum) otomatik hallediliyor.

---

## Bölüm 3 — Dataset kalitesi (yeni)

Sprite'ları doğru kesmek işin yarısı. Diğer yarısı sonucun eğitilmeye
değer olup olmadığı — farklı bir soru, farklı hata biçimleri. Detay
`README.md` §3'te.

- **`auto_tagger.py`** — kategori/style/tag önerisi. En güçlü sinyal
  **provenans**: tile grid'den çıkan sprite tileset karosudur, separator
  grid'den çıkan animasyon karesidir. Bunlar içerik tahmini değil, nasıl
  üretildiğine dair gerçek. `AUTO_TAG_MIN_CONFIDENCE` altında KATEGORİ
  "unknown"a düşer (yanlış kategori boş kategoriden kötüdür); style
  iddiaları piksellerin destekleyebileceğiyle sınırlı (4 renk = Game Boy
  DEĞİL; `gameboy` sadece gerçek 4-tonlu monokrom rampa için, NES tahmini
  yok). Her otomatik satır insan dokunana kadar `auto_tagged=1` taşıyor.
- **Toplu atama** (`POST /api/batch/assign`) — kapsam: aktif sheet / tüm
  pending / hepsi. Etiketler **varsayılan olarak eklemeli**, böylece
  toplu geçiş auto-tagger'ın sprite başına bulduklarını ezmiyor.
- **`POST /api/batch/dedupe-keep-one`** — duplicate zincirini
  **geçişli** takip edip (#40 → #12 → #3 tek kümedir) her kümeden en iyi
  puanlıyı tutuyor, gerisini reddediyor. "Reject Duplicates"tan farkı:
  bir tileset aynı zemin karosunu meşru olarak onlarca kez tekrar eder.
- **Train/val/test** (`dataset_manager.assign_split`) — deterministik
  (hash, shuffle değil) ve **sheet bazlı gruplu**. Animasyonun 24 karesi
  neredeyse aynı görüntüler; sprite bazlı bölmek kare 7'yi train'e kare
  8'i test'e koyar ve skor ezberi ölçer. Az sayıda sheet varken bir bölüm
  boş kalabilir — split önizlemesi bunu saklamak yerine söylüyor.
- **`dataset_report.py`** — kompozisyon uyarıları (bir sınıf >%60, çok
  ince sınıflar, çoğu metadata denetlenmemiş, tek kaynak sheet, tek
  çözünürlük) + kalite skoru kalibrasyonu. Kalibrasyon **çoğunluk taban
  çizgisini** de raporluyor: en iyi eşik "hep büyük sınıfı tahmin et"i
  ancak geçiyorsa, uydurma bir öneri yerine "bu skor senin kararlarını
  ayırmıyor, elle incelemeye devam et" diyor.
- **Animasyon önizleme** (`GET /api/animation/frames`) — kareler
  **orijinal sheet konumlarına** göre ortak bir tuvale yerleştiriliyor.
  Sıkı kırpılmış crop'ları arka arkaya oynatmak animasyonu titretir.

## Test durumu

100/100 geçiyor: segmentation 26, dataset 20, api 14, auto_tagger 12,
extraction 10, duplicates 10, background 8.

`test_dataset.py` ve `test_api.py` `config.DB_PATH`'i geçici bir dosyaya
yönlendirip `database`'i reload ediyor, yani Space'in gerçek verisine
dokunmuyorlar (doğrulandı).

## Hâlâ yapılmadı

- Arayüzde segmentasyon modu seçici / "Force grid size" alanı yok.
  `segment_sheet(mode=...)` üç modu da destekliyor ("auto", "gap",
  "grid") ama `analyzer.process_sheet` her zaman "auto" çağırıyor;
  bunu bir API parametresi olarak dışarı açmak küçük bir iş.
- Kompozit birleştirme, objenin araziye değdiği durumları çözemiyor
  (yukarıda "bilinen sınır"). Bunun için semantik bir model gerekir.