From 603efcf7e2ad35a21b46f1f21bdf750d92713117 Mon Sep 17 00:00:00 2001 From: m3ultra Date: Sun, 19 Jul 2026 14:03:53 +1000 Subject: [PATCH] =?UTF-8?q?docs+benchmarks:=20dark-patch=20verdict=20?= =?UTF-8?q?=E2=80=94=20decoder=20attrs=20near-fal=20clean,=20Metal=20texel?= =?UTF-8?q?-sampling=20convicted;=20regular-grid=20gather=20fix=20designed?= =?UTF-8?q?;=20parity=20fixtures=20complete?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- BENCHMARKS.md | 27 +++++++++++++++++++++++++++ docs/FABLE_STARTUP_PACKET.md | 27 +++++++++++++++++++++++++++ 2 files changed, 54 insertions(+) diff --git a/BENCHMARKS.md b/BENCHMARKS.md index 3e62cda..c686749 100644 --- a/BENCHMARKS.md +++ b/BENCHMARKS.md @@ -243,3 +243,30 @@ on M3 Ultra these 2B GEMM-bound models get ~1% from mx.compile fusion; the tune's real wins were T4 fused attention (texture stage) + T3 compile-safety. Branch mlx-tune @ 5a32240; flag HY3D_MLX_COMPILE=1. Worth re-benching on M1 Ultra where launch overhead is proportionally larger. + +## 10 · DARK-PATCH VERDICT: Metal texel-sampling convicted (2026-07-19) + +Decisive experiment: dumped the decoded tex voxels (E2 fixture, +1,398,769 voxels × 6 PBR attrs) and rendered base_color as a direct +front-projection — `trellis2-bench/attrs_front.png`. **The attrs are +near-fal quality** (clean anatomy palette; dark voxels only 5.6%, all +interior). Both local pipelines (trellis-mac MPS and Jourloy MLX) produce +the same mottled dark bake from these clean attrs, and both share the +pedronaugusto mtldiffrast/mtlbvh texel→voxel sampling. ⇒ **the bake's +attr-sampling is the sole quality gap.** The 3h+ KDTree run is now merely +confirmatory (left running). + +### Designed fix (next session's opening move) +The attrs live on a REGULAR voxel grid — no BVH/KDTree needed at all: +texel → (xatlas UV → triangle barycentric → world pos) → +`grid[(pos-origin)/voxel_size]` direct index (+8-neighbor occupancy +search). One vectorized gather over all texels; replaces the suspect +ray-cast sampling entirely; implementable in torch-MPS or MLX in ~a page. +Validate against `attrs_front.png` colors + the fal render. If it works, +BOTH local paths get fal-class texture quality at zero bake-speed risk. + +### Parity fixture set: COMPLETE +All 8 fixtures captured at `trellis2-bench/parity_fixtures/` (cond_512/ +1024, ss_coords, shape_slat, shape_dec, tex_slat, tex_voxels, mesh_final; +seed 42, 1024-cascade). Hook env needed: PYTORCH_ENABLE_MPS_FALLBACK=1 +ATTN_BACKEND=sdpa SPARSE_ATTN_BACKEND=sdpa SPARSE_CONV_BACKEND=flex_gemm. diff --git a/docs/FABLE_STARTUP_PACKET.md b/docs/FABLE_STARTUP_PACKET.md index 4d654c2..abf962a 100644 --- a/docs/FABLE_STARTUP_PACKET.md +++ b/docs/FABLE_STARTUP_PACKET.md @@ -383,3 +383,30 @@ Done this session (all committed; BENCHMARKS.md has the rows): 5. **Dark-patch culprit narrowed**: reproduces on BOTH independent pipelines (trellis-mac MPS + Jourloy MLX) → shared pedronaugusto Metal texel-sampling (mtldiffrast/BVH) or decoded attrs. fal is clean on the same weights → attrs likely fine → **Metal sampling = prime suspect**. KDTree pure-Python bake control still grinding (2h+, alive, 300% CPU) — its render decides. NEXT (in order): read KDTree verdict when it lands → Hunyuan e2e A/B number → wire prep_local into MESHGOD behind a flag → Target 2 (whole-DiT compile now that T3 unblocked it) → promote mlx-experimental into MODELBEAST as a `trellis2_mlx` operator behind a flag once the bake-quality question is settled. + +## 10 · DARK-PATCH VERDICT: Metal texel-sampling convicted (2026-07-19) + +Decisive experiment: dumped the decoded tex voxels (E2 fixture, +1,398,769 voxels × 6 PBR attrs) and rendered base_color as a direct +front-projection — `trellis2-bench/attrs_front.png`. **The attrs are +near-fal quality** (clean anatomy palette; dark voxels only 5.6%, all +interior). Both local pipelines (trellis-mac MPS and Jourloy MLX) produce +the same mottled dark bake from these clean attrs, and both share the +pedronaugusto mtldiffrast/mtlbvh texel→voxel sampling. ⇒ **the bake's +attr-sampling is the sole quality gap.** The 3h+ KDTree run is now merely +confirmatory (left running). + +### Designed fix (next session's opening move) +The attrs live on a REGULAR voxel grid — no BVH/KDTree needed at all: +texel → (xatlas UV → triangle barycentric → world pos) → +`grid[(pos-origin)/voxel_size]` direct index (+8-neighbor occupancy +search). One vectorized gather over all texels; replaces the suspect +ray-cast sampling entirely; implementable in torch-MPS or MLX in ~a page. +Validate against `attrs_front.png` colors + the fal render. If it works, +BOTH local paths get fal-class texture quality at zero bake-speed risk. + +### Parity fixture set: COMPLETE +All 8 fixtures captured at `trellis2-bench/parity_fixtures/` (cond_512/ +1024, ss_coords, shape_slat, shape_dec, tex_slat, tex_voxels, mesh_final; +seed 42, 1024-cascade). Hook env needed: PYTORCH_ENABLE_MPS_FALLBACK=1 +ATTN_BACKEND=sdpa SPARSE_ATTN_BACKEND=sdpa SPARSE_CONV_BACKEND=flex_gemm.