# FikoYT CAM Simülasyonu + Kütük (Stock Removal) Motorları — fikatia-local Native (Vulkan Compute) Taşıma Blueprint'i

> **Amaç:** Web `fiko-similasyon-v1` simülasyon penceresi + tüm kütük-simülasyon motorlarını (voxel, triple-dexel, SDF+Marching Cubes, Z-buffer) native fikatia-local'e **daha da geliştirerek, HATASIZ**, native Vulkan compute performansıyla taşımak.
> **Kural:** Web KODU kopyalanmaz — yalnız algoritma/veri modeli/düzen. Referans: fikoyt-sistem `.../fiko-similasyon-v1/` (fikoyt-zorro.com YASAK).
> **Ayrı, pinlenebilir ImGui penceresi** (`###cam_sim`), op penceresi kalıbı (bkz `cam_paneli.cpp` + `pencere_util.hpp`). Fog YOK.

---

## 0. MOTOR SEÇİM MATRİSİ (hangi senaryoda hangi motor)

| Motor | Model | Doğruluk | Bellek | Undercut/5-eksen | İdeal senaryo |
|-------|-------|----------|--------|------------------|---------------|
| **Triple-Dexel** | 3 dik ışın-demeti grid (span listesi) | Yüksek (dik duvar mükemmel, eğim basamaklı) | **O(yüzey)** ≈123 MB @800³ | Tri-grid ile kısmen (isPointInMaterial AND) | **Finiş**, doğruluk kritik, undo gerekli, 3-eksen |
| **Voxel (CSG/GPU)** | Sparse octree (CPU) / paketli grid (GPU) | Orta (blocky, gerçek MC yok) | O(hacim) ama octree ile boş blok bedava | **Tam** (yan/undercut/5-eksen) | Karmaşık 3D, undercut, 5-eksen, gerçekçilik |
| **SDF + Marching Cubes** | İşaretli mesafe alanı (float) + MC izo-yüzey | **En pürüzsüz** (sürekli interp); keskin kenar yuvarlar | O(hacim) tam grid (narrow-band yok) | Tam (analitik takım SDF) | **Finiş doğrulama + yüksek görsel kalite** önizleme |
| **Z-Buffer** | 6-yön near/far depth map (Vericut tarzı) | Yüksek 2.5D; undercut zayıf | Düşük (6 depth map ≪ voxel) | Hayır (dikey takıma indirger) | **2.5D dikey freze** hızlı önizleme, çarpışma takibi |

