# How To

Quick reference for common tasks.

---

## Building

### Workspace Selection
```bash
# Main demo (default)
cmake -S . -B build -DDEMO_WORKSPACE=main
cmake --build build -j4
./build/demo64k

# Test demo
cmake -S . -B build_test -DDEMO_WORKSPACE=test
cmake --build build_test -j4
./build_test/test_demo
```

### Debug Build
```bash
cmake -S . -B build
cmake --build build -j4
./build/demo64k
```
Options: `--fullscreen`, `--resolution WxH`, `--seek TIME`, `--hot-reload`

### Production Builds
```bash
# Size-optimized (development)
cmake -B build -DDEMO_SIZE_OPT=ON && cmake --build build -j4

# 64k target (full checks, no debug)
cmake -B build -DDEMO_STRIP_ALL=ON && cmake --build build -j4

# Final release (no checks, absolute minimum)
./scripts/build_final.sh
```

### Developer Build
```bash
cmake -B build -DDEMO_BUILD_TESTS=ON -DDEMO_BUILD_TOOLS=ON
cmake --build build -j4
```

### Headless Testing
```bash
cmake -B build_headless -DDEMO_HEADLESS=ON && cmake --build build_headless -j4
./build_headless/demo64k --headless --duration 30
```
See `doc/HEADLESS_MODE.md`.

### Size Measurement
```bash
./scripts/measure_size.sh
```
Measures demo vs external library size. See `doc/SIZE_MEASUREMENT.md`.

---

## Testing

### Run All Tests
```bash
cmake -B build -DDEMO_BUILD_TESTS=ON
cmake --build build -j4
cd build && ctest
# OR: make run_all_tests
```

### Run Subsystem Tests
```bash
make run_audio_tests    # Audio system tests
make run_gpu_tests      # GPU/shader tests
make run_3d_tests       # 3D rendering tests
make run_assets_tests   # Asset system tests
make run_util_tests     # Utility tests
```

### Run Specific Test
```bash
./build/test_synth
```

---

## Training

### Patch-Based (Recommended)
Extracts patches at salient points, trains on center pixels only (matches WGSL sliding window):
```bash
# Train with 32×32 patches at detected corners/edges
./training/train_cnn.py \
  --input training/input/ --target training/output/ \
  --patch-size 32 --patches-per-image 64 --detector harris \
  --layers 3 --kernel_sizes 3,5,3 --epochs 5000 --batch_size 16 \
  --checkpoint-every 1000
```

**Training behavior:**
- Loss computed only on center pixels (excludes conv padding borders)
- For 3-layer network: excludes 3px border on each side
- Matches GPU shader sliding-window paradigm

**Detectors:** `harris` (default), `fast`, `shi-tomasi`, `gradient`

### Full-Image
Processes entire image with sliding window (matches WGSL):
```bash
./training/train_cnn.py \
  --input training/input/ --target training/output/ \
  --layers 3 --kernel_sizes 3,5,3 --epochs 10000 --batch_size 8 \
  --checkpoint-every 1000
```

### Export & Validation
```bash
# Generate shaders from checkpoint
./training/train_cnn.py --export-only checkpoints/checkpoint_epoch_5000.pth

# Generate ground truth (sliding window, no tiling)
./training/train_cnn.py --infer input.png \
  --export-only checkpoints/checkpoint_epoch_5000.pth \
  --output ground_truth.png
```

**Inference:** Processes full image with sliding window (each pixel from NxN neighborhood). No tiling artifacts.

**Kernel sizes:** 3×3 (36 weights), 5×5 (100 weights), 7×7 (196 weights)

### CNN v2 Training

Enhanced CNN with parametric static features (7D input: RGBD + UV + sin encoding + bias).

**Complete Pipeline** (recommended):
```bash
# Train → Export → Build → Validate (default config)
./scripts/train_cnn_v2_full.sh

# Custom training parameters
./scripts/train_cnn_v2_full.sh --epochs 500 --batch-size 32 --checkpoint-every 100

# Custom architecture
./scripts/train_cnn_v2_full.sh --kernel-sizes 3,5,3 --num-layers 3 --mip-level 1

# Grayscale loss (compute loss on luminance instead of RGBA)
./scripts/train_cnn_v2_full.sh --grayscale-loss

# Custom directories
./scripts/train_cnn_v2_full.sh --input training/input --target training/target_2

# Full-image mode (instead of patch-based)
./scripts/train_cnn_v2_full.sh --full-image --image-size 256

# See all options
./scripts/train_cnn_v2_full.sh --help
```

**Defaults:** 200 epochs, 3×3 kernels, 8→4→4 channels, batch-size 16, patch-based (8×8, harris detector).
- Live progress with single-line update
- Validates all input images on final epoch
- Exports binary weights (storage buffer architecture)
- All parameters configurable via command-line

