# SPH Ana Sahne Entegrasyonu - İmplementasyon Planı

**Tarih:** 2026-03-20
**Hazırlayan:** 20 Araştırma Ajanı
**Hedef:** SPH simülasyonunu ana Three.js sahnesine entegre et, UI'yi sadeleştir

---

## ÖZET

SPH döküm simülasyonu şu anda kendi izole WebGPU canvas'ında çalışıyor. Hedef:
1. Parçacıkları ana Three.js sahnesinde göster (THREE.Points + GPU readback)
2. UI'yi 13 component'ten 6'ya düşür (%60 azalma)
3. 3D sahnede eleman yerleştirme (sağ tık + raycaster)
4. Minimalist HUD overlay'ler (glassmorphism)

---

## MİMARİ KARAR

**Seçilen Yaklaşım: Async GPU Readback + THREE.Points**

```
WebGPU Compute (fizik) → mapAsync readback (10Hz) → Float32Array
  → THREE.Points geometry güncelle → Ana Three.js sahne render
```

**Neden bu yaklaşım:**
- WebGPU compute ve WebGL2 render aynı anda çalışabilir
- THREE.Points 100K+ parçacık için yeterli performans
- 10Hz readback = 100ms latency (kabul edilebilir)
- Ana kamera paylaşımı otomatik (aynı sahne)
- Mevcut seçim sistemi (FikoSecililer) ile uyumlu

---

## YENİ DOSYA YAPISI

```
fiko-sph-sivi/
├── services/
│   ├── fiko-dokum.service.ts           (MEVCUT, genişlet)
│   ├── fiko-dokum-sahne.service.ts     (YENİ - sahne entegrasyonu)
│   └── fiko-dokum-motor.service.ts     (YENİ - compute yönetimi)
│
├── components/
│   ├── fiko-dokum-panel.component.ts/html/less     (YENİ - sidebar drawer)
│   ├── fiko-dokum-overlay.component.ts/html/less   (YENİ - HUD overlay'ler)
│   ├── fiko-dokum-element-modal.component.ts/html  (YENİ - eleman düzenleme)
│   ├── fiko-dokum-kesit.component.ts               (MEVCUT, minimal değişiklik)
│   ├── fiko-heatmap-legend.component.ts             (MEVCUT, overlay olarak)
│   │
│   ├── (SİL) fiko-dokum-wizard.component.ts
│   ├── (SİL) fiko-sph-sivi.component.ts
│   ├── (SİL) fiko-dokum-karsilastir.component.ts
│   ├── (SİL) fiko-sph-eleman-panel.component.ts
│   ├── (SİL) fiko-sph-analiz-panel.component.ts
│   ├── (SİL) fiko-senaryo-secici.component.ts
│   └── (SİL) fiko-dokum-kontrol.component.ts
│
├── visual/                             (YENİ - 3D görselleştirme)
│   ├── sph-particle-renderer.ts        (THREE.Points yönetimi)
│   ├── sph-element-visualizer.ts       (8 tip eleman mesh)
│   ├── sph-placement-mode.ts           (raycaster yerleştirme)
│   └── sph-element-meshes.ts           (mesh factory)
│
├── elemanlar/                          (MEVCUT, değişiklik yok)
├── gpu/                                (MEVCUT, bug fix'ler uygulandı)
├── dokum/                              (MEVCUT, değişiklik yok)
└── analiz/                             (MEVCUT, değişiklik yok)
```

---

## İMPLEMENTASYON FAZLARI

### FAZ 1: Altyapı Servisleri (Bağımlılık yok)

**1.1 FikoDokumSahneServisi** (YENİ)
- Ana sahneye SPH particle grubu ekleme/çıkarma
- THREE.Points oluşturma + BufferGeometry güncelleme
- Eleman mesh'leri yönetimi
- Heatmap vertex color güncelleme
- Kamera senkronizasyonu (ana kamera → SPH uniform)

**1.2 FikoDokumMotorServisi** (YENİ)
- WebGPU compute başlatma (FikoSPHMotor wrapper)
- GPU→CPU readback pipeline (double buffer, 10Hz)
- Simülasyon lifecycle (başlat/durdur/sıfırla)
- Eleman GPU buffer senkronizasyonu

**1.3 SPHParticleRenderer** (YENİ)
```typescript
class SPHParticleRenderer {
  private points: THREE.Points;
  private geometry: THREE.BufferGeometry;
  private positionAttr: THREE.BufferAttribute;
  private colorAttr: THREE.BufferAttribute;

  constructor(maxParticles: number) {
    const positions = new Float32Array(maxParticles * 3);
    const colors = new Float32Array(maxParticles * 3);

    this.geometry = new THREE.BufferGeometry();
    this.positionAttr = new THREE.BufferAttribute(positions, 3);
    this.colorAttr = new THREE.BufferAttribute(colors, 3);

    this.geometry.setAttribute('position', this.positionAttr);
    this.geometry.setAttribute('color', this.colorAttr);
    this.geometry.setDrawRange(0, 0);

    this.points = new THREE.Points(this.geometry, new THREE.PointsMaterial({
      size: 0.015,
      vertexColors: true,
      sizeAttenuation: true,
      transparent: true,
      opacity: 0.85
    }));
  }

  update(posBuffer: Float32Array, colorBuffer: Float32Array, count: number) {
    (this.positionAttr.array as Float32Array).set(posBuffer.subarray(0, count * 3));
    this.positionAttr.needsUpdate = true;

    (this.colorAttr.array as Float32Array).set(colorBuffer.subarray(0, count * 3));
    this.colorAttr.needsUpdate = true;

    this.geometry.setDrawRange(0, count);
  }

  addToScene(scene: THREE.Scene) { scene.add(this.points); }
  removeFromScene(scene: THREE.Scene) { scene.remove(this.points); }
  dispose() { this.geometry.dispose(); this.points.material.dispose(); }
}
```

