# Topolojik Görsel Özellikler — Tasarım (Proje 1)

**Tarih:** 2026-07-08
**Durum:** Onaylanmış tasarım · uygulama planı bekliyor
**Kapsam:** Proje 1 (per-öğe görsel özellik sistemi). Proje 2 (topolojik isimlendirme / işlem-kalıcılığı) ayrı spec.

## 1. Amaç

Her topolojik öğenin (yüz / kenar / nokta) kendine ait profesyonel görsel özellikleri olsun (renk, alpha, çizgi stili, kalınlık, boyut, görünürlük, basit malzeme). Bu özellikler:

- **Undo/redo'da korunur** (şu an kayboluyor — asıl tetikleyen şikâyet).
- **.fikocad dosyasında korunur.**
- **Özellikler panelinden düzenlenir** (tek + çoklu seçim).
- Renderer tarafından **per-öğe** uygulanır.
- Proje 2 (topo-naming) için **kararlı kimlik + geometrik imza** temeli baştan atılır → boşa iş olmaz.

### Non-goals (Proje 1 dışı)
- B-Rep/3D işlemler (boolean/fillet/pah) boyunca kalıcılık → **Proje 2** (OCCT history + imza eşleme).
- Doku/UV haritalı malzeme, tam PBR. (Basit metalik+pürüz yeterli.)
- Per-kenar keyfi çizgi-genişliği gradyanı (kova-tabanlı ayrık kalınlık yeterli).

## 2. Veri modeli

```
enum class KenarStil : u8 { Duz, Dash, Dot, DashDot };
enum class NoktaSekil : u8 { Nokta, Kare, Arti };

struct OgeOzellik {
  Vec3f renk{...};        // öğe tipine göre varsayılan (yüz malzeme, kenar koyu, nokta)
  f32   alfa = 1.0f;
  bool  gorunur = true;
  // Kenar
  KenarStil stil = KenarStil::Duz;
  f32   kalinlik = 1.6f;
  // Nokta
  f32   noktaBoyut = 7.0f;
  NoktaSekil sekil = NoktaSekil::Nokta;
  // Yüz (basit malzeme)
  f32   metalik = 0.0f;
  f32   puruz = 0.6f;
  // --- Proje 2 kancası: geometrik imza (öğe tipine göre) ---
  // Yüz: merkez+normal+alan · Kenar: orta+uzunluk+tip · Nokta: konum
  ImzaVeri imza{};
};
```

**Depolama (Dugum başına, seyrek — yalnız override edilen öğeler):**
```
std::unordered_map<u32, OgeOzellik> yuzOz;    // yüz ordinali → özellik
std::unordered_map<u32, OgeOzellik> kenarOz;  // kenar ordinali
std::unordered_map<u32, OgeOzellik> noktaOz;  // nokta ordinali
OgeOzellik yuzVars, kenarVars, noktaVars;     // gövde-seviyesi varsayılan (override yoksa bu)
```
Öğe özelliği çözümü: `override varsa onu, yoksa gövde varsayılanı`. Ordinal 1-tabanlı (mevcut altKimlik ile birebir).

**Nerede yaşar:** `motor/sahne/Dugum` (veya ayrı `OgeOzellikDeposu` üyesi). STEP import'ta gelen `yuzRenkleri` → `yuzOz[i].renk`'e taşınır (mevcut mekanizma köprülenir, çift kaynak olmaz).

## 3. Kalıcılık

1. **Undo/redo** — `DugumPusula`'ya (`motor/sahne/sahne.hpp`) üç harita + varsayılanlar eklenir. `Sahne::diril()` bunları geri yükler → **undo/redo renk/özellik kaybı biter.** (İlgili known-bug: diril() Sketch/Tel/Yuzey kök-state kaybı — bu spec yalnız öğe-özelliklerini ekler, o ayrı.)
2. **Dosya** — `.fikocad` (`motor/io/fiko_format`) düğüm bloğuna özellik haritaları serileştirilir (sürüm bump; eski dosya = varsayılan). `.fkcache` (STEP mesh cache) da özellik taşımalı ya da özellik cache-dışı tutulmalı (mesh'ten bağımsız).

## 4. Render (per-öğe uygulama)

**Yüz:**
- Renk + alfa mesh vertex'ine pişirilir. `Vertex` struct'ına **alpha kanalı** eklenir (şu an renk[3] yok; ya `renk[4]` ya ayrı `f32 alfa`). Mesh pişirme (`brep.cpp ucgenle` / mega-parti) yüz ordinaline göre `yuzOz` renk+alfa okur.
- **Görünürlük:** gizli yüzün üçgenleri mesh'e hiç girmez (yeniden-pişir).
- **Malzeme (metalik/pürüz):** model.frag'e per-yüz metalik/pürüz (vertex'e paketlenir veya altKimlik→doku). Basit: speküler gücü pürüzden, yansıma metalikten.

