.kilo/plans/fx-optimization-pipeline.md

# FX Optimizasyon Pipeline — Çalışma Notları

## Tarih: 2026-06-18

## Amaç
Her FX türü (InnerShadow, DropShadow, OuterGlow, InnerGlow, BevelEmboss, Satin, Stroke vb.) için:
1. Photoshop ground-truth PNG'ler üretmek
2. Algoritma parametrelerini MAE ile optimize etmek
3. Başarılı sonuçları ayrı crate olarak kilitlemek

---

## 1. PSD Saver — Photoshop Uyumluluğu

### Problem
`hcie-psd/src/psd_saver.rs` tarafından üretilen PSD dosyaları Photoshop'ta açılmıyordu.

### Kök Nedenler ve Düzeltmeler

| # | Sorun | Düzeltme |
|---|-------|----------|
| 1 | Header ch=4 (RGBA) | ch=3 (RGB) yapıldı |
| 2 | Merged image 4 kanal | 3 kanal (RGB) yapıldı |
| 3 | lfx2 version fields ters | `[0, 16]` sırası düzeltildi |
| 4 | Layer bounds full canvas | `find_content_bounds()` ile auto-crop |
| 5 | write_8bim_block padding | Length field even'a yuvarlandı (PSD spec) |
| 6 | Extra keys (layerConceals, Cntn) | DropShadow, InnerShadow, ColorOverlay'dan kaldırıldı |
| 7 | Ckmt/spread dönüştürme | %→px dönüşümü kaldırıldı, raw pixel değeri yazılıyor |
| 8 | uglg=true | false yapıldı (local angle kullanılıyor) |
| 9 | Contour name "Linear" | "Linear\0" null terminator eklendi |
| 10 | shmd LyrI=0 | LyrI=1 yapıldı |
| 11 | shmd conditional Lefx | Efekt varsa Lefx yazıyor, yoksa yazmıyor |
| 12 | Image Resources eksik | 0x03ED, 0x0408, 0x040D, 0x0414, 0x0419, 0x042D, 0x0435 eklendi |
| 13 | Missing layer blocks | luni, lyid, lsct, lclr, fxrp, lspf eklendi |

### Dosya Yapısı (Yeni)
```
hcie-psd-saver/           ← AYRI CRATE (kilitli)
├── Cargo.toml
└── src/
    ├── lib.rs            ← chmod 555 — save_psd, layer records, merged image
    ├── helpers.rs        ← chmod 555 — w_key4, w_bool, w_enum, w_untf vb.
    └── fx_descriptors.rs ← chmod 644 — AÇIK, 10 efekt writer

hcie-psd/
├── src/lib.rs            ← pub use hcie_psd_saver::save_psd (re-export)
└── Cargo.toml            ← hcie-psd-saver dependency
```

### Korumalar
- `lib.rs` ve `helpers.rs`: chmod 555 (dizin kilitli, dosya kilitli)
- `fx_descriptors.rs`: chmod 644 (açık — AI ajanları sadece burayı düzenler)
- AI ajanı `chmod u+w` bile yapamaz (dizin 555)

---

## 2. Inner Shadow MAE Optimizasyonu

### Adımlar

#### 2a. PSD Set Oluşturma
- `hcie-io/examples/generate_inner_shadow_psd_set.rs`
- 1536 PSD: 4 angle × 3 dist × 2 size × 2 choke × 2 opacity × 2 noise × 2 blend × 4 color
- Renkler: red(220,30,30), green(30,180,30), blue(30,60,220), white(220,220,220)
- Blend modes: normal, multiply
- Canvas: 256×256, siyah rectangle (25% margin)
- Output: `_tmp/inner_shadow_psd_set/`

#### 2b. Photoshop Export
- `_tools/photoshop/export_psd_folder_to_png.jsx` ile batch PNG export
- Output: `_tmp/inner_shadow_png_set/`
- **ÖNEMLİ**: "Export As → PNG → Transparency" kullanın, "Flatten Image" DEĞİL!
- Flatten → beyaz arka plan → MAE patlar

#### 2c. MAE Grid Search
- `hcie-io/examples/tune_mae_inner_shadow_grid.rs`
- 768 sample (noise>0 atlandı) × 384 combo = 294912 evaluation
- Grid: blur_factor[6], passes[4], choke_scale[4], mask_strength[4]
- Content-only comparison: beyaz/shaffaf arka plan pikselleri atlanıyor
- `content_mask` ile sadece şekil+gölge pikselleri karşılaştırılıyor

#### 2d. Sonuçlar
```
Best avg MAE = 11.14
  blur_factor    = 6.0
  passes         = 1
  choke_scale    = 0.00
  mask_strength  = 0.75
```

