bake fix PROVEN: KDTree-IDW vertex sampling kills the dark patches in 0.3s; axis + gamma gotchas documented; production path defined

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

BENCHMARKS.md

@@ -280,3 +280,35 @@ unusably slow (per-triangle Python rasterizer loop). Verdict unchanged —
 the attrs-projection had already convicted the Metal texel-sampling — but
 this rules out "just use the Python baker" as shipped: it needs the
 fast-rasterizer rewrite + export fix (in progress as fast_bake_test.py).
+
+## 11 · BAKE FIX PROVEN (2026-07-19 evening) — dark patches eliminated
+
+`trellis2-bench/render_vbake5_front.png`: full anatomy figure, correct
+colors, ZERO dark patches — from the same decoder attrs the Metal baker
+mangles. Method: cKDTree IDW sampling of the voxel grid at mesh vertices
+(k=4, distance² weights, 1.5-voxel radius, single-nearest fallback) →
+vertex-colored GLB. **Sampling cost: 0.3s** for 270K verts / 1.4M voxels.
+
+Two integration gotchas (cost hours; do not rediscover):
+1. **Axis spaces.** Voxel grid + raw pipeline mesh = Z-up-long-axis in
+   [-0.5,0.5]³; GLB-loaded meshes = glTF Y-up. Transform before sampling:
+   `(x,y,z)_gltf → (x,−z,y)_voxel`. The "mangled blob" renders were ONLY
+   this (figure viewed down its own axis) — no data corruption anywhere.
+2. **glTF vertex colors are LINEAR** — do not pre-gamma (double-gamma =
+   washed out). Store linear, let the renderer do the transfer.
+
+Also learned: raw `MeshWithVoxel.vertices/faces` need to_glb's weld/init
+before use as a plain triangle soup; `output_3d.obj` inherits the raw
+convention. And xatlas hangs (2h+) on écorché-topology meshes — the UV
+path needs chart budgeting or per-island parallel unwrap.
+
+### Production path (next session)
+- Option A (fast to ship): full-density vertex-colored GLB as the raw
+  output; MESHGOD's Blender finish farm already decimates + can bake
+  verts→texture (standard Blender bake) — sidesteps xatlas entirely.
+- Option B (fal-parity): fast bucket rasterizer (written, in
+  fast_bake_test.py) + xatlas-alternative UV → 2048² texture bake with
+  this sampler. Needs the écorché-safe unwrap.
+- Wire as `--baker python-fast` in the Jourloy fork + trellis-mac, make it
+  the default over the convicted Metal texel path; port sampler to MLX
+  (trivial — gather + weighted sum) for the pure-MLX lane.

docs/FABLE_STARTUP_PACKET.md

@@ -417,3 +417,35 @@ The vendored Jourloy/PR#175 tree now lives on our Gitea:
 hyphens), branch `main`, pin tag `pr175-head-754d403`. m3 staging clone has
 it as remote `partly`; `origin` stays github/Jourloy for rebases. All our
 kernel/bake work lands as commits on this fork.
+
+## 11 · BAKE FIX PROVEN (2026-07-19 evening) — dark patches eliminated
+
+`trellis2-bench/render_vbake5_front.png`: full anatomy figure, correct
+colors, ZERO dark patches — from the same decoder attrs the Metal baker
+mangles. Method: cKDTree IDW sampling of the voxel grid at mesh vertices
+(k=4, distance² weights, 1.5-voxel radius, single-nearest fallback) →
+vertex-colored GLB. **Sampling cost: 0.3s** for 270K verts / 1.4M voxels.
+
+Two integration gotchas (cost hours; do not rediscover):
+1. **Axis spaces.** Voxel grid + raw pipeline mesh = Z-up-long-axis in
+   [-0.5,0.5]³; GLB-loaded meshes = glTF Y-up. Transform before sampling:
+   `(x,y,z)_gltf → (x,−z,y)_voxel`. The "mangled blob" renders were ONLY
+   this (figure viewed down its own axis) — no data corruption anywhere.
+2. **glTF vertex colors are LINEAR** — do not pre-gamma (double-gamma =
+   washed out). Store linear, let the renderer do the transfer.
+
+Also learned: raw `MeshWithVoxel.vertices/faces` need to_glb's weld/init
+before use as a plain triangle soup; `output_3d.obj` inherits the raw
+convention. And xatlas hangs (2h+) on écorché-topology meshes — the UV
+path needs chart budgeting or per-island parallel unwrap.
+
+### Production path (next session)
+- Option A (fast to ship): full-density vertex-colored GLB as the raw
+  output; MESHGOD's Blender finish farm already decimates + can bake
+  verts→texture (standard Blender bake) — sidesteps xatlas entirely.
+- Option B (fal-parity): fast bucket rasterizer (written, in
+  fast_bake_test.py) + xatlas-alternative UV → 2048² texture bake with
+  this sampler. Needs the écorché-safe unwrap.
+- Wire as `--baker python-fast` in the Jourloy fork + trellis-mac, make it
+  the default over the convicted Metal texel path; port sampler to MLX
+  (trivial — gather + weighted sum) for the pure-MLX lane.