hcie-rust-v3.05/.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

# 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