### FAZ 2: 3D Sahne Entegrasyonu (Faz 1'e bağlı)

**2.1 Ana sahneye particle ekleme**
- `sahneler[0].ekle(particlePoints)` ile ekleme
- `surekliCiz()` ile continuous render mode
- Kamera matrislerini SPH motor'a aktarma

**2.2 Hızlı menüye SPH entegrasyonu**
- Mesh'e sağ tık → "Döküm Simülasyonu" menü öğesi
- `mesh.hizli3DMenu.push({ simgeYazi: '💧', baslik: 'Döküm Simülasyonu', ... })`
- Koşullu görünürlük: sadece THREE.Mesh nesne tipinde

**2.3 Eleman 3D görselleştirme**
- 8 eleman tipi için mesh factory
- Inlet: Kırmızı ok + disk
- Outlet: Mor ok
- Sensor: Sarı küre + wireframe radius
- Engel: Mavi yarı saydam plaka
- CSS2DObject ile etiketler

### FAZ 3: UI Bileşenleri (Faz 2'ye bağlı)

**3.1 FikoDokumPanelComponent** (sidebar drawer, ~380 satır)
- NzDrawer (sağ, 340px)
- 5 NzCollapse bölümü:
  1. Malzeme: Dropdown + tag'lar + sıcaklık slider
  2. Ayarlar: Döküm türü butonları + kalite + toggle'lar
  3. Elemanlar: Ekle butonları + liste
  4. Kontrol: Başlat/Pause/Stop/Reset + hız slider
  5. Sonuçlar: Dolum %, FPS, Niyama, Rapor indir

**3.2 FikoDokumOverlayComponent** (HUD, ~180 satır)
- Sol üst: Heatmap modu seçici (8 ikon buton)
- Sol alt: Heatmap legend (gradient bar)
- Sağ üst: Canlı istatistik (FPS, parçacık, dolum, Niyama)
- Alt orta: Mini timeline (progress + play/pause + hız)
- Glassmorphism: backdrop-filter blur + rgba background

**3.3 FikoDokumElementModalComponent** (eleman düzenleme, ~100 satır)
- NzModal ile eleman parametreleri düzenleme
- Dinamik form: eleman tipine göre alan gösterimi
- Eleman seçilince otomatik açılır

### FAZ 4: 3D Etkileşim (Faz 3'e bağlı)

**4.1 Eleman yerleştirme modu**
- State machine: IDLE → PLACEMENT → PREVIEW → PLACED
- "Giriş Ekle" butonu → cursor crosshair
- Mouse move → raycaster → preview mesh (yarı saydam)
- Click → eleman oluştur + sahneye ekle
- ESC → iptal

**4.2 Surface normal algılama**
- `raycaster.intersectObject(mesh)` → intersection.face.normal
- World normal = normal.transformDirection(mesh.matrixWorld)
- Eleman yönü = surface normal

**4.3 Eleman sürükleme**
- TransformControls entegrasyonu
- Snap-to-surface: sürükleme sırasında mesh yüzeyine yapışma

**4.4 Keyboard shortcuts**
- G: Giriş ekle modu
- H: Hava deliği ekle modu
- S: Sensör ekle modu
- Space: Play/Pause
- Delete: Seçili eleman sil
- ESC: Modu iptal

### FAZ 5: Temizlik (Faz 4'e bağlı)

**5.1 Eski component'leri kaldır**
- 7 component sil (wizard, karsilastir, kontrol, senaryo, vb.)

**5.2 Route güncelleme**
- SPH artık ayrı route değil, ana 3D viewer'ın bir özelliği

---

## PERFORMANS BÜTÇESİ

```
GPU Readback (10Hz):  ~2ms × 10/s = 20ms/s toplam
THREE.Points update:  ~0.5ms/frame
Eleman mesh render:   ~0.1ms/frame (max 64 eleman)
CSS2D label render:   ~0.2ms/frame (max 64 etiket)
Heatmap color update: ~1ms/frame (CPU renk hesabı)

TOPLAM EKSTRA YÜK: ~3ms/frame (16ms bütçe içinde)
```

---

## KULLANICI DENEYİMİ AKIŞI

```
1. Model yükle (STEP dosyası)
2. Mesh'e sağ tık → "💧 Döküm Simülasyonu"
3. Sağ sidebar açılır:
   - Malzeme seç (dropdown)
   - Sıcaklık ayarla (slider)
   - "Giriş Ekle" → 3D'de tıkla
   - "Hava Deliği Ekle" → 3D'de tıkla
4. [▶ Başlat] butonuna tıkla
5. Parçacıklar 3D sahnede akmaya başlar
6. HUD: FPS, parçacık sayısı, dolum %, Niyama
7. Heatmap: sıcaklık/basınç/hız overlay
8. Bitince: "📥 Rapor İndir"
```

---

*Bu plan 20 paralel araştırma ajanının analiz sonuçlarına dayanmaktadır.*