# Voxel CSG Motor Entegrasyonu

## Genel Bakış

FikoYT 3D CAD sistemine **Voxel CSG (Constructive Solid Geometry)** tabanlı yeni bir stok simülasyon motoru eklendi. Bu motor, mevcut **Triple-Dexel** motoruna alternatif olarak çalışır ve kullanıcı seçimine göre aktif edilebilir.

### Neden Voxel CSG?

| Özellik | Triple-Dexel | Voxel CSG |
|---------|--------------|-----------|
| **Boyut** | 2.5D (XY grid + Z depth) | Tam 3D voxel |
| **Hassasiyet** | Yüksek (dikey kesimler) | Çok Yüksek (tüm yönler) |
| **Performans** | Çok Hızlı | Orta-Hızlı (GPU ile hızlı) |
| **Bellek** | Düşük | Orta (Octree ile optimize) |
| **Karmaşık Takımlar** | İyi | Mükemmel |
| **Yan Frezeleme** | Sınırlı | Tam destek |

### Hangi Durumlarda Kullanılmalı?

**Triple-Dexel Kullan:**
- Dikey frezeleme operasyonları (Z ekseninde kesim)
- Hız öncelikli simülasyonlar
- Düz frezeleme işlemleri
- Torna operasyonları

**Voxel CSG Kullan:**
- 5-eksen frezeleme
- Karmaşık takım geometrileri (bull nose, tapered)
- Yan frezeleme ve rampalama
- Gerçekçi simülasyon gereksinimi
- Alttan kesme kontrolü

## Teknik Mimari

### 1. Voxel CSG Engine (VoxelCSGEngine.ts)

**Özellikleri:**
- **Adaptive Octree:** Bellek verimliliği için hierarşik voxel organizasyonu
- **CSG Boolean Operations:** Tool sweep'lerde gerçek boolean çıkarma
- **Marching Cubes:** Yüksek kaliteli mesh oluşturma
- **Smart Subdivision:** Sadece gerekli bölgelerde detay artırma

**Kullanım:**

```typescript
import { VoxelCSGEngine, createVoxelCSGEngine } from './VoxelCSGEngine';

// Motor başlatma
const bbox = { minX: -100, maxX: 100, minY: -100, maxY: 100, minZ: 0, maxZ: 200 };
const engine = createVoxelCSGEngine(bbox, 1.0); // 1mm voxel resolution

// Dikdörtgen stok başlat
engine.initializeRectangularStock();

// Material removal (takım ile kesim)
const tool = {
  type: 'ball',
  diameter: 10,
  cornerRadius: 0,
  length: 50
};

engine.removeMaterial(0, 0, 100, tool, 0, 0, 1);

// Mesh oluştur
const geometry = engine.generateMesh();

// İstatistikler
const stats = engine.getStats();
console.log(`Active voxels: ${stats.activeVoxels}, Memory: ${stats.memoryUsage} bytes`);
```

### 2. GPU Acceleration (VoxelGPUCompute.ts)

**WebGPU Compute Shaders:**
- Paralel voxel removal (binlerce voxel/frame)
- GPU tabanlı marching cubes
- Otomatik CPU fallback

**Kullanım:**

```typescript
import { createVoxelGPUCompute } from './VoxelGPUCompute';

// GPU compute başlat
const gpuCompute = await createVoxelGPUCompute(
  resX, resY, resZ,
  voxelSize,
  [bbox.minX, bbox.minY, bbox.minZ]
);

if (gpuCompute) {
  // GPU ile material removal
  const result = await gpuCompute.removeVoxelsGPU(
    centerX, centerY, centerZ, tool, dirX, dirY, dirZ
  );

  console.log(`GPU removal: ${result.executionTime}ms`);
}
```

### 3. Worker Threading (VoxelWorkerBridge.ts)

**Paralel İşleme:**
- Multi-threaded voxel processing
- Main thread blocking önleme
- Otomatik worker pool yönetimi

**Kullanım:**

```typescript
import { createVoxelWorkerBridge } from './VoxelWorkerBridge';

// Worker pool başlat (4 worker)
const workerBridge = createVoxelWorkerBridge(4);
await workerBridge.initialize(resX, resY, resZ, voxelSize, bbox);

// Async material removal
const result = await workerBridge.removeVoxels(
  centerX, centerY, centerZ, tool
);

// Mesh generation
const meshResult = await workerBridge.generateMesh();
const geometry = new THREE.BufferGeometry();
geometry.setAttribute('position', new THREE.Float32BufferAttribute(meshResult.meshData.vertices, 3));
```

