171 lines
11 KiB
Markdown
171 lines
11 KiB
Markdown
# KRA Optimize Plan — Krita .kra İthalat ve İhracat Optimizasyonu
|
||
|
||
## Hedef
|
||
|
||
Krita tarafından yazılmış/beklenen `.kra` dosyaları için hem **ihracat (export)** hem de **ithalat (import)** performansını, boyutunu ve açılış doğruluğunu optimize etmek. Ayrıca Krita’da açılan PSD-benzeri layer stillerinin (drop shadow, inner shadow, outer glow, inner glow, bevel/emboss, stroke, color/gradient/pattern overlay, satin) HCIE içinde Photoshop referansına yakın görünmesini sağlamak.
|
||
|
||
## Kapsam
|
||
|
||
- `hcie-kra/src/lib.rs` — KRA ithalatı (maindoc.xml + VERS tile decoder + layerstyles.asl)
|
||
- `hcie-kra/src/kra_saver.rs` — KRA ihracatı (maindoc.xml + VERS tile encoder + SVG shapelayer)
|
||
- `hcie-io/examples/` — referans KRA seti üreten/tune eden yeni örnekler
|
||
- Gerekirse `hcie-fx` ASL parser’ı genişletmeleri (ama `hcie-fx` locked crate; sadece gerekirse unlock)
|
||
- Gerekirse `hcie-protocol::effects::LayerEffect` renk/birim haritalamaları için eşleme güncellemeleri (locked crate; sadece gerekirse unlock)
|
||
|
||
## Bugünkü Durum
|
||
|
||
`hcie-kra` çift yönlü çalışıyor fakat birkaç zayıf noktası var:
|
||
|
||
### İthalat Zafiyetleri
|
||
|
||
1. **Tile decoder sınırlı**:
|
||
- Sadece `LZF` ve raw tile compression destekliyor; Krita’nın bazı yeni varyantları (`DATA`, `RAW`, `RLE`, deflate, zlib, store) desteklenmiyor.
|
||
- `parse_vers_tiles` her satırı `from_utf8_lossy` ile tarıyor; bu yavaş ve binary-tolerant değil.
|
||
- Header parsing header string üzerinden yapılıyor; DATA offset hesabı hataya açık.
|
||
2. **Layer file discovery kırılgan**:
|
||
- `find_layer_file` çok fazla aday suffix deniyor; `filename` bazen XML’de tam yol (`layers/xxx.png`) veriliyor, bazen de göreli.
|
||
- VERS tile’ın `.defaultpixel` dosyası olmayınca tile tamamen 0 doluyor; default pixel hesabı hatalı.
|
||
3. **ASL layerstyle parse**:
|
||
- `hcie_fx::parse_asl_styles` KRA’daki `layerstyles.asl` üzerinden dönüyor.
|
||
- Renk değerleri, teknik (technique), soften, v.b. protokole aktarılıyor; bazı enum mapping’ler `format!("{:?}", ...)` ile string yapılıyor ve `hcie-engine-api` içinde tekrar parse ediliyor, bu hata kaynağı.
|
||
4. **Bellek**:
|
||
- Her layer tam canvas boyutunda `Vec<u8>` oluşturuyor (canvas_w * canvas_h * 4). Büyük dosyalarda çok pahalı.
|
||
5. **Shape/Text layer**:
|
||
- `vectorlayer`/`shapelayer` farkı parse edilmiyor; Krita’nın SVG layer’ları sadece `LayerType::Vector` olarak alınıyor, Krita’ya export edilirken `content.svg` yazılıyor fakat import edilirken okunmuyor.
|
||
|
||
### İhracat Zafiyetleri
|
||
|
||
1. **Tile format**:
|
||
- Her tile 64×64, sadece LZF v1 (literaller 32 bayt) kullanılıyor; Krita 5/6 bazı durumlarda farklı tile boyutu, farklı sıkıştırma bekleyebilir.
|
||
- Tile’lar `has_content` kontrolüyle atılıyor; default pixel dolu olmayan transparent layer’lar Krita’da eksik görünebilir.
|
||
2. **Layer attributes**:
|
||
- `x="0" y="0"` sabit; orijinal layer offsetleri kayboluyor.
|
||
- `parent_id` / grouplayer hiyerarşisi KRA’ya yazılmıyor.
|
||
- `fill_opacity`, `clipping_mask`, `locked`, `collapsed` vb. XML’e aktarılmıyor.
|
||
3. **Layer styles export**:
|
||
- `hcie-kra` layer styles ihracatı yapmıyor (`layerstyles.asl` üretilmiyor).
|
||
- Krita’da açıldığında HCIE’de ayarlanan drop shadow / bevel emboss gibi efektler kaybolur.
|
||
4. **Sıkıştırma**:
|
||
- Tüm ZIP içeriği `Stored` (sıkıştırılmamış). KRA dosyaları gereksiz yere büyük.
|
||
|
||
### Genel Doğruluk
|
||
|
||
- KRA ↔ HCIE ↔ PSD üçgeninde round-trip test yok.
|
||
- `hcie-fx` MAE tune scriptleri sadece PSD üzerinden çalışıyor; KRA referansları yok.
|
||
|
||
## Yapılacaklar
|
||
|
||
### Aşama 1: İthalat Optimizasyonu ve Robustluk
|
||
|
||
**Hedef:** Daha büyük, daha çeşitli KRA dosyalarını hızlı ve doğru açmak.
|
||
|
||
1. **Tile decoder yeniden yazımı**
|
||
- `parse_vers_tiles` binary-safe hale getir: header satırlarını `
|
||
` üzerinden ayır ama ardından `DATA` sonrası binary blokları doğrudan oku.
|
||
- `TILEWIDTH`/`TILEHEIGHT`/ `PIXELSIZE` / `DATA` parse mantığını ayrı bir `VersHeader` struct’ına çek.
|
||
- Hatalı tile’ları atlayıp geri kalanını decode et (graceful degradation).
|
||
2. **Compression desteği genişletme**
|
||
- `LZF` zaten var; `RAW` (literal copy) ve `RLE`-benzeri varyantları ekle.
|
||
- Zlib/deflate tile payload’larına destek ekle (Krita 5 bazen kullanıyor).
|
||
3. **Default pixel mantığı**
|
||
- Eğer layer’ın `.defaultpixel` dosyası yoksa ve hiç tile yoksa, layer’ı tamamen transparent kabul et; canvas boyutunda 0 buffer yerine lazy olarak bir solid renk maskesi üret.
|
||
4. **Layer file discovery hızlandırma**
|
||
- `find_layer_file` yerine önce XML’deki `filename`’ı olduğu gibi dene, sonra normalize et.
|
||
- `archive.file_names()` HashSet’e çevir; `O(1)` lookup.
|
||
5. **Memory optimization**
|
||
- `Layer::from_rgba` canvas boyutunda allocate ediyor; KRA importunda bu gerekli ama sparse tile layer’lar için tile-based `LayerData` kullanmak daha iyi. Protokole dokunmadan `hcie-kra` içinde tile cache’den doğrudan `hcie-tile` formatına dönüştürme seçeneği ekle (opsiyonel).
|
||
6. **Shape/Text import**
|
||
- `shapelayer` nodetype için SVG parse desteği ekle: `content.svg` dosyasını oku, `VectorShape` listesine çevir (basit `<path>`, `<rect>`, `<ellipse>`, `<text>` tagleri).
|
||
- `textlayer`/`adjustmentlayer` için uygun placeholder behavior belirle (şimdilik rasterize veya skip).
|
||
|
||
### Aşama 2: İhracat Optimizasyonu ve Boyut
|
||
|
||
**Hedef:** Daha küçük, Krita uyumlu KRA dosyaları üretmek.
|
||
|
||
1. **ZIP compression**
|
||
- `zip::CompressionMethod::Deflated` kullan; en hızlı/iyi oran için compression level 6 (Krita default).
|
||
2. **Tile sıkıştırma iyileştirmesi**
|
||
- LZF encoder’ı daha büyük literallerle (64 bayt+) çalışacak şekilde güncelle; tekrarlayan satırlar için back-ref kullan.
|
||
3. **Layer offset ve hiyerarşi**
|
||
- `x`, `y` değerlerini layer boundary’den hesapla ve XML’e yaz.
|
||
- `parent_id`’ye göre `grouplayer` ve iç içe layer yapısını `maindoc.xml`’e yaz.
|
||
4. **Layer styles export (ASL üretimi)**
|
||
- `hcie-fx` ASL writer yok. Eğer KRA’daki efektleri Krita’da görmek istiyorsak, `hcie-kra` içinde basit bir ASL binary writer implemente et veya `hcie-fx`’e yeni writer ekle.
|
||
- Öncelik: Drop Shadow, Inner Shadow, Outer Glow, Inner Glow, Stroke, Color Overlay, BevelEmboss.
|
||
- Her effect için UUID üret, `<layer layerstyle="{uuid}" ... />` yaz, `layerstyles.asl` olarak ZIP’e ekle.
|
||
5. **Default pixel**
|
||
- Tamamen tek renk (solid) layer’lar için tile yerine sadece `.defaultpixel` yaz; Krita bunu destekliyor.
|
||
6. **Merged image / preview**
|
||
- `mergedimage.png` ve `preview.png` zaten yazılıyor; preview 256×256 thumbnail olarak scale edilebilir.
|
||
|
||
### Aşama 3: Krita Efekt Doğruluğu (MAE Döngüsü)
|
||
|
||
**Hedef:** KRA formatı üzerinden Krita’ya yazılan HCIE efektleri, Krita tarafından render edilip tekrar açıldığında Photoshop referansına yakın olsun. Bu aynı zamanda HCIE’nin kendi renderer’ını da doğrulayan bir çapraz test olacak.
|
||
|
||
1. **Referans KRA seti üretimi**
|
||
- `hcie-io/examples/generate_drop_shadow_kra_set.rs` gibi örnekler yaz.
|
||
- Aynı parametreleri (açı, mesafe, size, spread, renk, blend) hem PSD hem KRA olarak üret; sonra Krita ve Photoshop’ta açıp transparent PNG export al.
|
||
2. **Ground-truth PNG pipeline**
|
||
- Krita batch render için `krita --export` CLI kullanılabilir (sistemde Krita yüklüyse).
|
||
- Eğer Krita CLI yoksa, manuel açma/kaydetme talimatları + dosya bekleyen bir `tune_mae_*_kra_grid.rs` scripti yaz.
|
||
3. **MAE tune scriptleri**
|
||
- `hcie-io/examples/tune_mae_drop_shadow_kra_grid.rs`
|
||
- `hcie-io/examples/tune_mae_inner_shadow_kra_grid.rs`
|
||
- `hcie-io/examples/tune_mae_outer_glow_kra_grid.rs`
|
||
- `hcie-io/examples/tune_mae_inner_glow_kra_grid.rs`
|
||
- `hcie-io/examples/tune_mae_stroke_kra_grid.rs`
|
||
- `hcie-io/examples/tune_mae_bevel_emboss_kra_grid.rs`
|
||
- Bunlar PSD tune scriptlerinin KRA varyantları olacak; `hcie-kra::export_kra` + `hcie-kra::import_kra` + `hcie-engine-api` composite kullanarak HCIE render’ını Krita referansıyla karşılaştıracak.
|
||
4. **Teknik haritalama**
|
||
- Krita’nın ASL/Photoshop efekt parametrelerini HCIE `LayerEffect` değerlerine doğru çevir:
|
||
- `distance` / `size` / `spread` / `choke` aynı.
|
||
- `angle` aynı.
|
||
- `opacity` 0..1 ↔ Krita 0..255.
|
||
- Renkler RGBA8, doğrudan passthrough.
|
||
- Blend mode isimleri Krita’nın `compositeop` namespace’inden alınacak.
|
||
- Bevel/Emboss için `style`, `technique`, `direction` enum mapping’lerini netleştir.
|
||
|
||
### Aşama 4: Test ve Validasyon
|
||
|
||
1. **Round-trip testleri**
|
||
- `hcie-kra/tests/roundtrip.rs`: rastgele layer’ları KRA’ya yaz, tekrar oku, piksel / stil / blend / opacity / visibility eşitliğini kontrol et.
|
||
- Büyük boyutlu (4K, çok katmanlı) test ekle.
|
||
2. **Krita açılış testi**
|
||
- Eğer sistemde Krita varsa: `examples/verify_krita_opens.rs` ile üretilen KRA’yı Krita’da açma komutunu çalıştır ve `mergedimage.png` karşılaştır.
|
||
3. **Regresyon testleri**
|
||
- `cargo test -p hcie-kra`
|
||
- `cargo test -p hcie-engine-api --test visual_regression`
|
||
- `cargo test -p hcie-engine-api --test performance_stroke_4k -- --nocapture`
|
||
|
||
## Kilitleme / Unlock Notları
|
||
|
||
- `hcie-kra` şu an locked crate değil (Cargo.toml root workspace’te listeli; `AGENTS.md`’de `hcie-kra/src/*.rs` locked listesinde yok). Ancak `hcie-fx/src/parser.rs`, `hcie-protocol/src/*.rs`, `hcie-engine-api/src/*.rs` locked. Aşağıdaki durumlarda unlock gerekebilir:
|
||
- `hcie-fx` ASL writer eklenirse: `unlock.sh hcie-fx`
|
||
- Yeni `LayerEffect` varyant veya alan gerekirse: `unlock.sh hcie-protocol`
|
||
- Engine API’de yeni bir import/export helper gerekirse: `unlock.sh hcie-engine-api`
|
||
|
||
## Riskler
|
||
|
||
- Krita’nın ASL formatı Photoshop’unkindan hafifçe farklı; writer yazarken Krita’nın beklediği farklılıklar (örneğin ekstra Unicode name prefix) gözden kaçabilir.
|
||
- ZIP deflated kullanmak build zamanını hafifçe artırır ama dosya boyutunu ciddi azaltır.
|
||
- Tile-based layer data geçişi protokol değişikliği gerektirebilir; bu planın ilk fazında yapılmayacak.
|
||
|
||
## Çıktılar (Deliverables)
|
||
|
||
- Optimize edilmiş `hcie-kra/src/lib.rs` ve `hcie-kra/src/kra_saver.rs`.
|
||
- Yeni `hcie-io/examples/generate_*_kra_set.rs` dosyaları.
|
||
- Yeni `hcie-io/examples/tune_mae_*_kra_grid.rs` dosyaları (örnek olarak 2-3 efekt, sonra gerisi kopyalanabilir).
|
||
- `hcie-kra/tests/roundtrip.rs` round-trip testleri.
|
||
- Güncellenmiş `hcie-egui-app/crates/hcie-gui-egui/src/app/mod.rs` KRA aç/kaydet yollarında hata raporlama iyileştirmeleri (opsiyonel).
|
||
- Performans/boyut ölçüm raporu (örnek: 4K 10 layer dosyanın eski/yeni boyutu ve açma süresi).
|
||
|
||
## Öncelik Sırası
|
||
|
||
1. ZIP deflate + tile encoder iyileştirmesi (hızlı kazanım, dosya boyutu düşer).
|
||
2. Tile decoder robustluk ve hız (import hatası azalır).
|
||
3. Layer offset / grouplayer / basic attributes (doğruluk artar).
|
||
4. Layer styles export ASL writer (Krita’da efektler görünür).
|
||
5. Referans KRA setleri + MAE tune scriptleri (doğruluk ölçülebilir hale gelir).
|
||
6. Shape/Text import desteği.
|
||
7. Tile-based bellek optimizasyonu (gelecek aşama).
|