#### 2e. Parametre Uygulama
- `hcie-fx/src/shadow.rs` → `generate_inner_shadow()` fonksiyonunda sabit değerler güncellendi:
  - blur_factor: 2.5 → 6.0
  - passes: 3 → 1
  - choke: devre dışı
  - mask_strength: 1.0 → 0.75

---

## 3. GUI Example Düzeltmeleri

### `hcie-io/examples/gui.rs`
1. **Blend mode hardcoded Normal** → `composite()` fonksiyonunda `from_blend_mode()` ile gerçek blend mode kullanılıyor
2. **Canvas size yanlış** → PSD header'dan okunuyor (`Psd::from_bytes` ile), `layers[0].width` yerine

---

## 4. Pre-commit Hook Değişiklikleri

- `.git/hooks/pre-commit`: Testleri çalıştırır ama commit'i ASLA engellemez
- `.git/hooks/post-commit`: Sadece semantic log, ağır test yok

---

## 5. Backup

- `_tmp/psd_saver_backup_20260617_212138.zip`: İlk halinin yedeği

---

## 6. Sonraki Adımlar (Diğer FX Türleri İçin)

Her FX türü için aynı pipeline uygulanacak:

### DropShadow
1. `generate_inner_shadow_psd_set.rs`'i kopyala → `generate_drop_shadow_psd_set.rs`
2. Parametre grid: angle, distance, spread, size, opacity, noise, blend, color
3. PSD'leri üret → Photoshop'ta PNG'ye çevir
4. `tune_mae_drop_shadow_grid.rs` yaz
5. MAE grid search çalıştır
6. En iyi parametreleri `hcie-fx/src/shadow.rs` → `generate_shadow()`'a uygula

### OuterGlow / InnerGlow
- Parametreler: spread/choke, size, opacity, noise, blend, color
- `generate_glow()` fonksiyonu `shadow.rs`'da

### BevelEmboss
- Parametreler: style, technique, depth, size, soften, angle, altitude
- `generate_bevel_emboss()` fonksiyonu `shadow.rs`'da (NDL-based)

### Satin
- Parametreler: angle, distance, size, invert, blend, color, opacity

### Stroke
- Parametreler: position (inside/center/outside), fill_type, size, color, opacity

### Her FX için:
1. PSD set oluştur (varyasyonlu renkler, blend modes)
2. Photoshop'ta batch PNG export (Export As, flatten DEĞİL!)
3. MAE grid search (content-only comparison)
4. En iyi parametreleri uygula
5. `hcie-fx/src/` altındaki ilgili dosyayı güncelle
6. Başarılı olursa ayrı crate olarak kilitle

---

## 7. Kritik Dosyalar

| Dosya | Amaç |
|-------|------|
| `hcie-psd-saver/src/lib.rs` | PSD writer — KİLİTLİ |
| `hcie-psd-saver/src/helpers.rs` | PSD descriptor helpers — KİLİTLİ |
| `hcie-psd-saver/src/fx_descriptors.rs` | FX descriptor writers — AÇIK |
| `hcie-fx/src/shadow.rs` | Shadow/glow algoritmaları — MAE güncellendi |
| `hcie-fx/src/tuned.rs` | Tuned shadow algoritmaları (grid search için) |
| `hcie-io/examples/generate_inner_shadow_psd_set.rs` | 1536 PSD üretici |
| `hcie-io/examples/tune_mae_inner_shadow_grid.rs` | MAE grid search |
| `hcie-io/examples/gui.rs` | Test GUI (PNG vs PSD karşılaştırma) |

---

## 8. Komutlar

```bash
# PSD üret
cargo run --example generate_inner_shadow_psd_set -p hcie-io

# MAE grid search (arka planda)
cargo run --example tune_mae_inner_shadow_grid -p hcie-io

# GUI test
cargo run --example gui -p hcie-io

# Ana program
cargo run --bin hcie-gui

# PSD roundtrip test
cargo run --example roundtrip_psd -p hcie-io
```

---

## 9. Uyarılar

- **Flatten Image KULLANMAYIN** — beyaz arka plan MAE'yi patlatır
- **Export As → PNG → Transparency** kullanın
- `hcie-psd-saver/src/lib.rs` ve `helpers.rs` KİLİTLİ — değiştirmeyin
- `fx_descriptors.rs` AÇIK — sadece efekt descriptor'larını düzenleyin
- Pre-commit hook engellemez, ama testleri çalıştırır
- `hcie-fx/src/shadow.rs` locked crate'te değil, doğrudan düzenlenebilir