**Native strateji (GELİŞTİRME):** Tek motor dayatma. **Hibrit boru hattı:**
- **Kaba (roughing):** Z-buffer veya dexel GPU — hız öncelikli, düşük bellek.
- **Finiş doğrulama:** SDF + Marching Cubes (Surface Nets) — pürüzsüz, ball/bull takım tam doğru.
- **Undercut/5-eksen:** sparse-brick voxel (GPU).
- Kanonik doğruluk referansı = **Triple-Dexel CPU** (web'de en olgun, split + tri-grid + undo).

---

## 1. TRIPLE-DEXEL (kanonik motor)

**Dexel:** grid hücresinden tek eksen boyunca fırlatılan ışının dolu-malzeme aralıkları (`span=[min,max]`). Delik/köprü → çok span. Kütük başı: tek span (tam bbox).

**Triple:** 3 dik grid (XY→Z ışını, YZ→X ışını, XZ→Y ışını). Tek dexel kendi eksenine paralel yüzeyi göremez; 3 dik grid her yüzeyi iyi açıyla örnekler. `isPointInMaterial` = 3 grid AND (undercut boşluğu doğru dışlanır).

**Malzeme kaldırma = span çıkarma (5 durum):** dışında→değişmez / kapsar→siler / ortada→**ikiye böl (span+1)** / soldan→alt sınır yukarı / sağdan→üst sınır aşağı.

**Veri (SoA, sabit MAX_SPANS=8):** `data: f32[cell×8×2]` + `spanCounts: u8[cell]`. Sütun = 64 byte, cache-dostu, GPU-eşlenebilir. Bellek **O(yüzey)**: (XYalanı+YZalanı+XZalanı)×64B → 800³≈123 MB (gerçek voxel O(N³)'e karşı büyük avantaj).

**Takım profili (nokta örneği/hücre):** flat `tipZ=z`; ball `tipZ=z+R−√(R²−d²)`; bull flat bölge + köşe torus. `d²>R²`→atla. Süpürme = adaptif adımlı nokta örnekleme (`stepSize<cellSize` → sürekli oluk; adım cap 500/200).

**Mesh:** heightMap(üst)+bottomMap(alt) → bilateral smoothing → central-diff normal → horizon AO → top+bottom+4 yan şerit (statik index cache) + iç duvar mesh (cep kenarı) + kenar segmentleri. Incremental: `dirtyMask` ile sadece değişen hücre.

**GPU (WebGPU) KUSURLU:** yalnız XY grid, **split-case yok**, çok-span height yanlış → "deneysel". Native'de bu hatayı TEKRARLAMA.

### Native Vulkan eşleme
- 3 grid = 3 SSBO çifti (`spans f32[]` + `spanCounts u32[]`, std430).
- Kesim: `local_size=(8,8)`, dispatch **takım etki-kutusu** (tüm grid değil — CPU bbox optimizasyonunu koru). Push constant = takım örneği (≤128B).
- **Batch yarış çözümü:** hamle içinde ardışık dispatch + `vkCmdPipelineBarrier` (SSBO write→read) her adımda. (Sütun-atomik alternatifi karmaşık.)
- **Split-case'i TAM uygula** (WebGPU'nun eksiğini gider): orta-kesim → span kırp + `spanCounts` atomik artır + yeni span yaz. MAX_SPANS taşmasında kırpma yerine **en küçük span'ı birleştir**.
- 5-pass zincir: kesim → height/bottom → normal → AO → mesh. **Vertex SSBO = viewport vertex buffer** (`VERTEX|STORAGE` usage) → **zero-readback** (CPU'ya inmez, doğrudan çizilir). Readback yalnız stats/pick.

---

## 2. VOXEL (CSG octree + GPU)

**İki tutarsız model (web):** CPU = **sparse adaptif octree** (boş/dolu blok bedava, kesim yüzeyinde subdivide, derinlik `clamp(ceil(log2(maxDim/res)),8,14)`); GPU = **yoğun paketli grid** (2 bit/voxel, 4 voxel/u32). Senkron YOK. Native'de **tek tutarlı model** seç.

**Kaldırma:** takım AABB'sine göre gez; düğüm tam takım içi → collapse (isEmpty); kısmi → subdivide; yaprak → merkez-nokta testi. GPU: sub-region dispatch + `atomicAnd` (paketli byte'ta 4 komşu voxel yarışı).

**Takım süpürme:** analitik nokta-içi testi (SDF-benzeri, voxelizasyon değil) — flat/ball/bull; segment en-yakın-nokta + takım testi (kapsül). `tapered` eksik.

**Bellek:** paketli 512³=~33.5 MB, 1024³=~268 MB. Octree gerçek maliyet yüzeyle orantılı. **Ölü kod (taşıma):** `toolIdMap` (268 MB boşa @512³), `activeChunks`, kısmi-doluluk, MC tablosu kullanılmıyor → blocky merdiven.

### Native Vulkan eşleme (GELİŞTİRME)
- **2-seviyeli sparse brick** (VDB-benzeri): üst brick tablosu (dolu/boş/kısmi bayrağı) + kısmi brick için 8³/16³ blok. Tam octree GPU'da verimsiz (pointer-chase); brick hash-grid dallanmasız.
- Depolama = paketli u32 SSBO (VkImage3D **değil** — sub-byte + atomic desteklemez). `atomicAnd` core 1.0.
- Sub-region 3D dispatch (Vulkan 3D native, WebGPU 2D fallback'e gerek yok).
- Mesh = ayrı **gerçek Marching Cubes / Surface Nets** compute pass (blocky kutu-çıkarımı bırak) → aliasing çözülür.
- Tek model: CPU octree at, mesh aynı brick SSBO'dan.

---

## 3. SDF + MARCHING CUBES (en pürüzsüz)

**SDF:** her voxel işaretli mesafe (float). **Negatif=malzeme içi, pozitif=dış, 0=yüzey.** Katı kütük `-1000` başlatılır. **CSG çıkarma:** `result = max(stock, -toolSDF)`. Adımlar `max` ile doğal birleşir.

**Takım SDF (analitik, CPU+WGSL):** flat=`max(silindir,kapak)`; ball=`min(silindir,küre)`; bull=`min(torus,max(silindir,-kesim))`. Süpürme=`sdCapsule` (A→B en-yakın-nokta).

**Marching Cubes:** izo=0'da; vertex = komşu **gerçek mesafe** lineer interp (`t=(0−v1)/(v2−v1)`) → ikili voxel'den **çok daha pürüzsüz**. Zayıf: keskin kenar/köşe yuvarlar (Dual Contouring yok); tam grid (narrow-band yok) → kübik bellek. `MarchingCubesGPU` "zero-readback" der ama fiilen CPU'ya map ediyor (**yarı**-readback).

**Uyumsuzluk (web):** MC shader **ikili voxel** okur, SDFGPUCompute **float SDF** üretir → native'de **tek SDF image** ile birleştir.

### Native Vulkan eşleme (GELİŞTİRME)
- SDF = **`VkImage3D` R16F** (yarım bellek; 3D texture donanım trilineer interp → daha pürüzsüz). Alternatif SSBO.
- **Gerçek zero-readback:** MC compute `atomicAdd` ile vertex SSBO append + `VkDrawIndirectCommand.vertexCount` atomik güncelle → `vkCmdDrawIndirect`, mesh CPU'ya İNMEZ.
- Tek SDF image: oyma compute → barrier → MC compute → barrier → indirect draw (tek frame 3 pass 2 barrier).
- **HATASIZLIK:** `interpolateEdge` clamp EKLE (web'de yok); atomik taşmada kapasite guard (`if base+3>cap return` — web'de sessiz OOB); `POSITIVE_INFINITY` başlangıç → MC'den önce gerçek değerle doldur (yoksa NaN).

---

## 4. Z-BUFFER (2.5D hızlı, endüstri standardı)

**6-yön depth map (±X,±Y,±Z):** her piksel `{nearDepth, farDepth}` = dolu malzeme koridoru. Dikey takım: +Z `newNear=max(oldNear,toolEnd)`; −Z `newFar=min(oldFar,toolEnd)`; delinme guard `near≥far→boşalt`. Dik görünümler (±X,±Y) `updateSideView` **dikdörtgen yaklaşımı** (basitleştirilmiş). Kaldırılan hacim = `Δnear × pixelSize²`.

**Bellek:** 6×2 float = düşük (~12 MB @500²/görünüm), voxel'den çok az. GPU pratik olarak yalnız ±Z. Mesh yalnız +Z heightfield → **undercut/yan-cep kaybolur** (tek-değerli).

### Native Vulkan eşleme
- 6 SSBO çifti (near/far) VEYA 6× R32F storage image (SSBO daha basit — okuma doğrudan). `local_size=(8,8)`, sub-region dispatch (footprint). Push constant (ToolInfo≈48B + DispatchInfo=16B). Cache'li `VkDescriptorSet`. Batch tek `VkSubmitInfo` çok dispatch.
- İdeal: **kaba/hızlı önizleme + çarpışma takibi**. Undercut/5-eksen için değil.

---

## 5. NATIVE BİRLEŞİK KÜTÜK MOTORU (önerilen mimari)

**Tek `KutukSimMotoru` arayüzü, çoklu backend (kip seçilebilir):**
```
enum KutukSimKip { Dexel3, VoxelBrick, SDF_MC, ZBuffer6 };
```
- Ortak API: `kutukKur(Stok)`, `takimUygula(SimNokta)`, `sweptUygula(a,b,takim)`, `meshGuncelle()`, `kaldirilanHacim()`.
- Tüm backend'ler **Vulkan compute** (vulkan_baglam compute yeteneği). **Zero-readback** hedef: mesh SSBO doğrudan viewport'a.
- **Ortak takım geometrisi** (`TakimGeometri`): simülasyon toolType (0=silindir/1=küre/2=koni/torus) ile görsel takım mesh'i TEK kaynaktan (§7).
- Varsayılan: Dexel3 (finiş) + ZBuffer6 (kaba). SDF_MC opsiyonel yüksek-kalite. VoxelBrick undercut/5-eksen.

**HATASIZLIK & performans (tüm backend):**
- vulkan_baglam mevcut **timeout FIX** ile uyum (device-lost temiz yönetim, sonsuz bekleme yok).
- Sınır guard'ları shader'a taşı: NaN/sıfır eksen→(0,0,1); boş span/piksel erken çıkış; `cutMin≥cutMax` atla; MAX_SPANS/kapasite taşma birleştir (sessiz kayıp değil); **geçersiz bbox (min>max) init guard** (MEMORY: boş-mesh→NaN kamera fit → viewport kaybolur).
- Compute senkron: pass'ler arası `vkCmdPipelineBarrier`; bellek bütçesi kontrolü (çözünürlük→bellek uyarısı).

---

## 6. KÜTÜK (STOK) TANIMI — native genişletme

**Web gerçeği:** yalnız **AABB kutu** üretir (3 hizalama modu: Standart / face-aligned / 2-eksen OBB). `Silindir`, `GovdeOffset`, `pay` (offset) **web'de YOK** — native'de sıfırdan. UI'da boyut/pay girişi yok (parça AABB'sinden türetilir); yalnız renk/opacity/eksen.

**Native `Stok` (part_operasyon.hpp) — eşleme + eksikler:**
| Native | Web | Not |
|--------|-----|-----|
| `StokTip::Kutu` | ✅ (3 hizalama) | var |
| `StokTip::Silindir` (boyut.x=çap,z=boy) | ❌ | native'de yeni |
| `StokTip::GovdeOffset` + `pay` | ❌ | native'de yeni (offset uygula) |
| `boyut` | ⚠️ web otomatik | native elle girilebilir (Part Op penceresinde var) |
| `origin` | ⚠️ web **OBB rotasyonlu** | **EKSİK: native Stok'a eksen/rotasyon (Mat3/quat) eklenmeli** — yoksa yalnız world-eksenli kutu taşınır |

**Aksiyon:** Native `Stok`'a rotasyon/eksen bazı ekle (2-eksen face-aligned için). Silindir/GovdeOffset/pay mesh üretimi geliştir. Part Operation penceresi (zaten kuruldu) bu alanları sürüyor.

---

## 7. TAKIM GÖRSELLEŞTİRME

**Web `FikoTakimFrezeleme`:** mesh tamamen `cap/radius/boy/kesmeBoy`'dan primitif kombinasyonu: silindir gövde (gri) + kesme bölgesi (sarı) + uç (radius==cap/2→küre ball / 0<radius<cap/2→torus bull / 0→düz). **`takimTipi` alanı var ama KULLANILMIYOR** — V-kesici/matkap/havsa için ayrı profil yok. Tutucu boş grup.

### Native eşleme
- Primitif mesh: silindir gövde + silindir kesme + (yarım-küre / torus / düz) uç → web ile birebir, revolve gerekmez.
- **Tip-farkında profil (V-kesici/havsa koni) native'de YENİ geliştir** — `taperAngle` ile koni primitifi.
- **KRİTİK:** görsel takım mesh'i ile simülasyon toolType (0/1/2) **tek `TakimGeometri` tanımından** beslenmeli (tutarlılık).

---

## 8. SİMÜLASYON PENCERESİ — tam özellik listesi (ayrı `###cam_sim` pencere)

- **Transport:** ⏮ başa · ◀ geri oynat · ⏸ dur · ▶ ileri oynat · ⏭ sona + `simHizi` (1-1000) + `reelIlerleme` (%1-200) slider.
- **Renkli timeline (ImGui DrawList):** operasyon segmentleri renk kodlu (İşleme=yeşil/Yaklaşma=sarı/Uzaklaşma=mavi/Boşta=kırmızı) + operasyon sınır çizgileri + segment tıkla→atla. Scrubber (SliderInt poz).
- **Göstergeler (ImGui::Text):** aktif op adı+hareket türü+takım, Üst/Alt açı, Kaçma X/Y/Z, İşleme Ekseni adı, XYZ konum, İlerleme(mm/dk)+Devir(rpm), Geçen/Toplam süre + %.
- **Araçlar menüsü (CollapsingHeader):** Görünüm (çizgi/nokta/renk), Kamera (0 serbest/1 kilit-takip/2 drone + yumuşaklık/hız/mesafe/açı), Efektler (ses/talaş/titreşim/hayalet), Analiz (çarpışma canlı+tara, cycle time).
- **Kütük simülasyon:** kip seç (dexel/voxel/sdf/zbuffer), kütük seç, başlat/durdur, kaldırılan hacim (cm³).
- **Çarpışma & gouge:** Vulkan compute silindir-üçgen (native perf); statik gouge (rapid malzeme-altı / feed taban-altı / derin dik dalış). Çarpışma flash.
- **Nokta modeli:** `SimNokta{Vec3d p; f64 hiz,devir; HareketTuru tur; Takim* takim; Vec3d takimYonu; f64 guncelSure,toplamSure; u32 opId}` — CL noktalarından timeline/süre/renk üretimi.
- **Operasyon penceresi ▶ Replay → bu pencereyi açar** (op penceresi zaten iskeletle hazır).

---

## 9. YOL HARİTASI (dalgalar)

1. **Pencere iskeleti** (`cam_simulasyon_penceresi.cpp/.hpp`, `###cam_sim`+pin): transport + renkli timeline + göstergeler (SimNokta modeli, statik veri).
2. **CPU Triple-Dexel** (kanonik): 3 grid span çıkarma + heightmap mesh. Doğruluk referansı.
3. **Vulkan compute dexel/zbuffer**: SSBO + sub-region dispatch + zero-readback mesh. Kaba+finiş.
4. **SDF+Marching Cubes** (Surface Nets): yüksek-kalite finiş doğrulama, indirect draw.
5. **Voxel sparse-brick**: undercut/5-eksen.
6. **Çarpışma+gouge** (Vulkan compute) + takım mesh (tip-farkında) + Replay entegrasyonu + efektler.

Her dalga: Cekirdek registry → makro+plugin+olay bedavaya ([[fikatia-mimari-ilke-makro-plugin-olay]]). main.cpp/CMakeLists entegrasyonu tek elden (lider birleştirir). Fog YOK.

**Kritik hatasızlık notları:** WebGPU'da bozuk olan 3 şey native'de DÜZELT — (1) dexel GPU split-case eksik, (2) MC interpolateEdge clamp yok + atomik OOB sessiz, (3) voxel çift-model senkronsuz. Native tek-model + tam split + kapasite guard + geçersiz bbox guard ile başla.