From edd549e1527444ae9c74c70f1e3e44b11862f3da Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Fri, 13 Feb 2026 19:51:14 +0100
Subject: CNN test tool: Add CNN v2 support with compute shader architecture
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Implement full CNN v2 support for offline validation:
- Add --cnn-version flag (1=render pipeline, 2=compute shader)
- Load binary weights from storage buffer (~3-5 KB)
- Static features compute pass (7D: RGBD + UV + sin + bias)
- Dynamic layer count from binary header
- RGBA32Uint texture readback with f16→u8 conversion
- Custom f16 decoder (handles denormals, infinity, NaN)

Status:
- CNN v1: Produces incorrect output (all white)
- CNN v2: ✅ Fully functional, matches CNNv2Effect

Updated docs:
- doc/CNN_TEST_TOOL.md: Architecture, usage, validation workflow
- doc/HOWTO.md: Recommend v2 for validation

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 doc/HOWTO.md | 40 ++++++++++++----------------------------
 1 file changed, 12 insertions(+), 28 deletions(-)

(limited to 'doc/HOWTO.md')

diff --git a/doc/HOWTO.md b/doc/HOWTO.md
index 1e8b58b..85ce801 100644
--- a/doc/HOWTO.md
+++ b/doc/HOWTO.md
@@ -264,40 +264,24 @@ See `doc/ASSET_SYSTEM.md` and `doc/WORKSPACE_SYSTEM.md`.
 
 ### Offline Shader Validation
 
-**Note:** Tool builds and runs but produces incorrect output. Use CNNEffect visual validation in demo. See `doc/CNN_TEST_TOOL.md`.
-
 ```bash
-# Test trained CNN on PNG input
-./build/cnn_test input.png output.png
+# CNN v2 (recommended, fully functional)
+./build/cnn_test input.png output.png --cnn-version 2
 
-# Adjust blend amount (0.0 = original, 1.0 = full CNN)
-./build/cnn_test input.png output.png --blend 0.5
+# CNN v1 (produces incorrect output, debug only)
+./build/cnn_test input.png output.png --cnn-version 1
 
-# PPM output format
-./build/cnn_test input.png output.ppm --format ppm
-```
+# Adjust blend (0.0 = original, 1.0 = full CNN)
+./build/cnn_test input.png output.png --cnn-version 2 --blend 0.5
 
-### Ground Truth Comparison
-```bash
-# Generate Python ground truth
-./training/train_cnn.py --infer input.png \
-  --export-only checkpoints/checkpoint_epoch_1000.pth \
-  --output ground_truth.png
-
-# Run tool
-./build/cnn_test input.png tool_output.png
-
-# Compare (Python required)
-python3 -c "
-import numpy as np
-from PIL import Image
-gt = np.array(Image.open('ground_truth.png').convert('RGB'))
-out = np.array(Image.open('tool_output.png').convert('RGB'))
-mse = np.mean((gt.astype(float) - out.astype(float)) ** 2)
-print(f'MSE: {mse:.4f} (target: < 10.0)')
-"
+# 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.
 
 ---
-- 
cgit v1.2.3