## Component Entegrasyonu

### Motor Seçimi UI

`fiko-similasyon-v1.component.html` içinde kullanıcı motor seçebilir:

```html
<!-- Kütük seçildiğinde motor seçim paneli gösterilir -->
<div *ngIf="kutukMeshSecili && !kutukSimAktif">
  <button (click)="kutukSimModu='dexel'">Triple-Dexel</button>
  <button (click)="kutukSimModu='voxel'">Voxel CSG</button>
  <button (click)="kutukSimModu='visual'">Sadece Görsel</button>
</div>
```

### Component State

`fiko-similasyon-v1.component.ts` içinde yeni değişkenler:

```typescript
// Voxel CSG Engine
private voxelEngine: VoxelCSGEngine | null = null;
private voxelGPUCompute: VoxelGPUCompute | null = null;
private useGPUVoxel: boolean = false;
private voxelWorkerBridge: VoxelWorkerBridge | null = null;
private useWorkerVoxel: boolean = false;
private voxelMesh: THREE.Mesh | null = null;

// Motor modu
kutukSimModu: 'dexel' | 'voxel' | 'csg' | 'visual' = 'visual';
```

### Motor Başlatma (Örnek - Implement Gerekli)

```typescript
async initVoxelEngine(bbox: any, resolution: number) {
  console.log('[VoxelSim] Initializing Voxel CSG engine...');

  // CPU engine
  this.voxelEngine = createVoxelCSGEngine(bbox, resolution);
  this.voxelEngine.initializeRectangularStock();

  // Try GPU acceleration
  const resX = Math.ceil((bbox.maxX - bbox.minX) / resolution);
  const resY = Math.ceil((bbox.maxY - bbox.minY) / resolution);
  const resZ = Math.ceil((bbox.maxZ - bbox.minZ) / resolution);

  this.voxelGPUCompute = await createVoxelGPUCompute(
    resX, resY, resZ, resolution,
    [bbox.minX, bbox.minY, bbox.minZ]
  );

  if (this.voxelGPUCompute?.isInitialized()) {
    this.useGPUVoxel = true;
    console.log('[VoxelSim] GPU acceleration enabled');
  } else {
    // Fallback to worker threading
    this.voxelWorkerBridge = createVoxelWorkerBridge();
    const success = await this.voxelWorkerBridge.initialize(
      resX, resY, resZ, resolution, bbox
    );
    this.useWorkerVoxel = success;
  }

  // Create visualization mesh
  const geometry = this.voxelEngine.generateMesh();
  const material = new THREE.MeshStandardMaterial({
    color: 0xcccccc,
    metalness: 0.3,
    roughness: 0.7
  });

  this.voxelMesh = new THREE.Mesh(geometry, material);
  this._sahne.add(this.voxelMesh);

  console.log('[VoxelSim] Engine initialized successfully');
}
```

### Material Removal Loop (Örnek - Implement Gerekli)

```typescript
async processToolPosition(x: number, y: number, z: number, tool: any) {
  if (this.kutukSimModu !== 'voxel' || !this.voxelEngine) return;

  // GPU path
  if (this.useGPUVoxel && this.voxelGPUCompute) {
    await this.voxelGPUCompute.removeVoxelsGPU(x, y, z, tool, 0, 0, 1);
  }
  // Worker path
  else if (this.useWorkerVoxel && this.voxelWorkerBridge) {
    await this.voxelWorkerBridge.removeVoxels(x, y, z, tool);
  }
  // CPU fallback
  else {
    this.voxelEngine.removeMaterial(x, y, z, tool, 0, 0, 1);
  }

  // Update mesh periodically
  this.voxelGuncellemeSayac++;
  if (this.voxelGuncellemeSayac % 10 === 0) {
    this.updateVoxelMesh();
  }
}

updateVoxelMesh() {
  if (!this.voxelEngine || !this.voxelMesh) return;

  const geometry = this.voxelEngine.generateMesh();
  this.voxelMesh.geometry.dispose();
  this.voxelMesh.geometry = geometry;

  this._sahne?.anaGosterim?.ciz(); // Request render
}
```

## Performans Optimizasyonları

### 1. Adaptive Resolution