**Validation Only** (skip training):
```bash
# Use latest checkpoint
./scripts/train_cnn_v2_full.sh --validate

# Use specific checkpoint
./scripts/train_cnn_v2_full.sh --validate checkpoints/checkpoint_epoch_50.pth
```

**Manual Training:**
```bash
# Default config
./training/train_cnn_v2.py \
  --input training/input/ --target training/target_2/ \
  --epochs 100 --batch-size 16 --checkpoint-every 5

# Custom architecture (per-layer kernel sizes)
./training/train_cnn_v2.py \
  --input training/input/ --target training/target_2/ \
  --kernel-sizes 1,3,5 \
  --epochs 5000 --batch-size 16

# Mip-level for p0-p3 features (0=original, 1=half, 2=quarter, 3=eighth)
./training/train_cnn_v2.py \
  --input training/input/ --target training/target_2/ \
  --mip-level 1 \
  --epochs 100 --batch-size 16

# Grayscale loss (compute loss on luminance Y = 0.299*R + 0.587*G + 0.114*B)
./training/train_cnn_v2.py \
  --input training/input/ --target training/target_2/ \
  --grayscale-loss \
  --epochs 100 --batch-size 16
```

**Export Binary Weights:**
```bash
./training/export_cnn_v2_weights.py checkpoints/checkpoint_epoch_100.pth \
  --output-weights workspaces/main/cnn_v2_weights.bin
```

Generates binary format: header + layer info + f16 weights (~3.2 KB for 3-layer model).
Storage buffer architecture allows dynamic layer count.

**TODO:** 8-bit quantization for 2× size reduction (~1.6 KB). Requires quantization-aware training (QAT).

```

**Validation:** Use HTML tool (`tools/cnn_v2_test/index.html`) for CNN v2 validation. See `doc/CNN_V2_WEB_TOOL.md`.

---

## Timeline

### Manual Editing
Edit `workspaces/main/timeline.seq`:
```text
SEQUENCE 0.0 0
  EFFECT + HeptagonEffect 0.0 60.0 0
```
Rebuild to apply. See `doc/SEQUENCE.md`.

### Visual Editor
```bash
open tools/timeline_editor/index.html
```
Features: Drag/drop, beat-based editing, audio playback, waveform visualization, snap-to-beat. See `tools/timeline_editor/README.md`.

---

## Audio

```cpp
#include "audio/audio_engine.h"

audio_init();
static AudioEngine g_audio_engine;
g_audio_engine.init();
g_audio_engine.update(music_time);
g_audio_engine.shutdown();
audio_shutdown();
```
See `doc/TRACKER.md` for music system.

---

## Assets

Edit `workspaces/main/assets.txt`, then rebuild:
```bash
cmake --build build -j4
```
See `doc/ASSET_SYSTEM.md` and `doc/WORKSPACE_SYSTEM.md`.

---

## CNN Testing

### Offline Shader Validation

```bash
# CNN v2 (recommended, fully functional)
./build/cnn_test input.png output.png --cnn-version 2

# CNN v1 (produces incorrect output, debug only)
./build/cnn_test input.png output.png --cnn-version 1

# Adjust blend (0.0 = original, 1.0 = full CNN)
./build/cnn_test input.png output.png --cnn-version 2 --blend 0.5

# Debug hex dump (first 8 pixels)
./build/cnn_test input.png output.png --cnn-version 2 --debug-hex
```

**Status:**
- **CNN v2:** ✅ Fully functional, matches CNNv2Effect
- **CNN v1:** ⚠️ Produces incorrect output, use CNNEffect in demo for validation

See `doc/CNN_TEST_TOOL.md` for full documentation.

---

## Modifying Build System

- **Add build option:** Edit `cmake/DemoOptions.cmake`
- **Add source files:** Edit `cmake/DemoSourceLists.cmake`
- **Add test:** Edit `cmake/DemoTests.cmake`
- **Add tool:** Edit `cmake/DemoTools.cmake`
- **Add library:** Edit `cmake/DemoLibraries.cmake`

See `doc/CMAKE_MODULES.md` for full architecture and shared macros.

---

## Additional Documentation

- **Build System:** `doc/BUILD.md` - Multi-platform, size optimization
- **CMake Modules:** `doc/CMAKE_MODULES.md` - Module architecture, shared macros
- **Tools:** `doc/TOOLS_REFERENCE.md` - spectool, coverage, Windows cross-compile
- **Shaders:** `doc/SEQUENCE.md` - Timeline format, shader parameters
- **3D:** `doc/3D.md` - Hybrid rendering, scene format
- **Hot Reload:** `doc/HOT_RELOAD.md` - Debug file watching