phantom/hcie-rust-v3.05
1
0
Fork 0
Code Issues Pull Requests Actions 11 Packages Projects Releases Wiki Activity
Files
7ace048d945ae63797217cf8e4f442e64f8ce92a
hcie-rust-v3.05/.kilo/plans/kra-optimize-plan.md
T
phantom 7ace048d94 init
2026-07-09 02:59:53 +03:00

11 KiB
Raw Blame History

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).
Reference in New Issue View Git Blame Copy Permalink