```typescript
// Daha hızlı sim için düşük resolution
const fastEngine = createVoxelCSGEngine(bbox, 2.0); // 2mm voxel

// Daha hassas sim için yüksek resolution
const preciseEngine = createVoxelCSGEngine(bbox, 0.5); // 0.5mm voxel
```

### 2. Batch Processing

```typescript
// Birden fazla tool pozisyonunu batch'le
const positions = [...]; // Array of tool positions

for (const pos of positions) {
  engine.removeMaterial(pos.x, pos.y, pos.z, tool);
}

// Mesh'i bir kere güncelle (her pozisyon sonrası değil)
const geometry = engine.generateMesh();
```

### 3. Progressive Mesh Update

```typescript
// Mesh update throttle (her N update'te bir)
const UPDATE_INTERVAL = 10;

if (frameCount % UPDATE_INTERVAL === 0) {
  updateVoxelMesh();
}
```

## Kısıtlamalar ve İyileştirmeler

### Mevcut Kısıtlamalar

1. **Marching Cubes:** Basitleştirilmiş implementasyon (tam lookup table yok)
2. **Mesh Voxelization:** Sadece rectangular stock (custom mesh henüz yok)
3. **Octree Compression:** Manuel collapse (otomatik optimizasyon yok)

### Gelecek İyileştirmeler

1. **Full Marching Cubes:** Lookup table ile smooth surfaces
2. **Solid Voxelization:** STL/STEP meshlerinden voxel oluşturma
3. **Parallel Octree:** GPU compute ile octree traversal
4. **Adaptive Mesh:** LOD sistemi ile uzak voxeller için düşük detay
5. **Snapshot System:** Dexel gibi ileri/geri sarma desteği

## Test ve Debugging

### Stats Monitoring

```typescript
const stats = engine.getStats();
console.log(`
  Total Voxels: ${stats.totalVoxels}
  Active Voxels: ${stats.activeVoxels}
  Memory: ${(stats.memoryUsage / 1024 / 1024).toFixed(2)} MB
  Last Op Time: ${stats.lastOperationTime.toFixed(2)} ms
  Mesh: ${stats.meshVertices} vertices, ${stats.meshTriangles} triangles
`);
```

### Visualization Debug

```typescript
// Octree wireframe görselleştirmesi (debug için)
function visualizeOctree(engine: VoxelCSGEngine) {
  // Octree node'larını box helper ile göster
  // TODO: Implement octree traversal ve wireframe ekleme
}
```

## Örnek Kullanım Senaryoları

### Senaryo 1: Basit Frezeleme

```typescript
// Düz frezeleme - Triple-Dexel daha hızlı
kutukSimModu = 'dexel';
```

### Senaryo 2: 5-Eksen İşleme

```typescript
// Karmaşık 5-eksen - Voxel CSG daha doğru
kutukSimModu = 'voxel';

// Her tool pozisyonunda normal vektör değişir
tool.dirX = Math.sin(angle);
tool.dirY = 0;
tool.dirZ = Math.cos(angle);
```

### Senaryo 3: Performans Karşılaştırması

```typescript
// Benchmark her iki motoru test et
async function benchmarkEngines() {
  const positions = generateTestToolPath(); // 1000 pozisyon

  // Triple-Dexel
  const t0 = performance.now();
  for (const pos of positions) {
    dexelEngine.processSample(pos.x, pos.y, pos.z, tool);
  }
  const dexelTime = performance.now() - t0;

  // Voxel CSG
  const t1 = performance.now();
  for (const pos of positions) {
    voxelEngine.removeMaterial(pos.x, pos.y, pos.z, tool);
  }
  const voxelTime = performance.now() - t1;

  console.log(`Dexel: ${dexelTime}ms, Voxel: ${voxelTime}ms`);
}
```

## Sonuç

Voxel CSG motoru Triple-Dexel'e **alternatif** olarak eklenmiştir. Kullanıcılar:

1. ✅ Kütük seçerken motor seçebilir
2. ✅ Simülasyon sırasında motor değiştiremez (yeni sim başlatmalı)
3. ✅ Her iki motor da korunmuştur (Triple-Dexel hala varsayılan)
4. ✅ GPU/Worker fallback sistemi her iki motorda da mevcuttur

**Varsayılan davranış değişmedi** - Triple-Dexel hala varsayılan motor ve tüm mevcut fonksiyonlar çalışmaya devam eder.