**Kenar:**
- Renk kenar-vertex'ine pişirilir (KenarVertex'e renk paketlenir veya altKimlik→lookup).
- **Dash/Dot:** yeni `kenar_stil.vert/frag` — kenar boyunca yay-uzunluğu (vertex'te birikimli mesafe) + desen maskesi (fragment `fract(s/periyot)` ile discard).
- **Kalınlık:** aynı kalınlıktaki kenarlar **kova**lanır, kova başına tek draw (dinamik `lineWidth`). Az sayıda ayrık kalınlık → az draw.

**Nokta:**
- `nokta.vert/frag` genişletilir — per-nokta renk + `gl_PointSize` (boyut) + şekil (frag'da kare/artı maskesi).

**Mega-parti etkisi:** Öğe-özellikleri per-vertex pişik → mega-parti imzasına özellik-sürümü katılır (özellik değişince yeniden-pişer). Hover/seçim değişimi tetiklemez (mevcut mantık korunur).

## 5. UI — Özellikler paneli

- Seçili öğe(ler) tipine göre panel: yüz → renk/alfa/görünür/metalik/pürüz; kenar → renk/alfa/stil/kalınlık/görünür; nokta → renk/alfa/boyut/şekil/görünür.
- Çoklu seçim → toplu düzenleme (karışık değer "—" gösterir).
- Düzenle → `Dugum` haritası güncellenir + mesh dirty (yeniden-pişir) + undo işaretle + olay yayınla (`OgeOzellikDegisti`).
- "Varsayılana dön" (öğe / gövde).
- Mevcut Özellikler paneli/altyapısı genişletilir (yeni panel değil).

## 6. Mimari ilke (zorunlu)

Yeni sistem doğduğu an **makro + plugin + olay** erişilebilir: `OgeOzellikDegisti` olayı (olay.hpp enum SONUNA), Lua `fiko.ozellik.al/ata`, merkezi registry. (fikatia mimari anayasası.)

## 7. Sınıf/dosya yerleşimi

- `motor/sahne` — `OgeOzellik`, `Dugum` üye haritaları, `DugumPusula` genişletme, çözüm API'si (`yuzOzellik(ord)` vb.).
- `motor/geometri/brep.cpp` — mesh pişirmede özellik okuma (renk/alfa/görünür).
- `motor/render/shader` — `kenar_stil.*` (dash), `nokta.*` genişletme, `model.frag` (alfa+malzeme), `Vertex`/`KenarVertex` alpha/renk.
- `motor/io/fiko_format` — serileştirme.
- `uygulama/fikocad` — Özellikler paneli, olay/mesh-dirty köprüsü.
- `motor/betik` — `fiko.ozellik` Lua API.

## 8. Test

- `OgeOzellik` çözüm (override vs varsayılan) birim testi.
- Undo/redo round-trip: özellik ata → undo → redo → korunur (test_agac / test_brep kalıbı).
- .fikocad kaydet/yükle round-trip özellik korur.
- STEP `yuzRenkleri` → `yuzOz` köprü testi.

## 9. Dalgalar (uygulama sırası)

1. **Dalga 1** — Veri modeli (`OgeOzellik` + Dugum haritaları + çözüm API) + undo (`DugumPusula`) + STEP renk köprüsü. Görsel değişiklik yok ama undo/redo renk korur.
2. **Dalga 2** — Render: yüz renk+alfa+görünürlük (Vertex alpha), mega-parti/mesh entegrasyonu.
3. **Dalga 3** — Kenar: renk + dash/dot shader + kalınlık kovaları.
4. **Dalga 4** — Nokta: renk/boyut/şekil.
5. **Dalga 5** — Özellikler paneli UI + çoklu seçim + varsayılana-dön.
6. **Dalga 6** — .fikocad serileştirme + olay + Lua API.
7. **(Proje 2)** — Topolojik isimlendirme: OCCT history + imza eşleme ile işlem-kalıcılığı.

## 10. Riskler / açık noktalar

- `Vertex` struct değişikliği (alpha) hot-path — mega-parti + tüm mesh yolları güncellenir. Dikkatli.
- Per-kenar kalınlık kova-tabanlı → çok farklı kalınlık = çok draw; makul sınır (ör. 4-6 kova).
- `.fkcache` özellik ile mesh ayrımı: özellikler mesh'ten bağımsız saklanmalı (cache mesh'i, özellik ayrı).
- Geometrik imza formatı Proje 2 ile uyumlu seçilmeli (merkez/normal/alan/uzunluk — OCCT'den ucuz çıkar).