diff --git a/.gitignore b/.gitignore
index b600824..0c505ed 100644
--- a/.gitignore
+++ b/.gitignore
@@ -36,3 +36,25 @@ tests/ss_dec_ref.bin
 
 # clangd index
 .cache/
+corpus_*/
+crash-*
+
+# fuzzing
+/corpus_*/
+crash-*
+
+# demo server build artifacts
+/server/trellis2-server
+/server/trellis2-server-linux
+/server/vendor/
+
+# python bytecode
+__pycache__/
+*.pyc
+
+# model / reference artifacts
+/models/
+/ggufs/
+/dumps/
+/generations/
+slow-unit-*
diff --git a/CMakeLists.txt b/CMakeLists.txt
index f1c48c5..f6ed085 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -20,6 +20,17 @@ endif()
 # ─────────────────────────────────────────────────────────────────────────
 option(TRELLIS2_USE_EXTERNAL_GGML "Consume external ggml via find_package() instead of the bundled submodule" OFF)
 
+# libFuzzer harnesses (clang only). The sanitizer flags apply globally — set
+# BEFORE any target so the whole tree (ggml, stb decode, preprocessing,
+# loaders) is instrumented. Harness targets live in fuzz/ (added at the end).
+option(TRELLIS2_FUZZ "Build libFuzzer harnesses (requires clang)" OFF)
+set(TRELLIS2_FUZZ_SANITIZERS "address,undefined" CACHE STRING
+    "Sanitizers for the fuzz build")
+if(TRELLIS2_FUZZ)
+    add_compile_options(-fsanitize=${TRELLIS2_FUZZ_SANITIZERS} -fsanitize=fuzzer-no-link -fno-omit-frame-pointer -g -O1)
+    add_link_options(-fsanitize=${TRELLIS2_FUZZ_SANITIZERS})
+endif()
+
 # ggml options — enable Metal on Apple (bundled-ggml path only)
 option(TRELLIS2_METAL "Enable Metal backend" ON)
 if(APPLE AND TRELLIS2_METAL AND NOT TRELLIS2_USE_EXTERNAL_GGML)
@@ -35,17 +46,28 @@ else()
     set(TRELLIS2_GGML_TARGET ggml)
 endif()
 
-add_library(trellis2 trellis2.cpp trellis2.h)
+add_library(trellis2
+    trellis2.cpp trellis2.h
+    trellis2_capi.cpp trellis2_capi.h
+    mesh_export.cpp mesh_export.h
+    third_party/xatlas/xatlas.cpp)
 target_include_directories(trellis2 PUBLIC
     ${CMAKE_CURRENT_SOURCE_DIR}
     ${CMAKE_CURRENT_SOURCE_DIR}/stb
 )
+# trellis2_capi.cpp reuses the example isosurface extractor for the demo path;
+# mesh_export.cpp vendors xatlas for the optional chart-based UV unwrap.
+target_include_directories(trellis2 PRIVATE
+    ${CMAKE_CURRENT_SOURCE_DIR}/examples
+    ${CMAKE_CURRENT_SOURCE_DIR}/third_party/xatlas)
+
+find_package(Threads REQUIRED)  # xatlas uses std::thread
 
 if(TRELLIS2_USE_EXTERNAL_GGML AND DEFINED GGML_INCLUDE_DIR)
     target_include_directories(trellis2 PUBLIC ${GGML_INCLUDE_DIR})
 endif()
 
-target_link_libraries(trellis2 PUBLIC ${TRELLIS2_GGML_TARGET})
+target_link_libraries(trellis2 PUBLIC ${TRELLIS2_GGML_TARGET} PRIVATE Threads::Threads)
 target_compile_features(trellis2 PUBLIC cxx_std_14)
 
 set_property(TARGET trellis2 PROPERTY POSITION_INDEPENDENT_CODE ON)
@@ -62,5 +84,10 @@ endif()
 
 option(TRELLIS2_BUILD_TESTS "Build test executables" OFF)
 if(TRELLIS2_BUILD_TESTS)
+    enable_testing()
     add_subdirectory(tests)
 endif()
+
+if(TRELLIS2_FUZZ)
+    add_subdirectory(fuzz)
+endif()
diff --git a/README.md b/README.md
index cbc7f64..35aee87 100644
--- a/README.md
+++ b/README.md
@@ -1,23 +1,150 @@
 # trellis2.cpp
 
 A C++/[ggml](https://github.com/ggml-org/ggml) implementation of the
-**TRELLIS.2** image-to-3D pipeline (stage 1 first: sparse-structure flow).
+**TRELLIS.2** image-to-3D pipeline: an image goes in, a 3D mesh with per-vertex
+PBR textures comes out, with all inference in C++/ggml (no PyTorch at runtime).
+The demo can also export the result into a portable, full-density **GLB** with
+standard interpolated vertex colour and retained PBR attributes—no reference
+container required.
 
 Modeled structurally after [sam3.cpp](https://github.com/rms80/sam3.cpp):
 single-file library (`trellis2.h` / `trellis2.cpp`), bundled ggml as a
 submodule (Metal on by default on Apple), DLL-export decoration, and a
-CMake build with example executables.
+CMake build with example executables. A flat C ABI (`trellis2_capi.h`) drives
+a Go demo server with a browser mesh viewer.
 
-## Status
+## Quick start (demo)
 
-Early scaffolding. Implemented so far:
+```sh
+git submodule update --init --depth 1                 # ggml
+scripts/download_ggufs.sh                             # prebuilt f16 GGUFs -> ggufs/ (~14 GB)
+docker build -f docker/Dockerfile.demo -t trellis2-demo docker   # CUDA runtime + Go
+# build the CUDA shared lib + Go server, then run
+docker run --rm -v "$PWD":/work -w /work trellis2-demo bash -c '
+  cmake -B build-cuda-shared -G Ninja -DCMAKE_BUILD_TYPE=Release -DGGML_CUDA=ON \
+        -DCMAKE_CUDA_ARCHITECTURES=120 -DBUILD_SHARED_LIBS=ON && cmake --build build-cuda-shared -j
+  cd server && go build -o trellis2-server-linux .'
+docker run --rm --device nvidia.com/gpu=all -v "$PWD":/work -w /work/server -p 8742:8742 \
+  trellis2-demo ./trellis2-server-linux -lib /work/build-cuda-shared/libtrellis2.so \
+  -ggufs /work/ggufs -store /work/generations -unload-idle
+# open http://localhost:8742 and drop an image
+```
+
+Or just run `scripts/demo.sh`, which builds the lib + server, auto-downloads any
+missing GGUFs, and launches the container.
+
+### Prebuilt GGUFs
+
+`scripts/download_ggufs.sh` pulls the ready-made f16 GGUFs from three public repos
+under the [LocalAI-io](https://huggingface.co/LocalAI-io) org, so you can skip the
+safetensors download and the conversion step entirely:
+
+- [`TRELLIS.2-4B-GGUF`](https://huggingface.co/LocalAI-io/TRELLIS.2-4B-GGUF) — MIT
+- [`TRELLIS-image-large-GGUF`](https://huggingface.co/LocalAI-io/TRELLIS-image-large-GGUF) — MIT
+- [`dinov3-vitl16-pretrain-lvd1689m-GGUF`](https://huggingface.co/LocalAI-io/dinov3-vitl16-pretrain-lvd1689m-GGUF) — DINOv3 License (Built with DINOv3)
+
+**Developers** who need the f32 validation variants, or who want to regenerate the
+GGUFs from source, use the original flow instead: `scripts/download_models.sh` (HF
+safetensors → `models/`, ~7 GB) then `docker run … trellis2-ref bash
+scripts/convert_all.sh` (safetensors → GGUF, f16 + f32). The card + license sources
+for the published repos live in `scripts/hf/`, and `scripts/upload_ggufs.sh`
+(re)publishes them.
+
+Completed generations are committed atomically under `generations/` (final
+mesh, replay frames, and manifest) and restored with the same job IDs after a
+server restart. Pass `-store ''` to disable persistence or `-store PATH` to use
+a different durable location. Incomplete writes are ignored on startup. With
+`-unload-idle`, the HTTP server starts without allocating model VRAM, loads the
+pipeline on the first generation, and releases it again when the queue is idle.
+
+The browser UI has a **quality** selector: coarse preview (64³ marching cubes),
+512³ fine, or **1024³ cascade** (the TRELLIS.2 default and highest resolution
+currently supported here). Upstream's optional 1536 cascade is not yet ported. Coarse falls
+back automatically if the shape-SLAT models are absent (`-coarse`); the 1024
+cascade needs the extra 1024 model (`-no-1024` disables it).
+Enable **free VRAM when idle** to unload the resident model pipeline between
+generations; the next queued generation reloads it automatically.
+**Live steps** is off by default because each sparse-structure frame requires an
+extra CPU occupancy decode between GPU inference steps. Its button always says
+`on` or `off`; enabling it records the frames used by replay and showcase mode.
+Completed jobs expose `durationMs`, `livePreview`, and per-stage `stageTimings`
+through `/api/job/{id}` and persist those diagnostics in their manifest.
+The always-visible **asset export** panel preserves the generated polygon count,
+can preview component cleanup, optionally keep only the largest connected piece,
+restore the original preview, and download a Three.js-ready GLB. Dense generated
+materials are stored as standard interpolated vertex colours rather than a
+sub-texel per-triangle atlas; original metallic/roughness values are also retained
+in the custom `_METALLIC_ROUGHNESS` attribute. All components are preserved by
+default; destructive cleanup must be selected explicitly. Showcase mode likewise loads the original
+full-density mesh. Open `/showcase` for the separate full-screen storyboard: it
+starts each generation with its saved source image centered, moves that image to
+the upper-right, replays the recorded stages, and then lingers on a slowly
+rotating final model. New generations retain the original upload byte-for-byte
+for display, plus the full-resolution processed PNG actually used by TRELLIS for
+repeatable server-side regeneration without another upload. Select a saved mesh
+and use **regenerate from saved image** to run it again with the current settings.
+Older manifests fall back to their thumbnail and can only regenerate when their
+older processed source file is available.
+
+On a 16 GB RTX 50-series: the 512 fine path runs image→mesh in ~110 s (~1M-vertex
+512³ mesh); the 1024 cascade adds a second 1.3B-model pass and the 1024³ decoder
+for a ~5M-vertex mesh (~5 min, ~10 GB VRAM, and a ~14 GB host-RAM spike for the
+1024³ sparse-conv decode).
+
+## Pipeline
+
+```
+image (RGB/RGBA)
+  → background cleanup  border-connected black/white → feathered alpha        [C++/browser]
+  → preprocess          alpha bbox crop, premultiply, PIL-exact Lanczos-512   [C++, byte-exact]
+  → DINOv3 ViT-L/16     [1, 1029, 1024] conditioning tokens                   [C++/ggml]
+  → SS-flow DiT         1.3B dense DiT, 12-step CFG flow-Euler → z_s          [C++/ggml]
+  → SS decoder          dense 3D-conv → 64³ occupancy → 32³ voxel scaffold    [C++/ggml]
+  → shape-SLAT DiT      1.3B sparse DiT over active voxels, 12-step CFG       [C++/ggml]
+  → shape VAE decoder   sparse ConvNeXt U-Net, 16× up → decoded dual grid      [C++/ggml]
+  ├→ flexible dual grid → triangle mesh                                        [C++]
+  └→ shape VAE encoder  validated dual-grid → shape SLat + subdivision guide   [C++/ggml]
+     → texture-SLAT DiT shape-SLat concat conditioning                         [C++/ggml]
+     → texture decoder  replay subdivision → sparse 6-channel PBR volume       [C++/ggml]
+  → material sampling   trilinear PBR at surface vertices                      [C++]
+```
 
-- **`.dinodata` loader** — reads the DINOv3 conditioning tensor that the
-  sparse-structure flow DiT consumes as cross-attention K/V. This is the full
-  DINOv3 ViT-L/16 token sequence (`[1, 1029, 1024]` = 1 CLS + 4 register +
-  1024 patch) of the **last transformer layer** with an **affine-free
-  LayerNorm** (NOT HF's `last_hidden_state`). `neg_cond = zeros_like(cond)`,
-  so it is never stored. Files are produced by `trellis2-shiv/dump_dinodata.py`.
+The **1024 cascade** (default in TRELLIS.2) adds a second pass on top: the 512
+result's decoder `.upsample(×4)` predicts a denser coordinate scaffold, which is
+quantized to 64³ and fed to a second 1.3B shape-SLAT flow (the 1024 model,
+conditioned on a 1024-res DINOv3 encode) and the same decoder at 1024³ — a
+~5M-vertex mesh. The ~49k-token HR attention only fits in VRAM via flash
+attention (`sdpa_auto`); see [docs/VERIFICATION.md](docs/VERIFICATION.md).
+
+The neural components are validated tap-by-tap against the PyTorch reference,
+with separate integration regressions for subdivision guidance, sparse material
+sampling, and GLB alpha preservation — see
+[docs/VERIFICATION.md](docs/VERIFICATION.md). Highlights: preprocessing is
+byte-exact, the DINOv3 encoder matches to rel-L2 ≤ 7e-7 across 40 taps, and the
+sparse U-Net decoder is numerically exact through all four conv levels.
+
+## Components
+
+- **Image preprocessing + DINOv3 encoder** — `trellis2_preprocess_rgba()`
+  reproduces `pipeline.preprocess_image` (the has-alpha path) with a
+  PIL-compatible fixed-point Lanczos-3 resampler (byte-exact vs Pillow).
+  `trellis2_remove_solid_background_rgba()` first converts a detected near-black
+  or near-white background connected to the image border into softly feathered
+  alpha, while preserving enclosed black/white subject details and existing
+  alpha masks. The demo exposes automatic, forced-black, forced-white, and keep
+  original modes.
+  `trellis2_dino_encode()` runs the full DINOv3 ViT-L/16 (axial-2D RoPE,
+  LayerScale, exact-GELU MLP) and applies the affine-free final LayerNorm the
+  flow models expect — the `[1, 1029, 1024]` conditioning that used to come
+  from an external `dump_dinodata.py`. `dino_encode` chains them:
+
+  ```sh
+  ./build/examples/dino_encode ggufs/dino_f16.gguf image.png cond.dinodata
+  ```
+
+- **`.dinodata` loader** — `trellis2_load_dinodata()` still reads/writes the
+  precomputed conditioning tensor (1 CLS + 4 register + 1024 patch, last layer,
+  affine-free LN; `neg_cond = zeros_like(cond)`), for testing and CLI chaining.
 
 - **SS-flow DiT weights** — `convert_ss_flow_to_gguf.py` converts the stage-1
   `ss_flow_img_dit_1_3B_64_bf16` checkpoint to GGUF; `trellis2_ss_flow_load()`
@@ -58,10 +185,10 @@ Early scaffolding. Implemented so far:
   # -> logits [1,64,64,64], occupied(>0) grid (the coarse voxel scaffold)
   ```
 
-- **Occupancy → mesh** — `ss_mesh` decodes a z_s latent and exports the
+- **Occupancy → coarse mesh** — `ss_mesh` decodes a z_s latent and exports the
   `{logit = 0}` isosurface as a watertight OBJ via a self-contained marching
   cubes (`examples/marching_cubes.h`, the tetrahedral / Freudenthal variant — no
-  256-row table, provably manifold). Chain it after sampling to *see* the result:
+  256-row table, provably manifold). This is the fast preview path:
 
   ```sh
   ./build/examples/ss_sample ss_flow_dit_f16.gguf /path/img.dinodata z_s.latent
@@ -69,6 +196,27 @@ Early scaffolding. Implemented so far:
   # -> watertight shape.obj in the centered unit cube; open in any 3D viewer
   ```
 
+- **Shape-SLAT flow + decoder (fine geometry)** — `trellis2_slat_flow_sample()`
+  runs the sparse 1.3B DiT over the active voxels of the 32³ scaffold (same
+  block structure as the SS-flow DiT, 3D RoPE over each voxel's coords),
+  denormalized with `shape_slat_normalization` baked into the GGUF.
+  `trellis2_shape_dec_decode()` runs `FlexiDualGridVaeDecoder` — a sparse
+  ConvNeXt U-Net whose 3×3×3 submanifold convolutions are expressed as 27
+  gather+GEMM steps, with each level's learned subdivision growing the active
+  set (32³ → 512³, 16×). `examples/flexible_dual_grid.h` turns the 7-channel
+  per-voxel output (dual-vertex offset, per-axis intersection flags, quad split
+  weight) into the triangle mesh. This is the real TRELLIS.2 geometry, driven
+  end-to-end by the demo server.
+
+- **PBR texture generation** — the decoded dual grid is encoded to the shape
+  SLat used to condition texture flow, using the numerically validated
+  standalone texturing path. The decoded six-channel volume (base color,
+  metallic, roughness, alpha) is sampled trilinearly at the actual dual-grid
+  surface positions. Collapsed all-saturated outputs are rejected instead of
+  being persisted as apparently successful textures. The browser linearizes base
+  color before PBR lighting and preserves opacity. Material sampling steps are
+  controlled separately from geometry steps, matching upstream's defaults.
+
 ## Validate the forward pass
 
 ```sh
@@ -154,11 +302,16 @@ reduction.
 | `trellis2.cpp` | implementation                                         |
 | `convert_ss_flow_to_gguf.py` | stage-1 DiT checkpoint → GGUF converter  |
 | `convert_ss_dec_to_gguf.py`  | stage-1 decoder checkpoint → GGUF converter |
-| `examples/`    | CLI tools (`dino_info`, `ss_flow_info`, `ss_sample`, `ss_decode`, `ss_mesh`) |
+| `mesh_export.{h,cpp}` | CUDA-free full-density GLB export with direct vertex colour/PBR attributes |
+| `examples/`    | CLI tools (`dino_info`, `ss_flow_info`, `ss_sample`, `ss_decode`, `ss_mesh`, `mesh2glb`) |
 | `examples/marching_cubes.h` | single-file isosurface → OBJ extractor      |
+| `third_party/` | vendored `xatlas` (opt-in chart-based UV unwrap) |
 | `ggml/`        | submodule, pinned to the same commit as sam3.cpp       |
 | `stb/`         | `stb_image.h` / `stb_image_write.h` for image I/O      |
 
 ## License
 
-MIT. See [LICENSE](LICENSE).
+MIT. See [LICENSE](LICENSE). Vendored third-party code is also MIT:
+[meshoptimizer](https://github.com/zeux/meshoptimizer) (Arseny Kapoulkine) and
+[xatlas](https://github.com/jpcy/xatlas) (Jonathan Young) under `third_party/`,
+and `stb` (public domain / MIT).
diff --git a/convert_dino_to_gguf.py b/convert_dino_to_gguf.py
new file mode 100644
index 0000000..d5a102f
--- /dev/null
+++ b/convert_dino_to_gguf.py
@@ -0,0 +1,201 @@
+#!/usr/bin/env python3
+"""
+Convert the DINOv3 ViT-L/16 image-conditioning encoder (HF format,
+facebook/dinov3-vitl16-pretrain-lvd1689m or a mirror) to a GGUF file for
+trellis2.cpp.
+
+TRELLIS.2 uses this model (transformers DINOv3ViTModel) to turn the
+preprocessed 512x512 input image into the [1, 1029, 1024] conditioning tensor
+consumed by the flow models: 1 CLS + 4 register + 32x32 patch tokens, last
+transformer layer output passed through an affine-free layer norm (the model's
+own final `norm` layer is NOT applied).
+
+Architecture (config.json): hidden 1024, 24 layers, 16 heads, MLP 4096 (exact
+GELU, not gated), patch 16, axial 2D RoPE over patch-center coords with
+theta=100, LayerScale on both residual branches, q/v/o biases but no k bias.
+
+Self-contained like the other converters (safetensors + numpy). Tensors keep
+their HF state-dict names; hyperparameters travel as `trellis2.dino.*` KV.
+
+Usage:
+    python convert_dino_to_gguf.py --model models/dinov3-vitl16/model.safetensors \
+        --output ggufs/dino_f32.gguf --ftype 0
+
+ftype: 0 = f32 (validation), 1 = f16 (matrices f16; norms/biases/1-D f32).
+"""
+
+import argparse
+import json
+import os
+import struct
+import sys
+
+import numpy as np
+
+# ── GGUF / GGML constants (must match the bundled ggml) ──────────────────────
+GGUF_MAGIC = b"GGUF"
+GGUF_VERSION = 3
+GGUF_ALIGNMENT = 32
+
+GGML_TYPE_F32 = 0
+GGML_TYPE_F16 = 1
+
+GGUF_VT_UINT32 = 4
+GGUF_VT_FLOAT32 = 6
+GGUF_VT_BOOL = 7
+GGUF_VT_STRING = 8
+
+ARCH = "trellis2-dino"
+KV_PREFIX = "trellis2.dino."
+
+
+def _gguf_str(s: str) -> bytes:
+    b = s.encode("utf-8")
+    return struct.pack("<Q", len(b)) + b
+
+
+def _kv(key: str, vtype: int, payload: bytes) -> bytes:
+    return _gguf_str(key) + struct.pack("<I", vtype) + payload
+
+
+def kv_u32(key, v):  return _kv(key, GGUF_VT_UINT32,  struct.pack("<I", int(v)))
+def kv_f32(key, v):  return _kv(key, GGUF_VT_FLOAT32, struct.pack("<f", float(v)))
+def kv_bool(key, v): return _kv(key, GGUF_VT_BOOL,    struct.pack("<?", bool(v)))
+def kv_str(key, v):  return _kv(key, GGUF_VT_STRING,  _gguf_str(str(v)))
+
+
+def _align(n: int, a: int = GGUF_ALIGNMENT) -> int:
+    return (n + a - 1) // a * a
+
+
+def choose_type(name, shape, ftype: int) -> int:
+    if ftype == 0:
+        return GGML_TYPE_F32
+    # matrices f16; 1-D (biases, norms, layerscale) and token embeddings f32
+    if len(shape) < 2:
+        return GGML_TYPE_F32
+    if "cls_token" in name or "register_tokens" in name or "mask_token" in name:
+        return GGML_TYPE_F32
+    return GGML_TYPE_F16
+
+
+def to_bytes(arr_f32: np.ndarray, ggml_type: int) -> bytes:
+    if ggml_type == GGML_TYPE_F32:
+        return arr_f32.astype("<f4", copy=False).tobytes()
+    if ggml_type == GGML_TYPE_F16:
+        return arr_f32.astype("<f2", copy=False).tobytes()
+    raise ValueError(f"unhandled ggml type {ggml_type}")
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Convert DINOv3 ViT-L/16 to GGUF")
+    ap.add_argument("--model", default=os.path.join(os.path.dirname(__file__),
+                    "models", "dinov3-vitl16", "model.safetensors"))
+    ap.add_argument("--config", default=None, help="config.json (default: alongside model)")
+    ap.add_argument("--output", default="dino.gguf")
+    ap.add_argument("--ftype", type=int, default=1, choices=[0, 1])
+    args = ap.parse_args()
+
+    from safetensors.numpy import load_file
+
+    cfg_path = args.config or os.path.join(os.path.dirname(args.model), "config.json")
+    with open(cfg_path) as f:
+        cfg = json.load(f)
+
+    if cfg.get("model_type") != "dinov3_vit":
+        sys.exit(f"error: unexpected model_type {cfg.get('model_type')!r}")
+    if cfg.get("use_gated_mlp"):
+        sys.exit("error: gated MLP variant not supported")
+
+    print(f"model : {args.model}")
+    print(f"output: {args.output}  (ftype={args.ftype})")
+    print(f"arch  : hidden={cfg['hidden_size']} layers={cfg['num_hidden_layers']} "
+          f"heads={cfg['num_attention_heads']} mlp={cfg['intermediate_size']} "
+          f"patch={cfg['patch_size']} registers={cfg['num_register_tokens']} "
+          f"rope_theta={cfg['rope_theta']}")
+
+    metadata = [
+        kv_str("general.architecture", ARCH),
+        kv_str("general.name", "dinov3-vitl16-pretrain-lvd1689m"),
+        kv_u32("general.file_type", args.ftype),
+        kv_u32("general.alignment", GGUF_ALIGNMENT),
+        kv_u32(KV_PREFIX + "hidden_size",         cfg["hidden_size"]),
+        kv_u32(KV_PREFIX + "n_layers",            cfg["num_hidden_layers"]),
+        kv_u32(KV_PREFIX + "n_heads",             cfg["num_attention_heads"]),
+        kv_u32(KV_PREFIX + "intermediate_size",   cfg["intermediate_size"]),
+        kv_u32(KV_PREFIX + "patch_size",          cfg["patch_size"]),
+        kv_u32(KV_PREFIX + "num_register_tokens", cfg["num_register_tokens"]),
+        kv_f32(KV_PREFIX + "layer_norm_eps",      cfg["layer_norm_eps"]),
+        kv_f32(KV_PREFIX + "rope_theta",          cfg["rope_theta"]),
+        kv_bool(KV_PREFIX + "key_bias",           cfg.get("key_bias", False)),
+        # ImageNet normalization baked in so inference needs no external config.
+        kv_f32(KV_PREFIX + "image_mean.0", 0.485),
+        kv_f32(KV_PREFIX + "image_mean.1", 0.456),
+        kv_f32(KV_PREFIX + "image_mean.2", 0.406),
+        kv_f32(KV_PREFIX + "image_std.0",  0.229),
+        kv_f32(KV_PREFIX + "image_std.1",  0.224),
+        kv_f32(KV_PREFIX + "image_std.2",  0.225),
+    ]
+
+    print("loading state_dict...")
+    sd = load_file(args.model)
+
+    tensors = []
+    counts = {GGML_TYPE_F32: 0, GGML_TYPE_F16: 0}
+    for name in sorted(sd.keys()):
+        arr = np.asarray(sd[name]).astype(np.float32)
+        # squeeze leading singleton batch dims of the token embeddings so they
+        # arrive as [n_tokens, hidden] / [hidden]
+        if name.endswith(("cls_token", "mask_token", "register_tokens")):
+            arr = arr.reshape(arr.shape[-2], arr.shape[-1]) if arr.ndim == 3 else arr
+        shape = tuple(arr.shape)
+        # patch_embeddings.weight [OC, IC, KH, KW]: bytes already match ggml's
+        # ne=[KW, KH, IC, OC] expectation — dims just get written reversed.
+        gtype = choose_type(name, shape, args.ftype)
+        raw = to_bytes(np.ascontiguousarray(arr), gtype)
+        dims = list(reversed(shape)) if len(shape) > 0 else [1]
+        tensors.append((name, gtype, dims, raw))
+        counts[gtype] += 1
+
+    print(f"tensors: {len(tensors)}  (f32={counts[GGML_TYPE_F32]}, f16={counts[GGML_TYPE_F16]})")
+
+    header = bytearray()
+    header += GGUF_MAGIC
+    header += struct.pack("<I", GGUF_VERSION)
+    header += struct.pack("<Q", len(tensors))
+    header += struct.pack("<Q", len(metadata))
+    for m in metadata:
+        header += m
+
+    infos = bytearray()
+    offset = 0
+    offsets = []
+    for name, gtype, dims, raw in tensors:
+        offsets.append(offset)
+        offset = _align(offset + len(raw))
+    for (name, gtype, dims, raw), off in zip(tensors, offsets):
+        infos += _gguf_str(name)
+        infos += struct.pack("<I", len(dims))
+        for d in dims:
+            infos += struct.pack("<Q", int(d))
+        infos += struct.pack("<I", gtype)
+        infos += struct.pack("<Q", off)
+
+    pre_data = len(header) + len(infos)
+    pad0 = _align(pre_data) - pre_data
+
+    with open(args.output, "wb") as fout:
+        fout.write(header)
+        fout.write(infos)
+        fout.write(b"\x00" * pad0)
+        for (name, gtype, dims, raw), off in zip(tensors, offsets):
+            fout.write(raw)
+            pad = _align(len(raw)) - len(raw)
+            if pad:
+                fout.write(b"\x00" * pad)
+
+    print(f"wrote {args.output}  ({os.path.getsize(args.output):,} bytes)")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/convert_shape_dec_to_gguf.py b/convert_shape_dec_to_gguf.py
new file mode 100644
index 0000000..5d8b0bb
--- /dev/null
+++ b/convert_shape_dec_to_gguf.py
@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""
+Convert the TRELLIS.2 shape-SLAT VAE decoder checkpoint
+(shape_dec_next_dc_f16c32_fp16.safetensors) to a GGUF file for trellis2.cpp.
+
+This is FlexiDualGridVaeDecoder (a SparseUnetVaeDecoder): a sparse ConvNeXt
+U-Net decoder that turns the 32-channel structured latent on active voxels
+into 7 channels per voxel at 16x the input resolution (dual-vertex offset,
+per-axis intersection flags, quad split weight) for flexible-dual-grid mesh
+extraction. Architecture (config shape_dec_next_dc_f16c32_fp16.json):
+
+    model_channels [1024, 512, 256, 128, 64], num_blocks [4, 16, 8, 4, 0],
+    SparseConvNeXtBlock3d blocks, SparseResBlockC2S3d up-blocks, out 7.
+
+Checkpoint conv weights are stored in FlexGEMM layout [Co, kD, kH, kW, Ci]
+(permuted at module init, then saved). ggml tensors are 4-D, so the kernel
+axes merge: we reshape to [Co, kD*kH*kW, Ci] (identical bytes) and the C++
+side slices per kernel offset into [Ci, Co] GEMM operands.
+
+Usage:
+    python convert_shape_dec_to_gguf.py --output shape_dec.gguf --ftype 1
+
+ftype: 0 = f32 (lossless upcast, validation), 1 = f16 (default).
+"""
+
+import argparse
+import json
+import os
+import struct
+import sys
+
+import numpy as np
+
+GGUF_MAGIC = b"GGUF"
+GGUF_VERSION = 3
+GGUF_ALIGNMENT = 32
+
+GGML_TYPE_F32 = 0
+GGML_TYPE_F16 = 1
+
+GGUF_VT_UINT32 = 4
+GGUF_VT_FLOAT32 = 6
+GGUF_VT_STRING = 8
+
+ARCH = "trellis2-shape-dec"
+KV_PREFIX = "trellis2.shape_dec."
+
+
+def _gguf_str(s):
+    b = s.encode("utf-8")
+    return struct.pack("<Q", len(b)) + b
+
+
+def _kv(key, vtype, payload):
+    return _gguf_str(key) + struct.pack("<I", vtype) + payload
+
+
+def kv_u32(key, v):  return _kv(key, GGUF_VT_UINT32,  struct.pack("<I", int(v)))
+def kv_f32(key, v):  return _kv(key, GGUF_VT_FLOAT32, struct.pack("<f", float(v)))
+def kv_str(key, v):  return _kv(key, GGUF_VT_STRING,  _gguf_str(str(v)))
+
+
+def _align(n, a=GGUF_ALIGNMENT):
+    return (n + a - 1) // a * a
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Convert TRELLIS.2 shape decoder to GGUF")
+    ap.add_argument("--model", default=os.path.join(os.path.dirname(__file__),
+                    "models", "TRELLIS.2-4B", "ckpts", "shape_dec_next_dc_f16c32_fp16.safetensors"))
+    ap.add_argument("--config", default=None)
+    ap.add_argument("--output", default="shape_dec.gguf")
+    ap.add_argument("--ftype", type=int, default=1, choices=[0, 1])
+    args = ap.parse_args()
+
+    import torch
+    from safetensors.torch import load_file
+
+    cfg_path = args.config or (os.path.splitext(args.model)[0] + ".json")
+    with open(cfg_path) as f:
+        cfg = json.load(f)
+    a = cfg["args"]
+    channels = a["model_channels"]
+    nblocks = a["num_blocks"]
+    print(f"model : {args.model}")
+    print(f"output: {args.output}  (ftype={args.ftype})")
+    print(f"arch  : channels={channels} blocks={nblocks} latent={a['latent_channels']}")
+
+    metadata = [
+        kv_str("general.architecture", ARCH),
+        kv_str("general.name", "shape_dec_next_dc_f16c32_fp16"),
+        kv_u32("general.file_type", args.ftype),
+        kv_u32("general.alignment", GGUF_ALIGNMENT),
+        kv_u32(KV_PREFIX + "latent_channels", a["latent_channels"]),
+        kv_u32(KV_PREFIX + "out_channels",    7),
+        kv_u32(KV_PREFIX + "n_levels",        len(channels)),
+        kv_f32(KV_PREFIX + "norm_eps",        1e-6),
+        kv_f32(KV_PREFIX + "voxel_margin",    0.5),
+    ]
+    for i, ch in enumerate(channels):
+        metadata.append(kv_u32(KV_PREFIX + f"channels.{i}", ch))
+    for i, nb in enumerate(nblocks):
+        metadata.append(kv_u32(KV_PREFIX + f"num_blocks.{i}", nb))
+
+    print("loading state_dict...")
+    sd = load_file(args.model)
+
+    tensors = []
+    counts = {GGML_TYPE_F32: 0, GGML_TYPE_F16: 0}
+    for name in sorted(sd.keys()):
+        t = sd[name].float()
+        arr = t.numpy().astype(np.float32)
+        shape = tuple(arr.shape)
+        if arr.ndim == 5:  # FlexGEMM conv weight [Co, kD, kH, kW, Ci] -> [Co, 27, Ci]
+            Co, kD, kH, kW, Ci = shape
+            arr = np.ascontiguousarray(arr).reshape(Co, kD * kH * kW, Ci)
+            shape = arr.shape
+        gtype = GGML_TYPE_F32
+        if args.ftype == 1 and len(shape) >= 2:
+            gtype = GGML_TYPE_F16
+        raw = (arr.astype("<f2") if gtype == GGML_TYPE_F16 else arr.astype("<f4")).tobytes()
+        dims = list(reversed(shape)) if len(shape) > 0 else [1]
+        tensors.append((name, gtype, dims, raw))
+        counts[gtype] += 1
+
+    print(f"tensors: {len(tensors)}  (f32={counts[GGML_TYPE_F32]}, f16={counts[GGML_TYPE_F16]})")
+
+    header = bytearray()
+    header += GGUF_MAGIC
+    header += struct.pack("<I", GGUF_VERSION)
+    header += struct.pack("<Q", len(tensors))
+    header += struct.pack("<Q", len(metadata))
+    for m in metadata:
+        header += m
+
+    infos = bytearray()
+    offset = 0
+    offsets = []
+    for name, gtype, dims, raw in tensors:
+        offsets.append(offset)
+        offset = _align(offset + len(raw))
+    for (name, gtype, dims, raw), off in zip(tensors, offsets):
+        infos += _gguf_str(name)
+        infos += struct.pack("<I", len(dims))
+        for d in dims:
+            infos += struct.pack("<Q", int(d))
+        infos += struct.pack("<I", gtype)
+        infos += struct.pack("<Q", off)
+
+    pre_data = len(header) + len(infos)
+    pad0 = _align(pre_data) - pre_data
+
+    with open(args.output, "wb") as fout:
+        fout.write(header)
+        fout.write(infos)
+        fout.write(b"\x00" * pad0)
+        for (name, gtype, dims, raw), off in zip(tensors, offsets):
+            fout.write(raw)
+            pad = _align(len(raw)) - len(raw)
+            if pad:
+                fout.write(b"\x00" * pad)
+
+    print(f"wrote {args.output}  ({os.path.getsize(args.output):,} bytes)")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/convert_shape_enc_to_gguf.py b/convert_shape_enc_to_gguf.py
new file mode 100644
index 0000000..a03175f
--- /dev/null
+++ b/convert_shape_enc_to_gguf.py
@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""
+Convert the TRELLIS.2 shape-SLAT VAE encoder checkpoint
+(shape_enc_next_dc_f16c32_fp16.safetensors) to a GGUF file for trellis2.cpp.
+
+This is FlexiDualGridVaeEncoder (a SparseUnetVaeEncoder): the mirror of the
+shape/tex decoders. It ingests the res-1024 flexible-dual-grid of the input
+mesh as a 6-channel sparse tensor -- 3 dual-vertex offsets + 3 per-axis
+intersection flags (concatenated in FlexiDualGridVaeEncoder.forward) -- and
+downsamples 16x (four SparseResBlockS2C3d Spatial2Channel steps) to a 32-channel
+latent on the res-64 grid. The texture pipeline uses this latent as concat_cond
+for the tex flow, and the Spatial2Channel steps record the per-level
+subdivision the tex decoder replays to rebuild the res-1024 voxel set.
+
+    model_channels [64,128,256,512,1024], num_blocks [0,4,8,16,4],
+    SparseConvNeXtBlock3d blocks, SparseResBlockS2C3d down-blocks,
+    input_layer 6->64, to_latent 1024->2*32 (mean/logvar; we take mean).
+Conv weights are FlexGEMM [Co,kD,kH,kW,Ci] -> reshaped to [Co, kD*kH*kW, Ci].
+
+Usage: python convert_shape_enc_to_gguf.py --output ggufs/shape_enc_f16.gguf --ftype 1
+"""
+
+import argparse
+import json
+import os
+import struct
+
+import numpy as np
+
+GGUF_MAGIC = b"GGUF"
+GGUF_VERSION = 3
+GGUF_ALIGNMENT = 32
+GGML_TYPE_F32 = 0
+GGML_TYPE_F16 = 1
+GGUF_VT_UINT32 = 4
+GGUF_VT_FLOAT32 = 6
+GGUF_VT_STRING = 8
+
+ARCH = "trellis2-shape-enc"
+KV_PREFIX = "trellis2.shape_enc."
+
+
+def _gguf_str(s):
+    b = s.encode("utf-8")
+    return struct.pack("<Q", len(b)) + b
+
+
+def _kv(key, vtype, payload):
+    return _gguf_str(key) + struct.pack("<I", vtype) + payload
+
+
+def kv_u32(key, v):  return _kv(key, GGUF_VT_UINT32,  struct.pack("<I", int(v)))
+def kv_f32(key, v):  return _kv(key, GGUF_VT_FLOAT32, struct.pack("<f", float(v)))
+def kv_str(key, v):  return _kv(key, GGUF_VT_STRING,  _gguf_str(str(v)))
+
+
+def _align(n, a=GGUF_ALIGNMENT):
+    return (n + a - 1) // a * a
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Convert TRELLIS.2 shape encoder to GGUF")
+    ap.add_argument("--model", default=os.path.join(os.path.dirname(__file__),
+                    "models", "TRELLIS.2-4B", "ckpts", "shape_enc_next_dc_f16c32_fp16.safetensors"))
+    ap.add_argument("--config", default=None)
+    ap.add_argument("--output", default="shape_enc.gguf")
+    ap.add_argument("--ftype", type=int, default=1, choices=[0, 1])
+    args = ap.parse_args()
+
+    from safetensors.torch import load_file
+
+    cfg_path = args.config or (os.path.splitext(args.model)[0] + ".json")
+    with open(cfg_path) as f:
+        cfg = json.load(f)
+    a = cfg["args"]
+    channels = a["model_channels"]
+    nblocks = a["num_blocks"]
+    latent = a["latent_channels"]
+    print(f"model : {args.model}")
+    print(f"output: {args.output}  (ftype={args.ftype})")
+    print(f"arch  : channels={channels} blocks={nblocks} latent={latent}")
+
+    sd_keys_in = None
+    metadata = [
+        kv_str("general.architecture", ARCH),
+        kv_str("general.name", "shape_enc_next_dc_f16c32_fp16"),
+        kv_u32("general.file_type", args.ftype),
+        kv_u32("general.alignment", GGUF_ALIGNMENT),
+        kv_u32(KV_PREFIX + "in_channels",     6),   # 3 dual-vertex offsets + 3 intersection flags
+        kv_u32(KV_PREFIX + "latent_channels", latent),
+        kv_u32(KV_PREFIX + "n_levels",        len(channels)),
+        kv_f32(KV_PREFIX + "norm_eps",        1e-6),
+    ]
+    for i, ch in enumerate(channels):
+        metadata.append(kv_u32(KV_PREFIX + f"channels.{i}", ch))
+    for i, nb in enumerate(nblocks):
+        metadata.append(kv_u32(KV_PREFIX + f"num_blocks.{i}", nb))
+
+    print("loading state_dict...")
+    from safetensors.torch import load_file
+    sd = load_file(args.model)
+    # sanity: input_layer must be 6-channel in
+    il = sd["input_layer.weight"]
+    assert il.shape[1] == 6, f"encoder input_layer expects 6 channels, got {il.shape}"
+
+    tensors = []
+    counts = {GGML_TYPE_F32: 0, GGML_TYPE_F16: 0}
+    for name in sorted(sd.keys()):
+        arr = sd[name].float().numpy().astype(np.float32)
+        shape = tuple(arr.shape)
+        if arr.ndim == 5:  # FlexGEMM conv [Co,kD,kH,kW,Ci] -> [Co, 27, Ci]
+            Co, kD, kH, kW, Ci = shape
+            arr = np.ascontiguousarray(arr).reshape(Co, kD * kH * kW, Ci)
+            shape = arr.shape
+        gtype = GGML_TYPE_F32
+        if args.ftype == 1 and len(shape) >= 2:
+            gtype = GGML_TYPE_F16
+        raw = (arr.astype("<f2") if gtype == GGML_TYPE_F16 else arr.astype("<f4")).tobytes()
+        dims = list(reversed(shape)) if len(shape) > 0 else [1]
+        tensors.append((name, gtype, dims, raw))
+        counts[gtype] += 1
+
+    print(f"tensors: {len(tensors)}  (f32={counts[GGML_TYPE_F32]}, f16={counts[GGML_TYPE_F16]})")
+
+    header = bytearray()
+    header += GGUF_MAGIC
+    header += struct.pack("<I", GGUF_VERSION)
+    header += struct.pack("<Q", len(tensors))
+    header += struct.pack("<Q", len(metadata))
+    for m in metadata:
+        header += m
+
+    infos = bytearray()
+    offset = 0
+    offsets = []
+    for name, gtype, dims, raw in tensors:
+        offsets.append(offset)
+        offset = _align(offset + len(raw))
+    for (name, gtype, dims, raw), off in zip(tensors, offsets):
+        infos += _gguf_str(name)
+        infos += struct.pack("<I", len(dims))
+        for d in dims:
+            infos += struct.pack("<Q", int(d))
+        infos += struct.pack("<I", gtype)
+        infos += struct.pack("<Q", off)
+
+    pre_data = len(header) + len(infos)
+    pad0 = _align(pre_data) - pre_data
+
+    with open(args.output, "wb") as fout:
+        fout.write(header)
+        fout.write(infos)
+        fout.write(b"\x00" * pad0)
+        for (name, gtype, dims, raw), off in zip(tensors, offsets):
+            fout.write(raw)
+            pad = _align(len(raw)) - len(raw)
+            if pad:
+                fout.write(b"\x00" * pad)
+
+    print(f"wrote {args.output}  ({os.path.getsize(args.output):,} bytes)")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/convert_slat_flow_to_gguf.py b/convert_slat_flow_to_gguf.py
new file mode 100644
index 0000000..d188d4d
--- /dev/null
+++ b/convert_slat_flow_to_gguf.py
@@ -0,0 +1,246 @@
+#!/usr/bin/env python3
+"""
+Convert the TRELLIS.2 shape-SLAT flow DiT checkpoint (sparse DiT over active
+voxels; identical block structure to the SS-flow model, RoPE over voxel coords)
+(slat_flow_img2shape_dit_1_3B_512_bf16.safetensors) to a GGUF file for trellis2.cpp.
+
+This is the stage-1 generator: a ~1.3B-param DiT with adaLN-Zero modulation
+(share_mod), self-attention + cross-attention to the DINOv3 cond tokens, 3D
+RoPE, and QK-RMSNorm. See trellis2/models/sparse_structure_flow.py.
+
+Like the sam3.cpp converters this is a self-contained script (only safetensors
++ numpy + torch). It writes a standard GGUF v3 file — no `gguf` package needed —
+so the C++ side loads it with ggml's built-in gguf_init_from_file(): tensors are
+keyed by their original checkpoint names and hyperparameters travel as KV
+metadata under the `trellis2.slat_flow.*` namespace.
+
+Usage:
+    python convert_ss_flow_to_gguf.py \
+        --model /path/to/slat_flow_img2shape_dit_1_3B_512_bf16.safetensors \
+        --output ss_flow_dit.gguf --ftype 1
+
+    # --model/--config default to the microsoft/TRELLIS.2-4B HF cache snapshot.
+
+ftype: 0 = f32 (lossless upcast from the bf16 checkpoint),
+       1 = f16 (default; big 2-D weight matrices only, norms/gammas stay f32),
+       2 = bf16 (lossless, native checkpoint precision; needs bf16-capable ggml).
+"""
+
+import argparse
+import glob
+import json
+import os
+import struct
+import sys
+
+import numpy as np
+
+# ── GGUF / GGML constants (must match the bundled ggml) ──────────────────────
+GGUF_MAGIC = b"GGUF"
+GGUF_VERSION = 3
+GGUF_ALIGNMENT = 32
+
+# GGML tensor types
+GGML_TYPE_F32 = 0
+GGML_TYPE_F16 = 1
+GGML_TYPE_BF16 = 30
+
+# GGUF metadata value types
+GGUF_VT_UINT32 = 4
+GGUF_VT_INT32 = 5
+GGUF_VT_FLOAT32 = 6
+GGUF_VT_BOOL = 7
+GGUF_VT_STRING = 8
+
+ARCH = "trellis2-slat-flow"
+KV_PREFIX = "trellis2.slat_flow."
+
+DEFAULT_SNAPSHOT = os.path.expanduser(
+    "~/.cache/huggingface/hub/models--microsoft--TRELLIS.2-4B/snapshots/*/ckpts"
+)
+CKPT_STEM = "slat_flow_img2shape_dit_1_3B_512_bf16"
+
+
+# ── GGUF writer (minimal, v3) ────────────────────────────────────────────────
+def _gguf_str(s: str) -> bytes:
+    b = s.encode("utf-8")
+    return struct.pack("<Q", len(b)) + b
+
+
+def _kv(key: str, vtype: int, payload: bytes) -> bytes:
+    return _gguf_str(key) + struct.pack("<I", vtype) + payload
+
+
+def kv_u32(key, v):    return _kv(key, GGUF_VT_UINT32,  struct.pack("<I", int(v)))
+def kv_i32(key, v):    return _kv(key, GGUF_VT_INT32,   struct.pack("<i", int(v)))
+def kv_f32(key, v):    return _kv(key, GGUF_VT_FLOAT32, struct.pack("<f", float(v)))
+def kv_bool(key, v):   return _kv(key, GGUF_VT_BOOL,    struct.pack("<?", bool(v)))
+def kv_str(key, v):    return _kv(key, GGUF_VT_STRING,  _gguf_str(str(v)))
+
+
+def _align(n: int, a: int = GGUF_ALIGNMENT) -> int:
+    return (n + a - 1) // a * a
+
+
+# ── ftype policy ─────────────────────────────────────────────────────────────
+def choose_type(name: str, shape, ftype: int) -> int:
+    """Pick the on-disk ggml type for a tensor given the requested ftype."""
+    if ftype == 0:
+        return GGML_TYPE_F32
+    if ftype == 2:
+        return GGML_TYPE_BF16
+    # ftype == 1: f16 for the big 2-D weight matrices, f32 for everything that
+    # is precision-sensitive (norm gammas, modulation, biases, all 1-D).
+    keep_f32 = ("gamma" in name) or ("modulation" in name) or ("norm" in name)
+    if len(shape) >= 2 and not keep_f32:
+        return GGML_TYPE_F16
+    return GGML_TYPE_F32
+
+
+def to_bytes(t, ggml_type: int) -> bytes:
+    """torch tensor -> raw little-endian bytes in the chosen ggml type."""
+    import torch
+    t = t.detach().cpu().contiguous()
+    if ggml_type == GGML_TYPE_F32:
+        return t.float().numpy().astype("<f4", copy=False).tobytes()
+    if ggml_type == GGML_TYPE_F16:
+        return t.float().numpy().astype("<f2", copy=False).tobytes()
+    if ggml_type == GGML_TYPE_BF16:
+        # bf16 == upper 16 bits of f32, round-to-nearest-even.
+        u32 = t.float().numpy().view(np.uint32)
+        rounded = (u32 + 0x7FFF + ((u32 >> 16) & 1)) >> 16
+        return rounded.astype("<u2", copy=False).tobytes()
+    raise ValueError(f"unhandled ggml type {ggml_type}")
+
+
+def resolve_paths(args):
+    model = args.model
+    if model is None:
+        hits = sorted(glob.glob(os.path.join(DEFAULT_SNAPSHOT, CKPT_STEM + ".safetensors")))
+        if not hits:
+            sys.exit("error: --model not given and no TRELLIS.2-4B snapshot found in HF cache")
+        model = hits[-1]
+    cfg = args.config or (os.path.splitext(model)[0] + ".json")
+    out = args.output or (CKPT_STEM + ".gguf")
+    return model, cfg, out
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Convert TRELLIS.2 SS flow DiT to GGUF")
+    ap.add_argument("--model", default=None, help="path to ...ss_flow...safetensors (default: HF cache)")
+    ap.add_argument("--config", default=None, help="path to matching .json (default: alongside model)")
+    ap.add_argument("--output", default=None, help="output .gguf (default: <stem>.gguf)")
+    ap.add_argument("--pipeline-json", default=None, help="pipeline.json with shape_slat_normalization (default: alongside ckpts dir)")
+    ap.add_argument("--ftype", type=int, default=1, choices=[0, 1, 2],
+                    help="0=f32, 1=f16 (default), 2=bf16")
+    args = ap.parse_args()
+
+    from safetensors.torch import load_file
+
+    model_path, cfg_path, out_path = resolve_paths(args)
+    print(f"model : {model_path}")
+    print(f"config: {cfg_path}")
+    print(f"output: {out_path}  (ftype={args.ftype})")
+
+    with open(cfg_path) as f:
+        cfg = json.load(f)
+    a = cfg["args"]
+    print(f"arch  : {cfg.get('name')}  {a['num_blocks']} blocks, "
+          f"d={a['model_channels']}, heads={a['num_heads']}, cond={a['cond_channels']}")
+
+    rope_freq = a.get("rope_freq", (1.0, 10000.0))
+
+    # ── KV metadata ──────────────────────────────────────────────────────────
+    metadata = [
+        kv_str("general.architecture", ARCH),
+        kv_str("general.name", CKPT_STEM),
+        kv_u32("general.file_type", args.ftype),
+        kv_u32("general.alignment", GGUF_ALIGNMENT),
+        kv_u32(KV_PREFIX + "resolution",     a["resolution"]),
+        kv_u32(KV_PREFIX + "in_channels",    a["in_channels"]),
+        kv_u32(KV_PREFIX + "out_channels",   a["out_channels"]),
+        kv_u32(KV_PREFIX + "model_channels", a["model_channels"]),
+        kv_u32(KV_PREFIX + "cond_channels",  a["cond_channels"]),
+        kv_u32(KV_PREFIX + "num_blocks",     a["num_blocks"]),
+        kv_u32(KV_PREFIX + "num_heads",      a["num_heads"]),
+        kv_f32(KV_PREFIX + "mlp_ratio",      a["mlp_ratio"]),
+        kv_str(KV_PREFIX + "pe_mode",        a.get("pe_mode", "rope")),
+        kv_bool(KV_PREFIX + "share_mod",            a.get("share_mod", False)),
+        kv_bool(KV_PREFIX + "qk_rms_norm",          a.get("qk_rms_norm", False)),
+        kv_bool(KV_PREFIX + "qk_rms_norm_cross",    a.get("qk_rms_norm_cross", False)),
+        kv_f32(KV_PREFIX + "rope_freq_min",  float(rope_freq[0])),
+        kv_f32(KV_PREFIX + "rope_freq_base", float(rope_freq[1])),
+    ]
+
+    # shape_slat_normalization (pipeline.json): the sampler output is
+    # de-normalized with these before the decoder.
+    pj_path = args.pipeline_json or os.path.join(
+        os.path.dirname(os.path.dirname(model_path)), "pipeline.json")
+    with open(pj_path) as f:
+        norm = json.load(f)["args"]["shape_slat_normalization"]
+    assert len(norm["mean"]) == a["out_channels"]
+    for i, v in enumerate(norm["mean"]):
+        metadata.append(kv_f32(KV_PREFIX + f"norm_mean.{i}", v))
+    for i, v in enumerate(norm["std"]):
+        metadata.append(kv_f32(KV_PREFIX + f"norm_std.{i}", v))
+
+    # ── tensors ──────────────────────────────────────────────────────────────
+    print("loading state_dict...")
+    sd = load_file(model_path)
+
+    tensors = []  # (name, ggml_type, dims_ggml_order, raw_bytes)
+    counts = {GGML_TYPE_F32: 0, GGML_TYPE_F16: 0, GGML_TYPE_BF16: 0}
+    for name in sorted(sd.keys()):
+        t = sd[name]
+        shape = tuple(t.shape)
+        gtype = choose_type(name, shape, args.ftype)
+        raw = to_bytes(t, gtype)
+        dims = list(reversed(shape)) if len(shape) > 0 else [1]  # ggml ne[] order
+        tensors.append((name, gtype, dims, raw))
+        counts[gtype] += 1
+
+    print(f"tensors: {len(tensors)}  "
+          f"(f32={counts[GGML_TYPE_F32]}, f16={counts[GGML_TYPE_F16]}, bf16={counts[GGML_TYPE_BF16]})")
+
+    # ── assemble header + infos, compute aligned data offsets ────────────────
+    header = bytearray()
+    header += GGUF_MAGIC
+    header += struct.pack("<I", GGUF_VERSION)
+    header += struct.pack("<Q", len(tensors))
+    header += struct.pack("<Q", len(metadata))
+    for m in metadata:
+        header += m
+
+    infos = bytearray()
+    offset = 0
+    offsets = []
+    for name, gtype, dims, raw in tensors:
+        offsets.append(offset)
+        offset = _align(offset + len(raw))
+    for (name, gtype, dims, raw), off in zip(tensors, offsets):
+        infos += _gguf_str(name)
+        infos += struct.pack("<I", len(dims))
+        for d in dims:
+            infos += struct.pack("<Q", int(d))
+        infos += struct.pack("<I", gtype)
+        infos += struct.pack("<Q", off)
+
+    pre_data = len(header) + len(infos)
+    pad0 = _align(pre_data) - pre_data
+
+    with open(out_path, "wb") as fout:
+        fout.write(header)
+        fout.write(infos)
+        fout.write(b"\x00" * pad0)
+        for (name, gtype, dims, raw), off in zip(tensors, offsets):
+            cur = fout.tell()  # already aligned per loop invariant
+            fout.write(raw)
+            pad = _align(len(raw)) - len(raw)
+            if pad:
+                fout.write(b"\x00" * pad)
+
+    print(f"wrote {out_path}  ({os.path.getsize(out_path):,} bytes)")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/convert_tex_dec_to_gguf.py b/convert_tex_dec_to_gguf.py
new file mode 100644
index 0000000..ecde65f
--- /dev/null
+++ b/convert_tex_dec_to_gguf.py
@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""
+Convert the TRELLIS.2 texture-SLAT VAE decoder checkpoint
+(tex_dec_next_dc_f16c32_fp16.safetensors) to a GGUF file for trellis2.cpp.
+
+This is a SparseUnetVaeDecoder — the SAME sparse ConvNeXt U-Net as the shape
+decoder (FlexiDualGridVaeDecoder) except:
+  * out_channels = 6  (PBR: base_color[3], metallic[1], roughness[1], alpha[1]),
+    no dual-grid geometry head;
+  * pred_subdiv = False  -> NO `to_subdiv` layers. The decoder does not predict
+    which children to keep; it replays the subdivision structure recorded by the
+    shape encoder's Spatial2Channel steps (threaded through the SparseTensor
+    spatial cache). So the tex decoder reconstructs exactly the encoder's
+    res-1024 voxel set; the C++ side must supply that per-level subdivision.
+
+Same architecture/weight layout as the shape decoder otherwise:
+    model_channels [1024,512,256,128,64], num_blocks [4,16,8,4,0],
+    SparseConvNeXtBlock3d blocks, SparseResBlockC2S3d up-blocks.
+Conv weights are FlexGEMM [Co,kD,kH,kW,Ci] -> reshaped to [Co, kD*kH*kW, Ci].
+
+Usage: python convert_tex_dec_to_gguf.py --output ggufs/tex_dec_f16.gguf --ftype 1
+"""
+
+import argparse
+import json
+import os
+import struct
+
+import numpy as np
+
+GGUF_MAGIC = b"GGUF"
+GGUF_VERSION = 3
+GGUF_ALIGNMENT = 32
+GGML_TYPE_F32 = 0
+GGML_TYPE_F16 = 1
+GGUF_VT_UINT32 = 4
+GGUF_VT_FLOAT32 = 6
+GGUF_VT_STRING = 8
+
+ARCH = "trellis2-tex-dec"
+KV_PREFIX = "trellis2.tex_dec."
+
+
+def _gguf_str(s):
+    b = s.encode("utf-8")
+    return struct.pack("<Q", len(b)) + b
+
+
+def _kv(key, vtype, payload):
+    return _gguf_str(key) + struct.pack("<I", vtype) + payload
+
+
+def kv_u32(key, v):  return _kv(key, GGUF_VT_UINT32,  struct.pack("<I", int(v)))
+def kv_f32(key, v):  return _kv(key, GGUF_VT_FLOAT32, struct.pack("<f", float(v)))
+def kv_str(key, v):  return _kv(key, GGUF_VT_STRING,  _gguf_str(str(v)))
+
+
+def _align(n, a=GGUF_ALIGNMENT):
+    return (n + a - 1) // a * a
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Convert TRELLIS.2 texture decoder to GGUF")
+    ap.add_argument("--model", default=os.path.join(os.path.dirname(__file__),
+                    "models", "TRELLIS.2-4B", "ckpts", "tex_dec_next_dc_f16c32_fp16.safetensors"))
+    ap.add_argument("--config", default=None)
+    ap.add_argument("--output", default="tex_dec.gguf")
+    ap.add_argument("--ftype", type=int, default=1, choices=[0, 1])
+    args = ap.parse_args()
+
+    from safetensors.torch import load_file
+
+    cfg_path = args.config or (os.path.splitext(args.model)[0] + ".json")
+    with open(cfg_path) as f:
+        cfg = json.load(f)
+    a = cfg["args"]
+    channels = a["model_channels"]
+    nblocks = a["num_blocks"]
+    out_channels = a["out_channels"]
+    assert out_channels == 6, f"expected 6 PBR channels, got {out_channels}"
+    assert a.get("pred_subdiv", True) is False, "tex decoder must be pred_subdiv=False"
+    print(f"model : {args.model}")
+    print(f"output: {args.output}  (ftype={args.ftype})")
+    print(f"arch  : channels={channels} blocks={nblocks} latent={a['latent_channels']} out={out_channels}")
+
+    metadata = [
+        kv_str("general.architecture", ARCH),
+        kv_str("general.name", "tex_dec_next_dc_f16c32_fp16"),
+        kv_u32("general.file_type", args.ftype),
+        kv_u32("general.alignment", GGUF_ALIGNMENT),
+        kv_u32(KV_PREFIX + "latent_channels", a["latent_channels"]),
+        kv_u32(KV_PREFIX + "out_channels",    out_channels),
+        kv_u32(KV_PREFIX + "n_levels",        len(channels)),
+        kv_f32(KV_PREFIX + "norm_eps",        1e-6),
+    ]
+    for i, ch in enumerate(channels):
+        metadata.append(kv_u32(KV_PREFIX + f"channels.{i}", ch))
+    for i, nb in enumerate(nblocks):
+        metadata.append(kv_u32(KV_PREFIX + f"num_blocks.{i}", nb))
+
+    print("loading state_dict...")
+    sd = load_file(args.model)
+
+    tensors = []
+    counts = {GGML_TYPE_F32: 0, GGML_TYPE_F16: 0}
+    for name in sorted(sd.keys()):
+        arr = sd[name].float().numpy().astype(np.float32)
+        shape = tuple(arr.shape)
+        if arr.ndim == 5:  # FlexGEMM conv [Co,kD,kH,kW,Ci] -> [Co, 27, Ci]
+            Co, kD, kH, kW, Ci = shape
+            arr = np.ascontiguousarray(arr).reshape(Co, kD * kH * kW, Ci)
+            shape = arr.shape
+        gtype = GGML_TYPE_F32
+        if args.ftype == 1 and len(shape) >= 2:
+            gtype = GGML_TYPE_F16
+        raw = (arr.astype("<f2") if gtype == GGML_TYPE_F16 else arr.astype("<f4")).tobytes()
+        dims = list(reversed(shape)) if len(shape) > 0 else [1]
+        tensors.append((name, gtype, dims, raw))
+        counts[gtype] += 1
+
+    print(f"tensors: {len(tensors)}  (f32={counts[GGML_TYPE_F32]}, f16={counts[GGML_TYPE_F16]})")
+
+    header = bytearray()
+    header += GGUF_MAGIC
+    header += struct.pack("<I", GGUF_VERSION)
+    header += struct.pack("<Q", len(tensors))
+    header += struct.pack("<Q", len(metadata))
+    for m in metadata:
+        header += m
+
+    infos = bytearray()
+    offset = 0
+    offsets = []
+    for name, gtype, dims, raw in tensors:
+        offsets.append(offset)
+        offset = _align(offset + len(raw))
+    for (name, gtype, dims, raw), off in zip(tensors, offsets):
+        infos += _gguf_str(name)
+        infos += struct.pack("<I", len(dims))
+        for d in dims:
+            infos += struct.pack("<Q", int(d))
+        infos += struct.pack("<I", gtype)
+        infos += struct.pack("<Q", off)
+
+    pre_data = len(header) + len(infos)
+    pad0 = _align(pre_data) - pre_data
+
+    with open(args.output, "wb") as fout:
+        fout.write(header)
+        fout.write(infos)
+        fout.write(b"\x00" * pad0)
+        for (name, gtype, dims, raw), off in zip(tensors, offsets):
+            fout.write(raw)
+            pad = _align(len(raw)) - len(raw)
+            if pad:
+                fout.write(b"\x00" * pad)
+
+    print(f"wrote {args.output}  ({os.path.getsize(args.output):,} bytes)")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/convert_tex_flow_to_gguf.py b/convert_tex_flow_to_gguf.py
new file mode 100644
index 0000000..4c1abd9
--- /dev/null
+++ b/convert_tex_flow_to_gguf.py
@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""
+Convert a TRELLIS.2 texture-SLAT flow DiT checkpoint
+(slat_flow_imgshape2tex_dit_1_3B_{512,1024}_bf16.safetensors) to GGUF.
+
+Architecturally identical to the shape SLAT flow (same 1536-d / 30-block /
+12-head sparse DiT, adaLN-Zero share_mod, self+cross attention to DINOv3 cond,
+3D RoPE, QK-RMSNorm) with ONE difference: it is conditioned on the shape via
+`concat_cond`. So in_channels = 64 = 32 tex-noise + 32 shape-SLAT, out = 32.
+At sample time the (normalized) shape SLAT is concatenated onto the noise before
+the input layer each step.
+
+Emits the same `trellis2.slat_flow.*` KV as the shape-flow converter so the C++
+loader is shared, plus:
+  * trellis2.slat_flow.concat_cond_channels = 32   (0 on the shape flow)
+  * norm_mean/std          = tex_slat_normalization   (output de-norm, 32)
+  * concat_norm_mean/std   = shape_slat_normalization  (concat_cond in-norm, 32)
+both read from texturing_pipeline.json.
+
+Usage:
+    python convert_tex_flow_to_gguf.py \
+        --model models/TRELLIS.2-4B/ckpts/slat_flow_imgshape2tex_dit_1_3B_512_bf16.safetensors \
+        --texturing-json models/TRELLIS.2-4B/texturing_pipeline.json \
+        --output ggufs/tex_slat_flow_512_f16.gguf --ftype 1
+"""
+
+import argparse
+import json
+import os
+import struct
+
+import numpy as np
+
+GGUF_MAGIC = b"GGUF"
+GGUF_VERSION = 3
+GGUF_ALIGNMENT = 32
+GGML_TYPE_F32 = 0
+GGML_TYPE_F16 = 1
+GGML_TYPE_BF16 = 30
+GGUF_VT_UINT32 = 4
+GGUF_VT_FLOAT32 = 6
+GGUF_VT_BOOL = 7
+GGUF_VT_STRING = 8
+
+ARCH = "trellis2-slat-flow"          # shared loader with the shape SLAT flow
+KV_PREFIX = "trellis2.slat_flow."
+
+
+def _gguf_str(s): b = s.encode("utf-8"); return struct.pack("<Q", len(b)) + b
+def _kv(key, vtype, payload): return _gguf_str(key) + struct.pack("<I", vtype) + payload
+def kv_u32(key, v):  return _kv(key, GGUF_VT_UINT32,  struct.pack("<I", int(v)))
+def kv_f32(key, v):  return _kv(key, GGUF_VT_FLOAT32, struct.pack("<f", float(v)))
+def kv_bool(key, v): return _kv(key, GGUF_VT_BOOL,    struct.pack("<?", bool(v)))
+def kv_str(key, v):  return _kv(key, GGUF_VT_STRING,  _gguf_str(str(v)))
+def _align(n, a=GGUF_ALIGNMENT): return (n + a - 1) // a * a
+
+
+def choose_type(name, shape, ftype):
+    if ftype == 0: return GGML_TYPE_F32
+    if ftype == 2: return GGML_TYPE_BF16
+    keep_f32 = ("gamma" in name) or ("modulation" in name) or ("norm" in name)
+    return GGML_TYPE_F16 if (len(shape) >= 2 and not keep_f32) else GGML_TYPE_F32
+
+
+def to_bytes(t, ggml_type):
+    t = t.detach().cpu().contiguous()
+    if ggml_type == GGML_TYPE_F32: return t.float().numpy().astype("<f4", copy=False).tobytes()
+    if ggml_type == GGML_TYPE_F16: return t.float().numpy().astype("<f2", copy=False).tobytes()
+    if ggml_type == GGML_TYPE_BF16:
+        u32 = t.float().numpy().view(np.uint32)
+        return (((u32 + 0x7FFF + ((u32 >> 16) & 1)) >> 16).astype("<u2", copy=False)).tobytes()
+    raise ValueError(ggml_type)
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Convert TRELLIS.2 texture SLAT flow DiT to GGUF")
+    ap.add_argument("--model", required=True)
+    ap.add_argument("--config", default=None)
+    ap.add_argument("--texturing-json", default=None,
+                    help="texturing_pipeline.json (tex + shape slat normalization)")
+    ap.add_argument("--output", required=True)
+    ap.add_argument("--ftype", type=int, default=1, choices=[0, 1, 2])
+    args = ap.parse_args()
+
+    from safetensors.torch import load_file
+
+    cfg_path = args.config or (os.path.splitext(args.model)[0] + ".json")
+    with open(cfg_path) as f:
+        a = json.load(f)["args"]
+    print(f"model : {args.model}")
+    print(f"output: {args.output}  (ftype={args.ftype})")
+    print(f"arch  : in={a['in_channels']} out={a['out_channels']} cond={a['cond_channels']} "
+          f"d={a['model_channels']} blks={a['num_blocks']} heads={a['num_heads']}")
+
+    concat_cond_channels = a["in_channels"] - a["out_channels"]
+    assert concat_cond_channels > 0, "tex flow must have concat_cond (in > out)"
+
+    tj = args.texturing_json or os.path.join(os.path.dirname(os.path.dirname(args.model)),
+                                             "texturing_pipeline.json")
+    with open(tj) as f:
+        tpa = json.load(f)["args"]
+    tex_norm = tpa["tex_slat_normalization"]
+    shape_norm = tpa["shape_slat_normalization"]
+    assert len(tex_norm["mean"]) == a["out_channels"], "tex_slat_norm must match out_channels"
+    assert len(shape_norm["mean"]) == concat_cond_channels, "shape_slat_norm must match concat_cond"
+
+    rope_freq = a.get("rope_freq", (1.0, 10000.0))
+    metadata = [
+        kv_str("general.architecture", ARCH),
+        kv_str("general.name", os.path.splitext(os.path.basename(args.model))[0]),
+        kv_u32("general.file_type", args.ftype),
+        kv_u32("general.alignment", GGUF_ALIGNMENT),
+        kv_u32(KV_PREFIX + "resolution",     a["resolution"]),
+        kv_u32(KV_PREFIX + "in_channels",    a["in_channels"]),
+        kv_u32(KV_PREFIX + "out_channels",   a["out_channels"]),
+        kv_u32(KV_PREFIX + "concat_cond_channels", concat_cond_channels),
+        kv_u32(KV_PREFIX + "model_channels", a["model_channels"]),
+        kv_u32(KV_PREFIX + "cond_channels",  a["cond_channels"]),
+        kv_u32(KV_PREFIX + "num_blocks",     a["num_blocks"]),
+        kv_u32(KV_PREFIX + "num_heads",      a["num_heads"]),
+        kv_f32(KV_PREFIX + "mlp_ratio",      a["mlp_ratio"]),
+        kv_str(KV_PREFIX + "pe_mode",        a.get("pe_mode", "rope")),
+        kv_bool(KV_PREFIX + "share_mod",         a.get("share_mod", False)),
+        kv_bool(KV_PREFIX + "qk_rms_norm",       a.get("qk_rms_norm", False)),
+        kv_bool(KV_PREFIX + "qk_rms_norm_cross", a.get("qk_rms_norm_cross", False)),
+        kv_f32(KV_PREFIX + "rope_freq_min",  float(rope_freq[0])),
+        kv_f32(KV_PREFIX + "rope_freq_base", float(rope_freq[1])),
+    ]
+    # output de-normalization (tex slat) and concat_cond in-normalization (shape slat)
+    for i, v in enumerate(tex_norm["mean"]):   metadata.append(kv_f32(KV_PREFIX + f"norm_mean.{i}", v))
+    for i, v in enumerate(tex_norm["std"]):    metadata.append(kv_f32(KV_PREFIX + f"norm_std.{i}", v))
+    for i, v in enumerate(shape_norm["mean"]): metadata.append(kv_f32(KV_PREFIX + f"concat_norm_mean.{i}", v))
+    for i, v in enumerate(shape_norm["std"]):  metadata.append(kv_f32(KV_PREFIX + f"concat_norm_std.{i}", v))
+
+    print("loading state_dict...")
+    sd = load_file(args.model)
+    tensors, counts = [], {GGML_TYPE_F32: 0, GGML_TYPE_F16: 0, GGML_TYPE_BF16: 0}
+    for name in sorted(sd.keys()):
+        t = sd[name]; shape = tuple(t.shape)
+        gtype = choose_type(name, shape, args.ftype)
+        raw = to_bytes(t, gtype)
+        dims = list(reversed(shape)) if len(shape) > 0 else [1]
+        tensors.append((name, gtype, dims, raw)); counts[gtype] += 1
+    print(f"tensors: {len(tensors)}  (f32={counts[GGML_TYPE_F32]}, f16={counts[GGML_TYPE_F16]}, bf16={counts[GGML_TYPE_BF16]})")
+
+    header = bytearray(GGUF_MAGIC)
+    header += struct.pack("<I", GGUF_VERSION)
+    header += struct.pack("<Q", len(tensors))
+    header += struct.pack("<Q", len(metadata))
+    for m in metadata: header += m
+
+    infos = bytearray()
+    offset, offsets = 0, []
+    for name, gtype, dims, raw in tensors:
+        offsets.append(offset); offset = _align(offset + len(raw))
+    for (name, gtype, dims, raw), off in zip(tensors, offsets):
+        infos += _gguf_str(name); infos += struct.pack("<I", len(dims))
+        for d in dims: infos += struct.pack("<Q", int(d))
+        infos += struct.pack("<I", gtype); infos += struct.pack("<Q", off)
+
+    pre_data = len(header) + len(infos)
+    pad0 = _align(pre_data) - pre_data
+    with open(args.output, "wb") as fout:
+        fout.write(header); fout.write(infos); fout.write(b"\x00" * pad0)
+        for (name, gtype, dims, raw), off in zip(tensors, offsets):
+            fout.write(raw)
+            pad = _align(len(raw)) - len(raw)
+            if pad: fout.write(b"\x00" * pad)
+    print(f"wrote {args.output}  ({os.path.getsize(args.output):,} bytes)")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/docker/Dockerfile.demo b/docker/Dockerfile.demo
new file mode 100644
index 0000000..ae0b7a0
--- /dev/null
+++ b/docker/Dockerfile.demo
@@ -0,0 +1,14 @@
+# Demo/runtime image: the reference image (CUDA 12.8 runtime + toolchain)
+# plus a Go toolchain, so both libtrellis2.so (CUDA) and the Go demo server
+# build against the SAME glibc/libstdc++ that run them. NixOS host binaries
+# don't survive inside the container (different dynamic loader), hence this.
+#
+# Build:  docker build -f docker/Dockerfile.demo -t trellis2-demo docker
+# Usage:  see scripts/demo.sh
+FROM trellis2-ref
+
+ADD https://go.dev/dl/go1.24.4.linux-amd64.tar.gz /tmp/go.tgz
+RUN tar -C /usr/local -xzf /tmp/go.tgz && rm /tmp/go.tgz
+ENV PATH=/usr/local/go/bin:$PATH
+# go.sum is committed; `go build` fetches the single dep (purego) on demand.
+# A committed server/vendor/ dir (if present) is used automatically.
diff --git a/docker/Dockerfile.ref b/docker/Dockerfile.ref
new file mode 100644
index 0000000..afdd285
--- /dev/null
+++ b/docker/Dockerfile.ref
@@ -0,0 +1,25 @@
+# Python reference environment for parity dumps.
+#
+# Deliberately stock-PyTorch only: no FlexGEMM / flash-attn / o-voxel / CuMesh
+# CUDA extensions. Sparse attention and sparse conv are monkeypatched to dense
+# equivalents by scripts/ref_common.py (batch=1 makes them equal), so reference
+# activations can be produced on GPU or CPU without custom kernels — that also
+# keeps the RTX 5070 Ti (sm_120) out of extension-build trouble.
+#
+# Build:  docker build -f docker/Dockerfile.ref -t trellis2-ref docker
+# Run :   docker run --rm --device nvidia.com/gpu=all \
+#             -v "$PWD":/work -v "$PWD/../python/TRELLIS.2":/trellis2 \
+#             -e PYTHONPATH=/trellis2 -w /work trellis2-ref python scripts/...
+FROM pytorch/pytorch:2.7.1-cuda12.8-cudnn9-devel
+
+RUN pip install --no-cache-dir \
+    "transformers==4.57.1" \
+    safetensors \
+    pillow \
+    numpy \
+    easydict \
+    opencv-python-headless \
+    trimesh \
+    tqdm \
+    imageio \
+    gguf
diff --git a/docs/PLAN.md b/docs/PLAN.md
new file mode 100644
index 0000000..0659e6c
--- /dev/null
+++ b/docs/PLAN.md
@@ -0,0 +1,197 @@
+# trellis2.cpp completion plan
+
+Goal: image in → 3D mesh out, pure C++/ggml inference behind a Go demo server with a
+browser mesh viewer. No PBR textures for now. Process mirrors depth-anything.cpp
+(layer-by-layer parity vs the PyTorch reference) and privacy-filter.cpp (libFuzzer
+harnesses on untrusted inputs, sanitizer builds).
+
+## Pipeline target
+
+TRELLIS.2 "512" pipeline type (non-cascade), geometry only:
+
+```
+image (RGBA preferred)
+  → preprocess (alpha crop, premultiply, resize 512, ImageNet norm)   [C++ port]
+  → DINOv3 ViT-L/16 cond tokens [1, 1+4+1024, 1024]                   [C++ port — was external .dinodata]
+  → SS-flow DiT (1.3B dense, 12-step CFG flow Euler)                  [already ported + validated]
+  → SS decoder → 64³ occupancy → max_pool 32³ → coords                [already ported; pool/coords new]
+  → shape-SLAT flow (1.3B sparse DiT, res 32, 32ch)                   [to port]
+  → FlexiDualGrid VAE decoder (sparse ConvNeXt U-Net, 16× up)         [to port]
+  → flexible dual grid → triangle mesh                                [to port, CPU]
+  → (postprocess: fill holes — best effort, CuMesh not portable)
+```
+
+Fallback shipped at every point in time: marching-cubes preview mesh from the 64³
+occupancy (already works), so the demo is demoable before the SLAT stages land.
+
+The upstream neural background-removal net (BiRefNet/RMBG-2.0, a separate ~1 GB
+model) remains out of scope. The port does include deterministic removal of
+near-black/near-white backgrounds connected to the image border, with soft alpha
+edges and browser controls to force or disable it. Texture and cascade status is
+tracked below.
+
+## Weights
+
+`scripts/download_models.sh` → `models/`. DINOv3 comes from the ungated
+`camenduru/dinov3-vitl16-pretrain-lvd1689m` mirror because the official
+`facebook/dinov3-vitl16-pretrain-lvd1689m` is license-gated and this account has no
+access yet (403). Request access and re-download officially when possible.
+
+## Validation (depth-anything.cpp process)
+
+- Reference activations dumped from Python via forward hooks into
+  `dumps/reference_<stage>.gguf` + manifest (GGUF as the dump format so C++ reads it
+  with the ggml API it already links).
+- Reference env: docker `pytorch/pytorch:2.7.1-cuda12.8-cudnn9-devel` + stock pip
+  deps only. Custom CUDA backends (FlexGEMM/flash-attn/o-voxel) are NOT installed;
+  sparse attention (batch=1) is monkeypatched to dense SDPA and sparse conv to a
+  pure-torch gather-GEMM — slow but runs on CPU too, and doubles as an executable
+  spec for the C++ port. 16 GB VRAM is only a constraint for the reference runs;
+  stage-at-a-time + low_vram-style model swapping keeps us under it.
+- C++ side: per-layer taps compared with `tests/parity.hpp`-style
+  `atol+rtol*|ref|` gate (2e-3 default), ctest with `SKIP_RETURN_CODE 77` when
+  fixtures are absent.
+- Existing whole-stage tests (ss_flow/ss_sample/ss_dec) keep working; their
+  ref generators get path fixes (the `trellis2-shiv` layout doesn't exist here).
+
+## Fuzzing (privacy-filter.cpp process)
+
+Non-GGUF untrusted inputs, libFuzzer + ASan/UBSan (clang):
+- image bytes → stb_image decode → preprocess (the demo upload path)
+- `.dinodata` loader
+- `.latent`/occupancy readers used by the example CLIs
+GGUF model files are trusted assets (same threat model as privacy-filter).
+
+## Demo
+
+- `server/` Go (stdlib http + purego dlopen of `libtrellis2.so`), depth-anything
+  server pattern: single inference mutex, `POST /api/generate` (multipart image,
+  params) → job id, progress polling, `GET /api/mesh/<id>` binary mesh,
+  self-contained embedded `web/index.html` WebGL viewer (no CDN, no build step).
+- C API additions in `trellis2.h` for: dino encode from RGBA buffer, full pipeline
+  run with progress callback, mesh buffer accessors.
+
+## Order of work
+
+1. infra: ref container, weights, fix existing ref scripts, regenerate refs,
+   existing 3 tests green on this machine (CPU + asan)
+2. DINOv3 encoder port + per-layer validation → image→coarse-mesh e2e in C++
+3. Go server + web viewer on coarse pipeline (user-visible milestone)
+4. fuzz harnesses + short campaigns
+5. shape-SLAT flow port (sparse DiT) + validation
+6. FDG VAE decoder + flexible-dual-grid mesher + validation → real mesh in demo
+7. docs (VERIFICATION.md), CUDA build check, quantized variants, benchmarks
+
+## Status (done)
+
+All of 1–7 complete. Image→mesh works end-to-end, C++/ggml only, coarse
+(marching-cubes preview) and fine (512³ dual-grid) paths, in the Go demo. Every
+stage validated tap-by-tap (docs/VERIFICATION.md): preprocessing byte-exact,
+DINOv3 rel-L2 ≤7e-7, sparse U-Net decoder exact through 4 levels. CUDA build
+(sm_120) works; 3D-conv decoders pinned to CPU. One fuzz bug found+fixed.
+
+Runtime on the 16 GB RTX 5070 Ti (GPU shape decode auto-enabled): fine (512³)
+**~39 s**, 1024 cascade **~133 s**. (Was 85 s for 512 with the decoder on CPU.)
+
+### Where the fine-path time goes (measured, `TRELLIS2_TIMING=1`)
+
+Per-stage wall-clock for one 512³ generation (f16, ~1.09 M-vertex mesh), CPU
+decoder vs the auto GPU decoder:
+
+| stage      | CPU decode | GPU decode | device (GPU mode) |
+|------------|-----------:|-----------:|-------------------|
+| dino       | 0.1 s      | 0.1 s      | GPU               |
+| ss_flow    | 21 s       | 21 s       | GPU               |
+| ss_dec     | 3 s        | 3 s        | CPU (dense CONV_3D)|
+| slat_flow  | 11 s       | 10 s       | GPU               |
+| shape_dec  | **49 s**   | **2.5 s**  | **GPU** (was 59 % of the run) |
+| mesh       | 0.2 s      | 0.2 s      | CPU               |
+| **total**  | **85 s**   | **39 s**   |                   |
+
+The original "GPU ~30 %" reading was the *average*: the biggest stage (the
+FlexiDualGrid VAE decoder) ran on the CPU with the GPU idle. It now runs on the
+GPU — **~2.5 s vs ~49 s, ~20×** — placed there automatically when VRAM allows
+(see the shape-decoder note under "Not done"). The flow DiTs (`ss_flow` +
+`slat_flow`) are now the bulk of the run. Two facts about them, from
+`TRELLIS2_TIMING`:
+
+- Attention is now `ggml_flash_attn_ext` for **all** flow forwards, not just the
+  cascade's huge token counts (`sdpa_auto`, `TRELLIS2_SDPA_EXACT` restores the
+  old materialized softmax). Flash is bit-identical to full softmax on the CPU
+  (both flow forwards still validate at ~2.4e-4 / 2.9e-4 rel-L2) and on the GPU
+  it is ~30 % faster *and* O(L) memory — the exact path's 805 MB score matrix
+  `alloc_graph`-fails once the resident pipeline leaves <~2 GB free, so flash is
+  what keeps the flow fitting under host-VRAM pressure, not only a speedup.
+- Each forward still runs at only ~17 % of the card's f16 tensor-core peak; the
+  matmuls already hit the f16 cores (ggml converts the f32 activations), so the
+  remaining slack is the f32 elementwise/permute traffic between matmuls. CUDA
+  graphs do not help (they `cudaGraphInstantiate`-OOM with the pipeline
+  resident) and are left off.
+
+The shape decoder is a *sparse* net that keeps millions of voxels in the tensor
+**row** dimension (`ne1`). ggml's CUDA CONCAT/PAD kernels launch a grid
+dimension equal to that count and abort (`invalid configuration argument`) above
+the 65535 grid-Y/Z limit — which is why the original port used the CPU. But
+CONCAT/PAD were only used to append one missing-neighbor zero row; replacing
+that with a clamp-index + 0/1-mask formulation (get_rows a valid row, multiply
+the missing ones by zero — byte-identical) keeps every op inside ggml kernels
+that tile the voxel dimension (`get_rows`, broadcast `mul`, `mul_mat`, `add`,
+`norm`, `silu` all verified OK at 3 M voxels). The decoder then runs on the GPU
+in ~2.5 s (512³) / ~12.5 s (1024³).
+
+### VRAM-aware auto-placement of the shape decoder
+
+The decoder's placement is decided from **measured free VRAM**
+(`trellis2_gpu_free_vram()` → `cudaMemGetInfo`), not a hardcoded flag:
+
+- At load, `t2_pipeline_load` records the free VRAM *before* the flow DiTs are
+  loaded (= what freeing them again reclaims) and places the decoder on the GPU
+  when that covers the target tier's decode peak (~3 GB at 512³, ~7.5 GB at
+  1024³) plus the decoder weights and a margin; otherwise CPU. `TRELLIS2_SHAPE_DEC_GPU`
+  / `_CPU` force it; a CPU-only build (no GPU device) always picks CPU.
+- At decode time, `ensure_decode_vram` checks free VRAM again and, if the decode
+  would not fit, frees the flow DiTs (all finished by then) to reclaim their
+  ~5–7 GB; `reload_flows` brings them back on the next `t2_generate` (a few
+  seconds from page cache). So 512³ decodes with the flows resident (no reload
+  cost) while the big 1024³ decode transparently frees-and-reloads. This is the
+  `T2_LOAD_LOW_VRAM` idea, applied automatically only when the numbers require it.
+
+Validated end-to-end on the 16 GB card with **no env vars**: 512 → 39 s, 1024
+cascade → 133 s (the 1024³ GPU decode is 12.5 s), and three back-to-back cascade
+generations exercise the free/reload path with no OOM.
+
+## Not done (out of original scope / future)
+
+- **PBR textures — DONE.** The validated standalone texturing path re-encodes
+  the decoded dual grid to condition texture flow, then trilinearly samples the
+  decoded six-channel PBR volume at the surface. The browser and GLB path
+  preserve alpha and use the correct base-color space. The first integrated
+  subdivision-guide path was removed after it produced collapsed materials.
+- **`1024_cascade` — DONE.** Full high-resolution path: LR flow (512 model) →
+  `trellis2_shape_dec_upsample(×4)` → quantize+dedup to the 64³ HR scaffold →
+  HR flow (1024 model, cond_1024) → 1024³ decode → dual-grid mesh. Enabled by
+  flash attention (`sdpa_auto`) for the HR token counts. Validated by
+  `test_cascade`: upsample coords + HR scaffold exact (to 1 voxel of ~995k),
+  HR flow forward rel-L2 3.1e-4 (CPU). The 1024³ decode is the same decoder
+  validated exactly at the 512 tier; its explicit parity gate is behind
+  `TRELLIS2_CASCADE_DECODE` because it transiently needs ~14 GB host RAM.
+- **Still to do:** `1536_cascade` (add the token-reduction loop + res 1536). The
+  `<8 GB` case is now partly covered: the shape decoder auto-frees the flow DiTs
+  around a GPU decode (see below), so the pieces of the `T2_LOAD_LOW_VRAM`
+  lifecycle exist; a full per-stage load/free mode would extend that to the flow
+  DiTs themselves for cards that can't hold even one 1.3B DiT + a decode.
+- **Background removal** (BiRefNet/RMBG-2.0) — the demo instructs a transparent
+  PNG and uses the image as-is otherwise. A separate ~1 GB seg model.
+- **GPU shape decoder — DONE.** The mask-conv change plus the VRAM-aware
+  placement + free/reload lifecycle (both described above) make the decoder run
+  on the GPU automatically when it fits: 512³ ~2.5 s and 1024³ ~12.5 s vs ~49 s /
+  minutes on the CPU. No env var required; `TRELLIS2_SHAPE_DEC_{GPU,CPU}` still
+  force it, and it stays on the CPU on cards too small or in a CPU-only build.
+- **CUDA CONV_3D** — the SS *occupancy* decoder (`ss_dec`, 3 s) uses a genuine
+  dense `ggml_conv_3d_direct` with no CUDA kernel, so it stays on CPU regardless.
+- **Quantized shipping variants / benchmarks / CI** — f16 is the demo default;
+  q8/q4 conversion + a benchmark table + a two-tier CI workflow are the natural
+  next hardening steps (privacy-filter.cpp has the template).
+- **CPU-only SLAT sampler tightness in ctest** — the `slat` ctest is labeled
+  slow and validated in-container; the sampler validates tightly on CPU
+  (TRELLIS2_SLAT_STRICT=1) but that CPU run is minutes-long.
diff --git a/docs/VERIFICATION.md b/docs/VERIFICATION.md
new file mode 100644
index 0000000..0b383a6
--- /dev/null
+++ b/docs/VERIFICATION.md
@@ -0,0 +1,86 @@
+# Verification
+
+Every ported stage is validated numerically against the PyTorch reference, per
+component, not just end-to-end — the depth-anything.cpp approach. Reference
+activations are dumped from `microsoft/TRELLIS.2` (via `scripts/refgen.sh`
+inside the CUDA container) into GGUF files under `dumps/`, and the C++ side is
+compared tap-by-tap with `tests/parity.hpp` (gate: `|got-ref| <= atol +
+rtol*|ref|`, reported as max-abs / rel-L2 / per-row).
+
+## One-time setup
+
+```sh
+docker build -f docker/Dockerfile.ref -t trellis2-ref docker   # PyTorch reference env
+scripts/download_models.sh                                     # HF checkpoints -> models/
+docker run --rm -v "$PWD":/work -w /work trellis2-ref bash -c '
+  python convert_dino_to_gguf.py        --output ggufs/dino_f32.gguf       --ftype 0
+  python convert_ss_flow_to_gguf.py     --model models/TRELLIS.2-4B/ckpts/ss_flow_img_dit_1_3B_64_bf16.safetensors --output ggufs/ss_flow_f32.gguf --ftype 0
+  python convert_ss_dec_to_gguf.py      --model models/TRELLIS-image-large/ckpts/ss_dec_conv3d_16l8_fp16.safetensors --output ggufs/ss_dec_f32.gguf --ftype 0
+  python convert_slat_flow_to_gguf.py   --model models/TRELLIS.2-4B/ckpts/slat_flow_img2shape_dit_1_3B_512_bf16.safetensors --pipeline-json models/TRELLIS.2-4B/pipeline.json --output ggufs/slat_flow_f32.gguf --ftype 0
+  python convert_shape_dec_to_gguf.py   --output ggufs/shape_dec_f32.gguf  --ftype 0'
+scripts/refgen.sh                                              # dump reference activations
+```
+
+## Run
+
+```sh
+cmake -B build -DTRELLIS2_BUILD_TESTS=ON && cmake --build build -j
+ctest --test-dir build -LE model        # fast, no assets (marching cubes, preprocess)
+ctest --test-dir build                  # full parity (needs ggufs/ + dumps/)
+```
+
+## Parity table (f32 GGUF vs true-fp32 reference)
+
+| stage | test | tap coverage | result |
+|---|---|---|---|
+| image preprocess (alpha crop, premultiply, Lanczos-512) | `test_preprocess` | full 512×512 RGB | **byte-exact** (0/786432 differ) |
+| DINOv3 ViT-L/16 encoder | `test_dino` | 40 taps: embeddings, RoPE, per-layer output + first/last-layer detail (norm/attn/layerscale/mlp), final affine-free LN | **PASS**, rel-L2 ≤ 7e-7 all taps |
+| SS-flow DiT forward | `test_ss_flow_forward` | full output | **PASS**, rel-L2 2.4e-4 |
+| SS-flow Euler sampler (12-step CFG) | `test_ss_sample` | z_s latent | **PASS**, rel-L2 5.7e-3, sign 99.85% (CPU) |
+| SS decoder (dense 3D-conv → 64³ occupancy) | `test_ss_dec` | occupancy logits | **PASS**, rel-L2 2e-5 |
+| shape-SLAT flow forward | `test_slat` | full output | **PASS**, rel-L2 2.9e-4 (CPU) / 8e-4 (GPU) |
+| shape-SLAT VAE decoder (sparse ConvNeXt U-Net, 4 levels, 16× up) | `test_slat` | per-level features + subdivision logits + final 7-ch output, all 5 levels | **PASS**, rel-L2 ≤ 6e-7 (levels 0–3 exact; final set within 0.0001%) |
+| integrated subdivision guide | `test_slat` | all decoder levels; final guide coordinates equal decoded shape coordinates | **PASS** |
+| standalone shape encoder → texture flow → texture decoder | `test_texture` | shape latent, flow forward/sampler, guided 6-channel PBR decode | parity-gated; sampler backend drift uses the documented loose gate |
+| sparse PBR surface sampling | `test_pbr_sampling` | dense trilinear interpolation + sparse-boundary normalization | **PASS** |
+| GLB PBR/alpha export | `test_mesh_export` | direct vertex RGBA, retained metallic/roughness, glTF alpha mode | **PASS** |
+| dual-grid mesh extraction | `test_marching_cubes` (invariants) + visual | watertight-manifold, Euler characteristic, winding | **PASS** |
+| **1024 cascade** — decoder upsample(×4) → 512³ coords | `test_cascade` | full coord set + quantized 64³ HR scaffold | **PASS**, set match to 0.0001% (1 voxel of 995k) |
+| **1024 cascade** — HR (1024-model) flow forward | `test_cascade` | full output | **PASS**, rel-L2 ~3e-4 (CPU); ~1e-2 on GPU flash |
+| **1024 cascade** — final 1024³ decode (3.97M voxels) | `test_cascade` | per-level features + subdivision + 7-ch output | **PASS**, rel-L2 ≤ 2e-2, set within 0.0001% |
+
+Notes:
+- **Flash attention (default for every flow forward).** `sdpa_auto()` uses
+  `ggml_flash_attn_ext` for both flow DiTs at all token counts;
+  `TRELLIS2_SDPA_EXACT` restores the old materialized `[L_k, L_q, heads]`
+  softmax. Flash is bit-faithful to full softmax on CPU (SS-flow 2.4e-4, SLAT
+  2.9e-4 — identical to exact, so the tap parity above is unaffected) but incurs
+  ~3e-3 rel-L2 on the CUDA F16-MMA kernel. It was already required for the HR
+  cascade (49,152-token attention fits on 16 GB vs a 108 GiB exact matrix); it
+  is now the default because on the GPU it is also ~30 % faster per forward and
+  O(L) memory — the exact path's 805 MB SS-flow score matrix `alloc_graph`-fails
+  when the resident pipeline leaves little free VRAM. Was previously gated to
+  score matrices >1 GiB (i.e. only the HR stage). See docs/PLAN.md for the
+  per-stage runtime profile.
+- **TF32 matters.** PyTorch's default CUDA matmul/attention uses TF32 (≈10-bit
+  mantissa) and reduced-precision flash SDPA, which shows up as ~1e-3 relative
+  error versus true fp32. `scripts/ref_common.py` disables it so the golden
+  dumps are real fp32; otherwise a correct port looks like it has a 0.08-rel-L2
+  bug (this exact trap cost a debugging session — see the flow-forward gate).
+- **Sampler drift.** The 12-step Euler + CFG-rescale loop chaotically amplifies
+  per-step fp differences between backends; it validates tightly on CPU and
+  drifts to ~0.1 rel-L2 on GPU. The decoder gate therefore decodes the
+  *reference* SLAT so decoder parity is independent of sampler trajectory.
+- **Subdivision boundary.** A handful of level-3 subdivision logits sit within
+  fp-noise of zero; the `>0` threshold can flip them, so the final active-voxel
+  set differs by ~4 voxels out of ~4 million (0.0001%) run-to-run and
+  hardware-to-hardware. This is inherent to a hard threshold, not a port bug.
+
+## GPU
+
+`-DGGML_CUDA=ON -DCMAKE_CUDA_ARCHITECTURES=120` (Blackwell / RTX 50-series). The
+flow DiTs and DINOv3 run on CUDA; the 3D-conv decoders (SS decoder CONV_3D and
+the sparse-conv gather-GEMM) run on CPU because the bundled ggml has no CUDA
+CONV_3D kernel — they are a small fraction of total inference time. GPU f32
+matmul is fp16-class, so tap parity on CUDA is ~1e-3 (deterministic, not device
+noise); CPU is the tight-tolerance reference backend.
diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt
index 24bcf45..b27e908 100644
--- a/examples/CMakeLists.txt
+++ b/examples/CMakeLists.txt
@@ -22,3 +22,13 @@ target_compile_features(ss_decode PRIVATE cxx_std_14)
 add_executable(ss_mesh ss_mesh.cpp)
 target_link_libraries(ss_mesh PRIVATE trellis2)
 target_compile_features(ss_mesh PRIVATE cxx_std_14)
+
+# Example: image -> preprocessed 512x512 -> DINOv3 conditioning (.dinodata).
+add_executable(dino_encode dino_encode.cpp)
+target_link_libraries(dino_encode PRIVATE trellis2)
+target_compile_features(dino_encode PRIVATE cxx_std_14)
+
+# Example: export a demo mesh (T2MESH01/02/03) into a portable GLB (no GPU).
+add_executable(mesh2glb mesh2glb.cpp)
+target_link_libraries(mesh2glb PRIVATE trellis2)
+target_compile_features(mesh2glb PRIVATE cxx_std_14)
diff --git a/examples/dino_encode.cpp b/examples/dino_encode.cpp
new file mode 100644
index 0000000..f876b8c
--- /dev/null
+++ b/examples/dino_encode.cpp
@@ -0,0 +1,97 @@
+// Encode an image into the TRELLIS.2 DINOv3 conditioning tensor (.dinodata),
+// replacing the external dump_dinodata.py:
+//
+//   image (PNG/JPG; solid black/white backgrounds are removed automatically)
+//     -> background cleanup -> alpha bbox crop, premultiply, LANCZOS 512
+//     -> DINOv3 ViT-L/16 -> [1, 1029, 1024] cond -> .dinodata
+//
+// usage: dino_encode <dino.gguf> <image> [out.dinodata] [--size N] [--pre out.png]
+//
+#include "trellis2.h"
+
+#define STB_IMAGE_IMPLEMENTATION
+#include "stb_image.h"
+#define STB_IMAGE_WRITE_IMPLEMENTATION
+#include "stb_image_write.h"
+
+#include <cstdio>
+#include <cstring>
+#include <string>
+#include <vector>
+
+int main(int argc, char ** argv) {
+    if (argc < 3) {
+        std::fprintf(stderr,
+            "usage: %s <dino.gguf> <image> [out.dinodata] [--size N] [--pre out.png]\n",
+            argv[0]);
+        return 2;
+    }
+    const std::string gguf_path = argv[1];
+    const std::string img_path  = argv[2];
+    std::string out_path = "cond.dinodata";
+    std::string pre_path;
+    int size = 512;
+    for (int i = 3; i < argc; ++i) {
+        if (std::strcmp(argv[i], "--size") == 0 && i + 1 < argc) {
+            size = std::atoi(argv[++i]);
+        } else if (std::strcmp(argv[i], "--pre") == 0 && i + 1 < argc) {
+            pre_path = argv[++i];
+        } else {
+            out_path = argv[i];
+        }
+    }
+
+    int w = 0, h = 0, comp = 0;
+    unsigned char * pixels = stbi_load(img_path.c_str(), &w, &h, &comp, 4);
+    if (!pixels) {
+        std::fprintf(stderr, "failed to decode image %s: %s\n",
+                     img_path.c_str(), stbi_failure_reason());
+        return 1;
+    }
+    const int removed = trellis2_remove_solid_background_rgba(
+        pixels, w, h, TRELLIS2_BACKGROUND_AUTO);
+    std::printf("image  : %s  %dx%d (%d channels, background pixels changed: %d)\n",
+                img_path.c_str(), w, h, comp, removed);
+
+    std::string err;
+    std::vector<uint8_t> rgb;
+    if (!trellis2_preprocess_rgba(pixels, w, h, size, rgb, &err)) {
+        std::fprintf(stderr, "preprocess failed: %s\n", err.c_str());
+        stbi_image_free(pixels);
+        return 1;
+    }
+    stbi_image_free(pixels);
+
+    if (!pre_path.empty()) {
+        stbi_write_png(pre_path.c_str(), size, size, 3, rgb.data(), size * 3);
+        std::printf("wrote  : %s (preprocessed %dx%d RGB)\n", pre_path.c_str(), size, size);
+    }
+
+    trellis2_dino_model * model = trellis2_dino_load(gguf_path, true, &err);
+    if (!model) {
+        std::fprintf(stderr, "model load failed: %s\n", err.c_str());
+        return 1;
+    }
+    std::printf("model  : %s (backend %s)\n", gguf_path.c_str(),
+                trellis2_dino_backend_name(model));
+
+    trellis2_dino_cond cond;
+    if (!trellis2_dino_encode_rgb(model, rgb.data(), size, cond, &err)) {
+        std::fprintf(stderr, "encode failed: %s\n", err.c_str());
+        trellis2_dino_free(model);
+        return 1;
+    }
+    trellis2_dino_free(model);
+
+    const trellis2_dino_fingerprint fp = trellis2_dino_fingerprints(cond);
+    std::printf("cond   : [1, %lld, %lld]  min=%.4f max=%.4f mean=%.6f l2=%.4f\n",
+                (long long) cond.tokens(), (long long) cond.channels(),
+                fp.vmin, fp.vmax, fp.mean, fp.l2);
+
+    if (!trellis2_save_dinodata(out_path, cond, &err)) {
+        std::fprintf(stderr, "save failed: %s\n", err.c_str());
+        return 1;
+    }
+    std::printf("wrote  : %s (%zu floats)\n", out_path.c_str(), cond.count());
+    return 0;
+}
diff --git a/examples/flexible_dual_grid.h b/examples/flexible_dual_grid.h
new file mode 100644
index 0000000..6b9fd64
--- /dev/null
+++ b/examples/flexible_dual_grid.h
@@ -0,0 +1,345 @@
+// flexible_dual_grid.h — single-header CPU port of TRELLIS.2's flexible dual
+// grid mesh extraction (o-voxel/o_voxel/convert/flexible_dual_grid.py, eval
+// path). Turns the shape decoder's per-voxel 7-channel output into a triangle
+// mesh, replacing the CUDA hashmap kernel with an std::unordered_map.
+//
+// Per active voxel v at integer coord c (in [0, grid_size)):
+//   dual vertex   V_v = (c + offset_v) * voxel_size + aabb0   (unit cube here)
+//   offset_v      = (1 + 2*margin) * sigmoid(feat[0:3]) - margin
+//   intersected   feat[3:6] > 0, one flag per axis (x, y, z)
+//   split_weight  softplus(feat[6])
+// For each voxel with an intersected axis, the 4 voxels around that edge
+// (offsets below) contribute their dual vertices as a quad; if all 4 exist the
+// quad is split into 2 triangles along the diagonal chosen by the decoder's
+// learned split_weight = softplus(feat[6]) (reference eval-path tie-break).
+#pragma once
+
+#include <algorithm>
+#include <cmath>
+#include <cstdint>
+#include <unordered_map>
+#include <unordered_set>
+#include <vector>
+
+namespace fdg {
+
+struct Mesh {
+    std::vector<float> verts;  // 3 per vertex
+    std::vector<int>   tris;   // 3 indices per triangle
+    size_t n_verts() const { return verts.size() / 3; }
+    size_t n_tris()  const { return tris.size() / 3; }
+};
+
+namespace detail {
+
+inline uint64_t key(int32_t x, int32_t y, int32_t z) {
+    return ((uint64_t) (uint32_t) x << 40) |
+           ((uint64_t) (uint32_t) y << 20) |
+           (uint64_t) (uint32_t) z;
+}
+
+// The 4 neighbor-voxel offsets around an edge, per axis (matches
+// edge_neighbor_voxel_offset in the reference).
+static const int EDGE_OFF[3][4][3] = {
+    {{0,0,0},{0,0,1},{0,1,1},{0,1,0}},   // x-axis edge
+    {{0,0,0},{1,0,0},{1,0,1},{0,0,1}},   // y-axis edge
+    {{0,0,0},{0,1,0},{1,1,0},{1,0,0}},   // z-axis edge
+};
+
+inline void cross(const float * a, const float * b, float * o) {
+    o[0] = a[1]*b[2] - a[2]*b[1];
+    o[1] = a[2]*b[0] - a[0]*b[2];
+    o[2] = a[0]*b[1] - a[1]*b[0];
+}
+
+} // namespace detail
+
+// feats: [n_voxels * 7], voxel-major (dec output). coords: [n_voxels * 3].
+// grid_size = input_res * decoder upscale (e.g. 32 * 16 = 512). margin 0.5.
+inline Mesh extract(const float * feats, const int32_t * coords, int n,
+                    int grid_size, float margin = 0.5f) {
+    using namespace detail;
+    Mesh m;
+    if (n <= 0) return m;
+
+    const float vs = 1.0f / (float) grid_size;   // voxel size (aabb span 1)
+    const float aabb0 = -0.5f;
+
+    // dual vertices + hashmap
+    std::vector<float> V((size_t) n * 3);
+    std::unordered_map<uint64_t, int> idx;
+    idx.reserve((size_t) n * 2);
+    for (int v = 0; v < n; ++v) {
+        const float * f = feats + (size_t) v * 7;
+        for (int a = 0; a < 3; ++a) {
+            const float s = 1.0f / (1.0f + std::exp(-f[a]));          // sigmoid
+            const float off = (1.0f + 2.0f * margin) * s - margin;
+            V[(size_t) v * 3 + a] = ((float) coords[(size_t) v * 3 + a] + off) * vs + aabb0;
+        }
+        idx[key(coords[(size_t) v * 3], coords[(size_t) v * 3 + 1], coords[(size_t) v * 3 + 2])] = v;
+    }
+    m.verts = V;
+
+    // quads from intersected edges
+    for (int v = 0; v < n; ++v) {
+        const float * f = feats + (size_t) v * 7;
+        const int32_t cx = coords[(size_t) v * 3];
+        const int32_t cy = coords[(size_t) v * 3 + 1];
+        const int32_t cz = coords[(size_t) v * 3 + 2];
+        for (int axis = 0; axis < 3; ++axis) {
+            if (f[3 + axis] <= 0.0f) continue;   // not intersected on this axis
+            int q[4];
+            bool ok = true;
+            for (int i = 0; i < 4; ++i) {
+                const int32_t nx = cx + EDGE_OFF[axis][i][0];
+                const int32_t ny = cy + EDGE_OFF[axis][i][1];
+                const int32_t nz = cz + EDGE_OFF[axis][i][2];
+                auto it = idx.find(key(nx, ny, nz));
+                if (it == idx.end()) { ok = false; break; }
+                q[i] = it->second;
+            }
+            if (!ok) continue;
+
+            // Choose the quad diagonal by the decoder's learned split_weight
+            // (softplus of feat[6]), exactly as the reference eval path does
+            // (FlexiDualGridVaeDecoder -> flexible_dual_grid_to_mesh, train=False):
+            //   split 1: (0,1,2)+(0,2,3)   when sw0*sw2 >  sw1*sw3
+            //   split 2: (0,1,3)+(3,1,2)   otherwise
+            // (A geometric best-aligned-normals heuristic is the reference's
+            // split_weight=None fallback; the shipped decoder always emits
+            // feat[6], so we follow the learned choice.)
+            auto sw = [&](int i) {
+                const float x = feats[(size_t) q[i] * 7 + 6];
+                return x > 20.0f ? x : std::log1p(std::exp(x));   // softplus
+            };
+            if (sw(0) * sw(2) > sw(1) * sw(3)) {
+                m.tris.push_back(q[0]); m.tris.push_back(q[1]); m.tris.push_back(q[2]);
+                m.tris.push_back(q[0]); m.tris.push_back(q[2]); m.tris.push_back(q[3]);
+            } else {
+                m.tris.push_back(q[0]); m.tris.push_back(q[1]); m.tris.push_back(q[3]);
+                m.tris.push_back(q[3]); m.tris.push_back(q[1]); m.tris.push_back(q[2]);
+            }
+        }
+    }
+    return m;
+}
+
+// Per-vertex shading normals for the dual grid's *unoriented*, heavily
+// non-manifold mesh.
+//
+// The reference mesher emits every quad with a fixed vertex order regardless of
+// which way the surface crosses the edge, so a large fraction of faces are wound
+// opposite to their neighbours. Two failure modes follow: (a) a naive
+// area-weighted normal cancels at those seams, and (b) any *sign* fix that leaves
+// stray flips is not harmless — the normal is interpolated across the triangle
+// *before* the fragment shader's abs(dot), so two adjacent vertices with opposite
+// normals make the interpolated normal cross zero mid-face → normalize() explodes
+// → speckled/blocky specular. The mesh is too non-manifold to 2-colour the
+// winding cleanly (edges shared by >2 faces frustrate it), so we don't try to.
+//
+//   1. Recover a smooth, winding-INDEPENDENT normal *direction* per vertex as the
+//      dominant eigenvector of the area-weighted structure tensor Σ area·n̂n̂ᵀ
+//      (immune to winding sign since n̂n̂ᵀ == (−n̂)(−n̂)ᵀ).
+//   2. Resolve the arbitrary per-vertex *sign* consistently with a parity
+//      union-find over mesh edges, so edge-adjacent vertices share a hemisphere
+//      and the interpolated normal stays clear of zero. Only genuinely frustrated
+//      (odd-cycle / non-manifold) edges are left flipped.
+// Final shading is orientation-independent (viewer uses abs(dot)), so only local
+// smoothness matters, not a globally correct outward sign. (Winding unification
+// and sign diffusion were both tried and are worse on this mesh: 2-colouring the
+// >2-face non-manifold edges frustrates more, and Jacobi diffusion checkerboards.)
+inline std::vector<float> vertex_normals(const Mesh & m) {
+    const size_t nv = m.n_verts();
+    std::vector<double> A((size_t) nv * 6, 0.0);   // sym structure tensor per vertex
+    std::vector<float>  seed((size_t) nv * 3, 0.0f); // signed area sum: a sign hint
+    for (size_t t = 0; t < m.tris.size(); t += 3) {
+        const int i0 = m.tris[t], i1 = m.tris[t + 1], i2 = m.tris[t + 2];
+        const float * a = &m.verts[(size_t) i0 * 3];
+        const float * b = &m.verts[(size_t) i1 * 3];
+        const float * c = &m.verts[(size_t) i2 * 3];
+        float e1[3], e2[3], fn[3];
+        for (int k = 0; k < 3; ++k) { e1[k] = b[k]-a[k]; e2[k] = c[k]-a[k]; }
+        detail::cross(e1, e2, fn);
+        const double area = std::sqrt((double) fn[0]*fn[0] + (double) fn[1]*fn[1] + (double) fn[2]*fn[2]);
+        if (area <= 1e-20) continue;
+        const double inv = 1.0 / area;
+        const double xx = fn[0]*fn[0]*inv, yy = fn[1]*fn[1]*inv, zz = fn[2]*fn[2]*inv;
+        const double xy = fn[0]*fn[1]*inv, xz = fn[0]*fn[2]*inv, yz = fn[1]*fn[2]*inv;
+        for (int i : {i0, i1, i2}) {
+            double * Av = &A[(size_t) i * 6];
+            Av[0]+=xx; Av[1]+=yy; Av[2]+=zz; Av[3]+=xy; Av[4]+=xz; Av[5]+=yz;
+            float * sv = &seed[(size_t) i * 3];
+            sv[0]+=fn[0]; sv[1]+=fn[1]; sv[2]+=fn[2];
+        }
+    }
+    // (1) smooth, sign-ambiguous direction per vertex
+    std::vector<float> dir((size_t) nv * 3, 0.0f);
+    for (size_t v = 0; v < nv; ++v) {
+        const double * Av = &A[v * 6];
+        double x = seed[v*3], y = seed[v*3+1], z = seed[v*3+2];
+        double l = std::sqrt(x*x + y*y + z*z);
+        if (l < 1e-20) { x = Av[0]; y = Av[3]; z = Av[4]; l = std::sqrt(x*x+y*y+z*z); }
+        if (l < 1e-20) { dir[v*3+2] = 1.0f; continue; }
+        x/=l; y/=l; z/=l;
+        for (int it = 0; it < 8; ++it) {
+            const double nx = Av[0]*x + Av[3]*y + Av[4]*z;
+            const double ny = Av[3]*x + Av[1]*y + Av[5]*z;
+            const double nz = Av[4]*x + Av[5]*y + Av[2]*z;
+            const double nl = std::sqrt(nx*nx + ny*ny + nz*nz);
+            if (nl < 1e-20) break;
+            x = nx/nl; y = ny/nl; z = nz/nl;
+        }
+        dir[v*3] = (float) x; dir[v*3+1] = (float) y; dir[v*3+2] = (float) z;
+    }
+    // (2) Resolve the arbitrary per-vertex sign *consistently* via a parity
+    //     union-find over mesh edges: two edge-adjacent vertices whose directions
+    //     are anti-aligned must end up with opposite signs (and vice versa), so
+    //     within each connected component neighbours share a hemisphere. Only
+    //     genuinely frustrated (odd-cycle / non-manifold) edges are left flipped.
+    std::vector<int>     ufp(nv), ufr(nv, 0);
+    std::vector<uint8_t> ufb(nv, 0);   // parity of a vertex relative to its parent
+    for (size_t i = 0; i < nv; ++i) ufp[i] = (int) i;
+    auto find = [&](int v, int & parity) {
+        int p = 0;
+        while (ufp[v] != v) { p ^= ufb[v]; v = ufp[v]; }
+        parity = p; return v;
+    };
+    auto join = [&](int a, int b) {
+        const float * na = &dir[(size_t) a * 3];
+        const float * nb = &dir[(size_t) b * 3];
+        const int rel = (na[0]*nb[0] + na[1]*nb[1] + na[2]*nb[2]) < 0.0f ? 1 : 0;
+        int pa, pb, ra = find(a, pa), rb = find(b, pb);
+        if (ra == rb) return;
+        if (ufr[ra] < ufr[rb]) { std::swap(ra, rb); std::swap(pa, pb); }
+        ufp[rb] = ra; ufb[rb] = (uint8_t) (pa ^ pb ^ rel);
+        if (ufr[ra] == ufr[rb]) ufr[ra]++;
+    };
+    for (size_t t = 0; t < m.tris.size(); t += 3) {
+        const int a = m.tris[t], b = m.tris[t+1], c = m.tris[t+2];
+        join(a, b); join(b, c); join(c, a);
+    }
+    // (3) pick each component's global sign toward the signed-sum seed (so the
+    //     result is deterministic and roughly outward), then emit oriented normals
+    std::unordered_map<int, double> comp_sign;
+    for (size_t v = 0; v < nv; ++v) {
+        int p, r = find((int) v, p);
+        const double s = p ? -1.0 : 1.0;
+        const float * sv = &seed[v*3];
+        comp_sign[r] += s * (dir[v*3]*sv[0] + dir[v*3+1]*sv[1] + dir[v*3+2]*sv[2]);
+    }
+    std::vector<float> nrm((size_t) nv * 3, 0.0f);
+    for (size_t v = 0; v < nv; ++v) {
+        int p, r = find((int) v, p);
+        double s = p ? -1.0 : 1.0;
+        if (comp_sign[r] < 0.0) s = -s;
+        nrm[v*3]   = (float) (s * dir[v*3]);
+        nrm[v*3+1] = (float) (s * dir[v*3+1]);
+        nrm[v*3+2] = (float) (s * dir[v*3+2]);
+    }
+    return nrm;
+}
+
+// Remove triangles that belong to tiny disconnected islands (the floating
+// specks that read as "blemishes"), keeping the vertex array and its indexing
+// intact so a parallel per-vertex attribute array (e.g. baked PBR) stays
+// aligned. Components are face groups connected through shared vertices; a
+// component is dropped when its face count is below min_frac of the total.
+inline void drop_small_components(Mesh & m, float min_frac = 0.0005f) {
+    const size_t nt = m.n_tris();
+    if (nt == 0) return;
+    const size_t nv = m.n_verts();
+    std::vector<int> p(nv);
+    for (size_t i = 0; i < nv; ++i) p[i] = (int) i;
+    auto find = [&](int x) { while (p[x] != x) { p[x] = p[p[x]]; x = p[x]; } return x; };
+    auto uni  = [&](int a, int b) { a = find(a); b = find(b); if (a != b) p[a] = b; };
+    for (size_t t = 0; t < m.tris.size(); t += 3) {
+        uni(m.tris[t], m.tris[t+1]); uni(m.tris[t+1], m.tris[t+2]);
+    }
+    std::unordered_map<int, int> faces;
+    for (size_t t = 0; t < m.tris.size(); t += 3) faces[find(m.tris[t])]++;
+    const int min_faces = std::max(1, (int) (min_frac * (double) nt));
+    std::vector<int> keep;
+    keep.reserve(m.tris.size());
+    for (size_t t = 0; t < m.tris.size(); t += 3) {
+        if (faces[find(m.tris[t])] >= min_faces) {
+            keep.push_back(m.tris[t]); keep.push_back(m.tris[t+1]); keep.push_back(m.tris[t+2]);
+        }
+    }
+    m.tris.swap(keep);
+}
+
+// Fill the small holes extract() leaves where a dual-grid quad was skipped (a
+// neighbour voxel was missing). A boundary edge is one used by exactly one
+// triangle; boundary edges chain into loops around each hole. Each loop up to
+// `max_loop` vertices is fan-triangulated from its first vertex. Only triangles
+// are added — no new vertices — so a parallel per-vertex attribute array (baked
+// PBR) stays aligned. Large loops (genuine openings) are left unfilled.
+inline void fill_holes(Mesh & m, int max_loop = 64, int max_passes = 4) {
+    if (m.n_tris() == 0) return;
+    auto key = [](int a, int b) {
+        const uint32_t lo = a < b ? a : b, hi = a < b ? b : a;
+        return ((uint64_t) lo << 32) | hi;
+    };
+    // Iterate: the greedy loop walk misses some loops at non-manifold junctions,
+    // and each fill can expose newly closeable loops, so repeat until a pass
+    // adds nothing (or the pass cap is hit).
+    for (int pass = 0; pass < max_passes; ++pass) {
+        const size_t before = m.tris.size();
+        // run-length count of undirected edges via sort (lighter than a hashmap)
+        std::vector<uint64_t> ek;
+        ek.reserve(m.tris.size());
+        for (size_t t = 0; t < m.tris.size(); t += 3) {
+            ek.push_back(key(m.tris[t],   m.tris[t+1]));
+            ek.push_back(key(m.tris[t+1], m.tris[t+2]));
+            ek.push_back(key(m.tris[t+2], m.tris[t]));
+        }
+        std::sort(ek.begin(), ek.end());
+        std::unordered_map<int, std::vector<int>> adj;   // boundary-vertex adjacency
+        for (size_t i = 0; i < ek.size(); ) {
+            size_t j = i + 1;
+            while (j < ek.size() && ek[j] == ek[i]) ++j;
+            if (j - i == 1) {   // used by exactly one triangle -> boundary edge
+                const int a = (int) (ek[i] >> 32), b = (int) (ek[i] & 0xffffffffu);
+                adj[a].push_back(b); adj[b].push_back(a);
+            }
+            i = j;
+        }
+        if (adj.empty()) break;
+
+        std::unordered_set<uint64_t> used;   // consumed boundary edges
+        for (const auto & kv : adj) {
+            const int start = kv.first;
+            for (const int nb0 : kv.second) {
+                if (used.count(key(start, nb0))) continue;
+                std::vector<int> loop{start};
+                int prev = start, cur = nb0;
+                used.insert(key(prev, cur));
+                bool closed = false;
+                while ((int) loop.size() <= max_loop) {
+                    loop.push_back(cur);
+                    if (cur == start) { closed = true; break; }
+                    int next = -1;
+                    auto it = adj.find(cur);
+                    if (it != adj.end())
+                        for (const int c : it->second)
+                            if (c != prev && !used.count(key(cur, c))) { next = c; break; }
+                    if (next < 0) break;            // open chain / dead end
+                    used.insert(key(cur, next));
+                    prev = cur; cur = next;
+                }
+                if (!closed) continue;
+                loop.pop_back();                    // drop the repeated start vertex
+                const int k = (int) loop.size();
+                if (k < 3 || k > max_loop) continue;
+                for (int t = 1; t < k - 1; ++t) {   // fan-triangulate from loop[0]
+                    m.tris.push_back(loop[0]);
+                    m.tris.push_back(loop[t]);
+                    m.tris.push_back(loop[t + 1]);
+                }
+            }
+        }
+        if (m.tris.size() == before) break;         // converged
+    }
+}
+
+} // namespace fdg
diff --git a/examples/mesh2glb.cpp b/examples/mesh2glb.cpp
new file mode 100644
index 0000000..bc74152
--- /dev/null
+++ b/examples/mesh2glb.cpp
@@ -0,0 +1,85 @@
+// mesh2glb — export a demo mesh (T2MESH01/T2MESH02/T2MESH03 wire format) to a
+// portable vertex-coloured GLB. Exercises the CUDA-free component cleanup and
+// glTF path offline, with no models or GPU. T2GLB_XATLAS opts into image baking.
+//
+//   mesh2glb in.bin out.glb [texture_size]
+//
+// The wire format is what the demo server emits at /api/mesh/{id}:
+//   magic[8]  u32 nv  u32 nt  f32[3nv] verts  f32[3nv] normals
+//   [T2MESH02: f32[5nv] legacy pbr]
+//   [T2MESH03: f32[6nv] pbr incl. alpha] i32[3nt] tris (little-endian)
+
+#include "mesh_export.h"
+
+#include <cstdint>
+#include <cstdio>
+#include <cstring>
+#include <vector>
+
+template <class T>
+static bool rd(FILE * f, std::vector<T> & v, size_t n) {
+    v.resize(n);
+    return n == 0 || std::fread(v.data(), sizeof(T), n, f) == n;
+}
+
+int main(int argc, char ** argv) {
+    if (argc < 3) {
+        std::fprintf(stderr, "usage: %s in.bin out.glb [texture_size]\n", argv[0]);
+        return 2;
+    }
+    t2glb::MeshExportOptions opt;
+    opt.components = t2glb::ComponentFilter::KeepAll;
+    if (argc > 3) opt.texture_size = std::atoi(argv[3]);
+
+    FILE * f = std::fopen(argv[1], "rb");
+    if (!f) { std::fprintf(stderr, "open %s failed\n", argv[1]); return 1; }
+    char magic[9] = {0};
+    uint32_t nv = 0, nt = 0;
+    if (std::fread(magic, 1, 8, f) != 8 || std::fread(&nv, 4, 1, f) != 1 || std::fread(&nt, 4, 1, f) != 1) {
+        std::fprintf(stderr, "bad header\n"); return 1;
+    }
+    const bool legacy = std::memcmp(magic, "T2MESH02", 8) == 0;
+    const bool textured = legacy || std::memcmp(magic, "T2MESH03", 8) == 0;
+    if (!textured && std::memcmp(magic, "T2MESH01", 8) != 0) {
+        std::fprintf(stderr, "unknown magic\n"); return 1;
+    }
+    std::vector<float> verts, normals, pbr; std::vector<int32_t> tris;
+    bool ok = rd(f, verts, (size_t) nv * 3) && rd(f, normals, (size_t) nv * 3);
+    if (ok && textured) {
+        if (legacy) {
+            std::vector<float> old;
+            ok = rd(f, old, (size_t) nv * 5);
+            if (ok) {
+                pbr.resize((size_t) nv * 6);
+                for (uint32_t i = 0; i < nv; ++i) {
+                    std::memcpy(pbr.data() + (size_t) i * 6,
+                                old.data() + (size_t) i * 5, 5 * sizeof(float));
+                    pbr[(size_t) i * 6 + 5] = 1.0f;
+                }
+            }
+        } else {
+            ok = rd(f, pbr, (size_t) nv * 6);
+        }
+    }
+    ok = ok && rd(f, tris, (size_t) nt * 3);
+    std::fclose(f);
+    if (!ok) { std::fprintf(stderr, "truncated mesh\n"); return 1; }
+
+    std::fprintf(stderr, "in: %s  %u verts  %u tris  %s\n", magic, nv, nt,
+                 textured ? "textured" : "geometry-only");
+    std::fprintf(stderr, "export: preserving %u input tris ...\n", nt);
+
+    std::vector<uint8_t> glb; std::string err;
+    if (!t2glb::mesh_to_glb(verts.data(), (int) nv, tris.data(), (int) nt,
+                            textured ? pbr.data() : nullptr, opt, glb, err)) {
+        std::fprintf(stderr, "mesh_to_glb: %s\n", err.c_str());
+        return 1;
+    }
+
+    FILE * o = std::fopen(argv[2], "wb");
+    if (!o) { std::fprintf(stderr, "open %s failed\n", argv[2]); return 1; }
+    std::fwrite(glb.data(), 1, glb.size(), o);
+    std::fclose(o);
+    std::fprintf(stderr, "wrote %s (%.2f MB)\n", argv[2], glb.size() / 1048576.0);
+    return 0;
+}
diff --git a/fuzz/CMakeLists.txt b/fuzz/CMakeLists.txt
new file mode 100644
index 0000000..33ac1d8
--- /dev/null
+++ b/fuzz/CMakeLists.txt
@@ -0,0 +1,18 @@
+# libFuzzer harnesses for the untrusted (non-GGUF) input paths.
+# Requires clang; enable with the fuzz build:
+#   CC=clang CXX=clang++ cmake -B build-fuzz -DTRELLIS2_FUZZ=ON
+#   cmake --build build-fuzz -j
+#   ./build-fuzz/fuzz/fuzz_image     corpus_image/     -max_len=1048576
+#   ./build-fuzz/fuzz/fuzz_dinodata  corpus_dinodata/  -max_len=1048576
+
+if(NOT CMAKE_CXX_COMPILER_ID MATCHES "Clang")
+    message(FATAL_ERROR "TRELLIS2_FUZZ requires clang (libFuzzer)")
+endif()
+
+foreach(target fuzz_image fuzz_dinodata)
+    add_executable(${target} ${target}.cpp)
+    target_link_libraries(${target} PRIVATE trellis2)
+    target_compile_options(${target} PRIVATE -fsanitize=fuzzer)
+    target_link_options(${target} PRIVATE -fsanitize=fuzzer)
+    target_compile_features(${target} PRIVATE cxx_std_14)
+endforeach()
diff --git a/fuzz/crashes-fixed/README.md b/fuzz/crashes-fixed/README.md
new file mode 100644
index 0000000..35bd9c2
--- /dev/null
+++ b/fuzz/crashes-fixed/README.md
@@ -0,0 +1,10 @@
+# Fixed-crash regression seeds
+
+Inputs that once crashed a fuzz harness and now must not. Re-run after changes:
+
+    ./build-fuzz/fuzz/fuzz_dinodata fuzz/crashes-fixed/
+
+- `dinodata-shape-overflow` — a `.dinodata` header whose shape dims multiply to
+  an enormous element count; the loader used to `vector::resize` it and throw
+  `std::length_error`. Fixed by an overflow-checked element-count cap in
+  `trellis2_load_dinodata`.
diff --git a/fuzz/crashes-fixed/dinodata-shape-overflow b/fuzz/crashes-fixed/dinodata-shape-overflow
new file mode 100644
index 0000000..b26ae5d
Binary files /dev/null and b/fuzz/crashes-fixed/dinodata-shape-overflow differ
diff --git a/fuzz/fuzz_dinodata.cpp b/fuzz/fuzz_dinodata.cpp
new file mode 100644
index 0000000..ce1b487
--- /dev/null
+++ b/fuzz/fuzz_dinodata.cpp
@@ -0,0 +1,57 @@
+// libFuzzer harness for the .dinodata loader: arbitrary bytes -> temp file ->
+// trellis2_load_dinodata -> (on success) fingerprints over the payload.
+//
+// .dinodata files typically come from this codebase itself, but the demo and
+// CLI accept arbitrary paths, so the parser must be robust: reject bad magic /
+// truncated headers / shape overflow cleanly, never over-read.
+//
+// Invariants checked with abort() (not just "no crash"):
+//   * on success, data.size() == product(shape) and shape is non-empty
+//   * fingerprints run over the whole payload without UB
+//
+// Run: ./build-fuzz/fuzz/fuzz_dinodata corpus_dinodata/ -max_len=1048576
+
+#include "../trellis2.h"
+
+#include <cstdint>
+#include <cstdio>
+#include <cstdlib>
+#include <string>
+#include <unistd.h>
+
+extern "C" int LLVMFuzzerTestOneInput(const uint8_t * data, size_t size) {
+    if (size > (16u << 20)) {
+        return 0;
+    }
+
+    char path[] = "/tmp/fuzz_dinodata_XXXXXX";
+    const int fd = mkstemp(path);
+    if (fd < 0) {
+        return 0;
+    }
+    const ssize_t written = write(fd, data, size);
+    close(fd);
+    if (written != (ssize_t) size) {
+        unlink(path);
+        return 0;
+    }
+
+    trellis2_dino_cond cond;
+    std::string err;
+    if (trellis2_load_dinodata(path, cond, &err)) {
+        int64_t total = 1;
+        for (int64_t d : cond.shape) total *= d;
+        if (cond.shape.empty() || (size_t) total != cond.data.size()) {
+            abort();   // loader produced an inconsistent cond
+        }
+        const trellis2_dino_fingerprint fp = trellis2_dino_fingerprints(cond);
+        if (fp.count != cond.data.size()) {
+            abort();
+        }
+    } else if (err.empty()) {
+        abort();       // failure must come with a reason
+    }
+
+    unlink(path);
+    return 0;
+}
diff --git a/fuzz/fuzz_image.cpp b/fuzz/fuzz_image.cpp
new file mode 100644
index 0000000..c3a5373
--- /dev/null
+++ b/fuzz/fuzz_image.cpp
@@ -0,0 +1,33 @@
+// libFuzzer harness for the image upload path: arbitrary bytes ->
+// t2_preprocess_image_bytes (stb_image decode -> alpha bbox crop ->
+// premultiply -> PIL-compatible Lanczos resize).
+//
+// This is the demo server's untrusted-input surface: the Go server hands
+// uploaded bytes straight to this function. GGUF model files are trusted
+// assets and deliberately not fuzzed here (privacy-filter.cpp threat model).
+//
+// Build via -DTRELLIS2_FUZZ=ON (clang only); run:
+//   ./build-fuzz/fuzz/fuzz_image corpus_image/ -max_len=1048576
+//
+// Success invariant: the function either fails cleanly (nonzero + error
+// message) or fills exactly out_size^2*3 bytes. Any crash/leak/UB is a bug.
+
+#include "../trellis2_capi.h"
+
+#include <cstdint>
+#include <cstring>
+#include <vector>
+
+extern "C" int LLVMFuzzerTestOneInput(const uint8_t * data, size_t size) {
+    if (size == 0 || size > (32u << 20)) {
+        return 0;
+    }
+
+    // Small output target keeps per-input cost low; the resampler code path
+    // is identical for any out_size.
+    static thread_local std::vector<unsigned char> out(64 * 64 * 3);
+    char err[256] = {0};
+
+    (void) t2_preprocess_image_bytes(data, (int) size, 64, out.data(), err, sizeof(err));
+    return 0;
+}
diff --git a/mesh_export.cpp b/mesh_export.cpp
new file mode 100644
index 0000000..64506a3
--- /dev/null
+++ b/mesh_export.cpp
@@ -0,0 +1,643 @@
+#include "mesh_export.h"
+
+#include "xatlas.h"
+
+#define STB_IMAGE_WRITE_IMPLEMENTATION
+#include "stb_image_write.h"
+
+#include <algorithm>
+#include <cmath>
+#include <cstdio>
+#include <cstdlib>
+#include <cstring>
+#include <functional>
+#include <mutex>
+#include <unordered_map>
+
+namespace t2glb {
+namespace {
+
+// Stage logging to stderr, opt-in via T2GLB_VERBOSE (keeps the library quiet by
+// default while giving the CLI / debugging a progress trace).
+bool verbose() { static bool v = std::getenv("T2GLB_VERBOSE") != nullptr; return v; }
+#define GLBLOG(...) do { if (verbose()) { std::fprintf(stderr, "[glb] " __VA_ARGS__); std::fprintf(stderr, "\n"); } } while (0)
+
+// ─────────────────────────────────────────────────────────────────────────
+// Copy the original topology while dropping only invalid/degenerate faces and
+// unreferenced vertices. Export and showcase deliberately retain full polygon
+// density; component cleanup below is the only operation allowed to delete
+// valid faces.
+// ─────────────────────────────────────────────────────────────────────────
+bool copy_mesh(const float * verts, int nv, const int32_t * tris, int nt,
+               const float * pbr, std::vector<float> & dverts,
+               std::vector<int32_t> & dtris, std::vector<float> & dpbr,
+               std::string & err) {
+    std::vector<int> remap((size_t) nv, -1);
+    dverts.clear(); dverts.reserve((size_t) nv * 3);
+    dtris.clear(); dtris.reserve((size_t) nt * 3);
+    dpbr.clear(); if (pbr) dpbr.reserve((size_t) nv * 6);
+    for (int t = 0; t < nt; ++t) {
+        const int32_t a = tris[3*t], b = tris[3*t+1], c = tris[3*t+2];
+        if (a < 0 || b < 0 || c < 0 || a >= nv || b >= nv || c >= nv) {
+            err = "triangle index out of range";
+            return false;
+        }
+        if (a == b || b == c || a == c) continue;
+        for (int32_t v : {a, b, c}) {
+            if (remap[v] < 0) {
+                remap[v] = (int)(dverts.size() / 3);
+                dverts.push_back(verts[3*v+0]); dverts.push_back(verts[3*v+1]); dverts.push_back(verts[3*v+2]);
+                if (pbr) dpbr.insert(dpbr.end(), pbr + (size_t) v * 6, pbr + (size_t) v * 6 + 6);
+            }
+            dtris.push_back(remap[v]);
+        }
+    }
+    return true;
+}
+
+// Remove triangles belonging to small connected components (islands). The
+// dual-grid surface can contain tiny disconnected bits that each force a
+// separate UV chart and may correspond to unwanted background geometry.
+// Mirrors the reference's remove_small_connected_components. Keeps components
+// with at least `min_frac` of the triangles; recompacts verts/tris in place.
+void filter_components(std::vector<float> & v, std::vector<int32_t> & f,
+                       std::vector<float> & pbr,
+                       float min_frac, ComponentFilter mode) {
+    if (mode == ComponentFilter::KeepAll) return;
+    const int nv = (int)(v.size() / 3), nt = (int)(f.size() / 3);
+    if (nv == 0 || nt == 0) return;
+    std::vector<int> parent((size_t) nv), sz((size_t) nv, 1);
+    for (int i = 0; i < nv; ++i) parent[i] = i;
+    std::function<int(int)> find = [&](int x) { while (parent[x] != x) { parent[x] = parent[parent[x]]; x = parent[x]; } return x; };
+    auto uni = [&](int a, int b) { a = find(a); b = find(b); if (a==b) return; if (sz[a]<sz[b]) std::swap(a,b); parent[b]=a; sz[a]+=sz[b]; };
+    for (int t = 0; t < nt; ++t) { uni(f[3*t+0], f[3*t+1]); uni(f[3*t+1], f[3*t+2]); }
+
+    std::unordered_map<int, int> tris_in;   // component root -> triangle count
+    for (int t = 0; t < nt; ++t) tris_in[find(f[3*t+0])]++;
+    const int keep_min = std::max(1, (int)(nt * min_frac));
+    int largest = -1, largest_n = -1;
+    for (const auto & it : tris_in) {
+        if (it.second > largest_n) { largest = it.first; largest_n = it.second; }
+    }
+
+    std::vector<int> vremap((size_t) nv, -1);
+    std::vector<float> nvts; nvts.reserve(v.size());
+    std::vector<float> npbr; if (!pbr.empty()) npbr.reserve(pbr.size());
+    std::vector<int32_t> nfs; nfs.reserve(f.size());
+    for (int t = 0; t < nt; ++t) {
+        const int root = find(f[3*t+0]);
+        if (mode == ComponentFilter::KeepLargest ? root != largest
+                                                  : tris_in[root] < keep_min) continue;
+        for (int k = 0; k < 3; ++k) {
+            int vi = f[3*t+k];
+            if (vremap[vi] < 0) {
+                vremap[vi] = (int)(nvts.size()/3);
+                nvts.push_back(v[3*vi+0]); nvts.push_back(v[3*vi+1]); nvts.push_back(v[3*vi+2]);
+                if (!pbr.empty())
+                    npbr.insert(npbr.end(), pbr.begin() + (size_t) vi * 6,
+                                pbr.begin() + (size_t) vi * 6 + 6);
+            }
+            nfs.push_back(vremap[vi]);
+        }
+    }
+    if (!nfs.empty()) {
+        v.swap(nvts); f.swap(nfs);
+        if (!pbr.empty()) pbr.swap(npbr);
+    }
+}
+
+// Taubin (λ|μ) smoothing optionally regularises zig-zag sliver triangles so
+// per-face normals become coherent. Without this, xatlas may split a chart at
+// every normal jump (tens of thousands of one-off charts).
+// Taubin's alternating positive/negative passes smooth without the shrinkage of
+// plain Laplacian. The texture is unaffected (it samples the dense source).
+void taubin_smooth(std::vector<float> & v, const std::vector<int32_t> & f, int iters) {
+    const int nv = (int)(v.size() / 3), nt = (int)(f.size() / 3);
+    if (nv == 0 || nt == 0) return;
+    std::vector<int> deg((size_t) nv, 0);
+    // Accumulate neighbour sums per pass; build degree once.
+    for (int t = 0; t < nt; ++t)
+        for (int k = 0; k < 3; ++k) deg[f[3*t+k]] += 2; // each vertex in 2 edges of its triangle
+    const float lambda = 0.5f, mu = -0.53f;
+    std::vector<float> acc((size_t) nv * 3);
+    auto pass = [&](float w) {
+        std::fill(acc.begin(), acc.end(), 0.0f);
+        for (int t = 0; t < nt; ++t) {
+            int a = f[3*t+0], b = f[3*t+1], c = f[3*t+2];
+            for (int e = 0; e < 3; ++e) {
+                int i = (e==0?a:e==1?b:c), j = (e==0?b:e==1?c:a);
+                acc[3*i+0]+=v[3*j+0]; acc[3*i+1]+=v[3*j+1]; acc[3*i+2]+=v[3*j+2];
+                acc[3*j+0]+=v[3*i+0]; acc[3*j+1]+=v[3*i+1]; acc[3*j+2]+=v[3*i+2];
+            }
+        }
+        for (int i = 0; i < nv; ++i) {
+            if (deg[i] == 0) continue;
+            float inv = 1.0f / deg[i];
+            for (int k = 0; k < 3; ++k)
+                v[3*i+k] += w * (acc[3*i+k]*inv - v[3*i+k]); // move toward neighbour centroid
+        }
+    };
+    for (int it = 0; it < iters; ++it) { pass(lambda); pass(mu); }
+}
+
+// Area-weighted per-vertex normals over a mesh.
+void vertex_normals(const std::vector<float> & v, const std::vector<int32_t> & f,
+                    std::vector<float> & n) {
+    const size_t nv = v.size() / 3;
+    n.assign(nv * 3, 0.0f);
+    for (size_t t = 0; t < f.size() / 3; ++t) {
+        int a = f[3*t+0], b = f[3*t+1], c = f[3*t+2];
+        float e1[3] = {v[3*b+0]-v[3*a+0], v[3*b+1]-v[3*a+1], v[3*b+2]-v[3*a+2]};
+        float e2[3] = {v[3*c+0]-v[3*a+0], v[3*c+1]-v[3*a+1], v[3*c+2]-v[3*a+2]};
+        float fn[3] = {e1[1]*e2[2]-e1[2]*e2[1], e1[2]*e2[0]-e1[0]*e2[2], e1[0]*e2[1]-e1[1]*e2[0]};
+        for (int k : {a, b, c}) { n[3*k+0]+=fn[0]; n[3*k+1]+=fn[1]; n[3*k+2]+=fn[2]; }
+    }
+    for (size_t i = 0; i < nv; ++i) {
+        float l = std::sqrt(n[3*i+0]*n[3*i+0]+n[3*i+1]*n[3*i+1]+n[3*i+2]*n[3*i+2]) + 1e-20f;
+        n[3*i+0]/=l; n[3*i+1]/=l; n[3*i+2]/=l;
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// PNG encode to an in-memory byte vector.
+// ─────────────────────────────────────────────────────────────────────────
+void png_sink(void * ctx, void * data, int size) {
+    auto * v = (std::vector<uint8_t> *) ctx;
+    auto * p = (uint8_t *) data;
+    v->insert(v->end(), p, p + size);
+}
+bool encode_png(int w, int h, int comp, const uint8_t * pix, std::vector<uint8_t> & out) {
+    out.clear();
+    return stbi_write_png_to_func(png_sink, &out, w, h, comp, pix, w * comp) != 0;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// glTF 2.0 binary (GLB) assembly. One buffer holding, in order: POSITION,
+// NORMAL, TEXCOORD_0, indices, baseColor PNG, metallicRoughness PNG.
+// ─────────────────────────────────────────────────────────────────────────
+void put_u32(std::vector<uint8_t> & b, uint32_t v) {
+    b.push_back(v & 0xFF); b.push_back((v>>8)&0xFF); b.push_back((v>>16)&0xFF); b.push_back((v>>24)&0xFF);
+}
+void pad4(std::vector<uint8_t> & b, uint8_t fill) { while (b.size() % 4) b.push_back(fill); }
+
+void write_glb(const std::vector<float> & pos, const std::vector<float> & nrm,
+               const std::vector<float> & uv, const std::vector<uint32_t> & idx,
+               const std::vector<uint8_t> & basecolor_png,
+               const std::vector<uint8_t> & metalrough_png,
+               bool transparent,
+               std::vector<uint8_t> & out) {
+    const uint32_t nv = (uint32_t)(pos.size() / 3);
+    const uint32_t ni = (uint32_t) idx.size();
+
+    // Assemble the BIN buffer, tracking 4-aligned bufferView offsets.
+    std::vector<uint8_t> bin;
+    auto view = [&](const void * data, size_t bytes, uint32_t & off, uint32_t & len) {
+        pad4(bin, 0);
+        off = (uint32_t) bin.size();
+        len = (uint32_t) bytes;
+        const uint8_t * p = (const uint8_t *) data;
+        bin.insert(bin.end(), p, p + bytes);
+    };
+    uint32_t off_pos, len_pos, off_nrm, len_nrm, off_uv, len_uv, off_idx, len_idx;
+    uint32_t off_bc, len_bc, off_mr, len_mr;
+    view(pos.data(), pos.size()*4, off_pos, len_pos);
+    view(nrm.data(), nrm.size()*4, off_nrm, len_nrm);
+    view(uv.data(),  uv.size()*4,  off_uv,  len_uv);
+    view(idx.data(), idx.size()*4, off_idx, len_idx);
+    view(basecolor_png.data(), basecolor_png.size(), off_bc, len_bc);
+    view(metalrough_png.data(), metalrough_png.size(), off_mr, len_mr);
+    pad4(bin, 0);
+
+    float pmin[3] = {1e30f,1e30f,1e30f}, pmax[3] = {-1e30f,-1e30f,-1e30f};
+    for (uint32_t i = 0; i < nv; ++i)
+        for (int k = 0; k < 3; ++k) { pmin[k]=std::min(pmin[k],pos[3*i+k]); pmax[k]=std::max(pmax[k],pos[3*i+k]); }
+
+    char buf[2048];
+    std::string j = "{\"asset\":{\"version\":\"2.0\",\"generator\":\"trellis2cpp\"},";
+    j += "\"scene\":0,\"scenes\":[{\"nodes\":[0]}],\"nodes\":[{\"mesh\":0}],";
+    j += "\"meshes\":[{\"primitives\":[{\"attributes\":{\"POSITION\":0,\"NORMAL\":1,\"TEXCOORD_0\":2},\"indices\":3,\"material\":0}]}],";
+    j += "\"materials\":[{\"pbrMetallicRoughness\":{\"baseColorTexture\":{\"index\":0},\"metallicRoughnessTexture\":{\"index\":1},\"metallicFactor\":1.0,\"roughnessFactor\":1.0},";
+    if (transparent) j += "\"alphaMode\":\"BLEND\",";
+    j += "\"doubleSided\":true}],";
+    j += "\"textures\":[{\"source\":0,\"sampler\":0},{\"source\":1,\"sampler\":0}],";
+    j += "\"images\":[{\"bufferView\":4,\"mimeType\":\"image/png\"},{\"bufferView\":5,\"mimeType\":\"image/png\"}],";
+    // No mipmaps: opt-in xatlas charts use explicit dilation around their seams.
+    j += "\"samplers\":[{\"magFilter\":9729,\"minFilter\":9729,\"wrapS\":33071,\"wrapT\":33071}],";
+    snprintf(buf, sizeof buf,
+        "\"accessors\":[{\"bufferView\":0,\"componentType\":5126,\"count\":%u,\"type\":\"VEC3\",\"min\":[%.8g,%.8g,%.8g],\"max\":[%.8g,%.8g,%.8g]},"
+        "{\"bufferView\":1,\"componentType\":5126,\"count\":%u,\"type\":\"VEC3\"},"
+        "{\"bufferView\":2,\"componentType\":5126,\"count\":%u,\"type\":\"VEC2\"},"
+        "{\"bufferView\":3,\"componentType\":5125,\"count\":%u,\"type\":\"SCALAR\"}],",
+        nv, pmin[0],pmin[1],pmin[2], pmax[0],pmax[1],pmax[2], nv, nv, ni);
+    j += buf;
+    snprintf(buf, sizeof buf,
+        "\"bufferViews\":[{\"buffer\":0,\"byteOffset\":%u,\"byteLength\":%u,\"target\":34962},"
+        "{\"buffer\":0,\"byteOffset\":%u,\"byteLength\":%u,\"target\":34962},"
+        "{\"buffer\":0,\"byteOffset\":%u,\"byteLength\":%u,\"target\":34962},"
+        "{\"buffer\":0,\"byteOffset\":%u,\"byteLength\":%u,\"target\":34963},"
+        "{\"buffer\":0,\"byteOffset\":%u,\"byteLength\":%u},"
+        "{\"buffer\":0,\"byteOffset\":%u,\"byteLength\":%u}],",
+        off_pos,len_pos, off_nrm,len_nrm, off_uv,len_uv, off_idx,len_idx, off_bc,len_bc, off_mr,len_mr);
+    j += buf;
+    snprintf(buf, sizeof buf, "\"buffers\":[{\"byteLength\":%u}]}", (uint32_t) bin.size());
+    j += buf;
+
+    std::vector<uint8_t> json(j.begin(), j.end());
+    while (json.size() % 4) json.push_back(0x20); // pad JSON chunk with spaces
+
+    const uint32_t total = 12 + 8 + (uint32_t) json.size() + 8 + (uint32_t) bin.size();
+    out.clear();
+    out.reserve(total);
+    put_u32(out, 0x46546C67); put_u32(out, 2); put_u32(out, total);          // header
+    put_u32(out, (uint32_t) json.size()); put_u32(out, 0x4E4F534A);          // JSON chunk
+    out.insert(out.end(), json.begin(), json.end());
+    put_u32(out, (uint32_t) bin.size()); put_u32(out, 0x004E4942);           // BIN chunk
+    out.insert(out.end(), bin.begin(), bin.end());
+}
+
+// Portable full-density export. glTF natively supports interpolated RGBA
+// vertex colours, which are a much better representation for TRELLIS' dense
+// per-vertex material field than assigning millions of triangles to a finite
+// 2D atlas. Metallic/roughness have no standard per-vertex glTF semantics, so
+// their averages drive the standard material while the original quantised
+// values are retained in the application attribute _METALLIC_ROUGHNESS.
+void write_vertex_glb(const PreparedMesh & mesh, std::vector<uint8_t> & out) {
+    const uint32_t nv = (uint32_t)(mesh.verts.size() / 3);
+    const uint32_t ni = (uint32_t) mesh.tris.size();
+    const bool textured = mesh.pbr.size() == (size_t) nv * 6;
+    auto to8 = [](float f) {
+        int v = (int) std::lround(f * 255.0f);
+        return (uint8_t) std::min(255, std::max(0, v));
+    };
+    auto clamp01 = [](float f) { return std::min(1.0f, std::max(0.0f, f)); };
+    auto srgb_to_linear = [&](float f) {
+        f = clamp01(f);
+        return f <= 0.04045f ? f / 12.92f
+                             : std::pow((f + 0.055f) / 1.055f, 2.4f);
+    };
+    auto to16 = [](float f) {
+        int v = (int) std::lround(f * 65535.0f);
+        return (uint16_t) std::min(65535, std::max(0, v));
+    };
+
+    std::vector<float> pos((size_t) nv * 3), nrm((size_t) nv * 3);
+    // glTF COLOR_0 is linear rather than sRGB. Sixteen-bit UNORM keeps dark
+    // generated colours precise after converting from the texture model's
+    // sRGB-like output.
+    std::vector<uint16_t> color((size_t) nv * 4);
+    std::vector<uint8_t> metalrough((size_t) nv * 2);
+    std::vector<uint32_t> idx(ni);
+    double metal_sum = 0.0, rough_sum = 0.0, weight_sum = 0.0;
+    uint32_t translucent = 0;
+    for (uint32_t i = 0; i < nv; ++i) {
+        // Trellis -> glTF Y-up, preserving handedness.
+        pos[3*i+0]= mesh.verts[3*i+0]; pos[3*i+1]= mesh.verts[3*i+2]; pos[3*i+2]=-mesh.verts[3*i+1];
+        nrm[3*i+0]= mesh.normals[3*i+0]; nrm[3*i+1]= mesh.normals[3*i+2]; nrm[3*i+2]=-mesh.normals[3*i+1];
+        const float * p = textured ? mesh.pbr.data() + (size_t) i * 6 : nullptr;
+        const float r = p ? p[0] : 0.7f, g = p ? p[1] : 0.7f, b = p ? p[2] : 0.7f;
+        const float m = p ? clamp01(p[3]) : 0.0f;
+        const float ro = p ? clamp01(p[4]) : 0.6f;
+        const float a = p ? clamp01(p[5]) : 1.0f;
+        color[4*i+0]=to16(srgb_to_linear(r)); color[4*i+1]=to16(srgb_to_linear(g));
+        color[4*i+2]=to16(srgb_to_linear(b)); color[4*i+3]=to16(a);
+        metalrough[2*i+0]=to8(m); metalrough[2*i+1]=to8(ro);
+        // Near-transparent samples should not skew the visible material's
+        // standard fallback factors.
+        const double w = std::max(0.001f, a);
+        metal_sum += m * w; rough_sum += ro * w; weight_sum += w;
+        if (a < 0.95f) ++translucent;
+    }
+    for (uint32_t i = 0; i < ni; ++i) idx[i] = (uint32_t) mesh.tris[i];
+    const float metallic = weight_sum ? (float)(metal_sum / weight_sum) : 0.0f;
+    const float roughness = weight_sum ? (float)(rough_sum / weight_sum) : 0.6f;
+    // BLEND disables normal opaque depth writes in many viewers. Do not switch
+    // an entire multi-million-face primitive to blending because of a handful
+    // of near-one decoder outliers; upstream likewise exports ordinary surfaces
+    // as opaque. Keep blending for a material with meaningful transparency.
+    const bool transparent = translucent > 0 &&
+                             (uint64_t) translucent * 1000 >= (uint64_t) nv;
+
+    std::vector<uint8_t> bin;
+    auto view = [&](const void * data, size_t bytes, uint32_t & off, uint32_t & len) {
+        pad4(bin, 0);
+        off = (uint32_t) bin.size(); len = (uint32_t) bytes;
+        const uint8_t * p = (const uint8_t *) data;
+        bin.insert(bin.end(), p, p + bytes);
+    };
+    uint32_t off_pos, len_pos, off_nrm, len_nrm, off_col, len_col;
+    uint32_t off_mr, len_mr, off_idx, len_idx;
+    view(pos.data(), pos.size()*4, off_pos, len_pos);
+    view(nrm.data(), nrm.size()*4, off_nrm, len_nrm);
+    view(color.data(), color.size()*sizeof(uint16_t), off_col, len_col);
+    view(metalrough.data(), metalrough.size(), off_mr, len_mr);
+    view(idx.data(), idx.size()*4, off_idx, len_idx);
+    pad4(bin, 0);
+
+    float pmin[3] = {1e30f,1e30f,1e30f}, pmax[3] = {-1e30f,-1e30f,-1e30f};
+    for (uint32_t i = 0; i < nv; ++i)
+        for (int k = 0; k < 3; ++k) {
+            pmin[k]=std::min(pmin[k],pos[3*i+k]); pmax[k]=std::max(pmax[k],pos[3*i+k]);
+        }
+
+    char buf[3072];
+    std::string j = "{\"asset\":{\"version\":\"2.0\",\"generator\":\"trellis2cpp\"},";
+    j += "\"scene\":0,\"scenes\":[{\"nodes\":[0]}],\"nodes\":[{\"mesh\":0}],";
+    j += "\"meshes\":[{\"primitives\":[{\"attributes\":{\"POSITION\":0,\"NORMAL\":1,\"COLOR_0\":2,\"_METALLIC_ROUGHNESS\":3},\"indices\":4,\"material\":0}]}],";
+    std::snprintf(buf, sizeof buf,
+        "\"materials\":[{\"pbrMetallicRoughness\":{\"baseColorFactor\":[1,1,1,1],\"metallicFactor\":%.8g,\"roughnessFactor\":%.8g},",
+        metallic, roughness);
+    j += buf;
+    if (transparent) j += "\"alphaMode\":\"BLEND\",";
+    j += "\"doubleSided\":true}],";
+    std::snprintf(buf, sizeof buf,
+        "\"accessors\":[{\"bufferView\":0,\"componentType\":5126,\"count\":%u,\"type\":\"VEC3\",\"min\":[%.8g,%.8g,%.8g],\"max\":[%.8g,%.8g,%.8g]},"
+        "{\"bufferView\":1,\"componentType\":5126,\"count\":%u,\"type\":\"VEC3\"},"
+        "{\"bufferView\":2,\"componentType\":5123,\"normalized\":true,\"count\":%u,\"type\":\"VEC4\"},"
+        "{\"bufferView\":3,\"componentType\":5121,\"normalized\":true,\"count\":%u,\"type\":\"VEC2\"},"
+        "{\"bufferView\":4,\"componentType\":5125,\"count\":%u,\"type\":\"SCALAR\"}],",
+        nv, pmin[0],pmin[1],pmin[2], pmax[0],pmax[1],pmax[2], nv, nv, nv, ni);
+    j += buf;
+    std::snprintf(buf, sizeof buf,
+        "\"bufferViews\":[{\"buffer\":0,\"byteOffset\":%u,\"byteLength\":%u,\"target\":34962},"
+        "{\"buffer\":0,\"byteOffset\":%u,\"byteLength\":%u,\"target\":34962},"
+        "{\"buffer\":0,\"byteOffset\":%u,\"byteLength\":%u,\"target\":34962},"
+        "{\"buffer\":0,\"byteOffset\":%u,\"byteLength\":%u,\"target\":34962},"
+        "{\"buffer\":0,\"byteOffset\":%u,\"byteLength\":%u,\"target\":34963}],",
+        off_pos,len_pos, off_nrm,len_nrm, off_col,len_col, off_mr,len_mr, off_idx,len_idx);
+    j += buf;
+    std::snprintf(buf, sizeof buf, "\"buffers\":[{\"byteLength\":%u}]}", (uint32_t) bin.size());
+    j += buf;
+
+    std::vector<uint8_t> json(j.begin(), j.end());
+    while (json.size() % 4) json.push_back(0x20);
+    const uint32_t total = 12 + 8 + (uint32_t) json.size() + 8 + (uint32_t) bin.size();
+    out.clear(); out.reserve(total);
+    put_u32(out, 0x46546C67); put_u32(out, 2); put_u32(out, total);
+    put_u32(out, (uint32_t) json.size()); put_u32(out, 0x4E4F534A);
+    out.insert(out.end(), json.begin(), json.end());
+    put_u32(out, (uint32_t) bin.size()); put_u32(out, 0x004E4942);
+    out.insert(out.end(), bin.begin(), bin.end());
+}
+
+// Chart-based unwrap via xatlas → per-output-vertex position/normal/uv (texel
+// space) + index buffer + atlas dims. Proper editable charts, but only fast on
+// clean, manifold meshes. Opt-in with T2GLB_XATLAS.
+bool xatlas_unwrap(const std::vector<float> & dverts, const std::vector<float> & dnrm,
+                   const std::vector<float> & dpbr, int dnv,
+                   const std::vector<int32_t> & dtris, int dnt, const MeshExportOptions & opt, int TS,
+                   std::vector<float> & opos, std::vector<float> & onrm, std::vector<float> & ouv,
+                   std::vector<float> & opbr, std::vector<uint32_t> & oidx,
+                   int & AW, int & AH, std::string & err) {
+    xatlas::Atlas * atlas = xatlas::Create();
+    xatlas::MeshDecl md{};
+    md.vertexCount = (uint32_t) dnv;
+    md.vertexPositionData = dverts.data();
+    md.vertexPositionStride = sizeof(float) * 3;
+    md.indexCount = (uint32_t)(dnt * 3);
+    md.indexData = dtris.data();
+    md.indexFormat = xatlas::IndexFormat::UInt32;
+    if (xatlas::AddMesh(atlas, md) != xatlas::AddMeshError::Success) {
+        xatlas::Destroy(atlas); err = "xatlas AddMesh failed"; return false;
+    }
+    GLBLOG("xatlas computing charts ...");
+    xatlas::ChartOptions co{};
+    co.normalDeviationWeight = 0.5f; co.roundnessWeight = 0.0f; co.straightnessWeight = 1.0f;
+    co.normalSeamWeight = 1.0f; co.textureSeamWeight = 0.0f; co.maxCost = 8.0f; co.maxIterations = 1;
+    xatlas::ComputeCharts(atlas, co);
+
+    xatlas::PackOptions po{};
+    po.padding = (uint32_t) opt.padding;
+    po.bilinear = true;
+    po.createImage = false;
+    uint32_t res = (uint32_t) TS;
+    for (int attempt = 0; attempt < 4; ++attempt) {
+        po.resolution = res;
+        xatlas::PackCharts(atlas, po);
+        if (atlas->atlasCount <= 1) break;
+        res = (uint32_t)(res * 1.5f);
+    }
+    GLBLOG("atlas %ux%u, %u pages, %u charts", atlas->width, atlas->height, atlas->atlasCount, atlas->chartCount);
+    if (atlas->meshCount != 1 || atlas->atlasCount != 1 || atlas->width == 0 || atlas->height == 0) {
+        xatlas::Destroy(atlas); err = "xatlas packing failed (charts did not fit one atlas)"; return false;
+    }
+    AW = (int) atlas->width; AH = (int) atlas->height;
+    const xatlas::Mesh & om = atlas->meshes[0];
+    const uint32_t onv = om.vertexCount;
+    opos.resize(onv*3); onrm.resize(onv*3); ouv.resize(onv*2);
+    if (!dpbr.empty()) opbr.resize(onv*6);
+    for (uint32_t i = 0; i < onv; ++i) {
+        uint32_t xr = om.vertexArray[i].xref;
+        if (xr >= (uint32_t) dnv) xr = 0;
+        opos[3*i+0]=dverts[3*xr+0]; opos[3*i+1]=dverts[3*xr+1]; opos[3*i+2]=dverts[3*xr+2];
+        onrm[3*i+0]=dnrm[3*xr+0];   onrm[3*i+1]=dnrm[3*xr+1];   onrm[3*i+2]=dnrm[3*xr+2];
+        ouv[2*i+0]=om.vertexArray[i].uv[0]; ouv[2*i+1]=om.vertexArray[i].uv[1];
+        if (!dpbr.empty())
+            std::memcpy(opbr.data() + (size_t) i * 6,
+                        dpbr.data() + (size_t) xr * 6, 6 * sizeof(float));
+    }
+    oidx.assign(om.indexArray, om.indexArray + om.indexCount);
+    xatlas::Destroy(atlas);
+    return true;
+}
+
+bool prepare_mesh_locked(const float * verts, int nv,
+                         const int32_t * tris, int nt,
+                         const float * pbr,
+                         const MeshExportOptions & opt,
+                         PreparedMesh & out,
+                         std::string & err) {
+    if (!verts || !tris || nv <= 0 || nt <= 0) { err = "empty mesh"; return false; }
+    out = PreparedMesh{};
+
+    GLBLOG("input %d verts %d tris; preserving original topology", nv, nt);
+    if (!copy_mesh(verts, nv, tris, nt, pbr, out.verts, out.tris, out.pbr, err)) return false;
+
+    filter_components(out.verts, out.tris, out.pbr, 0.0005f, opt.components);
+    const int dnv = (int)(out.verts.size()/3), dnt = (int)(out.tris.size()/3);
+    if (dnv < 3 || dnt < 1) { err = "component cleanup produced an empty mesh"; return false; }
+    GLBLOG("after component filter -> %d verts %d tris", dnv, dnt);
+
+    // xatlas optionally regularises the geometry; do it here so the preview is
+    // the geometry that will actually be written to the GLB.
+    if (std::getenv("T2GLB_XATLAS") && !std::getenv("T2GLB_NOSMOOTH"))
+        taubin_smooth(out.verts, out.tris, 3);
+    vertex_normals(out.verts, out.tris, out.normals);
+    return true;
+}
+
+std::mutex g_bake_mu; // serialize bakes (bounds peak RAM; keeps stb/xatlas tidy)
+
+} // namespace
+
+bool prepare_mesh(const float * verts, int nv,
+                  const int32_t * tris, int nt,
+                  const float * pbr,
+                  const MeshExportOptions & opt,
+                  PreparedMesh & out,
+                  std::string & err) {
+    std::lock_guard<std::mutex> lock(g_bake_mu);
+    return prepare_mesh_locked(verts, nv, tris, nt, pbr, opt, out, err);
+}
+
+bool mesh_to_glb(const float * verts, int nv,
+                 const int32_t * tris, int nt,
+                 const float * pbr,
+                 const MeshExportOptions & opt,
+                 std::vector<uint8_t> & out,
+                 std::string & err) {
+    if (nv <= 0 || nt <= 0) { err = "empty mesh"; return false; }
+    const int TS = opt.texture_size;
+    if (TS < 16 || TS > 8192) { err = "bad texture_size"; return false; }
+
+    std::lock_guard<std::mutex> lock(g_bake_mu);
+
+    // 1) preserve topology + optional component filter --------------------
+    PreparedMesh prepared;
+    if (!prepare_mesh_locked(verts, nv, tris, nt, pbr, opt, prepared, err)) return false;
+    std::vector<float> & dverts = prepared.verts;
+    std::vector<float> & dnrm = prepared.normals;
+    std::vector<int32_t> & dtris = prepared.tris;
+    std::vector<float> & dpbr = prepared.pbr;
+    const int dnv = (int)(dverts.size()/3), dnt = (int)(dtris.size()/3);
+    const bool use_xatlas = std::getenv("T2GLB_XATLAS") != nullptr;
+
+    // A fixed-size per-triangle grid atlas cannot represent a full-density
+    // TRELLIS mesh: at 3.1M triangles, even 2048² gives each face barely one
+    // texel before gutters. The old fallback consequently emitted unpainted,
+    // transparent cells and visible rectangular/triangular colour blocks.
+    // Preserve the material field directly on the original vertices instead.
+    if (!use_xatlas) {
+        write_vertex_glb(prepared, out);
+        GLBLOG("GLB %zu bytes (%d verts, %d tris; vertex PBR)", out.size(), dnv, dnt);
+        return true;
+    }
+
+    // 2) UV atlas ----------------------------------------------------------
+    // Output-vertex streams: opos/onrm (geometry) and ouv (atlas-texel space),
+    // plus the triangle index buffer oidx and atlas dims AW×AH.
+    std::vector<float> opos, onrm, ouv, opbr;
+    std::vector<uint32_t> oidx;
+    int AW = TS, AH = TS;
+
+    // Chart-based unwrap (proper, editable UVs). Only fast on clean, manifold
+    // meshes — machine-generated dual-grid geometry shatters it into tens of
+    // thousands of charts. It remains an explicit experimental opt-in.
+    if (!xatlas_unwrap(dverts, dnrm, dpbr, dnv, dtris, dnt, opt, TS,
+                       opos, onrm, ouv, opbr, oidx, AW, AH, err))
+        return false;
+    const uint32_t onv = (uint32_t)(opos.size()/3);
+    const uint32_t ntri = (uint32_t)(oidx.size()/3);
+
+    // 3) bake --------------------------------------------------------------
+    GLBLOG("rasterizing %u tris ...", ntri);
+
+    const int NP = AW * AH;
+    std::vector<float> bc(NP*3, 0.0f), met(NP, 0.0f), rou(NP, 0.0f), alp(NP, 0.0f);
+    std::vector<uint8_t> mask(NP, 0);
+    // Defaults for the untextured path / unfilled charts.
+    auto set_default = [&](int pix) {
+        bc[3*pix+0]=bc[3*pix+1]=bc[3*pix+2]=0.7f;
+        met[pix]=0.0f; rou[pix]=0.6f; alp[pix]=1.0f;
+    };
+
+    for (uint32_t t = 0; t < ntri; ++t) {
+        uint32_t ia = oidx[3*t+0], ib = oidx[3*t+1], ic = oidx[3*t+2];
+        float ax=ouv[2*ia+0], ay=ouv[2*ia+1];
+        float bx=ouv[2*ib+0], by=ouv[2*ib+1];
+        float cx=ouv[2*ic+0], cy=ouv[2*ic+1];
+        float area = (bx-ax)*(cy-ay) - (by-ay)*(cx-ax);
+        if (std::fabs(area) < 1e-9f) continue;
+        float inv_area = 1.0f / area;
+        int x0 = std::max(0, (int)std::floor(std::min({ax,bx,cx}) - 1));
+        int x1 = std::min(AW-1, (int)std::ceil (std::max({ax,bx,cx}) + 1));
+        int y0 = std::max(0, (int)std::floor(std::min({ay,by,cy}) - 1));
+        int y1 = std::min(AH-1, (int)std::ceil (std::max({ay,by,cy}) + 1));
+        for (int py = y0; py <= y1; ++py) {
+            float sy = py + 0.5f;
+            for (int px = x0; px <= x1; ++px) {
+                float sx = px + 0.5f;
+                float w0 = ((bx-sx)*(cy-sy) - (by-sy)*(cx-sx)) * inv_area;
+                float w1 = ((cx-sx)*(ay-sy) - (cy-sy)*(ax-sx)) * inv_area;
+                float w2 = 1.0f - w0 - w1;
+                const float e = -0.001f;
+                if (w0 < e || w1 < e || w2 < e) continue;
+                int pix = py*AW + px;
+                if (!pbr) { set_default(pix); mask[pix]=1; continue; }
+                const float * a = opbr.data() + (size_t) ia * 6;
+                const float * b = opbr.data() + (size_t) ib * 6;
+                const float * c = opbr.data() + (size_t) ic * 6;
+                float val[6];
+                for (int ch = 0; ch < 6; ++ch) val[ch] = w0*a[ch] + w1*b[ch] + w2*c[ch];
+                bc[3*pix+0]=val[0]; bc[3*pix+1]=val[1]; bc[3*pix+2]=val[2];
+                met[pix]=val[3]; rou[pix]=val[4]; alp[pix]=val[5];
+                mask[pix]=1;
+            }
+        }
+    }
+
+    // 4) inpaint (edge-pad dilation) — fill the gutter so bilinear/mip sampling
+    // doesn't bleed empty texels across chart seams.
+    {
+        std::vector<uint8_t> m = mask;
+        for (int pass = 0; pass < opt.dilate; ++pass) {
+            std::vector<uint8_t> nm = m;
+            for (int py = 0; py < AH; ++py)
+            for (int px = 0; px < AW; ++px) {
+                int pix = py*AW+px;
+                if (m[pix]) continue;
+                float acc[6]={0,0,0,0,0,0}; int cnt=0;
+                for (int dy=-1; dy<=1; ++dy)
+                for (int dx=-1; dx<=1; ++dx) {
+                    int qx=px+dx, qy=py+dy;
+                    if (qx<0||qx>=AW||qy<0||qy>=AH) continue;
+                    int q=qy*AW+qx;
+                    if (!m[q]) continue;
+                    acc[0]+=bc[3*q+0]; acc[1]+=bc[3*q+1]; acc[2]+=bc[3*q+2];
+                    acc[3]+=met[q]; acc[4]+=rou[q]; acc[5]+=alp[q]; ++cnt;
+                }
+                if (cnt) {
+                    bc[3*pix+0]=acc[0]/cnt; bc[3*pix+1]=acc[1]/cnt; bc[3*pix+2]=acc[2]/cnt;
+                    met[pix]=acc[3]/cnt; rou[pix]=acc[4]/cnt; alp[pix]=acc[5]/cnt; nm[pix]=1;
+                }
+            }
+            m.swap(nm);
+        }
+    }
+
+    // 5) pack channel images. baseColor is an sRGB texture (values written as-is,
+    // matching the reference's base_color*255 → baseColorTexture). glTF packs
+    // metallic→B, roughness→G (R unused).
+    auto to8 = [](float f){ int v=(int)std::lround(f*255.0f); return (uint8_t) std::min(255,std::max(0,v)); };
+    std::vector<uint8_t> bc8(NP*4), mr8(NP*3);
+    for (int i = 0; i < NP; ++i) {
+        bc8[4*i+0]=to8(bc[3*i+0]); bc8[4*i+1]=to8(bc[3*i+1]);
+        bc8[4*i+2]=to8(bc[3*i+2]); bc8[4*i+3]=to8(alp[i]);
+        mr8[3*i+0]=0; mr8[3*i+1]=to8(rou[i]); mr8[3*i+2]=to8(met[i]);
+    }
+    int covered = 0, translucent = 0;
+    for (int i = 0; i < NP; ++i) if (mask[i]) {
+        ++covered;
+        if (alp[i] < 0.95f) ++translucent;
+    }
+    const bool transparent = translucent > 0 &&
+                             (int64_t) translucent * 1000 >= (int64_t) covered;
+    GLBLOG("inpaint + PNG encode ...");
+    std::vector<uint8_t> bc_png, mr_png;
+    if (!encode_png(AW, AH, 4, bc8.data(), bc_png) || !encode_png(AW, AH, 3, mr8.data(), mr_png)) {
+        err = "PNG encode failed"; return false;
+    }
+
+    // 6) final vertex streams with the Trellis→glTF (Y-up) axis convention:
+    // (x,y,z) → (x, z, -y); UVs normalised (top-left origin, no V flip).
+    std::vector<float> gpos(onv*3), gnrm(onv*3), guv(onv*2);
+    for (uint32_t i = 0; i < onv; ++i) {
+        gpos[3*i+0]= opos[3*i+0]; gpos[3*i+1]= opos[3*i+2]; gpos[3*i+2]=-opos[3*i+1];
+        gnrm[3*i+0]= onrm[3*i+0]; gnrm[3*i+1]= onrm[3*i+2]; gnrm[3*i+2]=-onrm[3*i+1];
+        guv[2*i+0]= ouv[2*i+0]/(float)AW; guv[2*i+1]= ouv[2*i+1]/(float)AH;
+    }
+    write_glb(gpos, gnrm, guv, oidx, bc_png, mr_png, transparent, out);
+    GLBLOG("GLB %zu bytes (%u verts, %u tris)", out.size(), onv, ntri);
+    return true;
+}
+
+} // namespace t2glb
diff --git a/mesh_export.h b/mesh_export.h
new file mode 100644
index 0000000..f2ebbc9
--- /dev/null
+++ b/mesh_export.h
@@ -0,0 +1,69 @@
+#pragma once
+//
+// mesh_export — CUDA-free port of o_voxel.postprocess.to_glb: take the demo's
+// dense per-vertex-PBR mesh and produce a portable glTF 2.0 binary (GLB). The
+// reference does this on the GPU (CuMesh simplify/unwrap/BVH, nvdiffrast
+// raster, flex_gemm grid_sample); here every stage is pure C++:
+//
+//   preserve topology -> optional component cleanup -> standard COLOR_0 vertex
+//   material + retained custom metallic/roughness attribute -> GLB.
+//
+// A practical fixed-size atlas cannot give millions of preserved triangles
+// enough texels, and the dual-grid geometry is heavily non-manifold. glTF vertex
+// colour is therefore both more faithful and substantially smaller. Set
+// T2GLB_XATLAS to opt into a conventional image atlas on clean meshes. No ggml /
+// CUDA dependency: plain float/int arrays.
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace t2glb {
+
+enum class ComponentFilter {
+    RemoveTiny = 0,  // preserve meaningful disconnected parts
+    KeepLargest = 1, // retain only the component with the most triangles
+    KeepAll = 2      // input is already prepared; do not filter again
+};
+
+struct MeshExportOptions {
+    int   texture_size  = 2048;    // opt-in T2GLB_XATLAS width/height
+    int   padding       = 2;       // xatlas chart padding (texels; T2GLB_XATLAS)
+    int   dilate        = 6;       // gutter dilation passes (kills UV seams)
+    ComponentFilter components = ComponentFilter::RemoveTiny;
+};
+
+// Geometry/material streams after the same component filtering used by
+// mesh_to_glb. Valid source triangles retain their original polygon density.
+struct PreparedMesh {
+    std::vector<float>   verts;
+    std::vector<float>   normals;
+    std::vector<int32_t> tris;
+    std::vector<float>   pbr;
+};
+
+bool prepare_mesh(const float * verts, int nv,
+                  const int32_t * tris, int nt,
+                  const float * pbr,
+                  const MeshExportOptions & opt,
+                  PreparedMesh & out,
+                  std::string & err);
+
+// Export a dense per-vertex-PBR mesh as a standard vertex-coloured GLB.
+//
+//   verts   3*nv  vertex positions (mesh/world space, as fdg::extract emits)
+//   tris    3*nt  triangle vertex indices
+//   pbr     6*nv  base_color rgb, metallic, roughness, alpha
+//                 (null -> untextured grey)
+//
+// On success fills `out` with the GLB bytes and returns true. On failure returns
+// false with a message in `err`. Not reentrant (Simplify.h uses global state):
+// serialized internally by a mutex.
+bool mesh_to_glb(const float * verts, int nv,
+                 const int32_t * tris, int nt,
+                 const float * pbr,
+                 const MeshExportOptions & opt,
+                 std::vector<uint8_t> & out,
+                 std::string & err);
+
+} // namespace t2glb
diff --git a/pbr_utils.h b/pbr_utils.h
new file mode 100644
index 0000000..9902a2b
--- /dev/null
+++ b/pbr_utils.h
@@ -0,0 +1,81 @@
+#pragma once
+
+#include <cstddef>
+#include <cmath>
+#include <cstdint>
+#include <unordered_map>
+
+namespace t2pbr {
+
+inline uint64_t voxel_key(int32_t x, int32_t y, int32_t z) {
+    return ((uint64_t) (uint32_t) x << 42) |
+           ((uint64_t) (uint32_t) y << 21) |
+           (uint64_t) (uint32_t) z;
+}
+
+// Trilinearly sample a sparse voxel field. query_vox is expressed in voxel
+// coordinates, exactly like upstream's (xyz - origin) / voxel_size. Missing
+// corners do not contribute and present weights are renormalized, matching the
+// reference helper used for per-vertex texture validation.
+inline void sample_sparse_trilinear(const float * feats, int n_voxels, int channels,
+                                    const int32_t * coords,
+                                    const float * query_vox, int n_queries,
+                                    float * out, float * out_weights = nullptr) {
+    std::unordered_map<uint64_t, int> rows;
+    rows.reserve((size_t) n_voxels * 2);
+    for (int i = 0; i < n_voxels; ++i) {
+        rows[voxel_key(coords[(size_t) i * 3], coords[(size_t) i * 3 + 1],
+                       coords[(size_t) i * 3 + 2])] = i;
+    }
+
+    for (int q = 0; q < n_queries; ++q) {
+        float * dst = out + (size_t) q * channels;
+        for (int c = 0; c < channels; ++c) dst[c] = 0.0f;
+
+        const float * p = query_vox + (size_t) q * 3;
+        const int32_t bx = (int32_t) std::floor(p[0]);
+        const int32_t by = (int32_t) std::floor(p[1]);
+        const int32_t bz = (int32_t) std::floor(p[2]);
+        const float fx = p[0] - bx, fy = p[1] - by, fz = p[2] - bz;
+        float wsum = 0.0f;
+
+        for (int dx = 0; dx <= 1; ++dx)
+        for (int dy = 0; dy <= 1; ++dy)
+        for (int dz = 0; dz <= 1; ++dz) {
+            const float w = (dx ? fx : 1.0f - fx) *
+                            (dy ? fy : 1.0f - fy) *
+                            (dz ? fz : 1.0f - fz);
+            if (w == 0.0f) continue;
+            auto it = rows.find(voxel_key(bx + dx, by + dy, bz + dz));
+            if (it == rows.end()) continue;
+            const float * src = feats + (size_t) it->second * channels;
+            for (int c = 0; c < channels; ++c) dst[c] += w * src[c];
+            wsum += w;
+        }
+        if (wsum > 1e-6f) {
+            const float inv = 1.0f / wsum;
+            for (int c = 0; c < channels; ++c) dst[c] *= inv;
+        }
+        if (out_weights) out_weights[q] = wsum;
+    }
+}
+
+// Detect the characteristic failed texture decode where nearly every vertex
+// has every material channel pinned to one. Requiring all channels avoids
+// rejecting legitimate white, fully opaque, metallic, or rough materials.
+inline bool is_collapsed_saturated(const float * pbr, int n_vertices,
+                                   int channels = 6, float threshold = 0.999f,
+                                   int permille = 995) {
+    if (!pbr || n_vertices <= 0 || channels <= 0) return false;
+    size_t saturated = 0;
+    for (int v = 0; v < n_vertices; ++v) {
+        bool all_one = true;
+        for (int c = 0; c < channels; ++c) {
+            all_one = all_one && pbr[(size_t) v * channels + c] >= threshold;
+        }
+        saturated += all_one;
+    }
+    return saturated * 1000 >= (size_t) n_vertices * permille;
+}
+
+} // namespace t2pbr
diff --git a/scripts/convert_all.sh b/scripts/convert_all.sh
new file mode 100755
index 0000000..d4f7f98
--- /dev/null
+++ b/scripts/convert_all.sh
@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# Convert every stage-1 geometry checkpoint to GGUF (f16 for the demo, f32 for
+# validation). Run inside the reference container:
+#   docker run --rm -v "$PWD":/work -w /work trellis2-ref bash scripts/convert_all.sh
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT"
+mkdir -p ggufs
+
+T2=models/TRELLIS.2-4B/ckpts
+T1=models/TRELLIS-image-large/ckpts
+PJ=models/TRELLIS.2-4B/pipeline.json
+TPJ=models/TRELLIS.2-4B/texturing_pipeline.json
+
+for ft in 0 1; do
+    suf=$([ "$ft" = 0 ] && echo f32 || echo f16)
+    python convert_dino_to_gguf.py                                       --output ggufs/dino_$suf.gguf      --ftype "$ft"
+    python convert_ss_flow_to_gguf.py   --model $T2/ss_flow_img_dit_1_3B_64_bf16.safetensors            --output ggufs/ss_flow_$suf.gguf   --ftype "$ft"
+    python convert_ss_dec_to_gguf.py    --model $T1/ss_dec_conv3d_16l8_fp16.safetensors                 --output ggufs/ss_dec_$suf.gguf    --ftype "$ft"
+    python convert_slat_flow_to_gguf.py --model $T2/slat_flow_img2shape_dit_1_3B_512_bf16.safetensors  --pipeline-json $PJ --output ggufs/slat_flow_$suf.gguf      --ftype "$ft"
+    python convert_slat_flow_to_gguf.py --model $T2/slat_flow_img2shape_dit_1_3B_1024_bf16.safetensors --pipeline-json $PJ --output ggufs/slat_flow_1024_$suf.gguf --ftype "$ft"
+    python convert_shape_dec_to_gguf.py --model $T2/shape_dec_next_dc_f16c32_fp16.safetensors           --output ggufs/shape_dec_$suf.gguf --ftype "$ft"
+    # PBR texturing stack (shape encoder retained for standalone parity tooling)
+    python convert_tex_dec_to_gguf.py   --model $T2/tex_dec_next_dc_f16c32_fp16.safetensors             --output ggufs/tex_dec_$suf.gguf   --ftype "$ft"
+    python convert_shape_enc_to_gguf.py --model $T2/shape_enc_next_dc_f16c32_fp16.safetensors           --output ggufs/shape_enc_$suf.gguf --ftype "$ft"
+    python convert_tex_flow_to_gguf.py  --model $T2/slat_flow_imgshape2tex_dit_1_3B_512_bf16.safetensors  --texturing-json $TPJ --output ggufs/tex_slat_flow_512_$suf.gguf  --ftype "$ft"
+    python convert_tex_flow_to_gguf.py  --model $T2/slat_flow_imgshape2tex_dit_1_3B_1024_bf16.safetensors --texturing-json $TPJ --output ggufs/tex_slat_flow_1024_$suf.gguf --ftype "$ft"
+done
+
+echo "all GGUFs written:"
+ls -la ggufs/
diff --git a/scripts/demo.sh b/scripts/demo.sh
new file mode 100755
index 0000000..7e1e664
--- /dev/null
+++ b/scripts/demo.sh
@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# Build and launch the demo server (CUDA lib + Go server) in the demo container.
+# The container carries a matching glibc/libstdc++/Go so both the CUDA
+# libtrellis2.so and the Go binary that dlopens it share one runtime — a NixOS
+# host binary won't run inside the CUDA image (different dynamic loader).
+#
+#   scripts/demo.sh            # fine path (needs the shape-SLAT GGUFs)
+#   scripts/demo.sh -coarse    # 64^3 marching-cubes preview only
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT"
+PORT="${PORT:-8742}"
+
+docker build -f docker/Dockerfile.demo -t trellis2-demo docker
+
+docker run --rm -v "$ROOT":/work -w /work -e GOCACHE=/tmp/gocache trellis2-demo bash -c '
+  cmake -B build-cuda-shared -G Ninja -DCMAKE_BUILD_TYPE=Release -DGGML_CUDA=ON \
+        -DCMAKE_CUDA_ARCHITECTURES=120 -DBUILD_SHARED_LIBS=ON >/dev/null 2>&1 &&
+  cmake --build build-cuda-shared -j"$(nproc)" &&
+  cd server && CGO_ENABLED=0 go build -o trellis2-server-linux .'
+
+# Fetch prebuilt f16 GGUFs from the public LocalAI-io repos. Files already present
+# are skipped, so this is a no-op once ggufs/ is populated; it lets fresh demo
+# users skip the separate download_models.sh + convert_all.sh steps.
+scripts/download_ggufs.sh
+
+docker rm -f trellis2-demo-run 2>/dev/null || true
+exec docker run --rm --name trellis2-demo-run --device nvidia.com/gpu=all \
+    -v "$ROOT":/work -w /work/server -p "$PORT":8742 trellis2-demo \
+    ./trellis2-server-linux -lib /work/build-cuda-shared/libtrellis2.so \
+    -ggufs /work/ggufs -store /work/generations -unload-idle -addr :8742 "$@"
diff --git a/scripts/download_ggufs.sh b/scripts/download_ggufs.sh
new file mode 100755
index 0000000..42fb07b
--- /dev/null
+++ b/scripts/download_ggufs.sh
@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Download the prebuilt f16 GGUFs for the demo from the public LocalAI-io repos.
+#
+# This is the fast path for running the demo: it replaces the two-step
+# download_models.sh (safetensors) + convert_all.sh (GGUF conversion) flow with a
+# direct pull of the ready-made f16 GGUFs. Developers who need the f32 validation
+# variants or want to regenerate GGUFs should still use those two scripts.
+#
+# Files land in $GGUFS (default: repo-root ggufs/). Already-present files are
+# skipped, so re-runs are cheap and downloads resume (-C -). No auth needed
+# (public repos); HF_TOKEN is used if set.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+GGUFS="${GGUFS:-$ROOT/ggufs}"
+ORG="${GGUF_ORG:-LocalAI-io}"
+TOKEN="${HF_TOKEN:-}"
+AUTH=()
+[ -n "$TOKEN" ] && AUTH=(-H "Authorization: Bearer $TOKEN")
+
+mkdir -p "$GGUFS"
+
+fetch() { # fetch <repo> <file>
+    local url="https://huggingface.co/$ORG/$1/resolve/main/$2"
+    local dest="$GGUFS/$2"
+    if [ -s "$dest" ]; then echo "have  $dest"; return 0; fi
+    echo "fetch $ORG/$1/$2"
+    curl -sSL --fail -C - "${AUTH[@]}" -o "$dest.part" "$url"
+    mv "$dest.part" "$dest"
+}
+
+T2=TRELLIS.2-4B-GGUF
+T1=TRELLIS-image-large-GGUF
+DINO=dinov3-vitl16-pretrain-lvd1689m-GGUF
+
+fetch "$DINO" dino_f16.gguf
+fetch "$T1"   ss_dec_f16.gguf
+fetch "$T2"   ss_flow_f16.gguf
+fetch "$T2"   slat_flow_f16.gguf
+fetch "$T2"   slat_flow_1024_f16.gguf
+fetch "$T2"   shape_dec_f16.gguf
+fetch "$T2"   shape_enc_f16.gguf
+fetch "$T2"   tex_dec_f16.gguf
+fetch "$T2"   tex_slat_flow_512_f16.gguf
+fetch "$T2"   tex_slat_flow_1024_f16.gguf
+
+echo "all GGUFs present in $GGUFS:"
+du -sh "$GGUFS"
diff --git a/scripts/download_models.sh b/scripts/download_models.sh
new file mode 100755
index 0000000..3b806b9
--- /dev/null
+++ b/scripts/download_models.sh
@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# Download the checkpoints needed for the stage-1 geometry pipeline ("512" path).
+#
+# NOTE on DINOv3: the official facebook/dinov3-vitl16-pretrain-lvd1689m repo is
+# gated behind a license-acceptance click. Until access is granted on your HF
+# account, this script pulls the widely-used ungated mirror
+# camenduru/dinov3-vitl16-pretrain-lvd1689m (byte-identical HF-format export,
+# ships Meta's LICENSE.md). Re-point DINO_REPO at the official repo once you
+# have access.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+MODELS="$ROOT/models"
+TOKEN="${HF_TOKEN:-$(cat ~/.cache/huggingface/token 2>/dev/null || true)}"
+AUTH=()
+[ -n "$TOKEN" ] && AUTH=(-H "Authorization: Bearer $TOKEN")
+
+fetch() { # fetch <repo> <rfile> <dest-subdir>
+    local url="https://huggingface.co/$1/resolve/main/$2"
+    local dest="$MODELS/$3/$2"
+    mkdir -p "$(dirname "$dest")"
+    if [ -s "$dest" ]; then echo "have  $dest"; return 0; fi
+    echo "fetch $1/$2"
+    curl -sSL --fail -C - "${AUTH[@]}" -o "$dest.part" "$url"
+    mv "$dest.part" "$dest"
+}
+
+T2=microsoft/TRELLIS.2-4B
+T1=microsoft/TRELLIS-image-large
+DINO_REPO="${DINO_REPO:-camenduru/dinov3-vitl16-pretrain-lvd1689m}"
+
+fetch $T2 pipeline.json                                          TRELLIS.2-4B
+fetch $T2 ckpts/ss_flow_img_dit_1_3B_64_bf16.json                TRELLIS.2-4B
+fetch $T2 ckpts/ss_flow_img_dit_1_3B_64_bf16.safetensors         TRELLIS.2-4B
+fetch $T2 ckpts/slat_flow_img2shape_dit_1_3B_512_bf16.json       TRELLIS.2-4B
+fetch $T2 ckpts/slat_flow_img2shape_dit_1_3B_512_bf16.safetensors TRELLIS.2-4B
+fetch $T2 ckpts/slat_flow_img2shape_dit_1_3B_1024_bf16.json       TRELLIS.2-4B
+fetch $T2 ckpts/slat_flow_img2shape_dit_1_3B_1024_bf16.safetensors TRELLIS.2-4B
+fetch $T2 ckpts/shape_dec_next_dc_f16c32_fp16.json               TRELLIS.2-4B
+fetch $T2 ckpts/shape_dec_next_dc_f16c32_fp16.safetensors        TRELLIS.2-4B
+# PBR texturing stack: the validated generation path needs the shape encoder,
+# texture decoder, and both texture-SLAT flows.
+fetch $T2 texturing_pipeline.json                                TRELLIS.2-4B
+fetch $T2 ckpts/shape_enc_next_dc_f16c32_fp16.json               TRELLIS.2-4B
+fetch $T2 ckpts/shape_enc_next_dc_f16c32_fp16.safetensors        TRELLIS.2-4B
+fetch $T2 ckpts/tex_dec_next_dc_f16c32_fp16.json                 TRELLIS.2-4B
+fetch $T2 ckpts/tex_dec_next_dc_f16c32_fp16.safetensors          TRELLIS.2-4B
+fetch $T2 ckpts/slat_flow_imgshape2tex_dit_1_3B_512_bf16.json        TRELLIS.2-4B
+fetch $T2 ckpts/slat_flow_imgshape2tex_dit_1_3B_512_bf16.safetensors  TRELLIS.2-4B
+fetch $T2 ckpts/slat_flow_imgshape2tex_dit_1_3B_1024_bf16.json       TRELLIS.2-4B
+fetch $T2 ckpts/slat_flow_imgshape2tex_dit_1_3B_1024_bf16.safetensors TRELLIS.2-4B
+fetch $T1 ckpts/ss_dec_conv3d_16l8_fp16.json                     TRELLIS-image-large
+fetch $T1 ckpts/ss_dec_conv3d_16l8_fp16.safetensors              TRELLIS-image-large
+fetch "$DINO_REPO" config.json               dinov3-vitl16
+fetch "$DINO_REPO" preprocessor_config.json  dinov3-vitl16
+fetch "$DINO_REPO" model.safetensors         dinov3-vitl16
+
+echo "all downloads complete:"
+du -sh "$MODELS"/*
diff --git a/scripts/dump_cascade_reference.py b/scripts/dump_cascade_reference.py
new file mode 100644
index 0000000..dba5590
--- /dev/null
+++ b/scripts/dump_cascade_reference.py
@@ -0,0 +1,239 @@
+#!/usr/bin/env python3
+"""Reference dumps for the 1024_cascade high-resolution geometry stage.
+
+Produces dumps/reference_cascade.gguf with the full HR chain so the C++ port can
+be validated stage by stage:
+
+  cond_512, cond_1024        the two DINOv3 conds (embedded → self-contained test)
+  coords32   [L,4]           32^3 scaffold (from the SS reference latent)
+  lr_noise   [L,32]          LR sampling noise (seed 4321)
+  lr_slat    [L,32]          512-model sampler output, denormalized
+  up_coords  [Nup,4]         decoder.upsample(lr_slat, upsample_times=4) → 512^3
+  hr_coords  [Lhr,4]         quantized+unique → 64^3 (the HR flow scaffold)
+  hr_noise   [Lhr,32]        HR sampling noise (seed 5678)
+  hr_flow_t500_out [Lhr,32]  1024-model flow forward at t=500 on hr_coords
+  hr_slat    [Lhr,32]        1024-model sampler output, denormalized
+  lvl{i}.*, out7, out_coords per-level decode taps at resolution 1024 (→ 1024^3)
+
+The reference is generated with TF32 disabled (ref_common.setup) so the golden
+values are true fp32. Run inside the container (see scripts/refgen.sh).
+"""
+
+import argparse
+import json
+import os
+import struct
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import ref_common  # noqa: E402
+
+ref_common.setup()  # TF32 off + sdpa sparse attention + pure-torch sparse conv
+
+import numpy as np  # noqa: E402
+import torch  # noqa: E402
+import torch.nn.functional as F  # noqa: E402
+
+
+def read_dinodata(path):
+    with open(path, "rb") as f:
+        assert f.read(8) == b"DINOCOND", "bad magic"
+        _, _, ndim = struct.unpack("<III", f.read(12))
+        shape = struct.unpack("<%dI" % ndim, f.read(4 * ndim))
+        arr = np.frombuffer(f.read(), dtype="<f4").reshape(shape)
+    return arr
+
+
+def load_ss_sample_latent(path):
+    with open(path, "rb") as f:
+        assert f.read(8) == b"SSSAMP01", "bad magic"
+        R, cin, lkv, cctx, steps = struct.unpack("<5i", f.read(20))
+        n = cin * R * R * R
+        f.seek(-(n * 4), os.SEEK_END)
+        z = np.frombuffer(f.read(n * 4), dtype="<f4").reshape(1, cin, R, R, R)
+    return torch.from_numpy(z.copy())
+
+
+def load_flow(stem, dev):
+    from safetensors.torch import load_file
+    from trellis2.models.structured_latent_flow import SLatFlowModel
+    with open(stem + ".json") as f:
+        cfg = json.load(f)["args"]
+    cfg.pop("initialization", None)
+    cfg.pop("dtype", None)
+    m = SLatFlowModel(**cfg, dtype="float32")
+    sd = {k: v.float() for k, v in load_file(stem + ".safetensors").items()}
+    missing, unexpected = m.load_state_dict(sd, strict=False)
+    assert not unexpected, unexpected
+    m.convert_to(torch.float32)
+    m.eval().to(dev)
+    return m, cfg
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--models", default=os.path.join(ref_common.MODELS, "TRELLIS.2-4B", "ckpts"))
+    ap.add_argument("--ss-dec", default=os.path.join(ref_common.MODELS, "TRELLIS-image-large",
+                                                     "ckpts", "ss_dec_conv3d_16l8_fp16"))
+    ap.add_argument("--cond-512", default=os.path.join(ref_common.DUMPS, "fixture.dinodata"))
+    ap.add_argument("--cond-1024", default=os.path.join(ref_common.DUMPS, "fixture_1024.dinodata"))
+    ap.add_argument("--ss-latent", default=os.path.join(ref_common.REPO, "tests", "ss_sample_ref.bin"))
+    ap.add_argument("--pipeline-json", default=os.path.join(ref_common.MODELS, "TRELLIS.2-4B", "pipeline.json"))
+    ap.add_argument("--device", default="cuda" if torch.cuda.is_available() else "cpu")
+    ap.add_argument("--t", type=float, default=500.0)
+    ap.add_argument("--lr-seed", type=int, default=4321)
+    ap.add_argument("--hr-seed", type=int, default=5678)
+    ap.add_argument("--lr-resolution", type=int, default=512)
+    ap.add_argument("--resolution", type=int, default=1024)
+    ap.add_argument("--out", default=os.path.join(ref_common.DUMPS, "reference_cascade.gguf"))
+    args = ap.parse_args()
+
+    from safetensors.torch import load_file
+    from trellis2.models.sparse_structure_vae import SparseStructureDecoder
+    from trellis2.models.sc_vaes.fdg_vae import FlexiDualGridVaeDecoder
+    from trellis2.pipelines.samplers import FlowEulerGuidanceIntervalSampler
+    from trellis2.modules import sparse as sp
+
+    dev = torch.device(args.device)
+    caps = {}
+
+    cond_512 = torch.from_numpy(read_dinodata(args.cond_512).copy()).float().to(dev)
+    cond_1024 = torch.from_numpy(read_dinodata(args.cond_1024).copy()).float().to(dev)
+    caps["cond_512"] = cond_512[0]
+    caps["cond_1024"] = cond_1024[0]
+
+    with open(args.pipeline_json) as f:
+        pj = json.load(f)["args"]
+    norm = pj["shape_slat_normalization"]
+    sampler_params = pj["shape_slat_sampler"]["params"]
+    mean = torch.tensor(norm["mean"], device=dev)[None]
+    std = torch.tensor(norm["std"], device=dev)[None]
+    sampler = FlowEulerGuidanceIntervalSampler(sigma_min=1e-5)
+
+    # ── 32^3 scaffold from the SS reference latent ───────────────────────────
+    with open(args.ss_dec + ".json") as f:
+        ss_cfg = json.load(f)["args"]
+    ss_cfg["use_fp16"] = False
+    ss_dec = SparseStructureDecoder(**ss_cfg)
+    ss_dec.load_state_dict({k: v.float() for k, v in load_file(args.ss_dec + ".safetensors").items()})
+    ss_dec.dtype = torch.float32
+    ss_dec.eval().float().to(dev)
+    z_s = load_ss_sample_latent(args.ss_latent).to(dev)
+    with torch.no_grad():
+        occ = ss_dec(z_s) > 0
+    occ = (F.max_pool3d(occ.float(), 2, 2, 0) > 0.5)
+    coords = torch.argwhere(occ)[:, [0, 2, 3, 4]].int().contiguous()
+    L = coords.shape[0]
+    caps["coords32"] = coords.float()
+    print(f"scaffold: {L} voxels at 32^3")
+    del ss_dec
+
+    # ── LR flow: sample with the 512 model + cond_512, denormalize ───────────
+    flow_lr, cfg_lr = load_flow(os.path.join(args.models, "slat_flow_img2shape_dit_1_3B_512_bf16"), dev)
+    g = torch.Generator().manual_seed(args.lr_seed)
+    lr_noise = torch.randn(L, cfg_lr["in_channels"], generator=g).to(dev)
+    caps["lr_noise"] = lr_noise
+    x0 = sp.SparseTensor(feats=lr_noise.clone(), coords=coords.to(dev))
+    with torch.no_grad():
+        lr_slat = sampler.sample(flow_lr, x0, cond=cond_512, neg_cond=torch.zeros_like(cond_512),
+                                 **sampler_params, verbose=True).samples
+    lr_slat = lr_slat * std + mean
+    caps["lr_slat"] = lr_slat.feats
+    print(f"lr_slat: {lr_slat.feats.shape} mean={lr_slat.feats.mean().item():.5f}")
+    del flow_lr
+    if dev.type == "cuda":
+        torch.cuda.empty_cache()
+
+    # ── shape decoder: upsample(×4) → 512^3 candidate coords ─────────────────
+    dstem = os.path.join(args.models, "shape_dec_next_dc_f16c32_fp16")
+    with open(dstem + ".json") as f:
+        dcfg = json.load(f)["args"]
+    dcfg.pop("use_fp16", None)
+    dcfg.pop("resolution", None)
+    dec = FlexiDualGridVaeDecoder(resolution=args.resolution, use_fp16=False, **dcfg)
+    dec.load_state_dict({k: v.float() for k, v in load_file(dstem + ".safetensors").items()})
+    # The decoder runs on CPU: the 1024^3 expansion materializes millions of
+    # voxels through the pure-torch sparse conv and would OOM the 16 GB GPU (and
+    # it is exactly what the C++ port runs on CPU). Flows stay on GPU.
+    dec.eval().float().cpu()
+
+    with torch.no_grad():
+        up_coords = dec.upsample(lr_slat.cpu(), upsample_times=4)   # [Nup, 4] at 512^3
+    caps["up_coords"] = up_coords.float()
+    print(f"upsample: {up_coords.shape[0]} candidate coords at {args.lr_resolution}^3")
+
+    # ── quantize + unique → 64^3 HR scaffold (verbatim pipeline formula) ─────
+    hr_res = args.resolution
+    quant_coords = torch.cat([
+        up_coords[:, :1],
+        ((up_coords[:, 1:] + 0.5) / args.lr_resolution * (hr_res // 16)).int(),
+    ], dim=1)
+    hr_coords = quant_coords.unique(dim=0)
+    Lhr = hr_coords.shape[0]
+    caps["hr_coords"] = hr_coords.float()
+    print(f"hr scaffold: {Lhr} voxels at {hr_res // 16}^3")
+
+    # ── HR flow: forward @ t=500 + full sampler with 1024 model + cond_1024 ──
+    flow_hr, cfg_hr = load_flow(os.path.join(args.models, "slat_flow_img2shape_dit_1_3B_1024_bf16"), dev)
+    g = torch.Generator().manual_seed(args.hr_seed)
+    hr_noise = torch.randn(Lhr, cfg_hr["in_channels"], generator=g).to(dev)
+    caps["hr_noise"] = hr_noise
+    xh = sp.SparseTensor(feats=hr_noise.clone(), coords=hr_coords.to(dev))
+    with torch.no_grad():
+        out = flow_hr(xh, torch.tensor([args.t], device=dev), cond_1024)
+    caps["hr_flow_t500_out"] = out.feats
+    print(f"hr flow t={args.t}: l2={out.feats.norm().item():.4f}")
+
+    xh0 = sp.SparseTensor(feats=hr_noise.clone(), coords=hr_coords.to(dev))
+    with torch.no_grad():
+        hr_slat = sampler.sample(flow_hr, xh0, cond=cond_1024, neg_cond=torch.zeros_like(cond_1024),
+                                 **sampler_params, verbose=True).samples
+    hr_slat = hr_slat * std + mean
+    caps["hr_slat"] = hr_slat.feats
+    print(f"hr_slat: {hr_slat.feats.shape} mean={hr_slat.feats.mean().item():.5f}")
+    del flow_hr
+    if dev.type == "cuda":
+        torch.cuda.empty_cache()
+
+    # ── final decode of the HR slat at resolution 1024, level by level ───────
+    # Only the final 7-channel output is kept: the per-level intermediates are
+    # multiple GB at 1024^3 (and the decoder's level logic is already validated
+    # exactly at the 512 tier). We run the base SparseUnetVaeDecoder forward
+    # manually to get the raw 7 channels — dec(...) would run the FDG mesh
+    # conversion (stubbed o_voxel). Running the decode on CPU is host-RAM heavy.
+    dec.set_resolution(args.resolution)
+    hr_slat_cpu = hr_slat.cpu()
+    with torch.no_grad():
+        h = dec.from_latent(hr_slat_cpu.float())
+        for i, res in enumerate(dec.blocks):
+            for j, block in enumerate(res):
+                if i < len(dec.blocks) - 1 and j == len(res) - 1:
+                    h, _sub = block(h)
+                else:
+                    h = block(h)
+            print(f"decode level {i}: {h.feats.shape[0]} voxels x {h.feats.shape[1]} ch")
+        hn = h.replace(F.layer_norm(h.feats, h.feats.shape[-1:]))
+        out7 = dec.output_layer(hn)
+    caps["out7"] = out7.feats
+    caps["out_coords"] = out7.coords.float()
+    print(f"out7: {out7.feats.shape}")
+
+    import gguf
+    writer = gguf.GGUFWriter(args.out, "reference")
+    manifest = {"shapes": {}, "atol": 2e-3, "rtol": 2e-3,
+                "lr_resolution": args.lr_resolution, "resolution": args.resolution}
+    for name, t in caps.items():
+        a = t.detach().cpu().float().numpy()
+        manifest["shapes"][name] = list(a.shape)
+        writer.add_tensor(name, np.ascontiguousarray(a.reshape(-1), dtype=np.float32))
+    writer.write_header_to_file()
+    writer.write_kv_data_to_file()
+    writer.write_tensors_to_file()
+    writer.close()
+    with open(os.path.join(ref_common.DUMPS, "manifest_cascade.json"), "w") as f:
+        json.dump(manifest, f, indent=1)
+    print(f"wrote {args.out} ({os.path.getsize(args.out):,} bytes), {len(caps)} tensors")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/dump_dino_reference.py b/scripts/dump_dino_reference.py
new file mode 100644
index 0000000..f4236ca
--- /dev/null
+++ b/scripts/dump_dino_reference.py
@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""Dump DINOv3 ViT-L/16 reference activations for the C++ port.
+
+Replicates DinoV3FeatureExtractor exactly (manual embeddings -> rope -> layer
+loop -> affine-free layer_norm; the model's own final layernorm is NOT applied)
+on the preprocessed fixture image, and writes:
+
+  dumps/reference_dino.gguf   input pixels + per-layer taps + final cond
+  dumps/manifest_dino.json    shapes + tolerances
+  dumps/fixture.dinodata      the conditioning tensor for the SS-flow tests
+  dumps/fixture_pre.png       preprocessed (cropped, premultiplied) image
+  dumps/fixture_512.png       the exact 512x512 LANCZOS-resized uint8 image
+
+Run inside the reference container (see scripts/refgen.sh):
+  python scripts/dump_dino_reference.py --image <rgba image> [--device cuda]
+"""
+
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import ref_common  # noqa: E402  (sets sys.path for trellis2, stubs cumesh)
+
+import numpy as np  # noqa: E402
+import torch  # noqa: E402
+import torch.nn.functional as F  # noqa: E402
+from PIL import Image  # noqa: E402
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--image", required=True, help="RGBA input image")
+    ap.add_argument("--model", default=os.path.join(ref_common.MODELS, "dinov3-vitl16"))
+    ap.add_argument("--resolution", type=int, default=512)
+    ap.add_argument("--device", default="cuda" if torch.cuda.is_available() else "cpu")
+    ap.add_argument("--out", default=os.path.join(ref_common.DUMPS, "reference_dino.gguf"))
+    args = ap.parse_args()
+
+    os.makedirs(ref_common.DUMPS, exist_ok=True)
+
+    from transformers import DINOv3ViTModel
+
+    model = DINOv3ViTModel.from_pretrained(args.model)
+    model.eval().float().to(args.device)
+
+    img = Image.open(args.image).convert("RGBA")
+    img.save(os.path.join(ref_common.DUMPS, "fixture_rgba.png"))
+    pre = ref_common.preprocess_rgba(img)
+    pre.save(os.path.join(ref_common.DUMPS, "fixture_pre.png"))
+
+    resized = pre.resize((args.resolution, args.resolution), Image.Resampling.LANCZOS)
+    resized.save(os.path.join(ref_common.DUMPS, "fixture_512.png"))
+
+    x = np.array(resized).astype(np.float32) / 255.0            # HWC
+    x = torch.from_numpy(x).permute(2, 0, 1).unsqueeze(0)       # 1CHW
+    mean = torch.tensor([0.485, 0.456, 0.406]).view(1, 3, 1, 1)
+    std = torch.tensor([0.229, 0.224, 0.225]).view(1, 3, 1, 1)
+    pixel_values = ((x - mean) / std).to(args.device)
+
+    caps = {}
+    caps["img_512_u8"] = torch.from_numpy(np.array(resized).astype(np.float32))
+    caps["pixel_values"] = pixel_values
+
+    # Detail taps inside the first and last layer via forward hooks.
+    detail_layers = {0, len(model.layer) - 1}
+    hooks = []
+
+    def tap(name):
+        def fn(_m, _inp, out):
+            o = out[0] if isinstance(out, tuple) else out
+            caps[name] = o.detach()
+        return fn
+
+    for i in sorted(detail_layers):
+        layer = model.layer[i]
+        for sub in ("norm1", "attention", "layer_scale1", "norm2", "mlp", "layer_scale2"):
+            m = getattr(layer, sub, None)
+            if m is not None:
+                hooks.append(m.register_forward_hook(tap(f"l{i}.{sub}")))
+
+    with torch.no_grad():
+        hidden = model.embeddings(pixel_values, bool_masked_pos=None)
+        caps["embd"] = hidden
+        rope = model.rope_embeddings(pixel_values)
+        if isinstance(rope, (tuple, list)):
+            for j, r in enumerate(rope):
+                caps[f"rope_{j}"] = r
+        else:
+            caps["rope_0"] = rope
+        for i, layer_module in enumerate(model.layer):
+            hidden = layer_module(hidden, position_embeddings=rope)
+            if isinstance(hidden, tuple):
+                hidden = hidden[0]
+            caps[f"l{i}.out"] = hidden
+        cond = F.layer_norm(hidden, hidden.shape[-1:])
+        caps["cond"] = cond
+
+    for h in hooks:
+        h.remove()
+
+    cond_np = cond.cpu().numpy().astype(np.float32)
+    ref_common.write_dinodata(os.path.join(ref_common.DUMPS, "fixture.dinodata"), cond_np)
+    print(f"cond: shape={tuple(cond_np.shape)} mean={cond_np.mean():.6f} "
+          f"min={cond_np.min():.4f} max={cond_np.max():.4f} l2={np.linalg.norm(cond_np):.4f}")
+
+    # Also emit the 1024-resolution conditioning (4101 tokens) that the HR stage
+    # of the 1024 cascade consumes. Same encode path, image_size 1024.
+    resized_hr = pre.resize((1024, 1024), Image.Resampling.LANCZOS)
+    xhr = np.array(resized_hr).astype(np.float32) / 255.0
+    xhr = torch.from_numpy(xhr).permute(2, 0, 1).unsqueeze(0)
+    pv_hr = ((xhr - mean) / std).to(args.device)
+    with torch.no_grad():
+        h = model.embeddings(pv_hr, bool_masked_pos=None)
+        rope_hr = model.rope_embeddings(pv_hr)
+        for layer_module in model.layer:
+            h = layer_module(h, position_embeddings=rope_hr)
+            if isinstance(h, tuple):
+                h = h[0]
+        cond_hr = F.layer_norm(h, h.shape[-1:]).cpu().numpy().astype(np.float32)
+    ref_common.write_dinodata(os.path.join(ref_common.DUMPS, "fixture_1024.dinodata"), cond_hr)
+    print(f"cond_1024: shape={tuple(cond_hr.shape)} l2={np.linalg.norm(cond_hr):.4f}")
+
+    import gguf
+    writer = gguf.GGUFWriter(args.out, "reference")
+    manifest = {"resolution": args.resolution, "atol": 2e-3, "rtol": 2e-3, "shapes": {}}
+    for name, t in caps.items():
+        a = t.detach().cpu().float().numpy()
+        manifest["shapes"][name] = list(a.shape)
+        writer.add_tensor(name, np.ascontiguousarray(a.reshape(-1), dtype=np.float32))
+    writer.write_header_to_file()
+    writer.write_kv_data_to_file()
+    writer.write_tensors_to_file()
+    writer.close()
+
+    with open(os.path.join(ref_common.DUMPS, "manifest_dino.json"), "w") as f:
+        json.dump(manifest, f, indent=1)
+    print(f"wrote {args.out} ({os.path.getsize(args.out):,} bytes), "
+          f"{len(caps)} tensors")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/dump_slat_reference.py b/scripts/dump_slat_reference.py
new file mode 100644
index 0000000..50de027
--- /dev/null
+++ b/scripts/dump_slat_reference.py
@@ -0,0 +1,198 @@
+#!/usr/bin/env python3
+"""Reference dumps for the shape-SLAT stage ("512" pipeline type, geometry only).
+
+Produces dumps/reference_slat.gguf with:
+
+  coords            [L, 4] f32    active voxels at 32^3 (from the SS stage)
+  slat_noise        [L, 32]       fixed sampling noise (seed 4321)
+  flow_t500_out     [L, 32]       SLAT flow forward at t=500 (f32)
+  slat              [L, 32]       full 12-step sampler output, denormalized
+  slat_mean/std     [32]          shape_slat_normalization
+  lvl{i}.in_coords  [L_i, 4]      decoder level i active voxels
+  lvl{i}.pre_up     [L_i, C_i]    features after level i's ConvNeXt blocks
+  lvl{i}.subdiv     [L_i, 8]      subdivision logits of level i's up-block
+  out7              [L_4, 7]      decoder output (pre split/sigmoid)
+  out_coords        [L_4, 4]
+
+The coords come from decoding tests/ss_sample_ref.bin's reference latent, so
+the same scaffold is reproducible from the validated C++ SS stages.
+
+Run inside the container: see scripts/refgen.sh.
+"""
+
+import argparse
+import json
+import os
+import struct
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import ref_common  # noqa: E402
+
+ref_common.setup()  # sdpa sparse attention + pure-torch sparse conv
+
+import numpy as np  # noqa: E402
+import torch  # noqa: E402
+import torch.nn.functional as F  # noqa: E402
+
+
+def load_ss_sample_latent(path):
+    """Read the z_s reference produced by tests/ref_ss_sample.py (SSSAMP01)."""
+    with open(path, "rb") as f:
+        assert f.read(8) == b"SSSAMP01", "bad magic"
+        R, cin, lkv, cctx, steps = struct.unpack("<5i", f.read(20))
+        f.read(4 * 3)  # gs, rescale, rescale_t
+        f.read(8)      # seed
+        n = cin * R * R * R
+        f.seek(-(n * 4), os.SEEK_END)
+        z = np.frombuffer(f.read(n * 4), dtype="<f4").reshape(1, cin, R, R, R)
+    return torch.from_numpy(z.copy())
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--models", default=os.path.join(ref_common.MODELS, "TRELLIS.2-4B", "ckpts"))
+    ap.add_argument("--ss-dec", default=os.path.join(ref_common.MODELS, "TRELLIS-image-large",
+                                                     "ckpts", "ss_dec_conv3d_16l8_fp16"))
+    ap.add_argument("--dinodata", default=os.path.join(ref_common.DUMPS, "fixture.dinodata"))
+    ap.add_argument("--ss-latent", default=os.path.join(ref_common.REPO, "tests", "ss_sample_ref.bin"))
+    ap.add_argument("--pipeline-json", default=os.path.join(ref_common.MODELS, "TRELLIS.2-4B", "pipeline.json"))
+    ap.add_argument("--device", default="cuda" if torch.cuda.is_available() else "cpu")
+    ap.add_argument("--t", type=float, default=500.0)
+    ap.add_argument("--seed", type=int, default=4321)
+    ap.add_argument("--resolution", type=int, default=512)
+    ap.add_argument("--out", default=os.path.join(ref_common.DUMPS, "reference_slat.gguf"))
+    args = ap.parse_args()
+
+    from safetensors.torch import load_file
+    from trellis2.models.sparse_structure_vae import SparseStructureDecoder
+    from trellis2.models.structured_latent_flow import SLatFlowModel
+    from trellis2.models.sc_vaes.fdg_vae import FlexiDualGridVaeDecoder
+    from trellis2.pipelines.samplers import FlowEulerGuidanceIntervalSampler
+    from trellis2.modules import sparse as sp
+
+    dev = torch.device(args.device)
+    caps = {}
+
+    # ── coords from the SS stage reference latent ────────────────────────────
+    with open(args.ss_dec + ".json") as f:
+        ss_cfg = json.load(f)["args"]
+    ss_cfg["use_fp16"] = False
+    ss_dec = SparseStructureDecoder(**ss_cfg)
+    ss_dec.load_state_dict({k: v.float() for k, v in load_file(args.ss_dec + ".safetensors").items()})
+    ss_dec.dtype = torch.float32
+    ss_dec.eval().float().to(dev)
+
+    z_s = load_ss_sample_latent(args.ss_latent).to(dev)
+    with torch.no_grad():
+        occ = ss_dec(z_s) > 0                                   # [1,1,64,64,64]
+    occ = (F.max_pool3d(occ.float(), 2, 2, 0) > 0.5)            # ss_res 32
+    coords = torch.argwhere(occ)[:, [0, 2, 3, 4]].int().contiguous()
+    L = coords.shape[0]
+    print(f"coords: {L} active voxels at 32^3 "
+          f"({100.0 * L / 32**3:.2f}% occupancy)")
+    caps["coords"] = coords.float()
+    del ss_dec
+
+    # ── conditioning ─────────────────────────────────────────────────────────
+    with open(args.dinodata, "rb") as f:
+        assert f.read(8) == b"DINOCOND"
+        _, _, ndim = struct.unpack("<III", f.read(12))
+        shape = struct.unpack("<%dI" % ndim, f.read(4 * ndim))
+        cond_np = np.frombuffer(f.read(), dtype="<f4").reshape(shape)
+    cond = torch.from_numpy(cond_np.copy()).float().to(dev)
+    neg_cond = torch.zeros_like(cond)
+
+    # ── SLAT flow: forward parity point + full sampler ───────────────────────
+    stem = os.path.join(args.models, "slat_flow_img2shape_dit_1_3B_512_bf16")
+    with open(stem + ".json") as f:
+        cfg = json.load(f)["args"]
+    cfg.pop("initialization", None)
+    cfg.pop("dtype", None)
+    flow = SLatFlowModel(**cfg, dtype="float32")
+    sd = {k: v.float() for k, v in load_file(stem + ".safetensors").items()}
+    missing, unexpected = flow.load_state_dict(sd, strict=False)
+    assert not unexpected, unexpected
+    flow.convert_to(torch.float32)
+    flow.eval().to(dev)
+
+    g = torch.Generator().manual_seed(args.seed)
+    noise = torch.randn(L, cfg["in_channels"], generator=g).to(dev)
+    caps["slat_noise"] = noise
+
+    x = sp.SparseTensor(feats=noise.clone(), coords=coords.to(dev))
+    with torch.no_grad():
+        out = flow(x, torch.tensor([args.t], device=dev), cond)
+    caps["flow_t500_out"] = out.feats
+    print(f"flow t={args.t}: out mean={out.feats.mean().item():.6f} "
+          f"l2={out.feats.norm().item():.4f}")
+
+    with open(args.pipeline_json) as f:
+        pj = json.load(f)["args"]
+    norm = pj["shape_slat_normalization"]
+    sampler_params = pj["shape_slat_sampler"]["params"]
+    print("sampler params:", sampler_params)
+
+    sampler = FlowEulerGuidanceIntervalSampler(sigma_min=1e-5)
+    x0 = sp.SparseTensor(feats=noise.clone(), coords=coords.to(dev))
+    with torch.no_grad():
+        slat = sampler.sample(flow, x0, cond=cond, neg_cond=neg_cond,
+                              **sampler_params, verbose=True).samples
+    mean = torch.tensor(norm["mean"], device=dev)[None]
+    std = torch.tensor(norm["std"], device=dev)[None]
+    slat = slat * std + mean
+    caps["slat"] = slat.feats
+    caps["slat_mean"] = mean[0]
+    caps["slat_std"] = std[0]
+    print(f"slat: mean={slat.feats.mean().item():.5f} std={slat.feats.std().item():.5f}")
+    del flow
+    if dev.type == "cuda":
+        torch.cuda.empty_cache()
+
+    # ── FDG decoder, level by level (mirrors SparseUnetVaeDecoder.forward) ──
+    dstem = os.path.join(args.models, "shape_dec_next_dc_f16c32_fp16")
+    with open(dstem + ".json") as f:
+        dcfg = json.load(f)["args"]
+    dcfg.pop("use_fp16", None)
+    dcfg.pop("resolution", None)
+    dec = FlexiDualGridVaeDecoder(resolution=args.resolution, use_fp16=False, **dcfg)
+    dec.load_state_dict({k: v.float() for k, v in load_file(dstem + ".safetensors").items()})
+    dec.eval().float().to(dev)
+
+    with torch.no_grad():
+        h = dec.from_latent(slat.float())
+        for i, res in enumerate(dec.blocks):
+            caps[f"lvl{i}.in_coords"] = h.coords.float()
+            for j, block in enumerate(res):
+                if i < len(dec.blocks) - 1 and j == len(res) - 1:
+                    caps[f"lvl{i}.pre_up"] = h.feats
+                    h, sub = block(h)
+                    caps[f"lvl{i}.subdiv"] = sub.feats
+                else:
+                    h = block(h)
+            print(f"level {i}: {h.feats.shape[0]} voxels x {h.feats.shape[1]} ch")
+        hn = h.replace(F.layer_norm(h.feats, h.feats.shape[-1:]))
+        out7 = dec.output_layer(hn)
+    caps["out7"] = out7.feats
+    caps["out_coords"] = out7.coords.float()
+    print(f"out7: {out7.feats.shape}, offsets mean={torch.sigmoid(out7.feats[:, 0:3]).mean().item():.4f}, "
+          f"intersected frac={(out7.feats[:, 3:6] > 0).float().mean().item():.4f}")
+
+    import gguf
+    writer = gguf.GGUFWriter(args.out, "reference")
+    manifest = {"shapes": {}, "atol": 2e-3, "rtol": 2e-3}
+    for name, t in caps.items():
+        a = t.detach().cpu().float().numpy()
+        manifest["shapes"][name] = list(a.shape)
+        writer.add_tensor(name, np.ascontiguousarray(a.reshape(-1), dtype=np.float32))
+    writer.write_header_to_file()
+    writer.write_kv_data_to_file()
+    writer.write_tensors_to_file()
+    writer.close()
+    with open(os.path.join(ref_common.DUMPS, "manifest_slat.json"), "w") as f:
+        json.dump(manifest, f, indent=1)
+    print(f"wrote {args.out} ({os.path.getsize(args.out):,} bytes), {len(caps)} tensors")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/dump_texture_reference.py b/scripts/dump_texture_reference.py
new file mode 100644
index 0000000..24f9cec
--- /dev/null
+++ b/scripts/dump_texture_reference.py
@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""Reference dumps for the PBR-texture stages, for validating the C++/ggml port.
+
+Produces dumps/reference_texture.gguf with per-stage golden tensors so each C++
+stage validates in isolation (feed identical inputs, compare outputs):
+
+  cond            [T, Cc]     DINOv3 conditioning at texture resolution R
+  enc_vert        [N, 3]      shape-encoder input: dual-vertex offsets  (QEF)
+  enc_inter       [N, 3]      shape-encoder input: intersection flags   (QEF)
+  enc_coords      [N, 4]      active voxels at R (batch-idx 0 + xyz)
+  shape_slat      [Nl, 32]    shape encoder output (mean), the concat_cond
+  shape_coords    [Nl, 4]     latent voxels at R/16
+  tex_noise       [Nl, 32]    fixed sampling noise (seed)
+  tex_flow_t500   [Nl, 32]    tex-flow forward at t=500 (concat_cond, f32)
+  tex_slat        [Nl, 32]    full sampler output, denormalized
+  pbr             [M, 6]      decoded PBR voxels (base_color,metal,rough,alpha), *0.5+0.5
+  pbr_coords      [M, 4]      decoded voxels at R (should equal enc_coords set)
+  shape_slat_mean/std  [32]   shape_slat_normalization (concat_cond in-norm)
+  tex_slat_mean/std    [32]   tex_slat_normalization   (output de-norm)
+
+This dump validates the standalone arbitrary-mesh texturing path, whose encoder
+is fed a reproducible QEF dual grid. Integrated image-to-3D generation instead
+retains the generated shape SLat and replays the shape decoder's subdivisions;
+that wiring is covered by test_slat plus the sparse PBR sampling regression.
+
+Run inside the reference container (real o-voxel), e.g.:
+  docker exec t2tex bash -lc \
+    'cd /work && TRELLIS2_PY=/trellis2 python scripts/dump_texture_reference.py \
+       --mesh /s/mesh_shipped.bin --image dumps/fixture_rgba.png --resolution 512'
+"""
+import argparse, json, os, struct, sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import o_voxel          # noqa: E402  real o-voxel BEFORE ref_common (skips its stub)
+import o_voxel.convert  # noqa: E402
+import ref_common       # noqa: E402
+ref_common.setup()      # sdpa attention + pure-torch sparse conv
+
+import numpy as np      # noqa: E402
+import torch            # noqa: E402
+import torch.nn.functional as F  # noqa: E402
+from PIL import Image   # noqa: E402
+import trimesh          # noqa: E402
+from safetensors.torch import load_file  # noqa: E402
+
+from trellis2.models.sc_vaes.fdg_vae import FlexiDualGridVaeEncoder      # noqa: E402
+from trellis2.models.sc_vaes.sparse_unet_vae import SparseUnetVaeDecoder  # noqa: E402
+from trellis2.models.structured_latent_flow import SLatFlowModel          # noqa: E402
+from trellis2.pipelines.samplers import FlowEulerGuidanceIntervalSampler  # noqa: E402
+from trellis2.pipelines import Trellis2TexturingPipeline                  # noqa: E402
+from trellis2.modules.image_feature_extractor import DinoV3FeatureExtractor  # noqa: E402
+from trellis2.modules import sparse as sp                                 # noqa: E402
+
+
+def load_t2mesh(path):
+    b = open(path, "rb").read()
+    assert b[:8] == b"T2MESH01", b[:8]
+    nv, nt = struct.unpack("<II", b[8:16]); o = 16
+    V = np.frombuffer(b, "<f4", 3 * nv, o).reshape(-1, 3).copy(); o += 12 * nv
+    o += 12 * nv  # skip normals
+    F_ = np.frombuffer(b, "<i4", 3 * nt, o).reshape(-1, 3).copy()
+    return V, F_
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--mesh", required=True)
+    ap.add_argument("--image", required=True)
+    ap.add_argument("--resolution", type=int, default=512, choices=[512, 1024])
+    ap.add_argument("--seed", type=int, default=42)
+    ap.add_argument("--t", type=float, default=500.0)
+    ap.add_argument("--out", default=os.path.join(ref_common.DUMPS, "reference_texture.gguf"))
+    args = ap.parse_args()
+    dev = "cuda"
+    R = args.resolution
+    CK = os.path.join(ref_common.MODELS, "TRELLIS.2-4B", "ckpts")
+    tpa = json.load(open(os.path.join(ref_common.MODELS, "TRELLIS.2-4B", "texturing_pipeline.json")))["args"]
+
+    def load_model(cls, stem, fp32_flags=False, **extra):
+        cfg = json.load(open(os.path.join(CK, stem + ".json")))["args"]
+        if fp32_flags:
+            cfg.pop("use_fp16", None); cfg["use_fp16"] = False
+        m = cls(**{**cfg, **extra})
+        sd = {k: v.float() for k, v in load_file(os.path.join(CK, stem + ".safetensors")).items()}
+        m.load_state_dict(sd)
+        return m.eval().to(dev)
+
+    print(f"loading models (res {R}) ...", flush=True)
+    shape_enc = load_model(FlexiDualGridVaeEncoder, "shape_enc_next_dc_f16c32_fp16", fp32_flags=True)
+    tex_dec = load_model(SparseUnetVaeDecoder, "tex_dec_next_dc_f16c32_fp16", fp32_flags=True)
+    tex_flow = load_model(SLatFlowModel, f"slat_flow_imgshape2tex_dit_1_3B_{R}_bf16", dtype="float32")
+
+    dino = DinoV3FeatureExtractor(os.path.join(ref_common.MODELS, "dinov3-vitl16"), image_size=R)
+    dino.model = dino.model.to(dev).eval()
+
+    sampler = FlowEulerGuidanceIntervalSampler(**tpa["tex_slat_sampler"]["args"])
+    pipe = Trellis2TexturingPipeline(
+        models={"shape_slat_encoder": shape_enc, "tex_slat_decoder": tex_dec,
+                f"tex_slat_flow_model_{R}": tex_flow},
+        tex_slat_sampler=sampler,
+        tex_slat_sampler_params=tpa["tex_slat_sampler"]["params"],
+        shape_slat_normalization=tpa["shape_slat_normalization"],
+        tex_slat_normalization=tpa["tex_slat_normalization"],
+        image_cond_model=dino, rembg_model=None, low_vram=False,
+    )
+    pipe._device = dev
+
+    V, Ftri = load_t2mesh(args.mesh)
+    mesh = trimesh.Trimesh(vertices=V, faces=Ftri, process=False)
+    img = Image.open(args.image).convert("RGBA")
+    print(f"mesh {len(V)} verts / {len(Ftri)} tris; image {img.size}", flush=True)
+
+    caps = {}
+    torch.manual_seed(args.seed)
+    with torch.no_grad():
+        image = pipe.preprocess_image(img)
+        mesh = pipe.preprocess_mesh(mesh)
+        cond = pipe.get_cond([image], R)
+        caps["cond"] = cond["cond"][0]  # [T, Cc]
+
+        # ── shape encoder (QEF dual grid input) ──────────────────────────────
+        vertices = torch.from_numpy(mesh.vertices).float()
+        faces = torch.from_numpy(mesh.faces).long()
+        voxel_indices, dual_vertices, intersected = o_voxel.convert.mesh_to_flexible_dual_grid(
+            vertices.cpu(), faces.cpu(), grid_size=R,
+            aabb=[[-0.5, -0.5, -0.5], [0.5, 0.5, 0.5]],
+            face_weight=1.0, boundary_weight=0.2, regularization_weight=1e-2, timing=True)
+        enc_vert_feats = dual_vertices * R - voxel_indices          # offset in voxel
+        vtx = sp.SparseTensor(
+            feats=enc_vert_feats,
+            coords=torch.cat([torch.zeros_like(voxel_indices[:, 0:1]), voxel_indices], dim=-1)).to(dev)
+        inter = vtx.replace(intersected).to(dev)
+        caps["enc_vert"] = vtx.feats
+        caps["enc_inter"] = inter.feats.float()
+        caps["enc_coords"] = vtx.coords.float()
+        print(f"enc input: {vtx.feats.shape[0]} voxels at {R}^3", flush=True)
+
+        shape_slat = shape_enc(vtx, inter)
+        caps["shape_slat"] = shape_slat.feats
+        caps["shape_coords"] = shape_slat.coords.float()
+        print(f"shape_slat: {shape_slat.feats.shape} coords {shape_slat.coords.shape}", flush=True)
+
+        # ── tex flow: forward parity point + full sampler ────────────────────
+        s_std = torch.tensor(tpa["shape_slat_normalization"]["std"], device=dev)[None]
+        s_mean = torch.tensor(tpa["shape_slat_normalization"]["mean"], device=dev)[None]
+        shape_slat_n = shape_slat.replace((shape_slat.feats - s_mean) / s_std)
+        caps["shape_slat_mean"] = s_mean[0]
+        caps["shape_slat_std"] = s_std[0]
+
+        Nl = shape_slat.coords.shape[0]
+        g = torch.Generator(device=dev).manual_seed(args.seed)
+        noise_feats = torch.randn(Nl, tex_flow.out_channels, generator=g, device=dev)
+        caps["tex_noise"] = noise_feats
+        x0 = shape_slat.replace(noise_feats.clone())
+
+        out = tex_flow(x0, torch.tensor([args.t], device=dev), cond["cond"], concat_cond=shape_slat_n)
+        caps["tex_flow_t500"] = out.feats
+        print(f"tex_flow t={args.t}: mean={out.feats.mean().item():.6f} l2={out.feats.norm().item():.4f}", flush=True)
+
+        slat = sampler.sample(
+            tex_flow, x0, concat_cond=shape_slat_n,
+            cond=cond["cond"], neg_cond=cond["neg_cond"],
+            **tpa["tex_slat_sampler"]["params"], verbose=True).samples
+        t_std = torch.tensor(tpa["tex_slat_normalization"]["std"], device=dev)[None]
+        t_mean = torch.tensor(tpa["tex_slat_normalization"]["mean"], device=dev)[None]
+        slat = slat.replace(slat.feats * t_std + t_mean)
+        caps["tex_slat"] = slat.feats
+        caps["tex_slat_mean"] = t_mean[0]
+        caps["tex_slat_std"] = t_std[0]
+        print(f"tex_slat: mean={slat.feats.mean().item():.5f} std={slat.feats.std().item():.5f}", flush=True)
+
+        # ── tex decoder → PBR voxels ─────────────────────────────────────────
+        pbr = tex_dec(slat) * 0.5 + 0.5
+        caps["pbr"] = pbr.feats
+        caps["pbr_coords"] = pbr.coords.float()
+        print(f"pbr: {pbr.feats.shape} range [{pbr.feats.min():.3f},{pbr.feats.max():.3f}]", flush=True)
+
+        # sanity: the tex decoder should reconstruct exactly the encoder's voxel set
+        enc_set = set(map(tuple, vtx.coords[:, 1:].cpu().numpy().tolist()))
+        pbr_set = set(map(tuple, pbr.coords[:, 1:].cpu().numpy().tolist()))
+        print(f"voxel-set match: pbr=={len(pbr_set)} enc=={len(enc_set)} "
+              f"symdiff={len(enc_set ^ pbr_set)} ({100.0*len(enc_set & pbr_set)/max(1,len(enc_set)):.2f}% common)",
+              flush=True)
+
+    import gguf
+    writer = gguf.GGUFWriter(args.out, "reference")
+    manifest = {"shapes": {}, "atol": 2e-3, "rtol": 2e-3, "resolution": R}
+    for name, t in caps.items():
+        a = t.detach().cpu().float().numpy()
+        manifest["shapes"][name] = list(a.shape)
+        writer.add_tensor(name, np.ascontiguousarray(a.reshape(-1), dtype=np.float32))
+    writer.write_header_to_file(); writer.write_kv_data_to_file(); writer.write_tensors_to_file(); writer.close()
+    with open(os.path.join(ref_common.DUMPS, "manifest_texture.json"), "w") as f:
+        json.dump(manifest, f, indent=1)
+    print(f"wrote {args.out} ({os.path.getsize(args.out):,} bytes), {len(caps)} tensors", flush=True)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/glb_atlas.py b/scripts/glb_atlas.py
new file mode 100644
index 0000000..40460f4
--- /dev/null
+++ b/scripts/glb_atlas.py
@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""Dump a GLB's baseColor + metallicRoughness atlas images side by side, so the
+bake's colour fidelity can be eyeballed without any renderer in the way.
+
+    python3 scripts/glb_atlas.py in.glb [out.png]
+"""
+import sys, numpy as np, trimesh
+from PIL import Image
+
+path = sys.argv[1]; out = sys.argv[2] if len(sys.argv) > 2 else "glb_atlas.png"
+scene = trimesh.load(path, process=False)
+mesh = scene if isinstance(scene, trimesh.Trimesh) else list(scene.geometry.values())[0]
+attrs = getattr(mesh.visual, "vertex_attributes", {})
+if "color" in attrs:
+    color = np.asarray(attrs["color"])
+    print(f"vertex-colour GLB: {len(color):,} COLOR_0 values ({color.dtype}); no UV atlas")
+    sys.exit(0)
+mat = mesh.visual.material
+bc = mat.baseColorTexture.convert("RGB")
+try:
+    mr = mat.metallicRoughnessTexture.convert("RGB")
+except Exception:
+    mr = Image.new("RGB", bc.size)
+W, H = bc.size
+# downscale for a quick look if huge
+scale = 1024 / max(W, H)
+if scale < 1:
+    bc = bc.resize((int(W*scale), int(H*scale)))
+    mr = mr.resize((int(W*scale), int(H*scale)))
+w, h = bc.size
+canvas = Image.new("RGB", (w*2 + 16, h), (30, 30, 30))
+canvas.paste(bc, (0, 0)); canvas.paste(mr, (w + 16, 0))
+canvas.save(out)
+a = np.asarray(bc, np.float64) / 255
+nz = a.reshape(-1, 3); nz = nz[nz.sum(1) > 0.05]
+print(f"atlas {W}x{H}  baseColor mean(nonblack)={nz.mean(0).round(3) if len(nz) else 'n/a'}  "
+      f"filled={len(nz)/(w*h)*100:.0f}%", flush=True)
+print("wrote", out, flush=True)
diff --git a/scripts/headless_smoke.py b/scripts/headless_smoke.py
new file mode 100644
index 0000000..4c44985
--- /dev/null
+++ b/scripts/headless_smoke.py
@@ -0,0 +1,324 @@
+#!/usr/bin/env python3
+"""Headless Chromium smoke checks for the trellis2.cpp demo.
+
+Uses only the Python standard library and Chromium's DevTools protocol so it can
+run on the headless demo host without Playwright/Selenium. It intentionally
+loads a persisted mesh and the showcase, exercising fetch, binary parsing,
+WebGL2 buffer upload, and rendering rather than merely checking the HTML.
+"""
+
+import argparse
+import base64
+import json
+import os
+import secrets
+import socket
+import struct
+import subprocess
+import tempfile
+import time
+import urllib.request
+from pathlib import Path
+from urllib.parse import urlparse
+
+
+class CDP:
+    def __init__(self, url):
+        parsed = urlparse(url)
+        self.sock = socket.create_connection((parsed.hostname, parsed.port), timeout=15)
+        key = base64.b64encode(secrets.token_bytes(16)).decode()
+        request = (
+            f"GET {parsed.path} HTTP/1.1\r\n"
+            f"Host: {parsed.hostname}:{parsed.port}\r\n"
+            "Upgrade: websocket\r\nConnection: Upgrade\r\n"
+            f"Sec-WebSocket-Key: {key}\r\nSec-WebSocket-Version: 13\r\n\r\n"
+        )
+        self.sock.sendall(request.encode())
+        response = b""
+        while b"\r\n\r\n" not in response:
+            response += self.sock.recv(4096)
+        if b" 101 " not in response.split(b"\r\n", 1)[0]:
+            raise RuntimeError(f"WebSocket upgrade failed: {response[:200]!r}")
+        self.next_id = 1
+        self.events = []
+
+    def _send_frame(self, payload):
+        data = payload.encode()
+        mask = secrets.token_bytes(4)
+        n = len(data)
+        header = bytearray([0x81])
+        if n < 126:
+            header.append(0x80 | n)
+        elif n < 65536:
+            header.append(0x80 | 126)
+            header.extend(struct.pack("!H", n))
+        else:
+            header.append(0x80 | 127)
+            header.extend(struct.pack("!Q", n))
+        header.extend(mask)
+        header.extend(bytes(b ^ mask[i % 4] for i, b in enumerate(data)))
+        self.sock.sendall(header)
+
+    def _read_exact(self, n):
+        chunks = []
+        while n:
+            chunk = self.sock.recv(n)
+            if not chunk:
+                raise RuntimeError("DevTools WebSocket closed")
+            chunks.append(chunk)
+            n -= len(chunk)
+        return b"".join(chunks)
+
+    def _recv_frame(self):
+        b0, b1 = self._read_exact(2)
+        opcode, n = b0 & 0x0F, b1 & 0x7F
+        if n == 126:
+            n = struct.unpack("!H", self._read_exact(2))[0]
+        elif n == 127:
+            n = struct.unpack("!Q", self._read_exact(8))[0]
+        masked = bool(b1 & 0x80)
+        mask = self._read_exact(4) if masked else None
+        data = self._read_exact(n)
+        if mask:
+            data = bytes(b ^ mask[i % 4] for i, b in enumerate(data))
+        if opcode == 0x9:  # ping
+            self._send_frame(data.decode(errors="ignore"))
+            return self._recv_frame()
+        if opcode == 0x8:
+            raise RuntimeError("DevTools WebSocket closed")
+        return json.loads(data.decode())
+
+    def call(self, method, params=None, timeout=90):
+        ident = self.next_id
+        self.next_id += 1
+        self._send_frame(json.dumps({"id": ident, "method": method, "params": params or {}}))
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            self.sock.settimeout(max(0.1, deadline - time.monotonic()))
+            message = self._recv_frame()
+            if message.get("id") == ident:
+                if "error" in message:
+                    raise RuntimeError(f"{method}: {message['error']}")
+                return message.get("result", {})
+            self.events.append(message)
+        raise TimeoutError(method)
+
+    def evaluate(self, expression, timeout=90):
+        result = self.call("Runtime.evaluate", {
+            "expression": expression,
+            "awaitPromise": True,
+            "returnByValue": True,
+            "userGesture": True,
+        }, timeout)
+        value = result.get("result", {})
+        if "exceptionDetails" in result:
+            raise RuntimeError(result["exceptionDetails"])
+        return value.get("value")
+
+
+def wait_json(url, timeout=15):
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            with urllib.request.urlopen(url, timeout=1) as response:
+                return json.load(response)
+        except Exception:
+            time.sleep(0.1)
+    raise TimeoutError(url)
+
+
+def screenshot(cdp, path):
+    encoded = cdp.call("Page.captureScreenshot", {
+        "format": "png", "captureBeyondViewport": False,
+    }, timeout=30)["data"]
+    path.write_bytes(base64.b64decode(encoded))
+
+
+def navigate(cdp, url, timeout=30):
+    cdp.call("Page.navigate", {"url": url}, timeout=timeout)
+    expected = urlparse(url).path or "/"
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            state = cdp.evaluate("({path: location.pathname, ready: document.readyState})", timeout=2)
+            if state and state["path"] == expected and state["ready"] == "complete":
+                return
+        except Exception:
+            pass
+        time.sleep(0.1)
+    raise TimeoutError(f"navigation to {url}")
+
+
+def browser_errors(events):
+    errors = []
+    for event in events:
+        method, params = event.get("method"), event.get("params", {})
+        if method == "Runtime.exceptionThrown":
+            detail = params.get("exceptionDetails", {})
+            errors.append(detail.get("text", "JavaScript exception"))
+        elif method == "Log.entryAdded":
+            entry = params.get("entry", {})
+            if entry.get("level") in ("error", "warning"):
+                location = f" ({entry['url']})" if entry.get("url") else ""
+                errors.append(f"{entry.get('level')}: {entry.get('text', '')}{location}")
+        elif method == "Runtime.consoleAPICalled" and params.get("type") == "error":
+            args = params.get("args", [])
+            errors.append("console: " + " ".join(str(a.get("value", a.get("description", ""))) for a in args))
+    return errors
+
+
+MAIN_CHECK = r"""
+(async () => {
+  const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+  for (let i = 0; i < 100 && (!history || !history.length); i++) await sleep(100);
+  if (!history.length) throw new Error('no persisted generations in history');
+  // Prefer the oldest retained asset: it is stable across new generations and
+  // avoids coupling this reusable smoke test to a particular server/job ID.
+  const preferred = history[history.length - 1];
+  await viewGeneration(preferred.id);
+  await sleep(1200);
+  await new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+  const mesh = originalExportMesh;
+  const pbr = mesh && mesh.pbr;
+  const range = pbr ? {min: Array(6).fill(Infinity), max: Array(6).fill(-Infinity)} : null;
+  if (pbr) {
+    const stride = Math.max(6, Math.floor((pbr.length / 6) / 50000) * 6);
+    for (let i = 0; i < pbr.length; i += stride) {
+      for (let c = 0; c < 6; c++) {
+        range.min[c] = Math.min(range.min[c], pbr[i + c]);
+        range.max[c] = Math.max(range.max[c], pbr[i + c]);
+      }
+    }
+  }
+  const canvas = document.getElementById('gl');
+  const gl = canvas.getContext('webgl2');
+  const pixel = new Uint8Array(4);
+  gl.readPixels(canvas.width >> 1, canvas.height >> 1, 1, 1, gl.RGBA, gl.UNSIGNED_BYTE, pixel);
+  return {
+    path: location.pathname, title: document.title,
+    historyCount: history.length, selected: preferred.id,
+    status: document.getElementById('status').textContent,
+    meshInfo: document.getElementById('meshinfo').textContent,
+    mesh: mesh ? {vertices: mesh.nv, triangles: mesh.nt, textured: mesh.textured} : null,
+    pbrRange: range, webgl2: !!gl, glError: gl.getError(), centerPixel: [...pixel],
+    canvas: {width: canvas.width, height: canvas.height,
+             cssWidth: canvas.clientWidth, cssHeight: canvas.clientHeight},
+    liveSteps: {text: document.getElementById('tsteps').textContent,
+                pressed: document.getElementById('tsteps').getAttribute('aria-pressed'),
+                keyframesDisabled: document.getElementById('tkf').disabled},
+    exportEnabled: !document.getElementById('dglb').disabled,
+    regenerateEnabled: !document.getElementById('regen').disabled,
+  };
+})()
+"""
+
+
+SHOWCASE_CHECK = r"""
+(async () => {
+  const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+  for (let i = 0; i < 600; i++) {
+    if (typeof showcaseAssets !== 'undefined' && history.length && showcaseAssets.length === history.length) break;
+    await sleep(100);
+  }
+  await sleep(1800);
+  await new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+  const canvas = document.getElementById('gl');
+  const gl = canvas.getContext('webgl2');
+  const display = selector => getComputedStyle(document.querySelector(selector)).display;
+  const pixel = new Uint8Array(4);
+  gl.readPixels(canvas.width >> 1, canvas.height >> 1, 1, 1, gl.RGBA, gl.UNSIGNED_BYTE, pixel);
+  return {
+    path: location.pathname, title: document.title,
+    historyCount: history.length,
+    loadedAssets: typeof showcaseAssets === 'undefined' ? -1 : showcaseAssets.length,
+    running: typeof showcaseRunning === 'undefined' ? false : showcaseRunning,
+    label: document.getElementById('showcaselabel').textContent,
+    sourceClass: document.getElementById('showcasesource').className,
+    chrome: {header: display('header'), side: display('#side'), timeline: display('#timeline')},
+    webgl2: !!gl, glError: gl.getError(), centerPixel: [...pixel],
+    canvas: {width: canvas.width, height: canvas.height,
+             cssWidth: canvas.clientWidth, cssHeight: canvas.clientHeight},
+  };
+})()
+"""
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--url", default="http://127.0.0.1:8742")
+    parser.add_argument("--chromium", default="chromium")
+    parser.add_argument("--output", default="/tmp/trellis2-headless")
+    args = parser.parse_args()
+    output = Path(args.output)
+    output.mkdir(parents=True, exist_ok=True)
+
+    with tempfile.TemporaryDirectory(prefix="trellis2-chrome-") as profile:
+        command = [
+            args.chromium, "--headless=new", "--no-sandbox", "--disable-dev-shm-usage",
+            "--enable-webgl", "--use-angle=swiftshader", "--enable-unsafe-swiftshader",
+            "--remote-debugging-port=0", "--remote-allow-origins=*",
+            f"--user-data-dir={profile}", "--window-size=1280,900", "about:blank",
+        ]
+        browser = subprocess.Popen(command, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE)
+        try:
+            port_file = Path(profile) / "DevToolsActivePort"
+            deadline = time.monotonic() + 15
+            while not port_file.exists() and time.monotonic() < deadline:
+                if browser.poll() is not None:
+                    raise RuntimeError(browser.stderr.read().decode(errors="replace"))
+                time.sleep(0.1)
+            port = int(port_file.read_text().splitlines()[0])
+            targets = wait_json(f"http://127.0.0.1:{port}/json/list")
+            page = next(t for t in targets if t["type"] == "page")
+            cdp = CDP(page["webSocketDebuggerUrl"])
+            for method in ("Page.enable", "Runtime.enable", "Log.enable"):
+                cdp.call(method)
+
+            results = {}
+            navigate(cdp, args.url.rstrip("/") + "/")
+            results["main"] = cdp.evaluate(MAIN_CHECK, timeout=120)
+            screenshot(cdp, output / "main.png")
+
+            navigate(cdp, args.url.rstrip("/") + "/showcase")
+            results["showcase"] = cdp.evaluate(SHOWCASE_CHECK, timeout=180)
+            screenshot(cdp, output / "showcase.png")
+            results["browserErrors"] = browser_errors(cdp.events)
+            results["screenshots"] = [str(output / "main.png"), str(output / "showcase.png")]
+            failures = []
+            main_result, showcase_result = results["main"], results["showcase"]
+            if not main_result["webgl2"] or main_result["glError"] != 0:
+                failures.append("main page WebGL2 failure")
+            if not main_result["mesh"]["textured"] or not main_result["pbrRange"]:
+                failures.append("main page did not load PBR data")
+            elif max(main_result["pbrRange"]["max"][c] - main_result["pbrRange"]["min"][c]
+                     for c in range(3)) < 0.1:
+                failures.append("main page base colour is effectively constant")
+            if main_result["status"] != "done":
+                failures.append(f"main page status is {main_result['status']!r}")
+            if main_result["liveSteps"] != {
+                    "text": "live steps: off", "pressed": "false", "keyframesDisabled": True}:
+                failures.append(f"live steps did not default clearly off: {main_result['liveSteps']!r}")
+            if showcase_result["loadedAssets"] != showcase_result["historyCount"]:
+                failures.append("showcase did not load every persisted asset")
+            if not showcase_result["webgl2"] or showcase_result["glError"] != 0:
+                failures.append("showcase WebGL2 failure")
+            if any(value != "none" for value in showcase_result["chrome"].values()):
+                failures.append("showcase page chrome is visible")
+            significant_errors = [e for e in results["browserErrors"] if "favicon.ico" not in e]
+            if significant_errors:
+                failures.extend(significant_errors)
+            results["failures"] = failures
+            results["passed"] = not failures
+            print(json.dumps(results, indent=2))
+            if failures:
+                raise SystemExit(1)
+        finally:
+            browser.terminate()
+            try:
+                browser.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                browser.kill()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/hf/TRELLIS-image-large-GGUF/LICENSE b/scripts/hf/TRELLIS-image-large-GGUF/LICENSE
new file mode 100644
index 0000000..22aed37
--- /dev/null
+++ b/scripts/hf/TRELLIS-image-large-GGUF/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Microsoft Corporation.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/scripts/hf/TRELLIS-image-large-GGUF/README.md b/scripts/hf/TRELLIS-image-large-GGUF/README.md
new file mode 100644
index 0000000..2be9c70
--- /dev/null
+++ b/scripts/hf/TRELLIS-image-large-GGUF/README.md
@@ -0,0 +1,41 @@
+---
+license: mit
+base_model: microsoft/TRELLIS-image-large
+tags:
+  - gguf
+  - trellis
+  - image-to-3d
+  - ggml
+pipeline_tag: image-to-3d
+---
+
+# TRELLIS-image-large — GGUF (f16)
+
+GGUF (`f16`) conversion of the sparse-structure decoder from
+[microsoft/TRELLIS-image-large](https://huggingface.co/microsoft/TRELLIS-image-large) for
+the **[trellis2cpp](https://github.com/localai-org/trellis2cpp)** /
+[ggml](https://github.com/ggml-org/ggml) runtime.
+
+The TRELLIS.2 geometry pipeline reuses this TRELLIS-1 sparse-structure decoder to turn the
+sparse-structure flow output into a 64³ voxel scaffold.
+
+## Files
+
+| File | Pipeline stage | Source safetensors |
+|---|---|---|
+| `ss_dec_f16.gguf` | Sparse-structure decoder → 64³ voxel scaffold | `ss_dec_conv3d_16l8_fp16` |
+
+The rest of the TRELLIS.2 pipeline is published at
+[TRELLIS.2-4B-GGUF](https://huggingface.co/LocalAI-io/TRELLIS.2-4B-GGUF) and
+[dinov3-vitl16-pretrain-lvd1689m-GGUF](https://huggingface.co/LocalAI-io/dinov3-vitl16-pretrain-lvd1689m-GGUF).
+
+## Conversion
+
+Converted from the upstream `fp16` safetensors to GGUF `f16` (ggml ftype 1) with
+`convert_ss_dec_to_gguf.py` in the trellis2cpp project. Format conversion only.
+
+## License
+
+MIT, inherited from
+[microsoft/TRELLIS-image-large](https://huggingface.co/microsoft/TRELLIS-image-large).
+See [`LICENSE`](LICENSE). Copyright (c) Microsoft Corporation.
diff --git a/scripts/hf/TRELLIS.2-4B-GGUF/LICENSE b/scripts/hf/TRELLIS.2-4B-GGUF/LICENSE
new file mode 100644
index 0000000..22aed37
--- /dev/null
+++ b/scripts/hf/TRELLIS.2-4B-GGUF/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Microsoft Corporation.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/scripts/hf/TRELLIS.2-4B-GGUF/README.md b/scripts/hf/TRELLIS.2-4B-GGUF/README.md
new file mode 100644
index 0000000..96e04d6
--- /dev/null
+++ b/scripts/hf/TRELLIS.2-4B-GGUF/README.md
@@ -0,0 +1,48 @@
+---
+license: mit
+base_model: microsoft/TRELLIS.2-4B
+tags:
+  - gguf
+  - trellis
+  - image-to-3d
+  - ggml
+pipeline_tag: image-to-3d
+---
+
+# TRELLIS.2-4B — GGUF (f16)
+
+GGUF (`f16`) conversions of [microsoft/TRELLIS.2-4B](https://huggingface.co/microsoft/TRELLIS.2-4B)
+for the **[trellis2cpp](https://github.com/localai-org/trellis2cpp)** /
+[ggml](https://github.com/ggml-org/ggml) runtime — a CUDA-free, PyTorch-free C++ port of
+the TRELLIS.2 image-to-3D pipeline. Load these directly; no safetensors conversion or
+Python is needed at inference.
+
+## Files
+
+| File | Pipeline stage | Source safetensors |
+|---|---|---|
+| `ss_flow_f16.gguf` | Sparse-structure flow (64³ occupancy) | `ss_flow_img_dit_1_3B_64_bf16` |
+| `slat_flow_f16.gguf` | Shape-SLAT flow, 512 fine | `slat_flow_img2shape_dit_1_3B_512_bf16` |
+| `slat_flow_1024_f16.gguf` | Shape-SLAT flow, 1024 cascade | `slat_flow_img2shape_dit_1_3B_1024_bf16` |
+| `shape_dec_f16.gguf` | Shape decoder → dual-grid fields | `shape_dec_next_dc_f16c32_fp16` |
+| `shape_enc_f16.gguf` | Shape encoder (re-encode for texture flow) | `shape_enc_next_dc_f16c32_fp16` |
+| `tex_dec_f16.gguf` | PBR texture decoder | `tex_dec_next_dc_f16c32_fp16` |
+| `tex_slat_flow_512_f16.gguf` | Texture-SLAT flow, 512 | `slat_flow_imgshape2tex_dit_1_3B_512_bf16` |
+| `tex_slat_flow_1024_f16.gguf` | Texture-SLAT flow, 1024 | `slat_flow_imgshape2tex_dit_1_3B_1024_bf16` |
+
+The image conditioning encoder (DINOv3) and the sparse-structure decoder are published
+separately:
+[dinov3-vitl16-pretrain-lvd1689m-GGUF](https://huggingface.co/LocalAI-io/dinov3-vitl16-pretrain-lvd1689m-GGUF)
+and
+[TRELLIS-image-large-GGUF](https://huggingface.co/LocalAI-io/TRELLIS-image-large-GGUF).
+
+## Conversion
+
+Converted from the upstream `bf16`/`fp16` safetensors to GGUF `f16` (ggml ftype 1) with
+the `convert_*_to_gguf.py` scripts in the trellis2cpp project. No weights were retrained
+or modified — this is a format conversion only.
+
+## License
+
+MIT, inherited from [microsoft/TRELLIS.2-4B](https://huggingface.co/microsoft/TRELLIS.2-4B).
+See [`LICENSE`](LICENSE). Copyright (c) Microsoft Corporation.
diff --git a/scripts/hf/dinov3-vitl16-pretrain-lvd1689m-GGUF/LICENSE b/scripts/hf/dinov3-vitl16-pretrain-lvd1689m-GGUF/LICENSE
new file mode 100644
index 0000000..f531b1e
--- /dev/null
+++ b/scripts/hf/dinov3-vitl16-pretrain-lvd1689m-GGUF/LICENSE
@@ -0,0 +1,66 @@
+# DINOv3 License
+
+*Last Updated: August 19, 2025*
+
+**“Agreement”** means the terms and conditions for use, reproduction, distribution and modification of the DINO Materials set forth herein.
+
+**“DINO Materials”** means, collectively, Documentation and the models, software and algorithms, including machine-learning model code, trained model weights, inference-enabling code, training-enabling code, fine-tuning enabling code, and other elements of the foregoing distributed by Meta and made available under this Agreement.
+
+**“Documentation”** means the specifications, manuals and documentation accompanying
+DINO Materials distributed by Meta.
+
+**“Licensee”** or **“you”** means you, or your employer or any other person or entity (if you are entering into this Agreement on such person or entity’s behalf), of the age required under applicable laws, rules or regulations to provide legal consent and that has legal authority to bind your employer or such other person or entity if you are entering in this Agreement on their behalf.
+
+**“Meta”** or **“we”** means Meta Platforms Ireland Limited (if you are located in or, if you are an entity, your principal place of business is in the EEA or Switzerland) or Meta Platforms, Inc. (if you are located outside of the EEA or Switzerland).
+
+**“Sanctions”** means any economic or trade sanctions or restrictions administered or enforced by the United States (including the Office of Foreign Assets Control of the U.S. Department of the Treasury (“OFAC”), the U.S. Department of State and the U.S. Department of Commerce), the United Nations, the European Union, or the United Kingdom.
+
+**“Trade Controls”** means any of the following: Sanctions and applicable export and import controls.
+
+By clicking “I Accept” below or by using or distributing any portion or element of the DINO Materials, you agree to be bound by this Agreement.
+
+## 1. License Rights and Redistribution.
+
+a. <ins>Grant of Rights</ins>. You are granted a non-exclusive, worldwide, non-transferable and royalty-free limited license under Meta’s intellectual property or other rights owned by Meta embodied in the DINO Materials to use, reproduce, distribute, copy, create derivative works of, and make modifications to the DINO Materials.
+
+b. <ins>Redistribution and Use</ins>.
+
+i. Distribution of DINO Materials, and any derivative works thereof, are subject to the terms of this Agreement. If you distribute or make the DINO Materials, or any derivative works thereof, available to a third party, you may only do so under the terms of this Agreement and you shall provide a copy of this Agreement with any such DINO Materials.
+
+ii.  If you submit for publication the results of research you perform on, using, or otherwise in connection with DINO Materials, you must acknowledge the use of DINO Materials in your publication.
+
+iii. Your use of the DINO Materials must comply with applicable laws and regulations, including Trade Control Laws and applicable privacy and data protection laws.
+
+iv. Your use of the DINO Materials will not involve or encourage others to reverse engineer, decompile or discover the underlying components of the DINO Materials.
+
+v. You are not the target of Trade Controls and your use of DINO Materials must comply with Trade Controls. You agree not to use, or permit others to use, DINO Materials for any activities subject to the International Traffic in Arms Regulations (ITAR) or end uses prohibited by Trade Controls, including those related to military or warfare purposes, nuclear industries or applications, espionage, or the development or use of guns or illegal weapons.
+
+## 2. User Support.
+
+Your use of the DINO Materials is done at your own discretion; Meta does not process any information nor provide any service in relation to such use.  Meta is under no obligation to provide any support services for the DINO Materials. Any support provided is “as is”, “with all faults”, and without warranty of any kind.
+
+## 3. Disclaimer of Warranty.
+
+UNLESS REQUIRED BY APPLICABLE LAW, THE DINO MATERIALS AND ANY OUTPUT AND RESULTS THEREFROM ARE PROVIDED ON AN “AS IS” BASIS, WITHOUT WARRANTIES OF ANY KIND, AND META DISCLAIMS ALL WARRANTIES OF ANY KIND, BOTH EXPRESS AND IMPLIED, INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. YOU ARE SOLELY RESPONSIBLE FOR DETERMINING THE APPROPRIATENESS OF USING OR REDISTRIBUTING THE DINO MATERIALS AND ASSUME ANY RISKS ASSOCIATED WITH YOUR USE OF THE DINO MATERIALS AND ANY OUTPUT AND RESULTS.
+
+## 4. Limitation of Liability.
+
+IN NO EVENT WILL META OR ITS AFFILIATES BE LIABLE UNDER ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, TORT, NEGLIGENCE, PRODUCTS LIABILITY, OR OTHERWISE, ARISING OUT OF THIS AGREEMENT, FOR ANY LOST PROFITS OR ANY DIRECT OR INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL, EXEMPLARY OR PUNITIVE DAMAGES, EVEN IF META OR ITS AFFILIATES HAVE BEEN ADVISED OF THE POSSIBILITY OF ANY OF THE FOREGOING.
+
+## 5. Intellectual Property.
+
+a. Subject to Meta’s ownership of DINO Materials and derivatives made by or for Meta, with respect to any derivative works and modifications of the DINO Materials that are made by you, as between you and Meta, you are and will be the owner of such derivative works and modifications.
+
+b. If you institute litigation or other proceedings against Meta or any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the DINO Materials, outputs or results, or any portion of any of the foregoing, constitutes infringement of intellectual property or other rights owned or licensable by you, then any licenses granted to you under this Agreement shall terminate as of the date such litigation or claim is filed or instituted. You will indemnify and hold harmless Meta from and against any claim by any third party arising out of or related to your use or distribution of the DINO Materials.
+
+## 6. Term and Termination.
+
+The term of this Agreement will commence upon your acceptance of this Agreement or access to the DINO Materials and will continue in full force and effect until terminated in accordance with the terms and conditions herein. Meta may terminate this Agreement if you are in breach of any term or condition of this Agreement. Upon termination of this Agreement, you shall delete and cease use of the DINO Materials. Sections 3, 4 and 7 shall survive the termination of this Agreement.
+
+## 7. Governing Law and Jurisdiction.
+
+This Agreement will be governed and construed under the laws of the State of California without regard to choice of law principles, and the UN Convention on Contracts for the International Sale of Goods does not apply to this Agreement. The courts of California shall have exclusive jurisdiction of any dispute arising out of this Agreement.
+
+## 8. Modifications and Amendments.
+
+Meta may modify this Agreement from time to time; provided that they are similar in spirit to the current version of the Agreement, but may differ in detail to address new problems or concerns. All such changes will be effective immediately. Your continued use of the DINO Materials after any modification to this Agreement constitutes your agreement to such modification. Except as provided in this Agreement, no modification or addition to any provision of this Agreement will be binding unless it is in writing and signed by an authorized representative of both you and Meta.
diff --git a/scripts/hf/dinov3-vitl16-pretrain-lvd1689m-GGUF/README.md b/scripts/hf/dinov3-vitl16-pretrain-lvd1689m-GGUF/README.md
new file mode 100644
index 0000000..089f50a
--- /dev/null
+++ b/scripts/hf/dinov3-vitl16-pretrain-lvd1689m-GGUF/README.md
@@ -0,0 +1,56 @@
+---
+license: other
+license_name: dinov3-license
+license_link: LICENSE
+base_model: facebook/dinov3-vitl16-pretrain-lvd1689m
+tags:
+  - gguf
+  - dinov3
+  - vision-encoder
+  - ggml
+---
+
+# DINOv3 ViT-L/16 (lvd1689m) — GGUF (f16)
+
+**Built with DINOv3.**
+
+GGUF (`f16`) conversion of the DINOv3 ViT-L/16 (`lvd1689m`) vision encoder for the
+**[trellis2cpp](https://github.com/localai-org/trellis2cpp)** /
+[ggml](https://github.com/ggml-org/ggml) runtime, where it produces the image conditioning
+features for the TRELLIS.2 image-to-3D pipeline.
+
+The weights derive from Meta's
+[facebook/dinov3-vitl16-pretrain-lvd1689m](https://huggingface.co/facebook/dinov3-vitl16-pretrain-lvd1689m)
+(obtained via the ungated
+[camenduru](https://huggingface.co/camenduru/dinov3-vitl16-pretrain-lvd1689m) mirror) and
+are redistributed under Meta's **DINOv3 License**, a full copy of which is included as
+[`LICENSE`](LICENSE). Your use of these weights is subject to that Agreement.
+
+The source `model.safetensors` is **byte-identical to the official Meta release** —
+verified SHA256 `dcb2e45127cccbf1601e5f42fef165eea275c8e5213197e8dcf3f48822718179`
+(1,212,559,808 bytes), matching `facebook/dinov3-vitl16-pretrain-lvd1689m` exactly.
+
+## Files
+
+| File | Pipeline stage | Source |
+|---|---|---|
+| `dino_f16.gguf` | Image conditioning encoder (DINOv3 ViT-L/16) | `model.safetensors` |
+
+## Conversion
+
+Converted from the upstream safetensors to GGUF `f16` (ggml ftype 1) with
+`convert_dino_to_gguf.py` in the trellis2cpp project. No weights were retrained or
+modified — this is a format conversion only.
+
+## License & attribution
+
+Meta **DINOv3 License** — see [`LICENSE`](LICENSE). This model is **Built with DINOv3**.
+DINOv3 is © Meta Platforms, Inc. Redistribution of these weights (or derivatives) must
+provide a copy of the Agreement and prominently display "Built with DINOv3"; downstream
+use is bound by the Agreement's terms (including its acceptable-use and trade-control
+provisions).
+
+## Companion models
+
+- [TRELLIS.2-4B-GGUF](https://huggingface.co/LocalAI-io/TRELLIS.2-4B-GGUF)
+- [TRELLIS-image-large-GGUF](https://huggingface.co/LocalAI-io/TRELLIS-image-large-GGUF)
diff --git a/scripts/ref_common.py b/scripts/ref_common.py
new file mode 100644
index 0000000..7101187
--- /dev/null
+++ b/scripts/ref_common.py
@@ -0,0 +1,320 @@
+"""Shared plumbing for the PyTorch reference dumps.
+
+The reference environment is deliberately stock PyTorch (docker/Dockerfile.ref):
+none of the custom CUDA extensions (flash-attn, FlexGEMM, cumesh, o-voxel) are
+installed. This module makes the trellis2 package importable and usable in that
+environment:
+
+  * stubs out `cumesh` (only needed by Mesh postprocess methods we don't call
+    while dumping activations),
+  * replaces the sparse attention dispatcher with a plain-SDPA implementation
+    (mathematically identical for the var-len batch-1 case we validate),
+  * registers a pure-PyTorch submanifold sparse-conv backend under the name
+    'none' (gather + GEMM per kernel offset — slow, but it runs anywhere and
+    doubles as the executable spec for the C++ implementation).
+
+Import this before importing anything from `trellis2`.
+"""
+
+import os
+import sys
+import types
+
+TRELLIS2_PY = os.environ.get("TRELLIS2_PY", "/trellis2")
+if TRELLIS2_PY not in sys.path:
+    sys.path.insert(0, TRELLIS2_PY)
+
+os.environ.setdefault("ATTN_BACKEND", "sdpa")
+os.environ.setdefault("SPARSE_CONV_BACKEND", "none")
+# The sparse attention config only accepts xformers/flash_attn/flash_attn_3;
+# we leave it alone and monkeypatch the dispatcher below instead.
+
+# --- cumesh stub (postprocess-only dependency of representations.mesh.base) ---
+if "cumesh" not in sys.modules:
+    stub = types.ModuleType("cumesh")
+
+    class _CuMeshStub:
+        def __init__(self, *_a, **_k):
+            raise RuntimeError("cumesh is stubbed out in the reference container")
+
+    stub.CuMesh = _CuMeshStub
+    sys.modules["cumesh"] = stub
+
+# --- o_voxel stub (CUDA hashmap mesher; we dump the decoder's raw 7-channel
+# --- output and do mesh comparison with scripts/ref_dual_grid.py instead) ---
+if "o_voxel" not in sys.modules:
+    ovx = types.ModuleType("o_voxel")
+    ovx_convert = types.ModuleType("o_voxel.convert")
+
+    def flexible_dual_grid_to_mesh(*_a, **_k):
+        raise RuntimeError("o_voxel is stubbed out in the reference container")
+
+    ovx_convert.flexible_dual_grid_to_mesh = flexible_dual_grid_to_mesh
+    ovx.convert = ovx_convert
+    sys.modules["o_voxel"] = ovx
+    sys.modules["o_voxel.convert"] = ovx_convert
+
+# --- flex_gemm stub (CUDA kernels; representations.mesh.base imports
+# --- grid_sample_3d for texture baking, unused on the geometry path) ---
+if "flex_gemm" not in sys.modules:
+    fg = types.ModuleType("flex_gemm")
+    fg_ops = types.ModuleType("flex_gemm.ops")
+    fg_gs = types.ModuleType("flex_gemm.ops.grid_sample")
+    fg_sp = types.ModuleType("flex_gemm.ops.spconv")
+
+    def _fg_unavailable(*_a, **_k):
+        raise RuntimeError("flex_gemm is stubbed out in the reference container")
+
+    fg_gs.grid_sample_3d = _fg_unavailable
+    fg_sp.sparse_submanifold_conv3d = _fg_unavailable
+    fg_ops.grid_sample = fg_gs
+    fg_ops.spconv = fg_sp
+    fg.ops = fg_ops
+    sys.modules["flex_gemm"] = fg
+    sys.modules["flex_gemm.ops"] = fg_ops
+    sys.modules["flex_gemm.ops.grid_sample"] = fg_gs
+    sys.modules["flex_gemm.ops.spconv"] = fg_sp
+
+
+def _install_sdpa_sparse_attention():
+    """Replace trellis2's sparse attention with a dense-SDPA equivalent."""
+    import torch
+    import torch.nn.functional as F
+    from trellis2.modules.sparse.attention import full_attn
+    from trellis2.modules.sparse import VarLenTensor
+
+    def sdpa_varlen(q, k, v, q_seqlen, kv_seqlen):
+        # q: [Tq, H, C], k/v: [Tkv, H, C] concatenated over batch. Query-chunked
+        # so the [H, chunk, L] score matrix stays bounded — the math SDPA backend
+        # (forced for true fp32) would otherwise OOM at the cascade's HR token
+        # counts. Chunking queries is mathematically exact (each query's softmax
+        # is independent), so the golden values are unchanged.
+        CHUNK = 2048
+        out = torch.empty_like(q)
+        qo = ko = 0
+        for ql, kl in zip(q_seqlen, kv_seqlen):
+            ks = k[ko:ko + kl].transpose(0, 1).unsqueeze(0)  # [1,H,kl,C]
+            vs = v[ko:ko + kl].transpose(0, 1).unsqueeze(0)
+            for s in range(0, ql, CHUNK):
+                e = min(s + CHUNK, ql)
+                qs = q[qo + s:qo + e].transpose(0, 1).unsqueeze(0)  # [1,H,chunk,C]
+                o = F.scaled_dot_product_attention(qs, ks, vs)
+                out[qo + s:qo + e] = o.squeeze(0).transpose(0, 1)
+            qo += ql
+            ko += kl
+        return out
+
+    def sparse_sdpa(*args, **kwargs):
+        num = len(args) + len(kwargs)
+        if num == 1:
+            qkv = args[0] if args else kwargs["qkv"]
+            assert isinstance(qkv, VarLenTensor)
+            q_seqlen = [qkv.layout[i].stop - qkv.layout[i].start for i in range(qkv.shape[0])]
+            q, k, v = qkv.feats.unbind(dim=1)  # [T,3,H,C] -> 3x[T,H,C]
+            out = sdpa_varlen(q, k, v, q_seqlen, q_seqlen)
+            return qkv.replace(out)
+        if num == 2:
+            q = args[0] if len(args) > 0 else kwargs["q"]
+            kv = args[1] if len(args) > 1 else kwargs["kv"]
+            s = q if isinstance(q, VarLenTensor) else None
+            if isinstance(q, VarLenTensor):
+                q_seqlen = [q.layout[i].stop - q.layout[i].start for i in range(q.shape[0])]
+                qf = q.feats
+            else:
+                N, L = q.shape[:2]
+                q_seqlen = [L] * N
+                qf = q.reshape(N * L, *q.shape[2:])
+            if isinstance(kv, VarLenTensor):
+                kv_seqlen = [kv.layout[i].stop - kv.layout[i].start for i in range(kv.shape[0])]
+                kvf = kv.feats
+            else:
+                N, L = kv.shape[:2]
+                kv_seqlen = [L] * N
+                kvf = kv.reshape(N * L, *kv.shape[2:])
+            k, v = kvf.unbind(dim=1)
+            out = sdpa_varlen(qf, k, v, q_seqlen, kv_seqlen)
+            if s is not None:
+                return s.replace(out)
+            N = len(q_seqlen)
+            return out.reshape(N, q_seqlen[0], *out.shape[1:])
+        if num == 3:
+            q = args[0] if len(args) > 0 else kwargs["q"]
+            k = args[1] if len(args) > 1 else kwargs["k"]
+            v = args[2] if len(args) > 2 else kwargs["v"]
+            s = q if isinstance(q, VarLenTensor) else None
+            if isinstance(q, VarLenTensor):
+                q_seqlen = [q.layout[i].stop - q.layout[i].start for i in range(q.shape[0])]
+                qf = q.feats
+            else:
+                N, L = q.shape[:2]
+                q_seqlen = [L] * N
+                qf = q.reshape(N * L, *q.shape[2:])
+            if isinstance(k, VarLenTensor):
+                kv_seqlen = [k.layout[i].stop - k.layout[i].start for i in range(k.shape[0])]
+                kf, vf = k.feats, v.feats
+            else:
+                N, L = k.shape[:2]
+                kv_seqlen = [L] * N
+                kf = k.reshape(N * L, *k.shape[2:])
+                vf = v.reshape(N * L, *v.shape[2:])
+            out = sdpa_varlen(qf, kf, vf, q_seqlen, kv_seqlen)
+            if s is not None:
+                return s.replace(out)
+            N = len(q_seqlen)
+            return out.reshape(N, q_seqlen[0], *out.shape[1:])
+        raise AssertionError("bad arg count")
+
+    full_attn.sparse_scaled_dot_product_attention = sparse_sdpa
+    # modules.py imported the symbol by value; patch it there too.
+    from trellis2.modules.sparse.attention import modules as attn_modules
+    attn_modules.sparse_scaled_dot_product_attention = sparse_sdpa
+
+
+def _install_torch_sparse_conv():
+    """Register a pure-PyTorch submanifold conv backend as 'none'."""
+    import math
+    import torch
+    import torch.nn as nn
+
+    from trellis2.modules.sparse.conv import conv as conv_dispatch
+
+    mod = types.ModuleType("trellis2.modules.sparse.conv.conv_none")
+
+    def sparse_conv3d_init(self, in_channels, out_channels, kernel_size,
+                           stride=1, dilation=1, padding=None, bias=True,
+                           indice_key=None):
+        assert stride == 1 and padding is None, "submanifold only"
+        self.in_channels = in_channels
+        self.out_channels = out_channels
+        ks = tuple(kernel_size) if isinstance(kernel_size, (list, tuple)) else (kernel_size,) * 3
+        self.kernel_size = ks
+        self.stride = (1, 1, 1)
+        self.dilation = tuple(dilation) if isinstance(dilation, (list, tuple)) else (dilation,) * 3
+        # flex_gemm weight layout: (Co, Kd, Kh, Kw, Ci)
+        self.weight = nn.Parameter(torch.empty(out_channels, *ks, in_channels))
+        if bias:
+            self.bias = nn.Parameter(torch.zeros(out_channels))
+        else:
+            self.register_parameter("bias", None)
+        nn.init.kaiming_uniform_(self.weight, a=math.sqrt(5))
+
+    def _coord_key(coords, spatial_shape):
+        # coords: [N,4] int (b,x,y,z) -> int64 linear key
+        b, x, y, z = coords.unbind(-1)
+        sx, sy, sz = spatial_shape
+        return ((b.long() * sx + x.long()) * sy + y.long()) * sz + z.long()
+
+    def sparse_conv3d_forward(self, x):
+        coords = x.coords
+        feats = x.feats
+        n = feats.shape[0]
+        spatial = tuple(x.spatial_shape)
+        keys = _coord_key(coords, spatial)
+        order = torch.argsort(keys)
+        keys_sorted = keys[order]
+
+        Co, Kd, Kh, Kw, Ci = self.weight.shape
+        w = self.weight
+        out = feats.new_zeros(n, Co)
+        if self.bias is not None:
+            out += self.bias.to(out.dtype)
+        rd, rh, rw = Kd // 2, Kh // 2, Kw // 2
+        dd, dh, dw = self.dilation
+        for kd in range(Kd):
+            for kh in range(Kh):
+                for kw in range(Kw):
+                    off = coords.new_tensor([0, (kd - rd) * dd, (kh - rh) * dh, (kw - rw) * dw])
+                    ncoords = coords + off
+                    inb = ((ncoords[:, 1] >= 0) & (ncoords[:, 1] < spatial[0]) &
+                           (ncoords[:, 2] >= 0) & (ncoords[:, 2] < spatial[1]) &
+                           (ncoords[:, 3] >= 0) & (ncoords[:, 3] < spatial[2]))
+                    nkeys = _coord_key(ncoords, spatial)
+                    pos = torch.searchsorted(keys_sorted, nkeys)
+                    pos_c = pos.clamp(max=n - 1)
+                    hit = inb & (keys_sorted[pos_c] == nkeys)
+                    src = order[pos_c[hit]]
+                    # out[i] += feats[neighbor(i, offset)] @ w[:, kd, kh, kw, :]^T
+                    contrib = feats[src] @ w[:, kd, kh, kw, :].to(feats.dtype).t()
+                    out[hit] += contrib
+        return x.replace(out)
+
+    def sparse_inverse_conv3d_init(self, *a, **k):
+        raise NotImplementedError
+
+    def sparse_inverse_conv3d_forward(self, x):
+        raise NotImplementedError
+
+    mod.sparse_conv3d_init = sparse_conv3d_init
+    mod.sparse_conv3d_forward = sparse_conv3d_forward
+    mod.sparse_inverse_conv3d_init = sparse_inverse_conv3d_init
+    mod.sparse_inverse_conv3d_forward = sparse_inverse_conv3d_forward
+    conv_dispatch._backends["none"] = mod
+    from trellis2.modules import sparse as sp
+    sp.config.CONV = "none"
+
+
+def _force_true_fp32():
+    """Make CUDA math bit-comparable to a real fp32 reference.
+
+    PyTorch's default CUDA matmul/attention uses TF32 (≈10-bit mantissa) and
+    flash/mem-efficient SDPA kernels that accumulate in reduced precision —
+    that shows up as ~1e-3 relative error versus a true fp32 (or ggml-CPU)
+    forward, which would otherwise masquerade as a port bug. Force full-width
+    fp32 so the golden dumps are the real reference regardless of --device.
+    """
+    import torch
+    torch.backends.cuda.matmul.allow_tf32 = False
+    torch.backends.cudnn.allow_tf32 = False
+    if hasattr(torch.backends.cuda, "enable_flash_sdp"):
+        torch.backends.cuda.enable_flash_sdp(False)
+        torch.backends.cuda.enable_mem_efficient_sdp(False)
+        torch.backends.cuda.enable_math_sdp(True)
+
+
+def setup():
+    _force_true_fp32()
+    _install_sdpa_sparse_attention()
+    _install_torch_sparse_conv()
+
+
+REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+MODELS = os.path.join(REPO, "models")
+DUMPS = os.path.join(REPO, "dumps")
+
+
+def write_dinodata(path, arr):
+    """.dinodata: DINOCOND | u32 version | u32 dtype(0=f32) | u32 ndim | dims | f32 payload"""
+    import struct
+    import numpy as np
+    arr = np.ascontiguousarray(arr, dtype="<f4")
+    with open(path, "wb") as f:
+        f.write(b"DINOCOND")
+        f.write(struct.pack("<III", 1, 0, arr.ndim))
+        f.write(struct.pack("<%dI" % arr.ndim, *arr.shape))
+        f.write(arr.tobytes())
+
+
+def preprocess_rgba(img):
+    """pipeline.preprocess_image for an RGBA input (no rembg): downscale to
+    <=1024, alpha bbox square crop, premultiply onto black. Returns RGB PIL."""
+    import numpy as np
+    from PIL import Image
+
+    assert img.mode == "RGBA", "fixture must have an alpha channel"
+    max_size = max(img.size)
+    scale = min(1, 1024 / max_size)
+    if scale < 1:
+        img = img.resize((int(img.width * scale), int(img.height * scale)),
+                         Image.Resampling.LANCZOS)
+    out = np.array(img)
+    alpha = out[:, :, 3]
+    bbox = np.argwhere(alpha > 0.8 * 255)
+    bbox = np.min(bbox[:, 1]), np.min(bbox[:, 0]), np.max(bbox[:, 1]), np.max(bbox[:, 0])
+    center = (bbox[0] + bbox[2]) / 2, (bbox[1] + bbox[3]) / 2
+    size = max(bbox[2] - bbox[0], bbox[3] - bbox[1])
+    size = int(size * 1)
+    bbox = center[0] - size // 2, center[1] - size // 2, center[0] + size // 2, center[1] + size // 2
+    img = img.crop(bbox)
+    out = np.array(img).astype(np.float32) / 255
+    out = out[:, :, :3] * out[:, :, 3:4]
+    return Image.fromarray((out * 255).astype(np.uint8))
diff --git a/scripts/ref_texture.py b/scripts/ref_texture.py
new file mode 100644
index 0000000..ef64eed
--- /dev/null
+++ b/scripts/ref_texture.py
@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""
+Reference PBR texturing, end-to-end, on OUR generated mesh -- the golden target
+the C++/ggml texture port validates against, and a quick eyeball of the texture
+NN stages.
+
+Runs the real Trellis2TexturingPipeline NN stages (shape encoder -> tex SLAT
+flow -> tex decoder) with sparse ops monkeypatched to pure torch (ref_common),
+so it needs NO custom CUDA kernels except o-voxel's CPU mesh->dual-grid.
+
+For the eyeball we skip the CUDA-only UV bake (nvdiffrast/cumesh/flexgemm) and
+instead trilinear-sample the decoded 6-channel PBR voxels at each mesh vertex
+(base_color / metallic / roughness), then dump a coloured mesh to render.
+
+  python scripts/ref_texture.py --mesh <T2MESH01.bin> --image <rgba.png> \
+      --resolution 512 --out dumps/tex_vcolor.bin
+"""
+import argparse, json, os, struct, sys
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import o_voxel  # noqa: E402  (import the REAL o-voxel BEFORE ref_common so its
+import o_voxel.convert          # stub guard skips it; we need mesh_to_flexible_dual_grid)
+import ref_common  # noqa: E402
+ref_common.setup()
+
+import numpy as np  # noqa: E402
+import torch  # noqa: E402
+from PIL import Image  # noqa: E402
+import trimesh  # noqa: E402
+
+from safetensors.torch import load_file  # noqa: E402
+from trellis2.models.sc_vaes.fdg_vae import FlexiDualGridVaeEncoder  # noqa: E402
+from trellis2.models.sc_vaes.sparse_unet_vae import SparseUnetVaeDecoder  # noqa: E402
+from trellis2.models.structured_latent_flow import SLatFlowModel  # noqa: E402
+from trellis2.pipelines.samplers import FlowEulerGuidanceIntervalSampler  # noqa: E402
+from trellis2.pipelines import Trellis2TexturingPipeline  # noqa: E402
+from trellis2.modules.image_feature_extractor import DinoV3FeatureExtractor  # noqa: E402
+
+
+def load_t2mesh(path):
+    b = open(path, "rb").read()
+    assert b[:8] == b"T2MESH01", b[:8]
+    nv, nt = struct.unpack("<II", b[8:16]); o = 16
+    V = np.frombuffer(b, "<f4", 3 * nv, o).reshape(-1, 3).copy(); o += 12 * nv
+    o += 12 * nv  # skip normals
+    F = np.frombuffer(b, "<i4", 3 * nt, o).reshape(-1, 3).copy()
+    return V, F
+
+
+def trilinear_sample_sparse(feats, coords_xyz, query_vox):
+    """feats [M,C], coords_xyz [M,3] int voxel coords, query_vox [Q,3] float.
+    Returns (sampled [Q,C], weight [Q]) trilinear over present voxels."""
+    dev = feats.device
+    MULT = 4096
+    enc = lambda c: (c[:, 0].long() * MULT + c[:, 1].long()) * MULT + c[:, 2].long()
+    ck = enc(coords_xyz)
+    order = torch.argsort(ck)
+    ck_s = ck[order]; f_s = feats[order]
+    base = torch.floor(query_vox)
+    frac = query_vox - base
+    out = torch.zeros(query_vox.shape[0], feats.shape[1], device=dev)
+    wsum = torch.zeros(query_vox.shape[0], device=dev)
+    for dx in (0, 1):
+        for dy in (0, 1):
+            for dz in (0, 1):
+                corner = base + torch.tensor([dx, dy, dz], device=dev, dtype=base.dtype)
+                w = (frac[:, 0] if dx else 1 - frac[:, 0]) * \
+                    (frac[:, 1] if dy else 1 - frac[:, 1]) * \
+                    (frac[:, 2] if dz else 1 - frac[:, 2])
+                cck = enc(corner)
+                pos = torch.searchsorted(ck_s, cck).clamp(max=ck_s.shape[0] - 1)
+                found = (ck_s[pos] == cck)
+                out += (w * found)[:, None] * f_s[pos]
+                wsum += w * found
+    return out / wsum.clamp(min=1e-6)[:, None], wsum
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--mesh", required=True)
+    ap.add_argument("--image", required=True)
+    ap.add_argument("--resolution", type=int, default=512, choices=[512, 1024])
+    ap.add_argument("--seed", type=int, default=42)
+    ap.add_argument("--out", default=os.path.join(ref_common.DUMPS, "tex_vcolor.bin"))
+    args = ap.parse_args()
+    dev = "cuda"
+    CK = os.path.join(ref_common.MODELS, "TRELLIS.2-4B", "ckpts")
+    tpa = json.load(open(os.path.join(ref_common.MODELS, "TRELLIS.2-4B", "texturing_pipeline.json")))["args"]
+
+    def load_model(cls, stem, **extra):
+        cfg = json.load(open(os.path.join(CK, stem + ".json")))["args"]
+        m = cls(**{**cfg, **extra})
+        sd = {k: v.float() for k, v in load_file(os.path.join(CK, stem + ".safetensors")).items()}
+        m.load_state_dict(sd)
+        return m.eval().to(dev)
+
+    R = args.resolution
+    print(f"loading models (res {R}) ...", flush=True)
+    shape_enc = load_model(FlexiDualGridVaeEncoder, "shape_enc_next_dc_f16c32_fp16")
+    tex_dec = load_model(SparseUnetVaeDecoder, "tex_dec_next_dc_f16c32_fp16")
+    tex_flow = load_model(SLatFlowModel, f"slat_flow_imgshape2tex_dit_1_3B_{R}_bf16", dtype="float32")
+
+    dino = DinoV3FeatureExtractor(os.path.join(ref_common.MODELS, "dinov3-vitl16"), image_size=R)
+    dino.model = dino.model.to(dev).eval()
+
+    sampler = FlowEulerGuidanceIntervalSampler(**tpa["tex_slat_sampler"]["args"])
+    pipe = Trellis2TexturingPipeline(
+        models={"shape_slat_encoder": shape_enc, "tex_slat_decoder": tex_dec,
+                f"tex_slat_flow_model_{R}": tex_flow},
+        tex_slat_sampler=sampler,
+        tex_slat_sampler_params=tpa["tex_slat_sampler"]["params"],
+        shape_slat_normalization=tpa["shape_slat_normalization"],
+        tex_slat_normalization=tpa["tex_slat_normalization"],
+        image_cond_model=dino, rembg_model=None, low_vram=False,
+    )
+    pipe._device = dev
+
+    V, F = load_t2mesh(args.mesh)
+    mesh = trimesh.Trimesh(vertices=V, faces=F, process=False)
+    img = Image.open(args.image).convert("RGBA")
+    print(f"mesh {len(V)} verts / {len(F)} tris; image {img.size}", flush=True)
+
+    torch.manual_seed(args.seed)
+    with torch.no_grad():
+        image = pipe.preprocess_image(img)
+        mesh = pipe.preprocess_mesh(mesh)
+        cond = pipe.get_cond([image], R)
+        print("encoding shape SLAT (o-voxel dual grid + shape encoder) ...", flush=True)
+        shape_slat = pipe.encode_shape_slat(mesh, R)
+        print(f"shape_slat: {shape_slat.feats.shape} coords {shape_slat.coords.shape}", flush=True)
+        print("sampling tex SLAT (flow, concat_cond) ...", flush=True)
+        tex_slat = pipe.sample_tex_slat(cond, tex_flow, shape_slat)
+        print("decoding tex SLAT -> PBR voxels ...", flush=True)
+        pbr = pipe.decode_tex_slat(tex_slat)   # SparseTensor, 6ch, already *0.5+0.5
+        print(f"pbr voxels: {pbr.feats.shape} coords {pbr.coords.shape} "
+              f"range [{pbr.feats.min():.3f},{pbr.feats.max():.3f}]", flush=True)
+
+        # per-vertex trilinear sample of the PBR voxels (mesh is now normalized to [-.5,.5])
+        Vt = torch.from_numpy(mesh.vertices).float().to(dev)
+        qvox = (Vt + 0.5) * R
+        feats = pbr.feats.float()
+        coords_xyz = pbr.coords[:, 1:].to(dev)
+        vals, w = trilinear_sample_sparse(feats, coords_xyz, qvox)
+        vals = vals.clamp(0, 1).cpu().numpy()
+        hit = (w > 1e-4).float().mean().item()
+        print(f"per-vertex sample hit-rate {hit*100:.1f}%", flush=True)
+
+    base_color = vals[:, 0:3]
+    metallic = vals[:, 3:4]; roughness = vals[:, 4:5]
+    Vout = mesh.vertices.astype("<f4")
+    Fout = mesh.faces.astype("<i4")
+    with open(args.out, "wb") as f:
+        f.write(b"T2VCOL01")
+        f.write(struct.pack("<II", len(Vout), len(Fout)))
+        f.write(Vout.tobytes())
+        f.write(base_color.astype("<f4").tobytes())
+        f.write(np.concatenate([metallic, roughness], 1).astype("<f4").tobytes())
+        f.write(Fout.tobytes())
+    print(f"wrote {args.out}  (verts+rgb+metal/rough+tris)", flush=True)
+    print(f"base_color mean {base_color.mean(0)}  metallic {metallic.mean():.3f}  rough {roughness.mean():.3f}", flush=True)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/refgen.sh b/scripts/refgen.sh
new file mode 100755
index 0000000..b88d57b
--- /dev/null
+++ b/scripts/refgen.sh
@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# Regenerate all PyTorch reference dumps inside the reference container.
+# Usage: scripts/refgen.sh [fixture-image]
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+TRELLIS2_PY_HOST="${TRELLIS2_PY_HOST:-/home/rich/python/TRELLIS.2}"
+FIXTURE="${1:-/trellis2/assets/example_image/0a34fae7ba57cb8870df5325b9c30ea474def1b0913c19c596655b85a79fdee4.webp}"
+
+run() {
+    docker run --rm --device nvidia.com/gpu=all \
+        -v "$ROOT":/work -v "$TRELLIS2_PY_HOST":/trellis2 \
+        -e PYTHONPATH=/trellis2 -e TRELLIS2_PY=/trellis2 \
+        -e ATTN_BACKEND=sdpa -e SPARSE_CONV_BACKEND=none \
+        -e HF_HUB_OFFLINE=1 \
+        -w /work trellis2-ref "$@"
+}
+
+mkdir -p "$ROOT/dumps"
+run python scripts/dump_dino_reference.py --image "$FIXTURE"
+run python tests/ref_ss_flow.py                 # CPU (true fp32 golden)
+run python tests/ref_ss_sample.py --device cuda
+run python tests/ref_ss_dec.py --device cuda
+run python scripts/dump_slat_reference.py --device cuda  # TF32 disabled in ref_common
+run python scripts/dump_cascade_reference.py --device cuda  # 1024 HR stage
+echo "reference dumps regenerated:"
+ls -la "$ROOT/dumps" "$ROOT"/tests/*.bin
diff --git a/scripts/render_glb.py b/scripts/render_glb.py
new file mode 100644
index 0000000..86fada8
--- /dev/null
+++ b/scripts/render_glb.py
@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+"""Load a GLB and render it three ways from vertex colour or a baked UV atlas.
+Also prints structural stats (a sanity check that the glTF is well-formed).
+
+    python3 scripts/render_glb.py in.glb [out.png]
+
+Runs anywhere with trimesh + numpy + Pillow (e.g. the t2tex container).
+"""
+import sys, numpy as np, trimesh
+from PIL import Image
+
+path = sys.argv[1]; out = sys.argv[2] if len(sys.argv) > 2 else "glb_render.png"
+scene = trimesh.load(path, process=False)
+mesh = scene if isinstance(scene, trimesh.Trimesh) else list(scene.geometry.values())[0]
+
+V = np.asarray(mesh.vertices, np.float64)
+F = np.asarray(mesh.faces, np.int64)
+visual_attrs = getattr(mesh.visual, "vertex_attributes", {})
+if "color" in visual_attrs:
+    raw = np.asarray(visual_attrs["color"])
+    scale = np.iinfo(raw.dtype).max if np.issubdtype(raw.dtype, np.integer) else 1.0
+    base_v = np.asarray(raw[:, :3], np.float64) / scale
+    # glTF COLOR_0 is already linear.
+    base_linear_v = np.clip(base_v, 0, 1)
+    custom = getattr(mesh, "vertex_attributes", {})
+    if "_METALLIC_ROUGHNESS" in custom:
+        mr = np.asarray(custom["_METALLIC_ROUGHNESS"])
+        mr_scale = np.iinfo(mr.dtype).max if np.issubdtype(mr.dtype, np.integer) else 1.0
+        metal_v = np.asarray(mr[:, 0], np.float64) / mr_scale
+        rough_v = np.asarray(mr[:, 1], np.float64) / mr_scale
+    else:
+        metal_v = np.zeros(len(V)); rough_v = np.full(len(V), 0.6)
+    print(f"GLB: {len(V):,} verts  {len(F):,} faces  COLOR_0 {raw.dtype}  "
+          f"custom metalRough={'yes' if '_METALLIC_ROUGHNESS' in custom else 'no'}", flush=True)
+else:
+    uv = np.asarray(mesh.visual.uv, np.float64)
+    mat = mesh.visual.material
+    base_img = np.asarray(mat.baseColorTexture.convert("RGB"), np.float64) / 255.0
+    try:
+        mr_img = np.asarray(mat.metallicRoughnessTexture.convert("RGB"), np.float64) / 255.0
+    except Exception:
+        mr_img = None
+    TH, TW = base_img.shape[:2]
+    def sample(img, u, v):
+        x = np.clip((u % 1.0) * (TW - 1), 0, TW - 1).astype(np.int32)
+        y = np.clip((v % 1.0) * (TH - 1), 0, TH - 1).astype(np.int32)
+        return img[y, x]
+    base_v = sample(base_img, uv[:, 0], uv[:, 1])
+    base_linear_v = np.clip(base_v, 0, 1) ** 2.2
+    if mr_img is not None:
+        rough_v = sample(mr_img, uv[:, 0], uv[:, 1])[:, 1]
+        metal_v = sample(mr_img, uv[:, 0], uv[:, 1])[:, 2]
+    else:
+        rough_v = np.full(len(V), 0.6); metal_v = np.zeros(len(V))
+    print(f"GLB: {len(V):,} verts  {len(F):,} faces  uv[{uv.min():.3f},{uv.max():.3f}]  "
+          f"baseColor {base_img.shape}  metalRough {None if mr_img is None else mr_img.shape}", flush=True)
+
+N = np.zeros_like(V)
+fn = np.cross(V[F[:, 1]] - V[F[:, 0]], V[F[:, 2]] - V[F[:, 0]])
+for k in range(3): np.add.at(N, F[:, k], fn)
+N /= np.linalg.norm(N, axis=1, keepdims=True) + 1e-9
+
+SS = 2; W = H = 720 * SS
+c = (V.max(0) + V.min(0)) / 2; Vc = V - c; Vc *= 0.92 / np.abs(Vc).max()
+LC = [(np.array([.32, .55, .77]), np.array([1., .96, .88]), .85),
+      (np.array([-.65, .20, .45]), np.array([.70, .80, 1.]), .45),
+      (np.array([.10, -.75, .35]), np.array([.85, .85, .90]), .25)]
+
+
+def Rmat(el, az):
+    a, e = np.radians(az), np.radians(el)
+    Ry = np.array([[np.cos(a), 0, np.sin(a)], [0, 1, 0], [-np.sin(a), 0, np.cos(a)]])
+    Rx = np.array([[1, 0, 0], [0, np.cos(e), -np.sin(e)], [0, np.sin(e), np.cos(e)]])
+    return Rx @ Ry
+
+
+def render(el, az):
+    r = Rmat(el, az); P = Vc @ r.T; Nr = N @ r.T
+    Nr /= np.linalg.norm(Nr, axis=1, keepdims=True) + 1e-9
+    sx = ((P[:, 0]*.5+.5)*(W-1)).astype(np.int32); sy = ((.5-P[:, 1]*.5)*(H-1)).astype(np.int32)
+    z = P[:, 2]
+    view = np.array([0., 0., 1.]); nv_ = np.abs(Nr @ view)
+    F0 = 0.04*(1-metal_v)[:, None] + base_linear_v*metal_v[:, None]
+    Fr = F0 + (1-F0)*((1-nv_)[:, None]**5)
+    shin = 6.0 + 214.0*np.clip(1-rough_v, 0, 1)**1.5
+    sn = (shin+2.0)/(2*np.pi)
+    diffuse = np.zeros_like(base_v); specular = np.zeros_like(base_v)
+    for Ld, Lc, w in LC:
+        l = Ld/np.linalg.norm(Ld); ndl = np.abs(Nr @ l)
+        diffuse += Lc[None]*w*ndl[:, None]
+        h = l+view; h = h/np.linalg.norm(h); nh = np.abs(Nr @ h)
+        specular += Lc[None]*w*(nh[:, None]**shin[:, None])*sn[:, None]*ndl[:, None]
+    albedo = base_linear_v*(1-metal_v)[:, None]
+    hemi = np.abs(N[:, 1])*0.5+0.5
+    amb = (1-hemi)[:, None]*np.array([.20, .19, .22]) + hemi[:, None]*np.array([.55, .58, .66])
+    col = np.clip(albedo*(amb*0.55 + diffuse*0.75) + specular*Fr + Fr*0.25, 0, 1)
+    img = np.ones((H, W, 3))
+    idx = np.argsort(z); sxi, syi, coli = sx[idx], sy[idx], col[idx]
+    for dx in range(SS+1):
+        for dy in range(SS+1):
+            xx = sxi+dx; yy = syi+dy
+            m = (xx >= 0) & (xx < W) & (yy >= 0) & (yy < H)
+            img[yy[m], xx[m]] = coli[m]
+    return (img**(1/2.2)*255).reshape(H//SS, SS, W//SS, SS, 3).mean((1, 3)).astype(np.uint8)
+
+
+row = np.concatenate([render(12, 25), render(12, 150), render(65, 20)], 1)
+Image.fromarray(row).save(out)
+print("wrote", out, flush=True)
diff --git a/scripts/render_mesh_pbr.py b/scripts/render_mesh_pbr.py
new file mode 100644
index 0000000..e4f786f
--- /dev/null
+++ b/scripts/render_mesh_pbr.py
@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""Render a T2MESH02/03 (per-vertex PBR) binary mesh to a PNG for eyeballing the
+demo's textured output. Mirrors the viewer's orientation-independent shading."""
+import struct, sys, numpy as np
+from PIL import Image
+
+path = sys.argv[1]; out = sys.argv[2] if len(sys.argv) > 2 else "mesh_pbr.png"
+b = open(path, "rb").read()
+magic = b[:8]; nv, nt = struct.unpack("<II", b[8:16]); o = 16
+V = np.frombuffer(b, "<f4", 3*nv, o).reshape(-1, 3).astype(np.float64); o += 12*nv
+o += 12*nv  # skip normals (recompute from faces)
+pbr = None
+if magic == b"T2MESH03":
+    pbr = np.frombuffer(b, "<f4", 6*nv, o).reshape(-1, 6).astype(np.float64); o += 24*nv
+elif magic == b"T2MESH02":
+    old = np.frombuffer(b, "<f4", 5*nv, o).reshape(-1, 5).astype(np.float64); o += 20*nv
+    pbr = np.concatenate([old, np.ones((nv, 1))], axis=1)
+F = np.frombuffer(b, "<i4", 3*nt, o).reshape(-1, 3)
+C = pbr[:, 0:3] if pbr is not None else np.full((nv, 3), 0.65)
+C_lin = np.clip(C, 0, 1) ** 2.2
+metal = pbr[:, 3] if pbr is not None else np.zeros(nv)
+print(f"{magic} {nv:,} verts  base_color mean {C.mean(0).round(3)}", flush=True)
+
+fn = np.cross(V[F[:, 1]] - V[F[:, 0]], V[F[:, 2]] - V[F[:, 0]])
+N = np.zeros_like(V)
+for k in range(3): np.add.at(N, F[:, k], fn)
+N /= np.linalg.norm(N, axis=1, keepdims=True) + 1e-9
+
+SS = 2; W = H = 720 * SS
+c = (V.max(0) + V.min(0)) / 2; Vc = V - c; Vc *= 0.92 / np.abs(Vc).max()
+l1 = np.array([0.5, 0.8, 0.6]); l1 /= np.linalg.norm(l1)
+l2 = np.array([-0.6, -0.2, -0.7]); l2 /= np.linalg.norm(l2)
+
+
+def R(el, az):
+    a, e = np.radians(az), np.radians(el)
+    Ry = np.array([[np.cos(a), 0, np.sin(a)], [0, 1, 0], [-np.sin(a), 0, np.cos(a)]])
+    Rx = np.array([[1, 0, 0], [0, np.cos(e), -np.sin(e)], [0, np.sin(e), np.cos(e)]])
+    return Rx @ Ry
+
+
+rough = pbr[:, 4] if pbr is not None else np.full(nv, 0.55)
+# view-space metallic-roughness PBR, matching server/web/index.html
+LC = [(np.array([.32, .55, .77]), np.array([1., .96, .88]), .85),
+      (np.array([-.65, .20, .45]), np.array([.70, .80, 1.]), .45),
+      (np.array([.10, -.75, .35]), np.array([.85, .85, .90]), .25)]
+
+
+def render(el, az):
+    r = R(el, az); P = Vc @ r.T; Nr = N @ r.T
+    Nr /= np.linalg.norm(Nr, axis=1, keepdims=True) + 1e-9
+    sx = ((P[:, 0]*.5+.5)*(W-1)).astype(np.int32); sy = ((.5-P[:, 1]*.5)*(H-1)).astype(np.int32)
+    z = P[:, 2]
+    V = np.array([0., 0., 1.])
+    nv_ = np.abs(Nr @ V)
+    F0 = 0.04*(1-metal)[:, None] + C_lin*metal[:, None]
+    F = F0 + (1-F0)*((1-nv_)[:, None]**5)
+    shin = 6.0 + (220.0-6.0)*np.clip(1-rough, 0, 1)**1.5
+    sn = (shin+2.0)/(2*np.pi)
+    diffuse = np.zeros((len(C), 3)); specular = np.zeros((len(C), 3))
+    for Ld, Lc, w in LC:
+        l = Ld/np.linalg.norm(Ld); ndl = np.abs(Nr @ l)
+        diffuse += Lc[None]*w*ndl[:, None]
+        h = l+V; h = h/np.linalg.norm(h); nh = np.abs(Nr @ h)
+        specular += Lc[None]*w*(nh[:, None]**shin[:, None])*sn[:, None]*ndl[:, None]
+    albedo = C_lin*(1-metal)[:, None]
+    hemi = np.abs(N[:, 1])*0.5+0.5
+    amb = (1-hemi)[:, None]*np.array([.20, .19, .22]) + hemi[:, None]*np.array([.55, .58, .66])
+    col = np.clip(albedo*(amb*0.55 + diffuse*0.75) + specular*F + F*0.25, 0, 1)
+    img = np.ones((H, W, 3))
+    idx = np.argsort(z); sx, sy, col = sx[idx], sy[idx], col[idx]
+    for dx in range(SS+1):
+        for dy in range(SS+1):
+            xx = sx+dx; yy = sy+dy
+            m = (xx >= 0) & (xx < W) & (yy >= 0) & (yy < H)
+            img[yy[m], xx[m]] = col[m]
+    return (img**(1/2.2)*255).reshape(H//SS, SS, W//SS, SS, 3).mean((1, 3)).astype(np.uint8)
+
+
+row = np.concatenate([render(12, 25), render(12, 150), render(65, 20)], 1)
+Image.fromarray(row).save(out)
+print("wrote", out, flush=True)
diff --git a/scripts/render_vcolor.py b/scripts/render_vcolor.py
new file mode 100644
index 0000000..a05adfc
--- /dev/null
+++ b/scripts/render_vcolor.py
@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+"""Render a T2VCOL01 coloured mesh (verts + per-vertex base_color) with a numpy
+z-buffer, a few views, for eyeballing the PBR texture NN output."""
+import struct, sys, numpy as np
+from PIL import Image
+
+path = sys.argv[1] if len(sys.argv) > 1 else "dumps/tex_vcolor.bin"
+out = sys.argv[2] if len(sys.argv) > 2 else "dumps/tex_vcolor.png"
+b = open(path, "rb").read()
+assert b[:8] == b"T2VCOL01", b[:8]
+nv, nt = struct.unpack("<II", b[8:16]); o = 16
+V = np.frombuffer(b, "<f4", 3 * nv, o).reshape(-1, 3).astype(np.float64); o += 12 * nv
+C = np.frombuffer(b, "<f4", 3 * nv, o).reshape(-1, 3).astype(np.float64); o += 12 * nv
+o += 8 * nv  # skip metal/rough
+F = np.frombuffer(b, "<i4", 3 * nt, o).reshape(-1, 3)
+print(f"{nv:,} verts {nt:,} tris  color mean {C.mean(0)}", flush=True)
+
+# face normals -> per-vertex (for a little shading on top of albedo)
+fn = np.cross(V[F[:, 1]] - V[F[:, 0]], V[F[:, 2]] - V[F[:, 0]])
+N = np.zeros_like(V)
+for k in range(3):
+    np.add.at(N, F[:, k], fn)
+N /= np.linalg.norm(N, axis=1, keepdims=True) + 1e-9
+
+SS = 2; W = H = 640 * SS
+c = (V.max(0) + V.min(0)) / 2; Vc = V - c; Vc *= 0.9 / np.abs(Vc).max()
+l1 = np.array([0.5, 0.8, 0.6]); l1 /= np.linalg.norm(l1)
+l2 = np.array([-0.6, -0.2, -0.7]); l2 /= np.linalg.norm(l2)
+
+
+def R(el, az):
+    a = np.radians(az); e = np.radians(el)
+    Ry = np.array([[np.cos(a), 0, np.sin(a)], [0, 1, 0], [-np.sin(a), 0, np.cos(a)]])
+    Rx = np.array([[1, 0, 0], [0, np.cos(e), -np.sin(e)], [0, np.sin(e), np.cos(e)]])
+    return Rx @ Ry
+
+
+def render(el, az):
+    r = R(el, az); P = Vc @ r.T; Nr = N @ r.T
+    sx = ((P[:, 0] * .5 + .5) * (W - 1)).astype(np.int32)
+    sy = ((.5 - P[:, 1] * .5) * (H - 1)).astype(np.int32)
+    z = P[:, 2]
+    shade = (np.abs(Nr @ l1) * .7 + np.abs(Nr @ l2) * .3) * 0.6 + 0.4  # gentle, keep albedo
+    col = np.clip(C * shade[:, None], 0, 1)
+    img = np.ones((H, W, 3)); zb = np.full((H, W), -1e9)
+    idx = np.argsort(z); sx, sy, z, col = sx[idx], sy[idx], z[idx], col[idx]
+    for dx in range(SS + 1):
+        for dy in range(SS + 1):
+            xx = sx + dx; yy = sy + dy
+            m = (xx >= 0) & (xx < W) & (yy >= 0) & (yy < H)
+            img[yy[m], xx[m]] = col[m]; zb[yy[m], xx[m]] = z[m]
+    im = (img ** (1 / 2.2) * 255).reshape(H // SS, SS, W // SS, SS, 3).mean((1, 3))
+    return im.astype(np.uint8)
+
+
+row = np.concatenate([render(15, 25), render(15, 120), render(70, 20)], 1)
+Image.fromarray(row).save(out)
+print("wrote", out, flush=True)
diff --git a/scripts/upload_ggufs.sh b/scripts/upload_ggufs.sh
new file mode 100755
index 0000000..7d7c274
--- /dev/null
+++ b/scripts/upload_ggufs.sh
@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# One-time (idempotent) publish of the prebuilt f16 GGUFs to the LocalAI-io org on
+# Hugging Face. Splits by upstream provenance so each repo carries a single clean
+# license:
+#   TRELLIS.2-4B-GGUF                     (MIT)            8 files
+#   TRELLIS-image-large-GGUF              (MIT)            ss_dec
+#   dinov3-vitl16-pretrain-lvd1689m-GGUF  (DINOv3 License) dino
+#
+# Cards + LICENSE files live under scripts/hf/<repo>/ and are uploaded alongside the
+# weights. Requires an authenticated `hf` (huggingface_hub >= 1.x) with write access
+# to the org. `hf` is often not on PATH; set HF=/path/to/venv/bin/hf to override.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+GGUFS="${GGUFS:-$ROOT/ggufs}"
+CARDS="$ROOT/scripts/hf"
+ORG="${GGUF_ORG:-LocalAI-io}"
+
+# Locate the hf CLI: explicit $HF, then PATH, then known project venvs.
+HF="${HF:-}"
+if [ -z "$HF" ]; then
+    if command -v hf >/dev/null 2>&1; then HF="$(command -v hf)"
+    else
+        for c in "$HOME"/.venvs/*/bin/hf "$HOME"/c/*/.venv*/bin/hf; do
+            [ -x "$c" ] && { HF="$c"; break; }
+        done
+    fi
+fi
+[ -n "$HF" ] && [ -x "$HF" ] || { echo "error: hf CLI not found; set HF=/path/to/hf" >&2; exit 1; }
+echo "using hf: $HF ($("$HF" --version 2>/dev/null))"
+"$HF" auth whoami >/dev/null || { echo "error: not logged in (hf auth login)" >&2; exit 1; }
+
+T2=TRELLIS.2-4B-GGUF
+T1=TRELLIS-image-large-GGUF
+DINO=dinov3-vitl16-pretrain-lvd1689m-GGUF
+
+T2_FILES=(ss_flow_f16.gguf slat_flow_f16.gguf slat_flow_1024_f16.gguf shape_dec_f16.gguf \
+          shape_enc_f16.gguf tex_dec_f16.gguf tex_slat_flow_512_f16.gguf tex_slat_flow_1024_f16.gguf)
+T1_FILES=(ss_dec_f16.gguf)
+DINO_FILES=(dino_f16.gguf)
+
+publish() { # publish <repo> <file>...
+    local repo="$1"; shift
+    local id="$ORG/$repo"
+    echo "== $id =="
+    "$HF" repo create "$id" --repo-type model --exist-ok
+    local f
+    for f in "$@"; do
+        [ -s "$GGUFS/$f" ] || { echo "error: missing $GGUFS/$f" >&2; exit 1; }
+        echo "-- upload $f"
+        "$HF" upload "$id" "$GGUFS/$f" "$f" --commit-message "Add $f"
+    done
+    "$HF" upload "$id" "$CARDS/$repo/README.md" README.md --commit-message "Add model card"
+    "$HF" upload "$id" "$CARDS/$repo/LICENSE"   LICENSE   --commit-message "Add license"
+}
+
+publish "$T2"   "${T2_FILES[@]}"
+publish "$T1"   "${T1_FILES[@]}"
+publish "$DINO" "${DINO_FILES[@]}"
+
+echo "done. repos:"
+echo "  https://huggingface.co/$ORG/$T2"
+echo "  https://huggingface.co/$ORG/$T1"
+echo "  https://huggingface.co/$ORG/$DINO"
diff --git a/server/engine.go b/server/engine.go
new file mode 100644
index 0000000..4d816c5
--- /dev/null
+++ b/server/engine.go
@@ -0,0 +1,415 @@
+package main
+
+// engine.go — in-process FFI to libtrellis2.so via purego (no cgo), following
+// the depth-anything.cpp server pattern. The C ABI is trellis2_capi.h; the
+// t2_abi_version binding guards against header/library drift.
+
+import (
+	"fmt"
+	"os"
+	"sync"
+	"unsafe"
+
+	"github.com/ebitengine/purego"
+)
+
+const abiVersion = 9
+
+// Progress stages (enum t2_stage).
+const (
+	stagePreprocess = 0
+	stageDino       = 1
+	stageSSFlow     = 2
+	stageSSDec      = 3
+	stageSLATFlow   = 4
+	stageShapeDec   = 5
+	stageMesh       = 6
+	stageUpsample   = 7
+	stageSLATFlowHR = 8
+	stageShapeDecHR = 9
+	stageTexture    = 10
+)
+
+var stageNames = map[int]string{
+	stagePreprocess: "preprocess",
+	stageDino:       "encoding image (DINOv3)",
+	stageSSFlow:     "sampling sparse structure",
+	stageSSDec:      "decoding occupancy",
+	stageSLATFlow:   "sampling shape SLAT",
+	stageShapeDec:   "decoding shape",
+	stageMesh:       "extracting mesh",
+	stageUpsample:   "upsampling scaffold",
+	stageSLATFlowHR: "sampling shape SLAT (1024)",
+	stageShapeDecHR: "decoding shape (1024)",
+	stageTexture:    "sampling material",
+}
+
+// Pipeline types (enum t2_pipeline_type) and capability bits (enum t2_caps).
+const (
+	pipeAuto   = 0
+	pipeCoarse = 1
+	pipe512    = 2
+	pipe1024   = 3
+
+	capCoarse  = 1
+	cap512     = 2
+	cap1024    = 4
+	capTexture = 8
+
+	backgroundAuto  = 0
+	backgroundKeep  = 1
+	backgroundBlack = 2
+	backgroundWhite = 3
+)
+
+type engine struct {
+	// inference is not thread-safe: one generation at a time.
+	mu      sync.Mutex
+	stateMu sync.RWMutex
+
+	pipeline uintptr
+	backend  string
+	caps     int  // bitmask of t2_caps
+	textured bool // PBR texturing enabled
+	models   engineModels
+
+	abiVersion      func() int32
+	pipelineLoad    func(dino, flow, dec, slat, slatHR, shapeDec, shapeEnc, texDec, texFlow, texFlowHR string, flags int32, err unsafe.Pointer, errLen int32) uintptr
+	pipelineFree    func(p uintptr)
+	pipelineBackend func(p uintptr) string
+	pipelineCaps    func(p uintptr) int32
+	generate        func(p uintptr, img unsafe.Pointer, imgLen int32, pipelineType, backgroundMode int32,
+		seed uint64, steps int32, guidance float32, textureSteps int32, cb uintptr, user unsafe.Pointer,
+		preview uintptr, previewUser unsafe.Pointer,
+		err unsafe.Pointer, errLen int32) uintptr
+	meshNVerts   func(r uintptr) int32
+	meshNTris    func(r uintptr) int32
+	meshVerts    func(r uintptr) uintptr
+	meshNormals  func(r uintptr) uintptr
+	meshTris     func(r uintptr) uintptr
+	meshHasPBR   func(r uintptr) int32
+	meshPBR      func(r uintptr) uintptr
+	meshFree     func(r uintptr)
+	prepareMeshC func(verts unsafe.Pointer, nv int32, tris unsafe.Pointer, nt int32, pbr unsafe.Pointer,
+		componentFilter int32, err unsafe.Pointer, errLen int32) uintptr
+	bakeGLB func(verts unsafe.Pointer, nv int32, tris unsafe.Pointer, nt int32, pbr unsafe.Pointer,
+		texSize, componentFilter int32, outLen unsafe.Pointer, err unsafe.Pointer, errLen int32) uintptr
+	freeBuffer func(buf uintptr)
+}
+
+// engineModels retains only the paths needed to recreate a freed pipeline. The
+// GGUF contents themselves remain owned by the C pipeline while it is loaded.
+type engineModels struct {
+	dino, flow, dec                      string
+	slat, slatHR, shapeDec               string
+	shapeEnc, texDec, texFlow, texFlowHR string
+}
+
+// progressSink receives per-stage/step updates for the currently running
+// generation. Exactly one generation runs at a time (engine.mu), so a single
+// global callback + current sink is safe.
+var (
+	progressMu   sync.Mutex
+	progressSink func(stage, step, total int)
+	previewSink  func(stage, step, total int, blob []byte)
+)
+
+var (
+	progressCallback uintptr // created once; purego callbacks are permanent
+	previewCallback  uintptr
+)
+
+// slatGGUF/shapeDecGGUF may be "" for the coarse path; slatHRGGUF may be "" to
+// disable the 1024 cascade (512 fine only).
+func newEngine(libPath, dinoGGUF, flowGGUF, decGGUF, slatGGUF, slatHRGGUF, shapeDecGGUF,
+	shapeEncGGUF, texDecGGUF, texFlowGGUF, texFlowHRGGUF string, startUnloaded bool) (*engine, error) {
+	lib, err := purego.Dlopen(libPath, purego.RTLD_NOW|purego.RTLD_GLOBAL)
+	if err != nil {
+		return nil, fmt.Errorf("dlopen %s: %w", libPath, err)
+	}
+
+	e := &engine{models: engineModels{
+		dino: dinoGGUF, flow: flowGGUF, dec: decGGUF,
+		slat: slatGGUF, slatHR: slatHRGGUF, shapeDec: shapeDecGGUF,
+		shapeEnc: shapeEncGGUF, texDec: texDecGGUF,
+		texFlow: texFlowGGUF, texFlowHR: texFlowHRGGUF,
+	}}
+	purego.RegisterLibFunc(&e.abiVersion, lib, "t2_abi_version")
+	if got := e.abiVersion(); got != abiVersion {
+		return nil, fmt.Errorf("ABI mismatch: library reports %d, server built for %d", got, abiVersion)
+	}
+	purego.RegisterLibFunc(&e.pipelineLoad, lib, "t2_pipeline_load")
+	purego.RegisterLibFunc(&e.pipelineFree, lib, "t2_pipeline_free")
+	purego.RegisterLibFunc(&e.pipelineBackend, lib, "t2_pipeline_backend")
+	purego.RegisterLibFunc(&e.pipelineCaps, lib, "t2_pipeline_caps")
+	purego.RegisterLibFunc(&e.generate, lib, "t2_generate")
+	purego.RegisterLibFunc(&e.meshNVerts, lib, "t2_mesh_n_verts")
+	purego.RegisterLibFunc(&e.meshNTris, lib, "t2_mesh_n_tris")
+	purego.RegisterLibFunc(&e.meshVerts, lib, "t2_mesh_verts")
+	purego.RegisterLibFunc(&e.meshNormals, lib, "t2_mesh_normals")
+	purego.RegisterLibFunc(&e.meshTris, lib, "t2_mesh_tris")
+	purego.RegisterLibFunc(&e.meshHasPBR, lib, "t2_mesh_has_pbr")
+	purego.RegisterLibFunc(&e.meshPBR, lib, "t2_mesh_pbr")
+	purego.RegisterLibFunc(&e.meshFree, lib, "t2_mesh_free")
+	purego.RegisterLibFunc(&e.prepareMeshC, lib, "t2_prepare_mesh")
+	purego.RegisterLibFunc(&e.bakeGLB, lib, "t2_bake_glb")
+	purego.RegisterLibFunc(&e.freeBuffer, lib, "t2_free_buffer")
+
+	if progressCallback == 0 {
+		progressCallback = purego.NewCallback(func(user unsafe.Pointer, stage, step, total int32) uintptr {
+			progressMu.Lock()
+			sink := progressSink
+			progressMu.Unlock()
+			if sink != nil {
+				sink(int(stage), int(step), int(total))
+			}
+			return 0
+		})
+	}
+	if previewCallback == 0 {
+		// Live intermediate-preview blobs (T2VOX01 voxel sets). `data` is only
+		// valid during the call, so copy before handing it to the sink.
+		previewCallback = purego.NewCallback(func(user unsafe.Pointer, stage, step, total int32,
+			data unsafe.Pointer, length int32) uintptr {
+			progressMu.Lock()
+			sink := previewSink
+			progressMu.Unlock()
+			if sink != nil && data != nil && length > 0 {
+				blob := make([]byte, int(length))
+				copy(blob, unsafe.Slice((*byte)(data), int(length)))
+				sink(int(stage), int(step), int(total), blob)
+			}
+			return 0
+		})
+	}
+
+	if startUnloaded {
+		e.backend = "GPU (models unloaded)"
+		if os.Getenv("TRELLIS2_DEVICE") == "cpu" {
+			e.backend = "CPU (models unloaded)"
+		}
+		e.caps = configuredCaps(e.models)
+		e.textured = e.caps&capTexture != 0
+	} else {
+		if err := e.loadLocked(); err != nil {
+			return nil, err
+		}
+	}
+	return e, nil
+}
+
+// configuredCaps mirrors t2_pipeline_caps from the model paths that main has
+// already existence-checked. It keeps /api/info and the quality picker useful
+// before a lazy first pipeline load.
+func configuredCaps(m engineModels) int {
+	caps := capCoarse
+	if m.slat != "" && m.shapeDec != "" {
+		caps |= cap512
+		if m.slatHR != "" {
+			caps |= cap1024
+		}
+		if m.shapeEnc != "" && m.texDec != "" && m.texFlow != "" {
+			caps |= capTexture
+		}
+	}
+	return caps
+}
+
+// loadLocked recreates the pipeline after an idle unload. e.mu must be held by
+// callers after construction.
+func (e *engine) loadLocked() error {
+	if e.pipeline != 0 {
+		return nil
+	}
+	m := e.models
+	errBuf := make([]byte, 512)
+	p := e.pipelineLoad(m.dino, m.flow, m.dec, m.slat, m.slatHR, m.shapeDec,
+		m.shapeEnc, m.texDec, m.texFlow, m.texFlowHR,
+		0 /*flags*/, unsafe.Pointer(&errBuf[0]), int32(len(errBuf)))
+	if p == 0 {
+		return fmt.Errorf("pipeline load: %s", cstr(errBuf))
+	}
+	e.stateMu.Lock()
+	e.pipeline = p
+	e.backend = e.pipelineBackend(p)
+	e.caps = int(e.pipelineCaps(p))
+	e.textured = e.caps&capTexture != 0
+	e.stateMu.Unlock()
+	return nil
+}
+
+// Unload releases all resident model buffers. Backend/capability metadata is
+// retained so /api/info and the quality picker remain useful while idle.
+func (e *engine) Unload() bool {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	if e.pipeline == 0 {
+		return false
+	}
+	e.pipelineFree(e.pipeline)
+	e.stateMu.Lock()
+	e.pipeline = 0
+	e.stateMu.Unlock()
+	return true
+}
+
+func (e *engine) Info() (backend string, caps int, textured, loaded bool) {
+	e.stateMu.RLock()
+	defer e.stateMu.RUnlock()
+	return e.backend, e.caps, e.textured, e.pipeline != 0
+}
+
+type meshData struct {
+	NVerts  int
+	NTris   int
+	Verts   []float32 // 3 * NVerts
+	Normals []float32 // 3 * NVerts
+	Tris    []int32   // 3 * NTris
+	PBR     []float32 // 6 * NVerts (base_color rgb, metallic, roughness, alpha); nil if untextured
+}
+
+// Generate runs the full image->mesh pipeline. onProgress and onPreview may be
+// nil. onPreview receives live intermediate 3D preview blobs (T2VOX01 voxel
+// sets) as the sparse structure emerges.
+func (e *engine) Generate(image []byte, pipelineType, backgroundMode int, seed uint64, steps int, guidance float32, textureSteps int,
+	onLoading func(),
+	onProgress func(stage, step, total int),
+	onPreview func(stage, step, total int, blob []byte)) (*meshData, error) {
+
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	if e.pipeline == 0 {
+		if onLoading != nil {
+			onLoading()
+		}
+		if err := e.loadLocked(); err != nil {
+			return nil, err
+		}
+	}
+
+	progressMu.Lock()
+	progressSink = onProgress
+	previewSink = onPreview
+	progressMu.Unlock()
+	defer func() {
+		progressMu.Lock()
+		progressSink = nil
+		previewSink = nil
+		progressMu.Unlock()
+	}()
+
+	cb := uintptr(0)
+	if onProgress != nil {
+		cb = progressCallback
+	}
+	pv := uintptr(0)
+	if onPreview != nil {
+		pv = previewCallback
+	}
+
+	errBuf := make([]byte, 512)
+	r := e.generate(e.pipeline, unsafe.Pointer(&image[0]), int32(len(image)), int32(pipelineType),
+		int32(backgroundMode), seed, int32(steps), guidance, int32(textureSteps), cb, nil, pv, nil,
+		unsafe.Pointer(&errBuf[0]), int32(len(errBuf)))
+	if r == 0 {
+		return nil, fmt.Errorf("%s", cstr(errBuf))
+	}
+	defer e.meshFree(r)
+
+	nv := int(e.meshNVerts(r))
+	nt := int(e.meshNTris(r))
+	if nv == 0 || nt == 0 {
+		return nil, fmt.Errorf("empty mesh")
+	}
+
+	m := &meshData{NVerts: nv, NTris: nt}
+	m.Verts = copyFloats(e.meshVerts(r), 3*nv)
+	m.Normals = copyFloats(e.meshNormals(r), 3*nv)
+	m.Tris = copyInts(e.meshTris(r), 3*nt)
+	if e.meshHasPBR(r) != 0 {
+		m.PBR = copyFloats(e.meshPBR(r), 6*nv)
+	}
+	return m, nil
+}
+
+// PrepareMesh returns the exact component-filtered, full-density geometry used by
+// GLB export. It is CPU-only and does not require the model pipeline to be loaded.
+func (e *engine) PrepareMesh(m *meshData, componentFilter int) (*meshData, error) {
+	if m == nil || m.NVerts == 0 || m.NTris == 0 {
+		return nil, fmt.Errorf("empty mesh")
+	}
+	var pbr unsafe.Pointer
+	if len(m.PBR) == 6*m.NVerts {
+		pbr = unsafe.Pointer(&m.PBR[0])
+	}
+	errBuf := make([]byte, 512)
+	r := e.prepareMeshC(unsafe.Pointer(&m.Verts[0]), int32(m.NVerts),
+		unsafe.Pointer(&m.Tris[0]), int32(m.NTris), pbr,
+		int32(componentFilter),
+		unsafe.Pointer(&errBuf[0]), int32(len(errBuf)))
+	if r == 0 {
+		return nil, fmt.Errorf("%s", cstr(errBuf))
+	}
+	defer e.meshFree(r)
+	nv, nt := int(e.meshNVerts(r)), int(e.meshNTris(r))
+	if nv == 0 || nt == 0 {
+		return nil, fmt.Errorf("empty prepared mesh")
+	}
+	out := &meshData{NVerts: nv, NTris: nt}
+	out.Verts = copyFloats(e.meshVerts(r), 3*nv)
+	out.Normals = copyFloats(e.meshNormals(r), 3*nv)
+	out.Tris = copyInts(e.meshTris(r), 3*nt)
+	if e.meshHasPBR(r) != 0 {
+		out.PBR = copyFloats(e.meshPBR(r), 6*nv)
+	}
+	return out, nil
+}
+
+// BakeGLB turns a generated mesh into a portable vertex-coloured GLB. texSize
+// remains an atlas hint for the explicit T2GLB_XATLAS mode. Geometry retains its
+// original polygon density. CPU-only; it can run while the GPU is idle.
+func (e *engine) BakeGLB(m *meshData, texSize, componentFilter int) ([]byte, error) {
+	if m == nil || m.NVerts == 0 || m.NTris == 0 {
+		return nil, fmt.Errorf("empty mesh")
+	}
+	var pbr unsafe.Pointer
+	if len(m.PBR) == 6*m.NVerts {
+		pbr = unsafe.Pointer(&m.PBR[0])
+	}
+	var outLen int32
+	errBuf := make([]byte, 512)
+	p := e.bakeGLB(unsafe.Pointer(&m.Verts[0]), int32(m.NVerts),
+		unsafe.Pointer(&m.Tris[0]), int32(m.NTris), pbr,
+		int32(texSize), int32(componentFilter),
+		unsafe.Pointer(&outLen), unsafe.Pointer(&errBuf[0]), int32(len(errBuf)))
+	if p == 0 {
+		return nil, fmt.Errorf("%s", cstr(errBuf))
+	}
+	defer e.freeBuffer(p)
+	out := make([]byte, outLen)
+	copy(out, unsafe.Slice((*byte)(unsafe.Pointer(p)), int(outLen)))
+	return out, nil
+}
+
+func copyFloats(p uintptr, n int) []float32 {
+	src := unsafe.Slice((*float32)(unsafe.Pointer(p)), n)
+	dst := make([]float32, n)
+	copy(dst, src)
+	return dst
+}
+
+func copyInts(p uintptr, n int) []int32 {
+	src := unsafe.Slice((*int32)(unsafe.Pointer(p)), n)
+	dst := make([]int32, n)
+	copy(dst, src)
+	return dst
+}
+
+func cstr(b []byte) string {
+	for i, c := range b {
+		if c == 0 {
+			return string(b[:i])
+		}
+	}
+	return string(b)
+}
diff --git a/server/go.mod b/server/go.mod
new file mode 100644
index 0000000..fd843e1
--- /dev/null
+++ b/server/go.mod
@@ -0,0 +1,5 @@
+module trellis2-server
+
+go 1.24
+
+require github.com/ebitengine/purego v0.8.2
diff --git a/server/go.sum b/server/go.sum
new file mode 100644
index 0000000..38eca3d
--- /dev/null
+++ b/server/go.sum
@@ -0,0 +1,2 @@
+github.com/ebitengine/purego v0.8.2 h1:jPPGWs2sZ1UgOSgD2bClL0MJIqu58nOmIcBuXr62z1I=
+github.com/ebitengine/purego v0.8.2/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ=
diff --git a/server/idle_test.go b/server/idle_test.go
new file mode 100644
index 0000000..fd958c8
--- /dev/null
+++ b/server/idle_test.go
@@ -0,0 +1,128 @@
+package main
+
+import (
+	"net/http/httptest"
+	"testing"
+	"unsafe"
+)
+
+func testEngine(pipeline uintptr, freed *int) *engine {
+	return &engine{
+		pipeline: pipeline,
+		backend:  "test GPU",
+		caps:     capCoarse | cap512 | capTexture,
+		textured: true,
+		pipelineFree: func(uintptr) {
+			*freed++
+		},
+	}
+}
+
+func TestEngineUnloadRetainsRuntimeInfoAndReloads(t *testing.T) {
+	freed, loads := 0, 0
+	e := testEngine(41, &freed)
+	e.models.dino = "dino.gguf"
+	e.pipelineLoad = func(dino, flow, dec, slat, slatHR, shapeDec, shapeEnc, texDec, texFlow, texFlowHR string,
+		flags int32, err unsafe.Pointer, errLen int32) uintptr {
+		loads++
+		if dino != "dino.gguf" {
+			t.Fatalf("reload used dino path %q", dino)
+		}
+		return 42
+	}
+	e.pipelineBackend = func(uintptr) string { return "test GPU" }
+	e.pipelineCaps = func(uintptr) int32 { return capCoarse | cap512 | capTexture }
+
+	if !e.Unload() || freed != 1 {
+		t.Fatalf("Unload() = true with one free wanted; freed=%d", freed)
+	}
+	backend, caps, textured, loaded := e.Info()
+	if loaded || backend != "test GPU" || caps != capCoarse|cap512|capTexture || !textured {
+		t.Fatalf("Info() after unload = %q, %d, %v, %v", backend, caps, textured, loaded)
+	}
+
+	e.mu.Lock()
+	err := e.loadLocked()
+	e.mu.Unlock()
+	if err != nil || loads != 1 {
+		t.Fatalf("reload: err=%v loads=%d", err, loads)
+	}
+	_, _, _, loaded = e.Info()
+	if !loaded {
+		t.Fatal("pipeline is not marked loaded after reload")
+	}
+}
+
+func TestConfiguredCapsForLazyStartup(t *testing.T) {
+	tests := []struct {
+		name string
+		m    engineModels
+		want int
+	}{
+		{"coarse", engineModels{}, capCoarse},
+		{"512", engineModels{slat: "slat", shapeDec: "shape"}, capCoarse | cap512},
+		{"1024 textured", engineModels{
+			slat: "slat", slatHR: "hr", shapeDec: "shape", shapeEnc: "shapeenc",
+			texDec: "texdec", texFlow: "texflow",
+		}, capCoarse | cap512 | cap1024 | capTexture},
+		{"texture missing encoder", engineModels{
+			slat: "slat", shapeDec: "shape", texDec: "texdec", texFlow: "texflow",
+		}, capCoarse | cap512},
+		{"incomplete fine", engineModels{slat: "slat", texDec: "texdec", texFlow: "texflow"}, capCoarse},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := configuredCaps(tt.m); got != tt.want {
+				t.Fatalf("configuredCaps() = %d, want %d", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestIdlePolicyWaitsForQueuedWork(t *testing.T) {
+	freed := 0
+	e := testEngine(41, &freed)
+	s := &server{eng: e, jobs: map[string]*job{}, q: make(chan *job, 1), queued: 1}
+
+	if s.setUnloadIdle(true) {
+		t.Fatal("enabled idle policy unloaded with queued work")
+	}
+	if freed != 0 {
+		t.Fatalf("pipeline freed with queued work: %d", freed)
+	}
+
+	s.mu.Lock()
+	s.queued = 0
+	s.mu.Unlock()
+	if !s.unloadModelsIfIdle(nil) || freed != 1 {
+		t.Fatalf("idle unload failed; freed=%d", freed)
+	}
+}
+
+func TestParseExportOptions(t *testing.T) {
+	def := parseExportOptions(httptest.NewRequest("GET", "/api/glb/job", nil))
+	if def.componentFilter != 2 || def.prepareKey() != "2" {
+		t.Fatalf("default export should preserve all components: %+v", def)
+	}
+	r := httptest.NewRequest("GET", "/api/glb/job?tex=1024&components=largest", nil)
+	o := parseExportOptions(r)
+	if o.textureSize != 1024 || o.componentFilter != 1 {
+		t.Fatalf("parseExportOptions() = %+v", o)
+	}
+	if o.prepareKey() != "1" || o.glbKey() != "1024-1" {
+		t.Fatalf("unexpected export cache keys: %q %q", o.prepareKey(), o.glbKey())
+	}
+}
+
+func TestKeepAllExportPreviewUsesOriginalMesh(t *testing.T) {
+	original := &meshData{NVerts: 3, NTris: 1}
+	j := &job{mesh: original}
+	s := &server{}
+	got, err := s.preparedExportMesh(j, exportOptions{textureSize: 2048, componentFilter: 2})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got != original {
+		t.Fatal("keep-all export preview did not return the exact source mesh")
+	}
+}
diff --git a/server/main.go b/server/main.go
new file mode 100644
index 0000000..a2dcced
--- /dev/null
+++ b/server/main.go
@@ -0,0 +1,1114 @@
+// trellis2 demo server: upload an image, get a 3D mesh back.
+//
+//	cmake -B build-shared -DBUILD_SHARED_LIBS=ON -DCMAKE_BUILD_TYPE=Release && cmake --build build-shared -j
+//	cd server && CGO_ENABLED=0 go build -o trellis2-server .
+//	./trellis2-server -lib ../build-shared/libtrellis2.so -ggufs ../ggufs
+//
+// API:
+//
+//	GET  /                 self-contained WebGL viewer (embedded web/index.html)
+//	GET  /api/info         {backend, defaults}
+//	POST /api/settings     form unload_idle=0|1 -> current runtime settings
+//	POST /api/generate     multipart image [+ source, background, seed, steps, guidance, texture_steps, preview=1] -> {job}
+//	POST /api/regenerate/{id} settings only; reuse the persisted generation input -> {job}
+//	GET  /api/jobs         durable completed-generation history
+//	GET  /api/job/{id}     {state, stage, step, total, previewSeq, livePreview, durationMs, stageTimings, error}
+//	GET  /api/source/{id}  original uploaded image (byte-for-byte when supplied)
+//	GET  /api/mesh/{id}    binary mesh: T2MESH01 geometry or T2MESH03 geometry +
+//	                       f32[6nv] PBR (base RGB, metal, roughness, alpha)
+//	GET  /api/export-preview/{id} full-density/component-filtered T2MESH0* geometry
+//	GET  /api/preview/{id} latest live 3D preview: "T2VOX01" u32 res u32 nvox
+//	                       u16[3nvox] voxel coords (little-endian)
+package main
+
+import (
+	"bytes"
+	"embed"
+	"encoding/binary"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"io"
+	"io/fs"
+	"log"
+	"math/rand"
+	"net/http"
+	"os"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+//go:embed web
+var webFS embed.FS
+
+const maxImage = 32 << 20                    // 32 MiB per original/processed image
+const maxUpload = (2 * maxImage) + (2 << 20) // both images plus multipart fields
+const maxFrames = 256                        // cap recorded preview frames per job (bounds memory)
+
+// frameMeta describes one recorded intermediate-preview frame so the viewer can
+// label and order the scrubber. Kind is "voxel" (T2VOX01) or "mesh" (T2MESH0*).
+type frameMeta struct {
+	Stage string `json:"stage"`
+	Step  int    `json:"step"`
+	Total int    `json:"total"`
+	Kind  string `json:"kind"`
+}
+
+// stageTiming records aggregate wall time spent in a reported pipeline stage.
+// It includes CPU work and host/device handoff time, which a GPU-utilisation
+// graph alone cannot explain.
+type stageTiming struct {
+	Stage        string `json:"stage"`
+	Milliseconds int64  `json:"milliseconds"`
+}
+
+type job struct {
+	mu    sync.Mutex
+	ID    string `json:"id"`
+	State string `json:"state"` // queued | running | done | error
+	// CreatedAt and Quality are retained in the durable manifest for future
+	// server-side history/indexing as well as diagnostics.
+	CreatedAt  int64  `json:"createdAt,omitempty"`
+	StartedAt  int64  `json:"startedAt,omitempty"`
+	FinishedAt int64  `json:"finishedAt,omitempty"`
+	DurationMS int64  `json:"durationMs,omitempty"`
+	Quality    string `json:"quality,omitempty"`
+	Thumbnail  string `json:"thumbnail,omitempty"`
+	Stage      string `json:"stage,omitempty"`
+	Step       int    `json:"step"`
+	Total      int    `json:"total"`
+	Error      string `json:"error,omitempty"`
+
+	// Recorded intermediate 3D previews: every frame is kept (not just the
+	// latest) so the viewer can scrub the whole generation back and forth.
+	// PreviewSeq == number of frames recorded; the browser fetches any frame it
+	// is still missing by index (/api/preview/{id}?seq=N). Frames carries the
+	// per-frame stage/step/kind metadata for labelling the scrubber.
+	PreviewSeq   int           `json:"previewSeq"`
+	PreviewStage string        `json:"previewStage,omitempty"`
+	PreviewStep  int           `json:"previewStep"`
+	PreviewTotal int           `json:"previewTotal"`
+	Frames       []frameMeta   `json:"frames,omitempty"`
+	LivePreview  bool          `json:"livePreview"`
+	StageTimings []stageTiming `json:"stageTimings,omitempty"`
+
+	image        []byte // processed image passed to TRELLIS
+	source       []byte // exact original upload, used for display and future edits
+	pipeline     int
+	background   int
+	seed         uint64
+	steps        int
+	textureSteps int
+	guidance     float32
+	keyframes    int      // intermediate shape-SLAT mesh keyframes to record (0 = off)
+	previews     [][]byte // every preview blob, in order; served by /api/preview?seq=
+	mesh         *meshData
+	exportMesh   *meshData  // cached component-cleanup preview for exportKey
+	exportKey    string     // component mode
+	glb          []byte     // cached last GLB bake
+	glbKey       string     // "tex-components" the cached GLB was baked with
+	exportMu     sync.Mutex // serializes large export preparation/bakes per job
+	persistDir   string     // committed on-disk job directory; empty before save
+	meshPath     string     // final T2MESH file, loaded lazily after a restart
+	inputPath    string     // processed generation input, persisted for regeneration
+	sourcePath   string     // exact original upload, persisted for showcase/display
+}
+
+type server struct {
+	eng        *engine
+	mu         sync.Mutex
+	lifecycle  sync.Mutex // serializes idle unloads with accepting new work
+	jobs       map[string]*job
+	q          chan *job
+	queued     int
+	active     bool
+	unloadIdle bool
+	storeDir   string // durable completed-job store; empty disables persistence
+}
+
+func (s *server) worker() {
+	for j := range s.q {
+		started := time.Now()
+		currentStage := ""
+		stageStarted := started
+		addStageTime := func(stage string, elapsed time.Duration) {
+			ms := elapsed.Milliseconds()
+			if ms < 0 {
+				return
+			}
+			for i := range j.StageTimings {
+				if j.StageTimings[i].Stage == stage {
+					j.StageTimings[i].Milliseconds += ms
+					return
+				}
+			}
+			j.StageTimings = append(j.StageTimings, stageTiming{Stage: stage, Milliseconds: ms})
+		}
+		setStage := func(stage string, step, total int) {
+			now := time.Now()
+			j.mu.Lock()
+			if stage != currentStage {
+				if currentStage != "" {
+					addStageTime(currentStage, now.Sub(stageStarted))
+				}
+				currentStage, stageStarted = stage, now
+			}
+			j.Stage, j.Step, j.Total = stage, step, total
+			j.mu.Unlock()
+		}
+		finishTiming := func() {
+			finished := time.Now()
+			j.mu.Lock()
+			if currentStage != "" {
+				addStageTime(currentStage, finished.Sub(stageStarted))
+				currentStage = ""
+			}
+			j.FinishedAt = finished.UnixMilli()
+			j.DurationMS = finished.Sub(started).Milliseconds()
+			j.mu.Unlock()
+		}
+
+		s.mu.Lock()
+		s.queued--
+		s.active = true
+		s.mu.Unlock()
+
+		j.mu.Lock()
+		j.State = "running"
+		j.StartedAt = started.UnixMilli()
+		j.mu.Unlock()
+
+		// The library reads T2_KEYFRAMES for opt-in intermediate mesh keyframes.
+		// A single worker goroutine runs generations serially, so setting the env
+		// per-job here is race-free.
+		os.Setenv("T2_KEYFRAMES", strconv.Itoa(j.keyframes))
+
+		var onPreview func(stage, step, total int, blob []byte)
+		if j.LivePreview {
+			onPreview = func(stage, step, total int, blob []byte) {
+				j.mu.Lock()
+				if len(j.previews) < maxFrames {
+					kind := "voxel"
+					if len(blob) >= 6 && string(blob[:6]) == "T2MESH" {
+						kind = "mesh"
+					}
+					j.previews = append(j.previews, blob)
+					j.Frames = append(j.Frames, frameMeta{
+						Stage: stageNames[stage], Step: step, Total: total, Kind: kind})
+					j.PreviewSeq = len(j.previews)
+				}
+				j.PreviewStage = stageNames[stage]
+				j.PreviewStep = step
+				j.PreviewTotal = total
+				j.mu.Unlock()
+			}
+		}
+
+		mesh, err := s.eng.Generate(j.image, j.pipeline, j.background, j.seed, j.steps, j.guidance, j.textureSteps,
+			func() {
+				setStage("loading models", 0, 0)
+			},
+			func(stage, step, total int) {
+				setStage(stageNames[stage], step, total)
+			},
+			onPreview)
+
+		j.mu.Lock()
+		if err != nil {
+			j.image = nil
+			j.source = nil
+			j.State = "error"
+			j.Error = err.Error()
+		} else {
+			j.mesh = mesh
+		}
+		j.mu.Unlock()
+		if err == nil {
+			setStage("saving generation", 0, 0)
+		}
+
+		s.mu.Lock()
+		s.active = false
+		s.mu.Unlock()
+		if s.unloadModelsIfIdle(func() {
+			setStage("freeing VRAM", 0, 0)
+		}) {
+			log.Printf("models unloaded while idle")
+		}
+
+		if err == nil {
+			setStage("saving generation", 0, 0)
+			// Freeze inference/load/unload timings before writing the manifest so
+			// the diagnostics survive a server restart. Large mesh-file I/O is not
+			// part of the inference duration.
+			finishTiming()
+			if saveErr := s.persistJob(j); saveErr != nil {
+				// The result remains usable for this process. A persistence failure is
+				// operational, not a reason to discard an otherwise valid generation.
+				log.Printf("persist job %s: %v", j.ID, saveErr)
+			}
+			j.mu.Lock()
+			// If persistence failed or is disabled, keep the bytes in memory so
+			// source display and regeneration remain available for this process.
+			if j.inputPath != "" {
+				j.image = nil
+			}
+			if j.sourcePath != "" {
+				j.source = nil
+			}
+			j.mu.Unlock()
+		} else {
+			finishTiming()
+		}
+
+		j.mu.Lock()
+		if err == nil {
+			j.State = "done"
+		}
+		j.Stage = ""
+		j.Step, j.Total = 0, 0
+		duration := j.DurationMS
+		timings := append([]stageTiming(nil), j.StageTimings...)
+		preview := j.LivePreview
+		j.mu.Unlock()
+		parts := make([]string, 0, len(timings))
+		for _, timing := range timings {
+			parts = append(parts, fmt.Sprintf("%s=%.1fs", timing.Stage, float64(timing.Milliseconds)/1000))
+		}
+		log.Printf("job %s finished in %.1fs (live preview: %t): %s",
+			j.ID, float64(duration)/1000, preview, strings.Join(parts, ", "))
+	}
+}
+
+// unloadModelsIfIdle rechecks idleness while holding lifecycle, so a generation
+// cannot be accepted in the gap between the check and freeing the pipeline.
+func (s *server) unloadModelsIfIdle(before func()) bool {
+	s.lifecycle.Lock()
+	defer s.lifecycle.Unlock()
+	s.mu.Lock()
+	idle := s.unloadIdle && !s.active && s.queued == 0
+	s.mu.Unlock()
+	if !idle {
+		return false
+	}
+	if before != nil {
+		before()
+	}
+	return s.eng.Unload()
+}
+
+func (s *server) setUnloadIdle(enabled bool) bool {
+	s.lifecycle.Lock()
+	defer s.lifecycle.Unlock()
+	s.mu.Lock()
+	s.unloadIdle = enabled
+	idle := !s.active && s.queued == 0
+	s.mu.Unlock()
+	return enabled && idle && s.eng.Unload()
+}
+
+func (s *server) handleGenerate(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		http.Error(w, "POST only", http.StatusMethodNotAllowed)
+		return
+	}
+	r.Body = http.MaxBytesReader(w, r.Body, maxUpload)
+	if err := r.ParseMultipartForm(maxUpload); err != nil {
+		http.Error(w, "bad multipart form: "+err.Error(), http.StatusBadRequest)
+		return
+	}
+	defer r.MultipartForm.RemoveAll()
+	file, _, err := r.FormFile("image")
+	if err != nil {
+		http.Error(w, "missing image field", http.StatusBadRequest)
+		return
+	}
+	defer file.Close()
+	img, err := readImage(file)
+	if err != nil {
+		http.Error(w, "invalid image: "+err.Error(), http.StatusBadRequest)
+		return
+	}
+	if len(img) == 0 {
+		http.Error(w, "empty image", http.StatusBadRequest)
+		return
+	}
+
+	// Browsers send the untouched selected File separately from the PNG they
+	// prepared for inference. API clients that only send `image` still retain
+	// that image as their original source.
+	source := img
+	if sourceFile, _, sourceErr := r.FormFile("source"); sourceErr == nil {
+		defer sourceFile.Close()
+		source, err = readImage(sourceFile)
+		if err != nil || len(source) == 0 {
+			if err == nil {
+				err = fmt.Errorf("empty image")
+			}
+			http.Error(w, "invalid source image: "+err.Error(), http.StatusBadRequest)
+			return
+		}
+	} else if sourceErr != http.ErrMissingFile {
+		http.Error(w, "invalid source image: "+sourceErr.Error(), http.StatusBadRequest)
+		return
+	}
+
+	// quality: "coarse" | "512" | "1024" (default auto → best available)
+	pt := pipelineForQuality(r.FormValue("quality"))
+
+	// Browser uploads are already cleaned so they pass "keep" to prevent a
+	// second heuristic pass. Other API clients get automatic cleanup by default.
+	background := backgroundAuto
+	switch r.FormValue("background") {
+	case "keep":
+		background = backgroundKeep
+	case "black":
+		background = backgroundBlack
+	case "white":
+		background = backgroundWhite
+	}
+
+	j := &job{
+		ID:           fmt.Sprintf("%016x", rand.Uint64()),
+		State:        "queued",
+		CreatedAt:    time.Now().UnixMilli(),
+		Quality:      r.FormValue("quality"),
+		Thumbnail:    r.FormValue("thumbnail"),
+		image:        img,
+		source:       source,
+		pipeline:     pt,
+		background:   background,
+		seed:         formUint(r, "seed", rand.Uint64()%1_000_000),
+		steps:        int(formUint(r, "steps", 12)),
+		textureSteps: int(formUint(r, "texture_steps", 12)),
+		guidance:     formFloat(r, "guidance", 7.5),
+		LivePreview:  r.FormValue("preview") == "1", // expensive preview decodes are explicitly opt-in
+		keyframes:    int(formUint(r, "keyframes", 0)),
+	}
+	s.normaliseJob(j)
+	s.enqueueJob(w, j)
+}
+
+func readImage(r io.Reader) ([]byte, error) {
+	data, err := io.ReadAll(io.LimitReader(r, maxImage+1))
+	if err != nil {
+		return nil, err
+	}
+	if len(data) > maxImage {
+		return nil, fmt.Errorf("image exceeds %d MiB", maxImage>>20)
+	}
+	return data, nil
+}
+
+func pipelineForQuality(quality string) int {
+	switch quality {
+	case "coarse":
+		return pipeCoarse
+	case "512":
+		return pipe512
+	case "1024":
+		return pipe1024
+	default:
+		return pipeAuto
+	}
+}
+
+func (s *server) normaliseJob(j *job) {
+	if len(j.Thumbnail) > 256<<10 ||
+		(j.Thumbnail != "" && !strings.HasPrefix(j.Thumbnail, "data:image/jpeg;base64,")) {
+		j.Thumbnail = ""
+	}
+	if j.steps < 1 || j.steps > 50 {
+		j.steps = 12
+	}
+	if j.textureSteps < 1 || j.textureSteps > 50 {
+		j.textureSteps = 12
+	}
+	if j.guidance < 0 || j.guidance > 20 {
+		j.guidance = 7.5
+	}
+	if j.keyframes > 8 {
+		j.keyframes = 8
+	}
+	if j.keyframes < 0 || !j.LivePreview {
+		j.keyframes = 0
+	}
+}
+
+func (s *server) enqueueJob(w http.ResponseWriter, j *job) bool {
+	s.lifecycle.Lock()
+	s.mu.Lock()
+	select {
+	case s.q <- j:
+		s.jobs[j.ID] = j
+		s.queued++
+		s.mu.Unlock()
+		s.lifecycle.Unlock()
+		writeJSON(w, map[string]string{"job": j.ID})
+		return true
+	default:
+		s.mu.Unlock()
+		s.lifecycle.Unlock()
+		http.Error(w, "queue full, try again later", http.StatusServiceUnavailable)
+		return false
+	}
+}
+
+// handleRegenerate creates a new job from the immutable, processed input saved
+// with a completed generation. No image bytes need to cross the network again.
+func (s *server) handleRegenerate(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		http.Error(w, "POST only", http.StatusMethodNotAllowed)
+		return
+	}
+	old := s.getJob(r, "/api/regenerate/")
+	if old == nil {
+		http.Error(w, "no such job", http.StatusNotFound)
+		return
+	}
+
+	old.mu.Lock()
+	state := old.State
+	input := append([]byte(nil), old.image...)
+	source := append([]byte(nil), old.source...)
+	inputPath, sourcePath := old.inputPath, old.sourcePath
+	quality, thumbnail := old.Quality, old.Thumbnail
+	seed, steps := old.seed, old.steps
+	textureSteps, guidance := old.textureSteps, old.guidance
+	old.mu.Unlock()
+	if state != "done" {
+		http.Error(w, "generation is not complete", http.StatusConflict)
+		return
+	}
+	// source.img was the processed input in the first persistence format. That
+	// makes legacy saved jobs regeneratable even though their exact original can
+	// no longer be recovered retroactively.
+	if inputPath == "" {
+		inputPath = sourcePath
+	}
+	var err error
+	if len(input) == 0 && inputPath != "" {
+		input, err = os.ReadFile(inputPath)
+	}
+	if err != nil || len(input) == 0 {
+		http.Error(w, "saved generation input is unavailable", http.StatusConflict)
+		return
+	}
+	if len(source) == 0 && sourcePath != "" {
+		source, err = os.ReadFile(sourcePath)
+		if err != nil {
+			source = nil
+		}
+	}
+	if len(source) == 0 {
+		source = append([]byte(nil), input...)
+	}
+
+	if requested := r.FormValue("quality"); requested != "" {
+		quality = requested
+	}
+	j := &job{
+		ID: fmt.Sprintf("%016x", rand.Uint64()), State: "queued",
+		CreatedAt: time.Now().UnixMilli(), Quality: quality, Thumbnail: thumbnail,
+		image: input, source: source, pipeline: pipelineForQuality(quality),
+		background: backgroundKeep,
+		seed:       formUint(r, "seed", seed), steps: int(formUint(r, "steps", uint64(steps))),
+		textureSteps: int(formUint(r, "texture_steps", uint64(textureSteps))),
+		guidance:     formFloat(r, "guidance", guidance),
+		LivePreview:  r.FormValue("preview") == "1",
+		keyframes:    int(formUint(r, "keyframes", 0)),
+	}
+	s.normaliseJob(j)
+	s.enqueueJob(w, j)
+}
+
+func (s *server) getJob(r *http.Request, prefix string) *job {
+	id := r.URL.Path[len(prefix):]
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.jobs[id]
+}
+
+func (s *server) handleJob(w http.ResponseWriter, r *http.Request) {
+	j := s.getJob(r, "/api/job/")
+	if j == nil {
+		http.Error(w, "no such job", http.StatusNotFound)
+		return
+	}
+	if r.Method == http.MethodDelete {
+		j.mu.Lock()
+		state, dir := j.State, j.persistDir
+		j.mu.Unlock()
+		if state != "done" && state != "error" {
+			http.Error(w, "generation is still active", http.StatusConflict)
+			return
+		}
+		if dir != "" {
+			if err := os.RemoveAll(dir); err != nil {
+				http.Error(w, "delete persisted generation: "+err.Error(), http.StatusInternalServerError)
+				return
+			}
+		}
+		s.mu.Lock()
+		delete(s.jobs, j.ID)
+		s.mu.Unlock()
+		w.WriteHeader(http.StatusNoContent)
+		return
+	}
+	if r.Method != http.MethodGet {
+		http.Error(w, "GET or DELETE only", http.StatusMethodNotAllowed)
+		return
+	}
+	j.mu.Lock()
+	defer j.mu.Unlock()
+	writeJSON(w, j)
+}
+
+// handleSource serves the original upload, retained byte-for-byte for the
+// full-screen showcase and other future use outside the inference pipeline.
+func (s *server) handleSource(w http.ResponseWriter, r *http.Request) {
+	j := s.getJob(r, "/api/source/")
+	if j == nil {
+		http.Error(w, "no such job", http.StatusNotFound)
+		return
+	}
+	j.mu.Lock()
+	image := j.source
+	if len(image) == 0 {
+		image = j.image // compatibility for an in-memory job from an older server
+	}
+	path := j.sourcePath
+	j.mu.Unlock()
+	if len(image) > 0 {
+		w.Header().Set("Content-Type", http.DetectContentType(image))
+		w.Header().Set("Cache-Control", "public, max-age=31536000, immutable")
+		w.Write(image)
+		return
+	}
+	if path == "" {
+		http.Error(w, "source image was not retained for this generation", http.StatusNotFound)
+		return
+	}
+	w.Header().Set("Cache-Control", "public, max-age=31536000, immutable")
+	http.ServeFile(w, r, path)
+}
+
+type jobSummary struct {
+	ID            string `json:"id"`
+	CreatedAt     int64  `json:"createdAt"`
+	Quality       string `json:"quality,omitempty"`
+	Thumbnail     string `json:"thumbnail,omitempty"`
+	PreviewSeq    int    `json:"previewSeq"`
+	Source        bool   `json:"sourceAvailable"`
+	Regeneratable bool   `json:"regeneratable"`
+}
+
+func (s *server) handleJobs(w http.ResponseWriter, r *http.Request) {
+	s.mu.Lock()
+	jobs := make([]*job, 0, len(s.jobs))
+	for _, j := range s.jobs {
+		jobs = append(jobs, j)
+	}
+	s.mu.Unlock()
+
+	if r.Method == http.MethodDelete {
+		deleted := 0
+		for _, j := range jobs {
+			j.mu.Lock()
+			state, dir := j.State, j.persistDir
+			j.mu.Unlock()
+			if state != "done" && state != "error" {
+				continue
+			}
+			if dir != "" {
+				if err := os.RemoveAll(dir); err != nil {
+					http.Error(w, "delete persisted generation: "+err.Error(), http.StatusInternalServerError)
+					return
+				}
+			}
+			s.mu.Lock()
+			if s.jobs[j.ID] == j {
+				delete(s.jobs, j.ID)
+				deleted++
+			}
+			s.mu.Unlock()
+		}
+		writeJSON(w, map[string]int{"deleted": deleted})
+		return
+	}
+	if r.Method != http.MethodGet {
+		http.Error(w, "GET or DELETE only", http.StatusMethodNotAllowed)
+		return
+	}
+
+	out := make([]jobSummary, 0, len(jobs))
+	for _, j := range jobs {
+		j.mu.Lock()
+		if j.State == "done" {
+			out = append(out, jobSummary{
+				ID: j.ID, CreatedAt: j.CreatedAt, Quality: j.Quality,
+				Thumbnail: j.Thumbnail, PreviewSeq: j.PreviewSeq,
+				Source:        len(j.source) > 0 || j.sourcePath != "",
+				Regeneratable: len(j.image) > 0 || j.inputPath != "" || j.sourcePath != "",
+			})
+		}
+		j.mu.Unlock()
+	}
+	sort.Slice(out, func(i, k int) bool { return out[i].CreatedAt > out[k].CreatedAt })
+	writeJSON(w, out)
+}
+
+func (s *server) handleMesh(w http.ResponseWriter, r *http.Request) {
+	j := s.getJob(r, "/api/mesh/")
+	if j == nil {
+		http.Error(w, "no such job", http.StatusNotFound)
+		return
+	}
+	mesh, err := s.loadJobMesh(j)
+	if err != nil {
+		http.Error(w, "mesh not ready: "+err.Error(), http.StatusConflict)
+		return
+	}
+	writeMesh(w, mesh)
+}
+
+// writeMesh emits T2MESH01 geometry or T2MESH03 geometry followed by six-float
+// PBR attributes. It is shared by generated and component-cleanup preview meshes.
+func writeMesh(w http.ResponseWriter, mesh *meshData) {
+	w.Header().Set("Content-Type", "application/octet-stream")
+	if err := writeMeshBinary(w, mesh); err != nil {
+		log.Printf("write mesh response: %v", err)
+	}
+}
+
+func writeMeshBinary(w io.Writer, mesh *meshData) error {
+	textured := len(mesh.PBR) == 6*mesh.NVerts
+	if textured {
+		if _, err := w.Write([]byte("T2MESH03")); err != nil {
+			return err
+		}
+	} else {
+		if _, err := w.Write([]byte("T2MESH01")); err != nil {
+			return err
+		}
+	}
+	if err := binary.Write(w, binary.LittleEndian, uint32(mesh.NVerts)); err != nil {
+		return err
+	}
+	if err := binary.Write(w, binary.LittleEndian, uint32(mesh.NTris)); err != nil {
+		return err
+	}
+	if err := binary.Write(w, binary.LittleEndian, mesh.Verts); err != nil {
+		return err
+	}
+	if err := binary.Write(w, binary.LittleEndian, mesh.Normals); err != nil {
+		return err
+	}
+	if textured {
+		if err := binary.Write(w, binary.LittleEndian, mesh.PBR); err != nil {
+			return err
+		}
+	}
+	return binary.Write(w, binary.LittleEndian, mesh.Tris)
+}
+
+type exportOptions struct {
+	textureSize     int
+	componentFilter int
+}
+
+func parseExportOptions(r *http.Request) exportOptions {
+	o := exportOptions{
+		textureSize:     2048,
+		componentFilter: 2, // safe default: preserve every connected component
+	}
+	if n := int(formUint(r, "tex", uint64(o.textureSize))); n >= 256 && n <= 4096 {
+		o.textureSize = n
+	}
+	switch r.FormValue("components") {
+	case "tiny":
+		o.componentFilter = 0
+	case "largest":
+		o.componentFilter = 1
+	}
+	return o
+}
+
+func (o exportOptions) prepareKey() string {
+	return strconv.Itoa(o.componentFilter)
+}
+
+func (o exportOptions) glbKey() string {
+	return fmt.Sprintf("%d-%s", o.textureSize, o.prepareKey())
+}
+
+func (s *server) preparedExportMesh(j *job, o exportOptions) (*meshData, error) {
+	// Keep-all preview is the saved source object itself: no copying, normal
+	// recomputation, topology cleanup, or other opportunity to alter it.
+	if o.componentFilter == 2 {
+		return s.loadJobMesh(j)
+	}
+	key := o.prepareKey()
+	j.mu.Lock()
+	if j.exportKey == key && j.exportMesh != nil {
+		mesh := j.exportMesh
+		j.mu.Unlock()
+		return mesh, nil
+	}
+	j.mu.Unlock()
+	source, err := s.loadJobMesh(j)
+	if err != nil {
+		return nil, err
+	}
+	mesh, err := s.eng.PrepareMesh(source, o.componentFilter)
+	if err != nil {
+		return nil, err
+	}
+	j.mu.Lock()
+	j.exportMesh, j.exportKey = mesh, key
+	// A restored source can always be re-read. Avoid pinning duplicate full-size
+	// source and component-cleanup meshes in server memory.
+	if j.persistDir != "" {
+		j.mesh = nil
+	}
+	j.mu.Unlock()
+	return mesh, nil
+}
+
+func (s *server) handleExportPreview(w http.ResponseWriter, r *http.Request) {
+	j := s.getJob(r, "/api/export-preview/")
+	if j == nil {
+		http.Error(w, "no such job", http.StatusNotFound)
+		return
+	}
+	mesh, err := s.preparedExportMesh(j, parseExportOptions(r))
+	if err != nil {
+		http.Error(w, "prepare export: "+err.Error(), http.StatusInternalServerError)
+		return
+	}
+	writeMesh(w, mesh)
+}
+
+// handlePreview streams a recorded intermediate-preview frame for a job. With
+// ?seq=N it returns that frame by index (the browser fetches every frame it is
+// missing so the scrubber can replay the whole generation); without it, the
+// latest frame (back-compat live view). Frames are T2VOX01 voxel sets or
+// T2MESH0* keyframe meshes; the client dispatches on the magic.
+func (s *server) handlePreview(w http.ResponseWriter, r *http.Request) {
+	j := s.getJob(r, "/api/preview/")
+	if j == nil {
+		http.Error(w, "no such job", http.StatusNotFound)
+		return
+	}
+	j.mu.Lock()
+	seq := -1
+	if q := r.URL.Query().Get("seq"); q != "" {
+		if i, err := strconv.Atoi(q); err == nil {
+			seq = i
+		}
+	} else if j.PreviewSeq > 0 {
+		seq = j.PreviewSeq - 1
+	}
+	j.mu.Unlock()
+	blob, err := loadJobPreview(j, seq)
+	if err != nil {
+		http.Error(w, "no such preview frame", http.StatusConflict)
+		return
+	}
+	w.Header().Set("Content-Type", "application/octet-stream")
+	w.Write(blob)
+}
+
+// handleGLB writes the exact prepared preview mesh into a vertex-coloured GLB.
+// Both prepared geometry and final GLB are cached by their export settings.
+func (s *server) handleGLB(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet && r.Method != http.MethodHead {
+		http.Error(w, "GET or HEAD only", http.StatusMethodNotAllowed)
+		return
+	}
+	j := s.getJob(r, "/api/glb/")
+	if j == nil {
+		http.Error(w, "no such job", http.StatusNotFound)
+		return
+	}
+	o := parseExportOptions(r)
+	key := o.glbKey()
+
+	j.exportMu.Lock()
+	glb, err := func() ([]byte, error) {
+		mesh, err := s.preparedExportMesh(j, o)
+		if err != nil {
+			return nil, fmt.Errorf("prepare export: %w", err)
+		}
+		j.mu.Lock()
+		glb, cached := j.glb, j.glbKey == key && j.glb != nil
+		j.mu.Unlock()
+		if cached {
+			return glb, nil
+		}
+		started := time.Now()
+		glb, err = s.eng.BakeGLB(mesh, o.textureSize, 2 /*already prepared*/)
+		if err != nil {
+			return nil, fmt.Errorf("bake glb: %w", err)
+		}
+		j.mu.Lock()
+		j.glb, j.glbKey = glb, key
+		j.mu.Unlock()
+		log.Printf("job %s baked %.1f MiB GLB in %.1fs (%s)", j.ID,
+			float64(len(glb))/(1<<20), time.Since(started).Seconds(), key)
+		return glb, nil
+	}()
+	j.exportMu.Unlock()
+	if err != nil {
+		w.Header().Set("X-Trellis-Error", err.Error())
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	j.mu.Lock()
+	finishedAt := j.FinishedAt
+	j.mu.Unlock()
+	var modTime time.Time
+	if finishedAt > 0 {
+		modTime = time.UnixMilli(finishedAt)
+	}
+	w.Header().Set("Content-Type", "model/gltf-binary")
+	w.Header().Set("Content-Disposition", fmt.Sprintf("attachment; filename=\"trellis2-%s.glb\"", j.ID))
+	w.Header().Set("ETag", fmt.Sprintf("\"%s-%s\"", j.ID, key))
+	// ServeContent supplies Content-Length plus byte-range support. Browsers can
+	// stream these 100+ MiB assets directly to disk and resume an interrupted
+	// transfer instead of JavaScript copying the whole response into a Blob.
+	http.ServeContent(w, r, fmt.Sprintf("trellis2-%s.glb", j.ID),
+		modTime, bytes.NewReader(glb))
+}
+
+func (s *server) info() map[string]interface{} {
+	backend, caps, textured, loaded := s.eng.Info()
+	qualities := []string{"coarse"}
+	if caps&cap512 != 0 {
+		qualities = append(qualities, "512")
+	}
+	if caps&cap1024 != 0 {
+		qualities = append(qualities, "1024")
+	}
+	best := "coarse"
+	if caps&cap1024 != 0 {
+		best = "1024"
+	} else if caps&cap512 != 0 {
+		best = "512"
+	}
+	s.mu.Lock()
+	unloadIdle := s.unloadIdle
+	generationActive := s.active || s.queued > 0
+	s.mu.Unlock()
+	return map[string]interface{}{
+		"backend":           backend,
+		"qualities":         qualities,
+		"best":              best,
+		"textured":          textured,
+		"models_loaded":     loaded,
+		"unload_idle":       unloadIdle,
+		"generation_active": generationActive,
+		"defaults": map[string]interface{}{
+			"steps":         12,
+			"guidance":      7.5,
+			"texture_steps": 12,
+		},
+	}
+}
+
+func (s *server) handleInfo(w http.ResponseWriter, r *http.Request) {
+	writeJSON(w, s.info())
+}
+
+func (s *server) handleSettings(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		http.Error(w, "POST only", http.StatusMethodNotAllowed)
+		return
+	}
+	if err := r.ParseForm(); err != nil {
+		http.Error(w, "bad form: "+err.Error(), http.StatusBadRequest)
+		return
+	}
+	v := r.FormValue("unload_idle")
+	enabled := v == "1" || v == "true" || v == "on"
+	if s.setUnloadIdle(enabled) {
+		log.Printf("models unloaded while idle")
+	}
+	writeJSON(w, s.info())
+}
+
+func writeJSON(w http.ResponseWriter, v interface{}) {
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(v)
+}
+
+func fileExists(p string) bool {
+	_, err := os.Stat(p)
+	return err == nil
+}
+
+func formUint(r *http.Request, key string, def uint64) uint64 {
+	if v := r.FormValue(key); v != "" {
+		if n, err := strconv.ParseUint(v, 10, 64); err == nil {
+			return n
+		}
+	}
+	return def
+}
+
+func formFloat(r *http.Request, key string, def float32) float32 {
+	if v := r.FormValue(key); v != "" {
+		if f, err := strconv.ParseFloat(v, 32); err == nil {
+			return float32(f)
+		}
+	}
+	return def
+}
+
+func main() {
+	libPath := flag.String("lib", "../build-shared/libtrellis2.so", "path to libtrellis2.so")
+	ggufDir := flag.String("ggufs", "../ggufs", "directory with the model ggufs")
+	dino := flag.String("dino", "", "dino gguf (default <ggufs>/dino_f16.gguf)")
+	flow := flag.String("flow", "", "ss_flow gguf (default <ggufs>/ss_flow_f16.gguf)")
+	dec := flag.String("dec", "", "ss_dec gguf (default <ggufs>/ss_dec_f16.gguf)")
+	slat := flag.String("slat", "", "512 shape-slat flow gguf (default <ggufs>/slat_flow_f16.gguf)")
+	slatHR := flag.String("slat-hr", "", "1024 shape-slat flow gguf (default <ggufs>/slat_flow_1024_f16.gguf)")
+	shapeDec := flag.String("shape-dec", "", "shape decoder gguf (default <ggufs>/shape_dec_f16.gguf)")
+	shapeEnc := flag.String("shape-enc", "", "shape encoder gguf (default <ggufs>/shape_enc_f16.gguf)")
+	texDec := flag.String("tex-dec", "", "texture decoder gguf (default <ggufs>/tex_dec_f16.gguf)")
+	texSlat := flag.String("tex-slat", "", "512 texture-slat flow gguf (default <ggufs>/tex_slat_flow_512_f16.gguf)")
+	texSlatHR := flag.String("tex-slat-hr", "", "1024 texture-slat flow gguf (default <ggufs>/tex_slat_flow_1024_f16.gguf)")
+	coarse := flag.Bool("coarse", false, "coarse marching-cubes path only (skip shape-SLAT models)")
+	no1024 := flag.Bool("no-1024", false, "disable the 1024 cascade (512 fine max)")
+	noTexture := flag.Bool("no-texture", false, "disable PBR texturing (geometry only)")
+	addr := flag.String("addr", ":8742", "listen address")
+	storeDir := flag.String("store", "../generations", "durable completed-generation directory (empty disables persistence)")
+	unloadIdle := flag.Bool("unload-idle", false, "start with models unloaded and release them after each idle generation")
+	flag.Parse()
+
+	// Recorded previews: capture one voxel frame per SS step (finer than the
+	// library's ~4-frame default) so the scrubber has a smooth structure-forming
+	// sequence to replay. The library reads T2_PREVIEW_STRIDE; respect an
+	// explicit override, else default to per-step.
+	if os.Getenv("T2_PREVIEW_STRIDE") == "" {
+		os.Setenv("T2_PREVIEW_STRIDE", "1")
+	}
+
+	pick := func(explicit, name string) string {
+		if explicit != "" {
+			return explicit
+		}
+		return filepath.Join(*ggufDir, name)
+	}
+	// The fine (dual-grid) path needs the two shape-SLAT models; the 1024 cascade
+	// additionally needs the 1024 model. Missing files degrade gracefully.
+	slatPath, shapePath, slatHRPath := "", "", ""
+	shapeEncPath, texDecPath, texSlatPath, texSlatHRPath := "", "", "", ""
+	if !*coarse {
+		slatPath = pick(*slat, "slat_flow_f16.gguf")
+		shapePath = pick(*shapeDec, "shape_dec_f16.gguf")
+		if !fileExists(slatPath) || !fileExists(shapePath) {
+			log.Printf("shape-SLAT models not found, using coarse path")
+			slatPath, shapePath = "", ""
+		} else {
+			if !*no1024 {
+				slatHRPath = pick(*slatHR, "slat_flow_1024_f16.gguf")
+				if !fileExists(slatHRPath) {
+					log.Printf("1024 model not found, 512 fine max")
+					slatHRPath = ""
+				}
+			}
+			// The validated PBR path re-encodes the decoded dual grid, so all three
+			// model families are required: shape encoder, texture decoder, and flow.
+			if !*noTexture {
+				shapeEncPath = pick(*shapeEnc, "shape_enc_f16.gguf")
+				texDecPath = pick(*texDec, "tex_dec_f16.gguf")
+				texSlatPath = pick(*texSlat, "tex_slat_flow_512_f16.gguf")
+				if fileExists(shapeEncPath) && fileExists(texDecPath) && fileExists(texSlatPath) {
+					texSlatHRPath = pick(*texSlatHR, "tex_slat_flow_1024_f16.gguf")
+					if !fileExists(texSlatHRPath) {
+						if slatHRPath != "" {
+							log.Printf("1024 texture model not found, using complete 512 textured pipeline")
+							slatHRPath = ""
+						}
+						texSlatHRPath = ""
+					}
+				} else {
+					log.Printf("shape encoder or texture models not found, geometry only")
+					shapeEncPath, texDecPath, texSlatPath = "", "", ""
+				}
+			}
+		}
+	}
+
+	eng, err := newEngine(*libPath, pick(*dino, "dino_f16.gguf"),
+		pick(*flow, "ss_flow_f16.gguf"), pick(*dec, "ss_dec_f16.gguf"),
+		slatPath, slatHRPath, shapePath,
+		shapeEncPath, texDecPath, texSlatPath, texSlatHRPath, *unloadIdle)
+	if err != nil {
+		log.Fatal(err)
+	}
+	backend, caps, textured, loaded := eng.Info()
+	mode := "coarse (marching cubes)"
+	if caps&cap1024 != 0 {
+		mode = "1024 cascade (+ 512 fine, coarse)"
+	} else if caps&cap512 != 0 {
+		mode = "512 fine (+ coarse)"
+	}
+	if loaded {
+		log.Printf("models loaded, backend: %s, qualities: %s, PBR: %v", backend, mode, textured)
+	} else {
+		log.Printf("models configured for lazy load, backend: %s, qualities: %s, PBR: %v", backend, mode, textured)
+	}
+
+	s := &server{
+		eng: eng, jobs: map[string]*job{}, q: make(chan *job, 8),
+		storeDir: *storeDir, unloadIdle: *unloadIdle,
+	}
+	restored, restoreErr := s.restoreJobs()
+	if restoreErr != nil {
+		log.Printf("job persistence disabled: %v", restoreErr)
+	} else if restored > 0 {
+		log.Printf("restored %d completed generation(s) from %s", restored, *storeDir)
+	}
+	go s.worker()
+
+	web, err := fs.Sub(webFS, "web")
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	mux := http.NewServeMux()
+	indexPage, err := fs.ReadFile(web, "index.html")
+	if err != nil {
+		log.Fatal(err)
+	}
+	mux.HandleFunc("/showcase", func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/showcase" {
+			http.NotFound(w, r)
+			return
+		}
+		w.Header().Set("Content-Type", "text/html; charset=utf-8")
+		w.Write(indexPage)
+	})
+	mux.Handle("/", http.FileServer(http.FS(web)))
+	mux.HandleFunc("/api/info", s.handleInfo)
+	mux.HandleFunc("/api/settings", s.handleSettings)
+	mux.HandleFunc("/api/generate", s.handleGenerate)
+	mux.HandleFunc("/api/regenerate/", s.handleRegenerate)
+	mux.HandleFunc("/api/jobs", s.handleJobs)
+	mux.HandleFunc("/api/job/", s.handleJob)
+	mux.HandleFunc("/api/source/", s.handleSource)
+	mux.HandleFunc("/api/mesh/", s.handleMesh)
+	mux.HandleFunc("/api/export-preview/", s.handleExportPreview)
+	mux.HandleFunc("/api/preview/", s.handlePreview)
+	mux.HandleFunc("/api/glb/", s.handleGLB)
+
+	log.Printf("listening on %s", *addr)
+	log.Fatal(http.ListenAndServe(*addr, mux))
+}
diff --git a/server/persistence.go b/server/persistence.go
new file mode 100644
index 0000000..bf5eca0
--- /dev/null
+++ b/server/persistence.go
@@ -0,0 +1,349 @@
+package main
+
+import (
+	"encoding/binary"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+const persistedJobVersion = 1
+
+// persistedJob is deliberately independent of the public job JSON. Runtime
+// state, caches, and locks never reach disk; only the data needed to restore a
+// completed generation is retained.
+type persistedJob struct {
+	Version      int           `json:"version"`
+	ID           string        `json:"id"`
+	CreatedAt    int64         `json:"createdAt"`
+	StartedAt    int64         `json:"startedAt,omitempty"`
+	FinishedAt   int64         `json:"finishedAt,omitempty"`
+	DurationMS   int64         `json:"durationMs,omitempty"`
+	Quality      string        `json:"quality,omitempty"`
+	Thumbnail    string        `json:"thumbnail,omitempty"`
+	Pipeline     int           `json:"pipeline"`
+	Seed         uint64        `json:"seed"`
+	Steps        int           `json:"steps"`
+	TextureSteps int           `json:"textureSteps"`
+	Guidance     float32       `json:"guidance"`
+	Frames       []frameMeta   `json:"frames,omitempty"`
+	LivePreview  bool          `json:"livePreview,omitempty"`
+	StageTimings []stageTiming `json:"stageTimings,omitempty"`
+}
+
+func persistedFrameName(i int) string {
+	return filepath.Join("frames", fmt.Sprintf("%06d.bin", i))
+}
+
+// persistJob writes a complete job into a temporary sibling directory and then
+// renames that directory into place. Startup therefore sees either the previous
+// complete job or no job, never a half-written mesh/frame set.
+func (s *server) persistJob(j *job) error {
+	if s.storeDir == "" {
+		return nil
+	}
+
+	j.mu.Lock()
+	if j.mesh == nil {
+		j.mu.Unlock()
+		return fmt.Errorf("job %s has no mesh", j.ID)
+	}
+	manifest := persistedJob{
+		Version: persistedJobVersion, ID: j.ID, CreatedAt: j.CreatedAt,
+		StartedAt: j.StartedAt, FinishedAt: j.FinishedAt, DurationMS: j.DurationMS,
+		Quality: j.Quality, Thumbnail: j.Thumbnail,
+		Pipeline: j.pipeline, Seed: j.seed, Steps: j.steps,
+		TextureSteps: j.textureSteps, Guidance: j.guidance,
+		Frames: append([]frameMeta(nil), j.Frames...), LivePreview: j.LivePreview,
+		StageTimings: append([]stageTiming(nil), j.StageTimings...),
+	}
+	mesh := j.mesh
+	input := j.image
+	source := j.source
+	if len(source) == 0 {
+		source = input
+	}
+	previews := append([][]byte(nil), j.previews...)
+	j.mu.Unlock()
+
+	if len(previews) != len(manifest.Frames) {
+		return fmt.Errorf("job %s has %d previews but %d frame records",
+			j.ID, len(previews), len(manifest.Frames))
+	}
+	if err := os.MkdirAll(s.storeDir, 0o755); err != nil {
+		return fmt.Errorf("create job store: %w", err)
+	}
+	tmp, err := os.MkdirTemp(s.storeDir, "."+j.ID+".tmp-")
+	if err != nil {
+		return fmt.Errorf("create temporary job directory: %w", err)
+	}
+	defer os.RemoveAll(tmp)
+
+	if err := writeMeshFile(filepath.Join(tmp, "mesh.t2mesh"), mesh); err != nil {
+		return err
+	}
+	if len(source) > 0 {
+		if err := os.WriteFile(filepath.Join(tmp, "source.img"), source, 0o644); err != nil {
+			return fmt.Errorf("write source image: %w", err)
+		}
+	}
+	if len(input) > 0 {
+		if err := os.WriteFile(filepath.Join(tmp, "input.img"), input, 0o644); err != nil {
+			return fmt.Errorf("write generation input: %w", err)
+		}
+	}
+	if len(previews) > 0 {
+		if err := os.Mkdir(filepath.Join(tmp, "frames"), 0o755); err != nil {
+			return fmt.Errorf("create frame directory: %w", err)
+		}
+		for i, blob := range previews {
+			if err := os.WriteFile(filepath.Join(tmp, persistedFrameName(i)), blob, 0o644); err != nil {
+				return fmt.Errorf("write preview %d: %w", i, err)
+			}
+		}
+	}
+	data, err := json.MarshalIndent(manifest, "", "  ")
+	if err != nil {
+		return fmt.Errorf("encode manifest: %w", err)
+	}
+	data = append(data, '\n')
+	if err := os.WriteFile(filepath.Join(tmp, "manifest.json"), data, 0o644); err != nil {
+		return fmt.Errorf("write manifest: %w", err)
+	}
+
+	finalDir := filepath.Join(s.storeDir, j.ID)
+	if err := os.Rename(tmp, finalDir); err != nil {
+		return fmt.Errorf("commit job %s: %w", j.ID, err)
+	}
+
+	// Frames are immutable and now durable, so release their duplicate in-memory
+	// copies. The preview endpoint transparently reads them from finalDir.
+	j.mu.Lock()
+	j.persistDir = finalDir
+	j.meshPath = filepath.Join(finalDir, "mesh.t2mesh")
+	if len(input) > 0 {
+		j.inputPath = filepath.Join(finalDir, "input.img")
+	}
+	if len(source) > 0 {
+		j.sourcePath = filepath.Join(finalDir, "source.img")
+	}
+	j.previews = nil
+	j.mu.Unlock()
+	return nil
+}
+
+// restoreJobs scans only complete, versioned job directories. Temporary
+// directories left by a killed write and malformed/corrupt entries are ignored
+// with a log message; one bad asset must not prevent the server from starting.
+func (s *server) restoreJobs() (int, error) {
+	if s.storeDir == "" {
+		return 0, nil
+	}
+	if err := os.MkdirAll(s.storeDir, 0o755); err != nil {
+		return 0, fmt.Errorf("create job store: %w", err)
+	}
+	entries, err := os.ReadDir(s.storeDir)
+	if err != nil {
+		return 0, fmt.Errorf("read job store: %w", err)
+	}
+	restored := 0
+	for _, entry := range entries {
+		if !entry.IsDir() || strings.HasPrefix(entry.Name(), ".") {
+			continue
+		}
+		dir := filepath.Join(s.storeDir, entry.Name())
+		j, err := loadPersistedJob(dir)
+		if err != nil {
+			log.Printf("ignoring persisted job %s: %v", entry.Name(), err)
+			continue
+		}
+		s.mu.Lock()
+		if _, exists := s.jobs[j.ID]; !exists {
+			s.jobs[j.ID] = j
+			restored++
+		}
+		s.mu.Unlock()
+	}
+	return restored, nil
+}
+
+func loadPersistedJob(dir string) (*job, error) {
+	data, err := os.ReadFile(filepath.Join(dir, "manifest.json"))
+	if err != nil {
+		return nil, fmt.Errorf("read manifest: %w", err)
+	}
+	var m persistedJob
+	if err := json.Unmarshal(data, &m); err != nil {
+		return nil, fmt.Errorf("decode manifest: %w", err)
+	}
+	if m.Version != persistedJobVersion {
+		return nil, fmt.Errorf("unsupported manifest version %d", m.Version)
+	}
+	if m.ID == "" || filepath.Base(m.ID) != m.ID || m.ID != filepath.Base(dir) {
+		return nil, fmt.Errorf("invalid job id %q", m.ID)
+	}
+	meshPath := filepath.Join(dir, "mesh.t2mesh")
+	if st, err := os.Stat(meshPath); err != nil || !st.Mode().IsRegular() {
+		if err == nil {
+			err = fmt.Errorf("not a regular file")
+		}
+		return nil, fmt.Errorf("mesh: %w", err)
+	}
+	sourcePath := filepath.Join(dir, "source.img")
+	if st, err := os.Stat(sourcePath); err != nil || !st.Mode().IsRegular() {
+		sourcePath = "" // optional for generations saved before source retention
+	}
+	inputPath := filepath.Join(dir, "input.img")
+	if st, err := os.Stat(inputPath); err != nil || !st.Mode().IsRegular() {
+		inputPath = "" // legacy jobs stored their processed input as source.img
+	}
+	for i := range m.Frames {
+		if st, err := os.Stat(filepath.Join(dir, persistedFrameName(i))); err != nil || !st.Mode().IsRegular() {
+			if err == nil {
+				err = fmt.Errorf("not a regular file")
+			}
+			return nil, fmt.Errorf("preview %d: %w", i, err)
+		}
+	}
+	return &job{
+		ID: m.ID, State: "done", CreatedAt: m.CreatedAt, StartedAt: m.StartedAt,
+		FinishedAt: m.FinishedAt, DurationMS: m.DurationMS,
+		Quality: m.Quality, Thumbnail: m.Thumbnail,
+		PreviewSeq: len(m.Frames), Frames: m.Frames,
+		LivePreview: m.LivePreview || len(m.Frames) > 0, StageTimings: m.StageTimings,
+		pipeline: m.Pipeline, seed: m.Seed, steps: m.Steps,
+		textureSteps: m.TextureSteps, guidance: m.Guidance,
+		persistDir: dir, meshPath: meshPath, inputPath: inputPath, sourcePath: sourcePath,
+	}, nil
+}
+
+func (s *server) loadJobMesh(j *job) (*meshData, error) {
+	j.mu.Lock()
+	defer j.mu.Unlock()
+	if j.mesh != nil {
+		return j.mesh, nil
+	}
+	if j.meshPath == "" {
+		return nil, fmt.Errorf("mesh not ready")
+	}
+	mesh, err := readMeshFile(j.meshPath)
+	if err != nil {
+		return nil, err
+	}
+	j.mesh = mesh
+	return mesh, nil
+}
+
+func loadJobPreview(j *job, seq int) ([]byte, error) {
+	j.mu.Lock()
+	if seq < 0 || seq >= j.PreviewSeq {
+		j.mu.Unlock()
+		return nil, fmt.Errorf("no such preview frame")
+	}
+	if seq < len(j.previews) && j.previews[seq] != nil {
+		blob := j.previews[seq]
+		j.mu.Unlock()
+		return blob, nil
+	}
+	dir := j.persistDir
+	j.mu.Unlock()
+	if dir == "" {
+		return nil, fmt.Errorf("no such preview frame")
+	}
+	return os.ReadFile(filepath.Join(dir, persistedFrameName(seq)))
+}
+
+func writeMeshFile(path string, mesh *meshData) error {
+	f, err := os.OpenFile(path, os.O_CREATE|os.O_WRONLY|os.O_EXCL, 0o644)
+	if err != nil {
+		return fmt.Errorf("create mesh: %w", err)
+	}
+	if err := writeMeshBinary(f, mesh); err != nil {
+		f.Close()
+		return fmt.Errorf("write mesh: %w", err)
+	}
+	if err := f.Sync(); err != nil {
+		f.Close()
+		return fmt.Errorf("sync mesh: %w", err)
+	}
+	if err := f.Close(); err != nil {
+		return fmt.Errorf("close mesh: %w", err)
+	}
+	return nil
+}
+
+func readMeshFile(path string) (*meshData, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return nil, fmt.Errorf("open mesh: %w", err)
+	}
+	defer f.Close()
+	var magic [8]byte
+	if _, err := io.ReadFull(f, magic[:]); err != nil {
+		return nil, fmt.Errorf("read mesh magic: %w", err)
+	}
+	pbrWidth := 0
+	switch string(magic[:]) {
+	case "T2MESH01":
+	case "T2MESH02":
+		pbrWidth = 5
+	case "T2MESH03":
+		pbrWidth = 6
+	default:
+		return nil, fmt.Errorf("bad mesh magic %q", magic)
+	}
+	var nv32, nt32 uint32
+	if err := binary.Read(f, binary.LittleEndian, &nv32); err != nil {
+		return nil, fmt.Errorf("read vertex count: %w", err)
+	}
+	if err := binary.Read(f, binary.LittleEndian, &nt32); err != nil {
+		return nil, fmt.Errorf("read triangle count: %w", err)
+	}
+	if nv32 == 0 || nt32 == 0 || nv32 > 100_000_000 || nt32 > 100_000_000 {
+		return nil, fmt.Errorf("invalid mesh size %d vertices, %d triangles", nv32, nt32)
+	}
+	nv, nt := int(nv32), int(nt32)
+	st, err := f.Stat()
+	if err != nil {
+		return nil, fmt.Errorf("stat mesh: %w", err)
+	}
+	expected := int64(16) + int64(nv)*24 + int64(nv*pbrWidth)*4 + int64(nt)*12
+	if st.Size() != expected {
+		return nil, fmt.Errorf("mesh size is %d bytes, expected %d", st.Size(), expected)
+	}
+	m := &meshData{NVerts: nv, NTris: nt, Verts: make([]float32, 3*nv), Normals: make([]float32, 3*nv)}
+	if err := binary.Read(f, binary.LittleEndian, m.Verts); err != nil {
+		return nil, fmt.Errorf("read vertices: %w", err)
+	}
+	if err := binary.Read(f, binary.LittleEndian, m.Normals); err != nil {
+		return nil, fmt.Errorf("read normals: %w", err)
+	}
+	if pbrWidth != 0 {
+		stored := make([]float32, pbrWidth*nv)
+		if err := binary.Read(f, binary.LittleEndian, stored); err != nil {
+			return nil, fmt.Errorf("read PBR attributes: %w", err)
+		}
+		if pbrWidth == 6 {
+			m.PBR = stored
+		} else {
+			m.PBR = make([]float32, 6*nv)
+			for i := 0; i < nv; i++ {
+				copy(m.PBR[6*i:6*i+5], stored[5*i:5*i+5])
+				m.PBR[6*i+5] = 1
+			}
+		}
+	}
+	m.Tris = make([]int32, 3*nt)
+	if err := binary.Read(f, binary.LittleEndian, m.Tris); err != nil {
+		return nil, fmt.Errorf("read triangles: %w", err)
+	}
+	var extra [1]byte
+	if n, err := f.Read(extra[:]); err != io.EOF || n != 0 {
+		return nil, fmt.Errorf("mesh contains trailing data")
+	}
+	return m, nil
+}
diff --git a/server/persistence_test.go b/server/persistence_test.go
new file mode 100644
index 0000000..93dd091
--- /dev/null
+++ b/server/persistence_test.go
@@ -0,0 +1,249 @@
+package main
+
+import (
+	"bytes"
+	"encoding/json"
+	"mime/multipart"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func testPersistedMesh(textured bool) *meshData {
+	m := &meshData{
+		NVerts: 3, NTris: 1,
+		Verts:   []float32{0, 0, 0, 1, 0, 0, 0, 1, 0},
+		Normals: []float32{0, 0, 1, 0, 0, 1, 0, 0, 1},
+		Tris:    []int32{0, 1, 2},
+	}
+	if textured {
+		m.PBR = []float32{
+			1, 0, 0, 0.1, 0.2, 1,
+			0, 1, 0, 0.3, 0.4, 0.9,
+			0, 0, 1, 0.5, 0.6, 0.8,
+		}
+	}
+	return m
+}
+
+func TestMeshFileRoundTrip(t *testing.T) {
+	for _, textured := range []bool{false, true} {
+		t.Run(map[bool]string{false: "geometry", true: "pbr"}[textured], func(t *testing.T) {
+			path := filepath.Join(t.TempDir(), "mesh.t2mesh")
+			want := testPersistedMesh(textured)
+			if err := writeMeshFile(path, want); err != nil {
+				t.Fatal(err)
+			}
+			got, err := readMeshFile(path)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if !reflect.DeepEqual(got, want) {
+				t.Fatalf("mesh round trip mismatch\n got: %#v\nwant: %#v", got, want)
+			}
+		})
+	}
+}
+
+func TestPersistAndRestoreCompletedJob(t *testing.T) {
+	store := t.TempDir()
+	s := &server{jobs: map[string]*job{}, storeDir: store}
+	wantFrames := []frameMeta{
+		{Stage: "sampling sparse structure", Step: 1, Total: 2, Kind: "voxel"},
+		{Stage: "sampling shape SLAT", Step: 2, Total: 2, Kind: "mesh"},
+	}
+	wantPreviews := [][]byte{[]byte("T2VOX01-frame"), []byte("T2MESH01-frame")}
+	j := &job{
+		ID: "0123456789abcdef", State: "running", CreatedAt: 123456789,
+		StartedAt: 123456800, FinishedAt: 123499000, DurationMS: 42200,
+		Quality: "1024", Thumbnail: "data:image/jpeg;base64,dGVzdA==",
+		PreviewSeq: len(wantFrames), Frames: wantFrames, LivePreview: true,
+		StageTimings: []stageTiming{{Stage: "sampling sparse structure", Milliseconds: 21000}},
+		pipeline:     pipe1024, seed: 42, steps: 12, textureSteps: 10, guidance: 7.5,
+		previews: wantPreviews, mesh: testPersistedMesh(true),
+		image: []byte("processed-input"), source: []byte("exact-original"),
+	}
+	if err := s.persistJob(j); err != nil {
+		t.Fatal(err)
+	}
+	if len(j.previews) != 0 || j.persistDir == "" || j.meshPath == "" ||
+		j.inputPath == "" || j.sourcePath == "" {
+		t.Fatalf("persist did not switch assets to disk: previews=%d dir=%q mesh=%q input=%q source=%q",
+			len(j.previews), j.persistDir, j.meshPath, j.inputPath, j.sourcePath)
+	}
+
+	restarted := &server{jobs: map[string]*job{}, storeDir: store}
+	n, err := restarted.restoreJobs()
+	if err != nil || n != 1 {
+		t.Fatalf("restoreJobs() = %d, %v; want 1, nil", n, err)
+	}
+	got := restarted.jobs[j.ID]
+	if got == nil || got.State != "done" || got.Quality != "1024" ||
+		got.Thumbnail != j.Thumbnail || got.CreatedAt != j.CreatedAt ||
+		got.StartedAt != j.StartedAt || got.FinishedAt != j.FinishedAt ||
+		got.DurationMS != j.DurationMS || got.LivePreview != j.LivePreview ||
+		!reflect.DeepEqual(got.StageTimings, j.StageTimings) {
+		t.Fatalf("restored metadata = %#v", got)
+	}
+	if got.mesh != nil || len(got.previews) != 0 {
+		t.Fatal("restored binary assets should remain lazy until requested")
+	}
+	if source, err := os.ReadFile(got.sourcePath); err != nil || string(source) != "exact-original" {
+		t.Fatalf("restored source image = %q, %v", source, err)
+	}
+	if input, err := os.ReadFile(got.inputPath); err != nil || string(input) != "processed-input" {
+		t.Fatalf("restored generation input = %q, %v", input, err)
+	}
+	rr := httptest.NewRecorder()
+	restarted.handleSource(rr, httptest.NewRequest(http.MethodGet, "/api/source/"+j.ID, nil))
+	if rr.Code != http.StatusOK || rr.Body.String() != "exact-original" {
+		t.Fatalf("GET source = %d %q", rr.Code, rr.Body.String())
+	}
+	mesh, err := restarted.loadJobMesh(got)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(mesh, j.mesh) {
+		t.Fatal("restored mesh mismatch")
+	}
+	for i, want := range wantPreviews {
+		blob, err := loadJobPreview(got, i)
+		if err != nil {
+			t.Fatalf("preview %d: %v", i, err)
+		}
+		if !bytes.Equal(blob, want) {
+			t.Fatalf("preview %d = %q, want %q", i, blob, want)
+		}
+	}
+}
+
+func TestRegenerateUsesPersistedInputWithoutUpload(t *testing.T) {
+	dir := t.TempDir()
+	inputPath := filepath.Join(dir, "input.img")
+	sourcePath := filepath.Join(dir, "source.img")
+	if err := os.WriteFile(inputPath, []byte("processed-input"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(sourcePath, []byte("exact-original"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	old := &job{
+		ID: "old", State: "done", CreatedAt: 1, Quality: "512", Thumbnail: "thumb",
+		inputPath: inputPath, sourcePath: sourcePath, pipeline: pipe512,
+		seed: 7, steps: 8, textureSteps: 9, guidance: 6.5,
+	}
+	s := &server{jobs: map[string]*job{"old": old}, q: make(chan *job, 1)}
+	req := httptest.NewRequest(http.MethodPost, "/api/regenerate/old",
+		strings.NewReader("quality=1024&seed=42&steps=14&texture_steps=15&guidance=8&preview=0"))
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	rr := httptest.NewRecorder()
+	s.handleRegenerate(rr, req)
+	if rr.Code != http.StatusOK {
+		t.Fatalf("POST regenerate = %d: %s", rr.Code, rr.Body.String())
+	}
+	var response map[string]string
+	if err := json.Unmarshal(rr.Body.Bytes(), &response); err != nil {
+		t.Fatal(err)
+	}
+	regenerated := s.jobs[response["job"]]
+	if regenerated == nil {
+		t.Fatal("regenerated job was not queued")
+	}
+	if string(regenerated.image) != "processed-input" || string(regenerated.source) != "exact-original" {
+		t.Fatalf("regenerated bytes = input %q, source %q", regenerated.image, regenerated.source)
+	}
+	if regenerated.Quality != "1024" || regenerated.pipeline != pipe1024 ||
+		regenerated.background != backgroundKeep || regenerated.seed != 42 ||
+		regenerated.steps != 14 || regenerated.textureSteps != 15 ||
+		regenerated.guidance != 8 || regenerated.LivePreview {
+		t.Fatalf("regenerated settings = %#v", regenerated)
+	}
+}
+
+func TestGenerateKeepsOriginalSeparateFromProcessedInput(t *testing.T) {
+	var body bytes.Buffer
+	mw := multipart.NewWriter(&body)
+	inputPart, err := mw.CreateFormFile("image", "input.png")
+	if err != nil {
+		t.Fatal(err)
+	}
+	inputPart.Write([]byte("processed-png"))
+	sourcePart, err := mw.CreateFormFile("source", "camera-original.webp")
+	if err != nil {
+		t.Fatal(err)
+	}
+	sourcePart.Write([]byte("exact-original-webp"))
+	if err := mw.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	s := &server{jobs: map[string]*job{}, q: make(chan *job, 1)}
+	req := httptest.NewRequest(http.MethodPost, "/api/generate", &body)
+	req.Header.Set("Content-Type", mw.FormDataContentType())
+	rr := httptest.NewRecorder()
+	s.handleGenerate(rr, req)
+	if rr.Code != http.StatusOK {
+		t.Fatalf("POST generate = %d: %s", rr.Code, rr.Body.String())
+	}
+	var response map[string]string
+	if err := json.Unmarshal(rr.Body.Bytes(), &response); err != nil {
+		t.Fatal(err)
+	}
+	j := s.jobs[response["job"]]
+	if j == nil || string(j.image) != "processed-png" || string(j.source) != "exact-original-webp" {
+		t.Fatalf("queued job bytes = %#v", j)
+	}
+}
+
+func TestServerHistoryListAndDelete(t *testing.T) {
+	root := t.TempDir()
+	oldDir := filepath.Join(root, "old")
+	if err := os.Mkdir(oldDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	old := &job{ID: "old", State: "done", CreatedAt: 10, Quality: "512", persistDir: oldDir}
+	newer := &job{ID: "new", State: "done", CreatedAt: 20, Quality: "1024", Thumbnail: "thumb"}
+	active := &job{ID: "active", State: "running", CreatedAt: 30}
+	s := &server{jobs: map[string]*job{"old": old, "new": newer, "active": active}}
+
+	rr := httptest.NewRecorder()
+	s.handleJobs(rr, httptest.NewRequest(http.MethodGet, "/api/jobs", nil))
+	if rr.Code != http.StatusOK {
+		t.Fatalf("GET /api/jobs = %d: %s", rr.Code, rr.Body.String())
+	}
+	var got []jobSummary
+	if err := json.Unmarshal(rr.Body.Bytes(), &got); err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 2 || got[0].ID != "new" || got[1].ID != "old" {
+		t.Fatalf("history order/content = %#v", got)
+	}
+
+	rr = httptest.NewRecorder()
+	s.handleJob(rr, httptest.NewRequest(http.MethodDelete, "/api/job/old", nil))
+	if rr.Code != http.StatusNoContent {
+		t.Fatalf("DELETE /api/job/old = %d: %s", rr.Code, rr.Body.String())
+	}
+	if s.jobs["old"] != nil {
+		t.Fatal("deleted job remains in server index")
+	}
+	if _, err := os.Stat(oldDir); !os.IsNotExist(err) {
+		t.Fatalf("deleted job directory still exists: %v", err)
+	}
+}
+
+func TestRestoreIgnoresIncompleteTemporaryDirectory(t *testing.T) {
+	store := t.TempDir()
+	if err := os.Mkdir(filepath.Join(store, ".unfinished.tmp-123"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	s := &server{jobs: map[string]*job{}, storeDir: store}
+	n, err := s.restoreJobs()
+	if err != nil || n != 0 {
+		t.Fatalf("restoreJobs() = %d, %v; want 0, nil", n, err)
+	}
+}
diff --git a/server/web/index.html b/server/web/index.html
new file mode 100644
index 0000000..83e13fa
--- /dev/null
+++ b/server/web/index.html
@@ -0,0 +1,1946 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>trellis2.cpp — image to 3D mesh</title>
+<script>
+  if (location.pathname === "/showcase") {
+    document.documentElement.classList.add("showcase-only");
+    document.title = "trellis2.cpp — showcase";
+  }
+</script>
+<style>
+  :root {
+    --bg: #101418; --panel: #1a2027; --edge: #2a333d;
+    --text: #d7dee6; --dim: #8b98a5; --accent: #4da3ff; --err: #ff6b6b;
+  }
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body {
+    background: var(--bg); color: var(--text);
+    font: 14px/1.45 system-ui, -apple-system, sans-serif;
+    display: flex; flex-direction: column; height: 100vh; overflow: hidden;
+  }
+  header {
+    padding: 10px 16px; border-bottom: 1px solid var(--edge);
+    display: flex; align-items: baseline; gap: 12px; flex-wrap: wrap;
+  }
+  header h1 { font-size: 16px; font-weight: 600; }
+  header .sub { color: var(--dim); font-size: 12px; }
+  main { flex: 1; display: flex; min-height: 0; }
+  #side {
+    width: 300px; min-width: 300px; border-right: 1px solid var(--edge);
+    padding: 14px; display: flex; flex-direction: column; gap: 12px;
+    overflow-y: auto; background: var(--panel);
+  }
+  #drop {
+    border: 2px dashed var(--edge); border-radius: 10px; padding: 14px;
+    text-align: center; color: var(--dim); cursor: pointer;
+    transition: border-color .15s;
+  }
+  #drop.hover, #drop:hover { border-color: var(--accent); }
+  #drop img {
+    max-width: 100%; max-height: 180px; border-radius: 6px;
+    background-color: #d8d8d8;
+    background-image: linear-gradient(45deg,#aaa 25%,transparent 25%),
+                      linear-gradient(-45deg,#aaa 25%,transparent 25%),
+                      linear-gradient(45deg,transparent 75%,#aaa 75%),
+                      linear-gradient(-45deg,transparent 75%,#aaa 75%);
+    background-size: 16px 16px; background-position: 0 0,0 8px,8px -8px,-8px 0;
+  }
+  label { color: var(--dim); font-size: 12px; display: block; margin-bottom: 3px; }
+  input[type=number] {
+    width: 100%; background: var(--bg); color: var(--text);
+    border: 1px solid var(--edge); border-radius: 6px; padding: 6px 8px;
+  }
+  .row { display: flex; gap: 8px; }
+  .row > div { flex: 1; }
+  button {
+    background: var(--accent); color: #06121f; border: 0; border-radius: 8px;
+    padding: 10px; font-weight: 700; font-size: 14px; cursor: pointer;
+  }
+  button:disabled { opacity: .45; cursor: default; }
+  #status { font-size: 13px; color: var(--dim); min-height: 34px; }
+  #status.error { color: var(--err); }
+  .idle-option {
+    display: flex; align-items: center; gap: 7px; margin: -2px 0 0;
+    color: var(--dim); cursor: pointer; user-select: none;
+  }
+  .idle-option input { accent-color: var(--accent); }
+  #bar { height: 6px; background: var(--edge); border-radius: 3px; overflow: hidden; display: none; }
+  #bar > div { height: 100%; width: 0%; background: var(--accent); transition: width .3s; }
+  #meshinfo { font-size: 12px; color: var(--dim); }
+  #exportpanel {
+    border-top: 1px solid var(--edge); padding-top: 10px;
+    display: flex; flex-direction: column; gap: 8px;
+  }
+  #exportpanel select {
+    width: 100%; background: var(--bg); color: var(--text);
+    border: 1px solid var(--edge); border-radius: 6px; padding: 6px 8px;
+  }
+  .export-actions { display: grid; grid-template-columns: 1fr 1fr; gap: 8px; }
+  .export-actions button { padding: 8px 6px; font-size: 12px; }
+  #exportinfo { min-height: 17px; font-size: 11px; color: var(--dim); }
+  #view { flex: 1; position: relative; min-width: 0; }
+  canvas#gl { width: 100%; height: 100%; display: block; }
+  #hint {
+    position: absolute; bottom: 10px; left: 12px; color: var(--dim);
+    font-size: 12px; pointer-events: none;
+  }
+  #timeline {
+    position: absolute; left: 12px; right: 12px; bottom: 10px;
+    display: none; align-items: center; gap: 10px;
+    background: rgba(16,20,24,.72); border: 1px solid var(--edge);
+    border-radius: 8px; padding: 7px 12px; backdrop-filter: blur(4px);
+  }
+  #timeline input[type=range] { flex: 1; accent-color: var(--accent); min-width: 0; }
+  #tlplay {
+    background: var(--bg); color: var(--text); border: 1px solid var(--edge);
+    border-radius: 6px; width: 30px; height: 26px; cursor: pointer; flex: none;
+  }
+  #tllabel {
+    font-size: 12px; color: var(--dim); flex: none;
+    min-width: 132px; text-align: right; white-space: nowrap;
+    font-variant-numeric: tabular-nums;
+  }
+  .toggles { display: flex; gap: 8px; }
+  .toggles button {
+    flex: 1; background: var(--bg); color: var(--dim);
+    border: 1px solid var(--edge); font-weight: 500; padding: 7px;
+  }
+  .toggles button.on { color: var(--accent); border-color: var(--accent); }
+  #histhead { display: flex; align-items: center; justify-content: space-between; }
+  #histactions { display: flex; align-items: center; gap: 4px; }
+  #showcasebtn, #histclear {
+    width: auto; background: none; border: 0; color: var(--dim);
+    font-size: 11px; font-weight: 500; padding: 2px 4px; cursor: pointer;
+  }
+  #showcasebtn:hover { color: var(--accent); }
+  #histclear:hover { color: var(--err); }
+  #hist { display: grid; grid-template-columns: repeat(4, 1fr); gap: 6px; }
+  .hitem {
+    position: relative; aspect-ratio: 1; border: 1px solid var(--edge);
+    border-radius: 6px; overflow: hidden; cursor: pointer; background: var(--bg);
+  }
+  .hitem.active { border-color: var(--accent); }
+  .hitem img { width: 100%; height: 100%; object-fit: cover; display: block; }
+  .hitem .q {
+    position: absolute; left: 0; right: 0; bottom: 0; padding: 1px 0;
+    background: rgba(0,0,0,.55); color: #fff; font-size: 9px; text-align: center;
+  }
+  .hitem .x {
+    position: absolute; top: 1px; right: 1px; width: 15px; height: 15px;
+    line-height: 14px; text-align: center; font-size: 12px; color: #fff;
+    background: rgba(0,0,0,.5); border-radius: 50%; opacity: 0; transition: opacity .1s;
+  }
+  .hitem:hover .x { opacity: 1; }
+  .hitem .x:hover { background: var(--err); }
+  #showcasehud {
+    position: absolute; top: 12px; right: 12px; display: none;
+    align-items: center; gap: 10px; max-width: calc(100% - 24px);
+    background: rgba(16,20,24,.82); border: 1px solid var(--edge);
+    border-radius: 8px; padding: 7px 9px 7px 12px; backdrop-filter: blur(4px);
+  }
+  #showcaselabel {
+    color: var(--text); font-size: 12px; min-width: 260px; text-align: right;
+    white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+    font-variant-numeric: tabular-nums;
+  }
+  #showcasestop {
+    width: auto; padding: 4px 8px; background: var(--bg); color: var(--dim);
+    border: 1px solid var(--edge); border-radius: 6px; font-size: 11px;
+  }
+  #showcasesource {
+    display: none; position: fixed; z-index: 20; object-fit: contain;
+    left: 50%; top: 50%; width: min(82vw, 1080px); height: 78vh;
+    transform: translate(-50%, -50%); opacity: 0;
+    border-radius: 14px; background: rgba(8, 10, 13, .8);
+    box-shadow: 0 24px 90px rgba(0, 0, 0, .7);
+    transition: left 1.2s cubic-bezier(.4,0,.2,1),
+                top 1.2s cubic-bezier(.4,0,.2,1),
+                width 1.2s cubic-bezier(.4,0,.2,1),
+                height 1.2s cubic-bezier(.4,0,.2,1),
+                transform 1.2s cubic-bezier(.4,0,.2,1),
+                opacity .35s ease;
+    pointer-events: none;
+  }
+  #showcaseempty {
+    display: none; position: absolute; inset: 0; z-index: 12;
+    place-items: center; color: var(--dim); font-size: 16px;
+    text-align: center; padding: 24px;
+  }
+  html.showcase-only header,
+  html.showcase-only #side,
+  html.showcase-only #hint,
+  html.showcase-only #timeline { display: none !important; }
+  html.showcase-only main { height: 100vh; width: 100vw; }
+  html.showcase-only #view { width: 100vw; height: 100vh; flex: none; }
+  html.showcase-only #showcasehud {
+    top: auto; right: auto; left: 18px; bottom: 18px;
+    max-width: calc(100% - 36px); padding: 8px 12px;
+    border-color: rgba(255,255,255,.08); border-radius: 12px;
+    background: rgba(10,13,17,.68); pointer-events: none;
+  }
+  html.showcase-only #showcaselabel { min-width: 0; text-align: left; }
+  html.showcase-only #showcasestop { display: none; }
+  html.showcase-only #showcasesource { display: block; }
+  html.showcase-only #showcasesource.visible { opacity: 1; }
+  html.showcase-only #showcasesource.corner {
+    left: calc(100% - 24px); top: 24px; width: min(24vw, 300px); height: 24vh;
+    transform: translate(-100%, 0);
+    border-radius: 10px; box-shadow: 0 12px 40px rgba(0,0,0,.55);
+  }
+  html.showcase-only #showcaseempty.visible { display: grid; }
+  footer { font-size: 11px; color: var(--dim); }
+  a { color: var(--accent); }
+</style>
+</head>
+<body>
+<header>
+  <h1>trellis2.cpp</h1>
+  <span class="sub">image &rarr; 3D mesh &middot; TRELLIS.2 stage-1 geometry &middot; pure C++/ggml &middot; backend: <span id="backend">…</span></span>
+</header>
+<main>
+  <div id="side">
+    <div id="drop" tabindex="0">
+      <span id="droptext">drop an image here or click to choose<br>
+      <small>transparent, black, and white backgrounds supported</small></span>
+    </div>
+    <input id="file" type="file" accept="image/*" hidden>
+    <div>
+      <label for="quality">quality</label>
+      <select id="quality" style="width:100%;background:var(--bg);color:var(--text);border:1px solid var(--edge);border-radius:6px;padding:6px 8px"></select>
+    </div>
+    <div>
+      <label for="background">background</label>
+      <select id="background" style="width:100%;background:var(--bg);color:var(--text);border:1px solid var(--edge);border-radius:6px;padding:6px 8px">
+        <option value="auto" selected>auto-remove black or white</option>
+        <option value="keep">keep original</option>
+        <option value="black">remove black</option>
+        <option value="white">remove white</option>
+      </select>
+    </div>
+    <div class="row">
+      <div><label for="seed">seed</label><input id="seed" type="number" value="42" min="0"></div>
+      <div><label for="steps">shape steps</label><input id="steps" type="number" value="12" min="1" max="50"></div>
+      <div><label for="texsteps">material steps</label><input id="texsteps" type="number" value="12" min="1" max="50"></div>
+      <div><label for="guidance">guidance</label><input id="guidance" type="number" value="7.5" step="0.5" min="0" max="20"></div>
+    </div>
+    <button id="go" disabled>Generate 3D mesh</button>
+    <label class="idle-option" for="unloadidle"
+           title="release model VRAM between generations; the next generation reloads the models">
+      <input id="unloadidle" type="checkbox">
+      <span>free VRAM when idle</span>
+    </label>
+    <div id="bar"><div></div></div>
+    <div id="status">waiting for an image</div>
+    <div id="meshinfo"></div>
+    <div id="exportpanel">
+      <label style="margin:0">asset export</label>
+      <div class="row">
+        <div>
+          <label for="exportcomponents">component cleanup</label>
+          <select id="exportcomponents">
+            <option value="all" selected>keep all components</option>
+            <option value="tiny">remove tiny fragments</option>
+            <option value="largest">keep largest connected piece only</option>
+          </select>
+        </div>
+      </div>
+      <button id="regen" disabled title="run TRELLIS again from the full-resolution image saved on the server">regenerate from saved image</button>
+      <div class="export-actions">
+        <button id="pexport" disabled>preview cleanup</button>
+        <button id="dglb" disabled>download GLB</button>
+      </div>
+      <div id="exportinfo">generate or open a mesh to enable export</div>
+    </div>
+    <div class="toggles">
+      <button id="twire">wireframe</button>
+      <button id="tspin" class="on">auto-rotate</button>
+      <button id="tsteps" aria-pressed="false"
+              title="record the shape forming; adds CPU decodes between GPU inference steps">live steps: off</button>
+      <button id="tkf" title="also record coarse mesh keyframes of the shape stage forming (slower)">keyframes</button>
+    </div>
+    <div id="histwrap" style="display:none">
+      <div id="histhead">
+        <label style="margin:0">past generations</label>
+        <div id="histactions">
+          <button id="showcasebtn" title="open the full-screen showcase at /showcase">showcase</button>
+          <button id="histclear" title="delete all saved generations from the server">clear</button>
+        </div>
+      </div>
+      <div id="hist"></div>
+    </div>
+    <footer><em>live steps</em> records each stage in 3D as it computes — the
+    sparse structure emerging as 64&sup3; voxels, then the final dual-grid mesh —
+    and a scrubber lets you replay the whole generation. <em>keyframes</em> adds
+    coarse meshes of the shape stage forming (a few extra decodes, slower). Turn
+    <em>live steps</em> off for the fastest run. <em>showcase</em> opens a separate
+    full-screen presentation at <code>/showcase</code>.</footer>
+  </div>
+  <div id="view">
+    <canvas id="gl"></canvas>
+    <img id="showcasesource" alt="generation source image">
+    <div id="showcaseempty">No saved generations yet.<br>Generate an asset from the main page first.</div>
+    <div id="showcasehud">
+      <span id="showcaselabel"></span>
+      <button id="showcasestop">stop</button>
+    </div>
+    <div id="hint">drag: rotate (trackball) &middot; wheel: zoom &middot; right-drag / shift-drag: pan &middot; double-click: reset view</div>
+    <div id="timeline">
+      <button id="tlplay" title="play the generation back">&#9654;</button>
+      <input id="tlrange" type="range" min="0" max="0" value="0" step="1"
+             title="scrub through the recorded generation stages">
+      <span id="tllabel"></span>
+    </div>
+  </div>
+</main>
+<script>
+"use strict";
+
+/* ── upload / job flow ──────────────────────────────────────────────────── */
+const $ = id => document.getElementById(id);
+const showcasePage = document.documentElement.classList.contains("showcase-only");
+let imageBlob = null;
+let stepsOn = false;  // preview decoding is deliberately opt-in: it stalls GPU inference
+
+let kfOn = false;     // also record coarse mesh keyframes during the shape stage (opt-in, slower)
+$("tsteps").addEventListener("click", () => {
+  setLiveSteps(!stepsOn);
+});
+function setLiveSteps(enabled) {
+  stepsOn = enabled;
+  $("tsteps").classList.toggle("on", enabled);
+  $("tsteps").textContent = `live steps: ${enabled ? "on" : "off"}`;
+  $("tsteps").setAttribute("aria-pressed", String(enabled));
+  if (!enabled) {
+    kfOn = false;
+    $("tkf").classList.remove("on");
+  }
+  $("tkf").disabled = !enabled;
+}
+setLiveSteps(false);
+$("tkf").addEventListener("click", () => {
+  kfOn = !kfOn;
+  $("tkf").classList.toggle("on", kfOn);
+});
+
+const QUALITY_LABELS = {
+  coarse: "coarse preview (64³, fast)",
+  "512":  "512³ fine",
+  "1024": "1024³ cascade (high detail, slow)",
+};
+let backendName = "";
+function applyRuntimeInfo(i) {
+  backendName = i.backend || backendName;
+  $("backend").textContent = backendName
+    + (i.models_loaded === false ? " · models unloaded" : "");
+  $("unloadidle").checked = !!i.unload_idle;
+}
+async function refreshRuntimeInfo() {
+  const r = await fetch("/api/info");
+  if (!r.ok) throw new Error(await r.text());
+  const i = await r.json();
+  applyRuntimeInfo(i);
+  return i;
+}
+fetch("/api/info").then(r => r.json())
+  .then(i => {
+    applyRuntimeInfo(i);
+    const sel = $("quality");
+    (i.qualities || ["coarse"]).forEach(q => {
+      const o = document.createElement("option");
+      o.value = q; o.textContent = QUALITY_LABELS[q] || q;
+      if (q === i.best) o.selected = true;
+      sel.appendChild(o);
+    });
+    $("texsteps").disabled = !i.textured;
+  })
+  .catch(() => { $("backend").textContent = "?"; });
+
+$("unloadidle").addEventListener("change", async () => {
+  const cb = $("unloadidle"), enabled = cb.checked;
+  cb.disabled = true;
+  try {
+    const body = new URLSearchParams({ unload_idle: enabled ? "1" : "0" });
+    const r = await fetch("/api/settings", { method: "POST", body });
+    if (!r.ok) throw new Error(await r.text());
+    const i = await r.json();
+    applyRuntimeInfo(i);
+    if (!i.models_loaded)
+      setStatus("models unloaded · the next generation will reload them");
+    else if (i.unload_idle && i.generation_active)
+      setStatus("models will unload when generation finishes");
+    else
+      setStatus(i.unload_idle ? "models will unload when idle" : "models will remain loaded");
+  } catch (e) {
+    cb.checked = !enabled;
+    setStatus("could not change VRAM policy: " + e.message, true);
+  } finally {
+    cb.disabled = false;
+  }
+});
+
+function setStatus(msg, isErr) {
+  $("status").textContent = msg;
+  $("status").className = isErr ? "error" : "";
+}
+
+// Deterministic solid-background cleanup. Auto mode trusts a meaningful
+// existing alpha mask; otherwise it detects a mostly black/white border and
+// flood-fills only colour-similar pixels connected to that border. This avoids
+// deleting enclosed black/white details in the subject. Alpha is feathered
+// across the last 60 colour levels to avoid a hard fringe.
+function removeSolidBackground(image, requested) {
+  const data = image.data, w = image.width, h = image.height, n = w * h;
+  if (requested === "keep") return { mode: "keep", changed: 0 };
+  let mode = requested;
+  if (mode === "auto") {
+    let translucent = 0;
+    for (let i = 0; i < n; i++) if (data[i * 4 + 3] < 250) translucent++;
+    if (translucent > Math.max(4, Math.floor(n / 100)))
+      return { mode: "alpha", changed: 0 };
+
+    let border = 0, dark = 0, light = 0;
+    const sample = (x, y) => {
+      const i = (y * w + x) * 4, r = data[i], g = data[i+1], b = data[i+2];
+      border++; if (Math.max(r, g, b) <= 80) dark++; if (Math.min(r, g, b) >= 175) light++;
+    };
+    for (let x = 0; x < w; x++) { sample(x, 0); if (h > 1) sample(x, h - 1); }
+    for (let y = 1; y + 1 < h; y++) { sample(0, y); if (w > 1) sample(w - 1, y); }
+    let dc = 0, lc = 0;
+    for (const [x, y] of [[0,0],[w-1,0],[0,h-1],[w-1,h-1]]) {
+      const i = (y * w + x) * 4, r = data[i], g = data[i+1], b = data[i+2];
+      if (Math.max(r, g, b) <= 80) dc++; if (Math.min(r, g, b) >= 175) lc++;
+    }
+    const isDark = dark / border >= .55 || dc >= 3;
+    const isLight = light / border >= .55 || lc >= 3;
+    if (!isDark && !isLight) return { mode: "none", changed: 0 };
+    mode = isDark && (!isLight || dark >= light) ? "black" : "white";
+  }
+
+  const distance = i => {
+    const o = i * 4, r = data[o], g = data[o+1], b = data[o+2];
+    return mode === "black" ? Math.max(r, g, b) : 255 - Math.min(r, g, b);
+  };
+  const seen = new Uint8Array(n), queue = new Int32Array(n);
+  let head = 0, tail = 0;
+  const visit = i => {
+    if (!seen[i] && distance(i) <= 80) { seen[i] = 1; queue[tail++] = i; }
+  };
+  for (let x = 0; x < w; x++) { visit(x); if (h > 1) visit((h - 1) * w + x); }
+  for (let y = 1; y + 1 < h; y++) { visit(y * w); if (w > 1) visit(y * w + w - 1); }
+
+  let changed = 0;
+  while (head < tail) {
+    const i = queue[head++], d = distance(i), o = i * 4;
+    let t = Math.max(0, Math.min(1, (d - 12) / 60));
+    t = t * t * (3 - 2 * t);
+    const a = Math.round(data[o+3] * t);
+    if (a !== data[o+3]) { data[o+3] = a; changed++; }
+    const x = i % w, y = Math.floor(i / w);
+    if (x > 0) visit(i - 1); if (x + 1 < w) visit(i + 1);
+    if (y > 0) visit(i - w); if (y + 1 < h) visit(i + w);
+  }
+  return { mode, changed };
+}
+
+// Re-encode whatever the browser can decode as PNG (keeps/adds alpha and
+// guarantees the server-side stb decoder understands WebP/AVIF inputs).
+async function toPNG(file, backgroundMode) {
+  const bmp = await createImageBitmap(file);
+  const cv = document.createElement("canvas");
+  cv.width = bmp.width; cv.height = bmp.height;
+  const ctx = cv.getContext("2d", { willReadFrequently: true });
+  ctx.drawImage(bmp, 0, 0); bmp.close();
+  const pixels = ctx.getImageData(0, 0, cv.width, cv.height);
+  const cleanup = removeSolidBackground(pixels, backgroundMode);
+  if (cleanup.changed) ctx.putImageData(pixels, 0, 0);
+  const blob = await new Promise((res, rej) => cv.toBlob(
+    b => b ? res(b) : rej(new Error("PNG encoding failed")), "image/png"));
+  return { blob, cleanup };
+}
+
+let sourceImageFile = null, imageObjectURL = "", imageLoadSeq = 0;
+async function setImage(file) {
+  if (!file || !file.type.startsWith("image/")) return;
+  sourceImageFile = file;
+  const seq = ++imageLoadSeq;
+  let cleanup;
+  try {
+    const converted = await toPNG(file, $("background").value);
+    if (seq !== imageLoadSeq) return;
+    imageBlob = converted.blob; cleanup = converted.cleanup;
+  } catch (e) {
+    setStatus("could not decode that image: " + e.message, true);
+    return;
+  }
+  if (imageObjectURL) URL.revokeObjectURL(imageObjectURL);
+  const url = URL.createObjectURL(imageBlob);
+  imageObjectURL = url;
+  $("droptext").innerHTML = "";
+  let img = $("drop").querySelector("img");
+  if (!img) { img = document.createElement("img"); $("drop").appendChild(img); }
+  img.src = url;
+  $("go").disabled = false;
+  if (cleanup.changed)
+    setStatus(`ready · ${cleanup.mode} background made transparent`);
+  else if (cleanup.mode === "alpha") setStatus("ready · existing transparency preserved");
+  else if (cleanup.mode === "none") setStatus("ready · no black/white background detected");
+  else setStatus("ready");
+}
+
+$("background").addEventListener("change", () => {
+  if (sourceImageFile) setImage(sourceImageFile);
+});
+
+$("drop").addEventListener("click", () => $("file").click());
+$("file").addEventListener("change", e => setImage(e.target.files[0]));
+$("drop").addEventListener("dragover", e => { e.preventDefault(); $("drop").classList.add("hover"); });
+$("drop").addEventListener("dragleave", () => $("drop").classList.remove("hover"));
+$("drop").addEventListener("drop", e => {
+  e.preventDefault(); $("drop").classList.remove("hover");
+  setImage(e.dataTransfer.files[0]);
+});
+document.addEventListener("paste", e => {
+  for (const item of e.clipboardData.items)
+    if (item.type.startsWith("image/")) setImage(item.getAsFile());
+});
+
+$("go").addEventListener("click", async () => {
+  if (!imageBlob) return;
+  stopShowcase(true);
+  $("go").disabled = true;
+  $("bar").style.display = "block";
+  $("bar").firstElementChild.style.width = "2%";
+  setStatus("uploading…");
+
+  // The small thumbnail is persisted with the server-side job manifest; the
+  // browser keeps no asset/history database of its own.
+  const genQuality = $("quality").value;
+  const genThumb = await makeThumb(imageBlob);
+  const fd = new FormData();
+  fd.append("image", imageBlob, "input.png");
+  // Keep the selected file byte-for-byte. The processed PNG above remains the
+  // deterministic inference input; this original is for showcase and reuse.
+  fd.append("source", sourceImageFile, sourceImageFile.name || "source-image");
+  // `imageBlob` already contains the selected browser cleanup. Tell the C++
+  // pipeline to preserve it rather than independently applying auto mode again.
+  fd.append("background", "keep");
+  fd.append("quality", genQuality);
+  fd.append("thumbnail", genThumb);
+  fd.append("seed", $("seed").value);
+  fd.append("steps", $("steps").value);
+  fd.append("texture_steps", $("texsteps").value);
+  fd.append("guidance", $("guidance").value);
+  fd.append("preview", stepsOn ? "1" : "0");
+  fd.append("keyframes", (stepsOn && kfOn) ? "3" : "0");
+
+  viewer.clear();   // blank any prior mesh; previews/mesh will populate the view
+  resetExportState();
+  resetTimeline();  // start a fresh recording for this run
+
+  try {
+    const r = await fetch("/api/generate", { method: "POST", body: fd });
+    if (!r.ok) throw new Error(await r.text());
+    const { job } = await r.json();
+    await poll(job, genThumb, genQuality);
+  } catch (e) {
+    setStatus(e.message, true);
+    $("bar").style.display = "none";
+  }
+  $("go").disabled = false;
+});
+
+async function poll(id, thumb, quality) {
+  // stage weights for a smooth-ish progress bar (coarse/fine/cascade)
+  const stageBase = { "preprocess": 2, "encoding image (DINOv3)": 4,
+                      "sampling sparse structure": 8, "decoding occupancy": 22,
+                      "sampling shape SLAT": 26, "decoding shape": 40,
+                      "upsampling scaffold": 42,
+                      "sampling shape SLAT (1024)": 46, "decoding shape (1024)": 88,
+                      "extracting mesh": 92, "sampling material": 95,
+                      "saving generation": 99 };
+  for (;;) {
+    const r = await fetch("/api/job/" + id);
+    if (!r.ok) throw new Error(await r.text());
+    const j = await r.json();
+    if (j.state === "error") {
+      try { await refreshRuntimeInfo(); } catch (e) { /* informational only */ }
+      throw new Error(j.error);
+    }
+    if (j.state === "done") {
+      $("bar").firstElementChild.style.width = "100%";
+      setStatus("fetching mesh…");
+      await loadMesh(id);
+      addHistory(id, thumb, quality);
+      try { await refreshRuntimeInfo(); } catch (e) { /* informational only */ }
+      const elapsed = j.durationMs ? ` in ${(j.durationMs / 1000).toFixed(1)}s` : "";
+      setStatus(`done${elapsed} · live steps ${j.livePreview ? "on" : "off"}`);
+      setTimeout(() => { $("bar").style.display = "none"; }, 600);
+      return;
+    }
+    if (j.state === "running" && j.stage) {
+      if (backendName && j.stage !== "loading models")
+        $("backend").textContent = backendName;
+      let pct = stageBase[j.stage] ?? 5;
+      if (j.stage === "sampling sparse structure" && j.total > 0)
+        pct = 8 + 14 * (j.step / j.total);
+      if (j.stage === "sampling shape SLAT" && j.total > 0)
+        pct = 26 + 14 * (j.step / j.total);
+      if (j.stage === "sampling shape SLAT (1024)" && j.total > 0)
+        pct = 46 + 42 * (j.step / j.total);
+      if (j.stage === "sampling material" && j.total > 0)
+        pct = 95 + 4 * (j.step / j.total);
+      $("bar").firstElementChild.style.width = pct + "%";
+      setStatus(j.stage + (j.total ? ` (${j.step}/${j.total})` : "") + "…");
+    } else {
+      setStatus("queued…");
+    }
+    // Record every new intermediate frame (the server keeps them all), showing
+    // the newest live. After the run these frames replay through the scrubber.
+    if (stepsOn && j.previewSeq > haveFrames) {
+      const fm = j.frames || [];
+      while (haveFrames < j.previewSeq) {
+        await recordFrame(id, haveFrames, fm);
+        haveFrames++;
+      }
+    }
+    await new Promise(res => setTimeout(res, 500));
+  }
+}
+
+/* ── recorded stage playback (scrubber) ─────────────────────────────────────
+ * The server records every intermediate preview (voxel frames as the sparse
+ * structure condenses, plus any decoded mesh keyframes). We fetch each by index
+ * and keep it, so a finished generation can be scrubbed / played back through
+ * its stages. The final mesh is appended as the last frame. */
+let recordedFrames = [];   // {kind:'voxel',res,coords,meta} | {kind:'mesh',verts,normals,tris,pbr,meta}
+let haveFrames = 0;        // preview seqs fetched so far this run
+let tlTimer = 0;           // setInterval handle while playing back
+
+function resetTimeline() {
+  recordedFrames = []; haveFrames = 0;
+  stopPlayback();
+  $("timeline").style.display = "none";
+  $("tllabel").style.width = "";
+  $("tllabel").textContent = "";
+  $("hint").style.display = "";
+}
+
+// Parse a T2MESH0* blob into typed arrays (shared by keyframes + the final mesh).
+function parseMesh(buf) {
+  const dv = new DataView(buf);
+  const magic = new TextDecoder().decode(new Uint8Array(buf, 0, 8));
+  const textured5 = magic === "T2MESH02"; // legacy base/metal/rough
+  const textured6 = magic === "T2MESH03"; // + alpha
+  const textured = textured5 || textured6;
+  const nv = dv.getUint32(8, true), nt = dv.getUint32(12, true);
+  let off = 16;
+  const verts = new Float32Array(buf, off, nv * 3); off += nv * 12;
+  const normals = new Float32Array(buf, off, nv * 3); off += nv * 12;
+  let pbr = null;
+  if (textured6) {
+    pbr = new Float32Array(buf, off, nv * 6); off += nv * 24;
+  } else if (textured5) {
+    const old = new Float32Array(buf, off, nv * 5); off += nv * 20;
+    pbr = new Float32Array(nv * 6);
+    for (let i = 0; i < nv; i++) {
+      pbr.set(old.subarray(i * 5, i * 5 + 5), i * 6);
+      pbr[i * 6 + 5] = 1.0;
+    }
+  }
+  const tris = new Int32Array(buf, off, nt * 3);
+  return { verts, normals, tris, pbr, nv, nt, textured };
+}
+
+// Fetch recorded frame `seq`, append it, and show it live. Best-effort.
+async function recordFrame(id, seq, framesMeta) {
+  try {
+    const r = await fetch(`/api/preview/${id}?seq=${seq}`);
+    if (!r.ok) return;
+    const buf = await r.arrayBuffer();
+    const magic = new TextDecoder().decode(new Uint8Array(buf, 0, 6));
+    const meta = framesMeta && framesMeta[seq];
+    if (magic === "T2VOX0") {
+      const dv = new DataView(buf);
+      const res = dv.getUint32(8, true), nvox = dv.getUint32(12, true);
+      const coords = new Uint16Array(buf, 16, nvox * 3);
+      recordedFrames.push({ kind: "voxel", res, coords, meta });
+    } else if (magic === "T2MESH") {
+      const m = parseMesh(buf);
+      recordedFrames.push({ kind: "mesh", verts: m.verts, normals: m.normals,
+                            tris: m.tris, pbr: m.pbr, meta });
+    } else return;
+    renderFrame(recordedFrames.length - 1);   // show it as it arrives
+  } catch (e) { /* previews are best-effort */ }
+}
+
+function timelineLabel(f, i, total) {
+  const m = f.meta || {};
+  let s = m.stage || (f.kind === "mesh" ? "mesh" : "voxels");
+  if (m.total) s += ` ${m.step}/${m.total}`;
+  return `${i + 1}/${total} · ${s}`;
+}
+
+// Keep the scrubber length stable while replaying: reserve enough room for the
+// widest status label in this recording instead of letting the flex item grow
+// and shrink as each frame changes the text.
+function sizeTimelineLabel() {
+  const label = $("tllabel"), total = recordedFrames.length;
+  label.style.width = "";
+  let widest = 0;
+  recordedFrames.forEach((f, i) => {
+    label.textContent = timelineLabel(f, i, total);
+    widest = Math.max(widest, label.getBoundingClientRect().width);
+  });
+  label.style.width = Math.ceil(widest) + "px";
+}
+
+// Show a recorded frame in the viewer (camera untouched) and sync the scrubber.
+function renderFrame(i) {
+  const f = recordedFrames[i];
+  if (!f) return;
+  if (previewingExport) {
+    previewingExport = false;
+    $("pexport").textContent = "preview cleanup";
+  }
+  if (f.kind === "voxel") viewer.setVoxels(f.res, f.coords);
+  else viewer.setMesh(f.verts, f.normals, f.tris, f.pbr);
+  const rng = $("tlrange");
+  if (+rng.value !== i) rng.value = i;
+  $("tllabel").textContent = timelineLabel(f, i, recordedFrames.length);
+}
+
+// Canonical stage order so the scrubber plays chronologically regardless of the
+// order frames arrive (mesh keyframes are emitted late, after the final decode).
+const STAGE_RANK = {
+  "preprocess": 0, "encoding image (DINOv3)": 1, "sampling sparse structure": 2,
+  "decoding occupancy": 3, "sampling shape SLAT": 4, "upsampling scaffold": 5,
+  "sampling shape SLAT (1024)": 6, "decoding shape": 7, "decoding shape (1024)": 7,
+  "extracting mesh": 8, "final mesh": 99,
+};
+function frameRank(f) {
+  const m = f.meta || {};
+  return (STAGE_RANK[m.stage] ?? 50) * 1000 + (m.step || 0);
+}
+
+// Reveal the scrubber once a run has more than one recorded frame.
+function buildTimeline() {
+  const n = recordedFrames.length;
+  if (n <= 1) return;
+  recordedFrames.sort((a, b) => frameRank(a) - frameRank(b));   // chronological
+  const rng = $("tlrange");
+  rng.max = n - 1; rng.value = n - 1;
+  $("timeline").style.display = "flex";
+  $("hint").style.display = "none";
+  sizeTimelineLabel();
+  renderFrame(n - 1);
+}
+
+function stopPlayback() {
+  if (tlTimer) { clearInterval(tlTimer); tlTimer = 0; $("tlplay").innerHTML = "&#9654;"; }
+}
+
+$("tlplay").addEventListener("click", () => {
+  if (tlTimer) { stopPlayback(); return; }
+  if (recordedFrames.length < 2) return;
+  let i = +$("tlrange").value;
+  if (i >= recordedFrames.length - 1) i = -1;   // replay from the start
+  $("tlplay").innerHTML = "&#10073;&#10073;";   // pause glyph
+  tlTimer = setInterval(() => {
+    if (++i >= recordedFrames.length) { stopPlayback(); return; }
+    renderFrame(i);
+  }, 220);
+});
+
+$("tlrange").addEventListener("input", () => {
+  stopPlayback();
+  renderFrame(+$("tlrange").value);
+});
+
+let glbJobId = null;
+let originalExportMesh = null;
+let previewingExport = false;
+
+function meshDescription(m, prefix) {
+  return `${prefix}${m.nv.toLocaleString()} vertices · ${m.nt.toLocaleString()} triangles`
+    + (m.textured ? " · PBR" : " · no material");
+}
+
+function resetExportState() {
+  glbJobId = null; originalExportMesh = null; previewingExport = false;
+  $("pexport").disabled = true;
+  $("pexport").textContent = "preview cleanup";
+  $("dglb").disabled = true;
+  $("dglb").textContent = "download GLB";
+  $("regen").disabled = true;
+  $("exportinfo").textContent = "generate or open a mesh to enable export";
+}
+
+function showOriginalExport() {
+  if (!originalExportMesh) return;
+  const m = originalExportMesh;
+  viewer.setMesh(m.verts, m.normals, m.tris, m.pbr);
+  $("meshinfo").textContent = meshDescription(m, "original · ");
+  previewingExport = false;
+  $("pexport").textContent = "preview cleanup";
+}
+
+function exportQuery() {
+  return new URLSearchParams({
+    components: $("exportcomponents").value,
+  });
+}
+
+function exportSettingsChanged() {
+  if (previewingExport) showOriginalExport();
+  if (!glbJobId) return;
+  if (!originalExportMesh?.textured) {
+    $("exportinfo").textContent =
+      "warning: this saved mesh has no material data; its GLB will be geometry-only";
+    return;
+  }
+  const mode = $("exportcomponents").value;
+  $("exportinfo").textContent = mode === "largest"
+    ? "warning: largest-piece cleanup removes every detached component"
+    : mode === "tiny"
+      ? "warning: fragment cleanup can remove intentional small parts"
+      : "direct vertex colour · every component and polygon is preserved";
+}
+
+$("exportcomponents").addEventListener("change", exportSettingsChanged);
+
+async function loadMesh(id) {
+  const r = await fetch("/api/mesh/" + id);
+  if (!r.ok) throw new Error(await r.text());
+  const buf = await r.arrayBuffer();
+  const magic = new TextDecoder().decode(new Uint8Array(buf, 0, 8));
+  if (magic !== "T2MESH01" && magic !== "T2MESH02" && magic !== "T2MESH03")
+    throw new Error("bad mesh magic");
+  const m = parseMesh(buf);
+  originalExportMesh = m;
+  previewingExport = false;
+  $("meshinfo").textContent = meshDescription(m, "original · ");
+  viewer.setMesh(m.verts, m.normals, m.tris, m.pbr);
+  // Append the finished mesh as the final frame of the scrub timeline.
+  recordedFrames.push({ kind: "mesh", verts: m.verts, normals: m.normals,
+                        tris: m.tris, pbr: m.pbr, meta: { stage: "final mesh" } });
+  buildTimeline();
+  glbJobId = id;
+  $("pexport").disabled = false;
+  $("pexport").textContent = "preview cleanup";
+  $("dglb").disabled = false;
+  $("dglb").textContent = "download GLB";
+  $("regen").disabled = !(history.find(h => h.id === id)?.regeneratable);
+  exportSettingsChanged();
+}
+
+// Reuse the immutable processed input stored with a completed job. Only the
+// current generation settings cross the network; no image is uploaded again.
+$("regen").addEventListener("click", async () => {
+  if (!glbJobId) return;
+  const sourceId = glbJobId;
+  const sourceAsset = history.find(h => h.id === sourceId);
+  if (!sourceAsset?.regeneratable) return;
+  stopShowcase(true);
+  const btn = $("regen");
+  btn.disabled = true; btn.textContent = "queueing…";
+  $("bar").style.display = "block";
+  $("bar").firstElementChild.style.width = "2%";
+  setStatus("queueing saved image…");
+  const genQuality = $("quality").value;
+  const body = new URLSearchParams({
+    quality: genQuality,
+    seed: $("seed").value,
+    steps: $("steps").value,
+    texture_steps: $("texsteps").value,
+    guidance: $("guidance").value,
+    preview: stepsOn ? "1" : "0",
+    keyframes: (stepsOn && kfOn) ? "3" : "0",
+  });
+  try {
+    const r = await fetch("/api/regenerate/" + sourceId, { method: "POST", body });
+    if (!r.ok) throw new Error(await r.text());
+    const { job } = await r.json();
+    viewer.clear();
+    resetExportState();
+    resetTimeline();
+    await poll(job, sourceAsset.thumb, genQuality);
+  } catch (e) {
+    setStatus("regeneration failed: " + e.message, true);
+    $("bar").style.display = "none";
+    btn.disabled = false;
+  } finally {
+    btn.textContent = "regenerate from saved image";
+  }
+});
+
+$("pexport").addEventListener("click", async () => {
+  if (!glbJobId) return;
+  if (previewingExport) { showOriginalExport(); return; }
+  const btn = $("pexport");
+  btn.disabled = true; btn.textContent = "preparing…";
+  setStatus("preparing component-cleanup preview…");
+  try {
+    const r = await fetch(`/api/export-preview/${glbJobId}?${exportQuery()}`);
+    if (!r.ok) throw new Error(await r.text());
+    const m = parseMesh(await r.arrayBuffer());
+    viewer.setMesh(m.verts, m.normals, m.tris, m.pbr);
+    $("meshinfo").textContent = meshDescription(m, "export preview · ");
+    const cleaned = $("exportcomponents").value !== "all";
+    $("exportinfo").textContent = cleaned
+      ? `${m.nt.toLocaleString()} triangles remain after explicit component cleanup`
+      : `${m.nt.toLocaleString()} triangles · exact original mesh, no cleanup`;
+    previewingExport = true;
+    btn.textContent = "show original";
+    setStatus(cleaned ? "previewing component-cleaned export mesh"
+                      : "export preview matches the original mesh");
+  } catch (e) {
+    setStatus("export preview failed: " + e.message, true);
+    btn.textContent = "preview cleanup";
+  } finally {
+    btn.disabled = false;
+  }
+});
+
+// Bake with a bodyless preflight, then let the browser stream the large GLB to
+// its native download manager. Fetching 100+ MiB into an ArrayBuffer/Blob can
+// exhaust a remote device's browser memory and reports only "Failed to fetch".
+$("dglb").addEventListener("click", async () => {
+  if (!glbJobId) return;
+  const btn = $("dglb");
+  btn.disabled = true; btn.textContent = "baking GLB…";
+  try {
+    const query = exportQuery();
+    const url = `/api/glb/${glbJobId}?${query}`;
+    const r = await fetch(url, { method: "HEAD" });
+    if (!r.ok) throw new Error(r.headers.get("x-trellis-error") || `server returned HTTP ${r.status}`);
+    const bytes = Number(r.headers.get("content-length")) || 0;
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = `trellis2-${glbJobId}.glb`;
+    document.body.appendChild(a); a.click(); a.remove();
+    const size = bytes ? ` (${(bytes / (1 << 20)).toFixed(1)} MiB)` : "";
+    $("exportinfo").textContent = `GLB download started${size} · ready for Three.js GLTFLoader`;
+    btn.textContent = "download GLB";
+  } catch (e) {
+    setStatus("GLB bake failed: " + e.message, true);
+    btn.textContent = "download GLB";
+  } finally {
+    btn.disabled = false;
+  }
+});
+
+/* ── past-generation history ────────────────────────────────────────────────
+ * Server-side only: /api/jobs is the durable index; each entry's thumbnail,
+ * final mesh, and replay frames live in the configured generation store. */
+let history = [];
+let activeGen = null;
+let showcaseBusy = false;
+
+// downscale the input image to a small cover-cropped JPEG data URL
+async function makeThumb(blob) {
+  try {
+    const bmp = await createImageBitmap(blob);
+    const s = 96, cv = document.createElement("canvas"); cv.width = cv.height = s;
+    const ctx = cv.getContext("2d");
+    const k = Math.max(s / bmp.width, s / bmp.height);
+    const w = bmp.width * k, h = bmp.height * k;
+    ctx.drawImage(bmp, (s - w) / 2, (s - h) / 2, w, h);
+    return cv.toDataURL("image/jpeg", 0.7);
+  } catch (e) { return ""; }
+}
+
+async function refreshHistory() {
+  try {
+    const r = await fetch("/api/jobs");
+    if (!r.ok) throw new Error(await r.text());
+    history = (await r.json()).map(h => ({
+      id: h.id, thumb: h.thumbnail || "", quality: h.quality || "auto",
+      ts: h.createdAt || 0, sourceAvailable: !!h.sourceAvailable,
+      regeneratable: !!h.regeneratable,
+    }));
+  } catch (e) {
+    history = [];
+  }
+  renderHistory();
+  if (showcasePage) {
+    $("showcaseempty").classList.toggle("visible", history.length === 0);
+    if (history.length && !showcaseAutostarted) {
+      showcaseAutostarted = true;
+      startShowcase();
+    }
+  }
+}
+
+function renderHistory() {
+  $("histwrap").style.display = history.length ? "" : "none";
+  $("showcasebtn").disabled = !history.length || showcaseBusy;
+  const grid = $("hist");
+  grid.innerHTML = "";
+  history.forEach(h => {
+    const el = document.createElement("div");
+    el.className = "hitem" + (h.id === activeGen ? " active" : "");
+    el.title = h.quality + " · " + new Date(h.ts).toLocaleString();
+    const img = document.createElement("img");
+    if (h.thumb) img.src = h.thumb;
+    img.alt = "";
+    const q = document.createElement("span"); q.className = "q"; q.textContent = h.quality;
+    const x = document.createElement("span"); x.className = "x"; x.title = "remove"; x.textContent = "×";
+    el.append(img, q, x);
+    el.addEventListener("click", e => {
+      if (e.target.classList.contains("x")) removeHistory(h.id);
+      else viewGeneration(h.id);
+    });
+    grid.appendChild(el);
+  });
+}
+
+function addHistory(id, thumb, quality) {
+  history = history.filter(h => h.id !== id);          // de-dupe
+  history.unshift({ id, thumb, quality, ts: Date.now(),
+                    sourceAvailable: true, regeneratable: true });
+  activeGen = id;
+  if (glbJobId === id) $("regen").disabled = false;
+  renderHistory();
+}
+
+async function removeHistory(id, deleteServer = true) {
+  stopShowcase(true);
+  if (deleteServer) {
+    try {
+      const r = await fetch("/api/job/" + id, { method: "DELETE" });
+      if (!r.ok && r.status !== 404) throw new Error(await r.text());
+    } catch (e) {
+      setStatus("could not delete saved generation: " + e.message, true);
+      return;
+    }
+  }
+  history = history.filter(h => h.id !== id);
+  if (activeGen === id) activeGen = null;
+  renderHistory();
+}
+
+// Re-view a past generation (its mesh still lives on the server). If the server
+// still holds its recorded stage frames, replay is scrubbable too.
+async function viewGeneration(id) {
+  stopShowcase(true);
+  setStatus("loading…");
+  try {
+    resetExportState();
+    resetTimeline();
+    try {
+      const jr = await fetch("/api/job/" + id);
+      if (jr.ok) {
+        const jj = await jr.json();
+        const fm = jj.frames || [];
+        for (let k = 0; k < (jj.previewSeq || 0); k++) await recordFrame(id, k, fm);
+        haveFrames = jj.previewSeq || 0;
+      }
+    } catch (e) { /* no recorded frames; mesh-only replay */ }
+    await loadMesh(id);
+    activeGen = id; renderHistory();
+    setStatus("done");
+  } catch (e) {
+    setStatus("that generation is no longer on the server", true);
+    removeHistory(id, false);
+  }
+}
+
+$("histclear").addEventListener("click", async () => {
+  if (!confirm("Delete every saved generation from the server?")) return;
+  stopShowcase(true);
+  try {
+    const r = await fetch("/api/jobs", { method: "DELETE" });
+    if (!r.ok) throw new Error(await r.text());
+    history = []; activeGen = null; renderHistory();
+    setStatus("saved generations cleared");
+  } catch (e) {
+    setStatus("could not clear saved generations: " + e.message, true);
+  }
+});
+
+try { localStorage.removeItem("t2history"); } catch (e) {}
+refreshHistory();
+
+/* ── WebGL2 mesh viewer ─────────────────────────────────────────────────── */
+const viewer = (() => {
+  const canvas = $("gl");
+  const gl = canvas.getContext("webgl2", { antialias: true });
+  if (!gl) {
+    setStatus("WebGL2 not available", true);
+    return {
+      setMesh(){}, setVoxels(){}, clear(){}, setShowcaseAssets(){ return []; },
+      setShowcaseFrame(){}, setShowcaseFocus(){}, finishShowcase(){}, clearShowcase(){},
+    };
+  }
+
+  // Safety net: if the GPU context is ever lost (driver reset / out of memory),
+  // preventDefault keeps it recoverable and we tell the user instead of leaving
+  // a silently-dead black canvas. Rebuilding GL state needs a reload.
+  canvas.addEventListener("webglcontextlost", (e) => {
+    e.preventDefault();
+    setStatus("3D view lost the GPU context — reload the page to restore it.", true);
+  }, false);
+
+  const VS = `#version 300 es
+  layout(location=0) in vec3 pos;
+  layout(location=1) in vec3 nrm;
+  layout(location=2) in vec3 baseColor;
+  layout(location=3) in vec3 metalRoughAlpha;
+  uniform mat4 mvp, viewModel;
+  out vec3 vN; out vec3 vV; out vec3 vNw; out vec3 vCol; out vec2 vMR; out float vA;
+  void main() {
+    gl_Position = mvp * vec4(pos, 1.0);
+    vec4 vp = viewModel * vec4(pos, 1.0);
+    vV  = -vp.xyz;                    // view-space: to-camera (camera at origin)
+    vN  = mat3(viewModel) * nrm;      // view-space normal (orbits with camera)
+    vNw = nrm;                        // model-space normal (for a stable ambient)
+    vCol = baseColor;
+    vMR = metalRoughAlpha.xy;
+    vA = metalRoughAlpha.z;
+  }`;
+  // Lightweight metallic-roughness PBR in view space. The dual-grid mesh has
+  // unoriented winding (faithful to TRELLIS.2), so a normal is a direction line,
+  // not a signed outward normal: every dot uses abs() so back-wound faces shade
+  // identically. No IBL — three studio lights + a Fresnel-lit ambient term
+  // approximate an environment; specular reacts to the orbit via the view vector.
+  // Metallic-roughness PBR with a cheap procedural environment (image-based
+  // lighting), in view space so the "studio" stays put as the model orbits.
+  // The dual-grid mesh is unoriented, so the normal is faced toward the camera.
+  // A broad environment reflection — rather than a single tight point-specular —
+  // is what makes metal read as metal and keeps highlights from "blocking" as
+  // they sweep the faceted surface.
+  const FS = `#version 300 es
+  precision highp float;
+  in vec3 vN; in vec3 vV; in vec3 vNw; in vec3 vCol; in vec2 vMR; in float vA;
+  uniform int wire;
+  uniform int textured;   // 1 = per-vertex PBR (base_color/metallic/roughness)
+  out vec4 frag;
+  // procedural environment radiance in a direction (view space; +y = up)
+  vec3 envColor(vec3 d) {
+    vec3 sky = mix(vec3(0.32, 0.40, 0.55), vec3(0.72, 0.80, 0.98), clamp(d.y, 0.0, 1.0));
+    vec3 gnd = vec3(0.14, 0.13, 0.12);
+    return mix(gnd, sky, smoothstep(-0.30, 0.12, d.y));
+  }
+  void main() {
+    if (wire == 1) { frag = vec4(0.30, 0.64, 1.00, 1.0); return; }
+    vec3 N = normalize(vN), V = normalize(vV);
+    if (dot(N, V) < 0.0) N = -N;   // face the camera (mesh is unoriented)
+    // The network/baseColorTexture convention stores gamma-encoded base color.
+    // PBR math must operate on linear reflectance, as in upstream (** 2.2).
+    vec3  base  = (textured == 1) ? pow(clamp(vCol, 0.0, 1.0), vec3(2.2))
+                                  : vec3(0.62, 0.66, 0.72);
+    float metal = (textured == 1) ? clamp(vMR.x, 0.0, 1.0) : 0.0;
+    float rough = (textured == 1) ? clamp(vMR.y, 0.06, 1.0) : 0.5;
+    float opacity = (textured == 1) ? clamp(vA, 0.0, 1.0) : 1.0;
+    if (opacity < 0.01) discard;
+    float nv = max(dot(N, V), 1e-3);
+
+    // Schlick Fresnel (grazing reflectance rises to 1 - roughness for metals).
+    vec3 F0 = mix(vec3(0.04), base, metal);
+    vec3 F  = F0 + (max(vec3(1.0 - rough), F0) - F0) * pow(1.0 - nv, 5.0);
+
+    // diffuse: hemispheric environment irradiance (metals have no diffuse)
+    vec3 irr = envColor(N) * 0.55 + vec3(0.12);
+    vec3 diffuse = base * (1.0 - metal) * irr;
+
+    // specular: environment reflection, blurred toward a flat tint by roughness
+    vec3 refl = mix(envColor(reflect(-V, N)), vec3(0.34, 0.37, 0.44), rough * rough);
+    vec3 specular = refl * F;
+
+    // one crisp studio key light for a lively highlight
+    vec3 L = normalize(vec3(0.45, 0.70, 0.55)), H = normalize(L + V);
+    float shin = mix(8.0, 260.0, pow(1.0 - rough, 2.0));
+    float sp = pow(max(dot(N, H), 0.0), shin) * (shin + 2.0) / 6.2831853;
+    vec3  kc = vec3(1.00, 0.96, 0.88);
+    float ndl = max(dot(N, L), 0.0);
+    specular += kc * sp * F * ndl;
+    diffuse  += base * (1.0 - metal) * kc * ndl * 0.28;
+
+    vec3 color = diffuse + specular;
+    color = (color * (2.51 * color + 0.03)) / (color * (2.43 * color + 0.59) + 0.14); // ACES
+    frag = vec4(pow(clamp(color, 0.0, 1.0), vec3(1.0/2.2)), opacity);
+  }`;
+
+  function shader(type, src) {
+    const s = gl.createShader(type);
+    gl.shaderSource(s, src); gl.compileShader(s);
+    if (!gl.getShaderParameter(s, gl.COMPILE_STATUS))
+      throw new Error(gl.getShaderInfoLog(s));
+    return s;
+  }
+  const prog = gl.createProgram();
+  gl.attachShader(prog, shader(gl.VERTEX_SHADER, VS));
+  gl.attachShader(prog, shader(gl.FRAGMENT_SHADER, FS));
+  gl.linkProgram(prog);
+  if (!gl.getProgramParameter(prog, gl.LINK_STATUS))
+    throw new Error(gl.getProgramInfoLog(prog));
+  const uMVP = gl.getUniformLocation(prog, "mvp");
+  const uViewModel = gl.getUniformLocation(prog, "viewModel");
+  const uWire = gl.getUniformLocation(prog, "wire");
+  const uTextured = gl.getUniformLocation(prog, "textured");
+
+  const vao = gl.createVertexArray();
+  const vbo = gl.createBuffer(), nbo = gl.createBuffer(), cbo = gl.createBuffer(), ibo = gl.createBuffer();
+  let nIndices = 0, wireIbo = gl.createBuffer(), nWire = 0, wireStride = 1, hasPBR = false;
+
+  // Showcase finals use one compact GPU resource per station. The focused
+  // station's intermediate frame continues to use the ordinary mesh/voxel
+  // buffers above, so advancing the animation only uploads one changing object.
+  let showcaseMeshes = [];
+  let showcaseActive = -1, showcaseStage = "final", showcaseFocus = 0;
+
+  function makeShowcaseMesh(mesh, offset) {
+    const r = {
+      vao: gl.createVertexArray(), vbo: gl.createBuffer(), nbo: gl.createBuffer(),
+      cbo: gl.createBuffer(), ibo: gl.createBuffer(), nIndices: mesh.tris.length,
+      hasPBR: !!mesh.pbr, offset,
+    };
+    gl.bindVertexArray(r.vao);
+    gl.bindBuffer(gl.ARRAY_BUFFER, r.vbo);
+    gl.bufferData(gl.ARRAY_BUFFER, mesh.verts, gl.STATIC_DRAW);
+    gl.enableVertexAttribArray(0); gl.vertexAttribPointer(0, 3, gl.FLOAT, false, 0, 0);
+    gl.bindBuffer(gl.ARRAY_BUFFER, r.nbo);
+    gl.bufferData(gl.ARRAY_BUFFER, mesh.normals, gl.STATIC_DRAW);
+    gl.enableVertexAttribArray(1); gl.vertexAttribPointer(1, 3, gl.FLOAT, false, 0, 0);
+    if (r.hasPBR) {
+      gl.bindBuffer(gl.ARRAY_BUFFER, r.cbo);
+      gl.bufferData(gl.ARRAY_BUFFER, mesh.pbr, gl.STATIC_DRAW);
+      gl.enableVertexAttribArray(2); gl.vertexAttribPointer(2, 3, gl.FLOAT, false, 24, 0);
+      gl.enableVertexAttribArray(3); gl.vertexAttribPointer(3, 3, gl.FLOAT, false, 24, 12);
+    } else {
+      gl.disableVertexAttribArray(2); gl.disableVertexAttribArray(3);
+    }
+    gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, r.ibo);
+    gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, new Uint32Array(mesh.tris), gl.STATIC_DRAW);
+    gl.bindVertexArray(null);
+    return r;
+  }
+
+  function disposeShowcaseMeshes() {
+    for (const r of showcaseMeshes) {
+      gl.deleteBuffer(r.vbo); gl.deleteBuffer(r.nbo); gl.deleteBuffer(r.cbo);
+      gl.deleteBuffer(r.ibo); gl.deleteVertexArray(r.vao);
+    }
+    showcaseMeshes = []; showcaseActive = -1; showcaseStage = "final";
+  }
+
+  /* ── instanced-voxel program (live intermediate previews) ───────────────── */
+  // One unit cube drawn once per occupied voxel; the "coarse" blocky look reads
+  // clearly as an in-progress stage against the final smooth mesh.
+  const VVS = `#version 300 es
+  layout(location=0) in vec3 cubePos;    // cube corner in [-0.5,0.5]
+  layout(location=1) in vec3 cubeNrm;    // per-face normal
+  layout(location=2) in vec3 cellCenter; // per-instance voxel center
+  uniform mat4 mvp, viewModel;
+  uniform float vsize;                    // voxel edge length (1/res)
+  out vec3 vN; out vec3 vNw;
+  void main() {
+    vec3 world = cellCenter + cubePos * vsize;
+    gl_Position = mvp * vec4(world, 1.0);
+    vN  = mat3(viewModel) * cubeNrm;
+    vNw = cubeNrm;
+  }`;
+  const VFS = `#version 300 es
+  precision highp float;
+  in vec3 vN; in vec3 vNw;
+  out vec4 frag;
+  void main() {
+    vec3 N = normalize(vN);
+    vec3 L1 = normalize(vec3(0.32, 0.55, 0.77)), L2 = normalize(vec3(-0.65, 0.20, 0.45));
+    float d = 0.75 * abs(dot(N, L1)) + 0.35 * abs(dot(N, L2));
+    float hemi = abs(normalize(vNw).y) * 0.5 + 0.5;
+    vec3 amb = mix(vec3(0.13, 0.15, 0.20), vec3(0.24, 0.34, 0.52), hemi);
+    vec3 base = vec3(0.30, 0.60, 1.00);   // "in-progress" blue
+    frag = vec4(pow(clamp(base * (amb + d), 0.0, 1.0), vec3(1.0/2.2)), 1.0);
+  }`;
+  const vprog = gl.createProgram();
+  gl.attachShader(vprog, shader(gl.VERTEX_SHADER, VVS));
+  gl.attachShader(vprog, shader(gl.FRAGMENT_SHADER, VFS));
+  gl.linkProgram(vprog);
+  if (!gl.getProgramParameter(vprog, gl.LINK_STATUS))
+    throw new Error(gl.getProgramInfoLog(vprog));
+  const uvMVP = gl.getUniformLocation(vprog, "mvp");
+  const uvViewModel = gl.getUniformLocation(vprog, "viewModel");
+  const uvSize = gl.getUniformLocation(vprog, "vsize");
+
+  // unit cube: 6 faces × 4 corners (pos in [-0.5,0.5], per-face normal), 36 idx
+  const cubePos = [], cubeNrm = [], cubeIdx = [];
+  const faces = [
+    { n: [1, 0, 0],  u: [0, 1, 0], v: [0, 0, 1] }, { n: [-1, 0, 0], u: [0, 0, 1], v: [0, 1, 0] },
+    { n: [0, 1, 0],  u: [0, 0, 1], v: [1, 0, 0] }, { n: [0, -1, 0], u: [1, 0, 0], v: [0, 0, 1] },
+    { n: [0, 0, 1],  u: [1, 0, 0], v: [0, 1, 0] }, { n: [0, 0, -1], u: [0, 1, 0], v: [1, 0, 0] },
+  ];
+  for (const f of faces) {
+    const b = cubePos.length / 3;
+    for (const [a, c] of [[-0.5, -0.5], [0.5, -0.5], [0.5, 0.5], [-0.5, 0.5]]) {
+      for (let k = 0; k < 3; k++) cubePos.push(f.n[k] * 0.5 + a * f.u[k] + c * f.v[k]);
+      cubeNrm.push(...f.n);
+    }
+    cubeIdx.push(b, b + 1, b + 2, b, b + 2, b + 3);
+  }
+  const vvao = gl.createVertexArray();
+  const cubeVbo = gl.createBuffer(), cubeNbo = gl.createBuffer(), cubeIbo = gl.createBuffer(), instBo = gl.createBuffer();
+  gl.bindVertexArray(vvao);
+  gl.bindBuffer(gl.ARRAY_BUFFER, cubeVbo);
+  gl.bufferData(gl.ARRAY_BUFFER, new Float32Array(cubePos), gl.STATIC_DRAW);
+  gl.enableVertexAttribArray(0); gl.vertexAttribPointer(0, 3, gl.FLOAT, false, 0, 0);
+  gl.bindBuffer(gl.ARRAY_BUFFER, cubeNbo);
+  gl.bufferData(gl.ARRAY_BUFFER, new Float32Array(cubeNrm), gl.STATIC_DRAW);
+  gl.enableVertexAttribArray(1); gl.vertexAttribPointer(1, 3, gl.FLOAT, false, 0, 0);
+  gl.bindBuffer(gl.ARRAY_BUFFER, instBo);
+  gl.enableVertexAttribArray(2); gl.vertexAttribPointer(2, 3, gl.FLOAT, false, 0, 0);
+  gl.vertexAttribDivisor(2, 1);   // one cellCenter per instance
+  gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, cubeIbo);
+  gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, new Uint16Array(cubeIdx), gl.STATIC_DRAW);
+  gl.bindVertexArray(null);
+
+  let renderMode = "none", nVox = 0, voxSize = 0;
+
+  /* ── trackball orientation (quaternion) ─────────────────────────────────────
+   * Rotation is an accumulated unit quaternion, not Euler yaw/pitch. Each drag
+   * composes a small rotation about the *screen* axes (camera right / up) onto
+   * the current orientation, so there are no poles and no gimbal lock — every
+   * orientation is reachable, and a pure horizontal or vertical drag turns about
+   * a single axis at a time. */
+  const Q = {
+    axisAngle(x, y, z, a) { const h = a * 0.5, s = Math.sin(h); return [x*s, y*s, z*s, Math.cos(h)]; },
+    mul(a, b) {   // Hamilton product a·b (apply b, then a)
+      return [
+        a[3]*b[0] + a[0]*b[3] + a[1]*b[2] - a[2]*b[1],
+        a[3]*b[1] - a[0]*b[2] + a[1]*b[3] + a[2]*b[0],
+        a[3]*b[2] + a[0]*b[1] - a[1]*b[0] + a[2]*b[3],
+        a[3]*b[3] - a[0]*b[0] - a[1]*b[1] - a[2]*b[2],
+      ];
+    },
+    norm(q) { const n = Math.hypot(q[0], q[1], q[2], q[3]) || 1; return [q[0]/n, q[1]/n, q[2]/n, q[3]/n]; },
+    toMat4(q) {   // column-major rotation matrix
+      const [x, y, z, w] = q;
+      const xx = x*x, yy = y*y, zz = z*z, xy = x*y, xz = x*z, yz = y*z, wx = w*x, wy = w*y, wz = w*z;
+      return new Float32Array([
+        1-2*(yy+zz), 2*(xy+wz),   2*(xz-wy),   0,
+        2*(xy-wz),   1-2*(xx+zz), 2*(yz+wx),   0,
+        2*(xz+wy),   2*(yz-wx),   1-2*(xx+yy), 0,
+        0, 0, 0, 1,
+      ]);
+    },
+  };
+  // Default view: TRELLIS is Z-up, so bring it Y-up (a -90° turn about X, the
+  // same convention as the exported GLB) then a gentle 3/4 turn. Reset (below,
+  // and double-click) returns here.
+  const QBASE = Q.norm(Q.mul(Q.axisAngle(1, 0, 0, -0.30),
+                       Q.mul(Q.axisAngle(0, 1, 0, 0.55),
+                             Q.axisAngle(1, 0, 0, -Math.PI / 2))));
+  let rot = QBASE.slice(), dist = 1.8, panX = 0, panY = 0;
+  let wire = false, spin = true;
+
+  function setMesh(verts, normals, tris, pbr, keepShowcase = false) {
+    if (!keepShowcase) disposeShowcaseMeshes();
+    gl.bindVertexArray(vao);
+    gl.bindBuffer(gl.ARRAY_BUFFER, vbo);
+    gl.bufferData(gl.ARRAY_BUFFER, verts, gl.STATIC_DRAW);
+    gl.enableVertexAttribArray(0);
+    gl.vertexAttribPointer(0, 3, gl.FLOAT, false, 0, 0);
+    gl.bindBuffer(gl.ARRAY_BUFFER, nbo);
+    gl.bufferData(gl.ARRAY_BUFFER, normals, gl.STATIC_DRAW);
+    gl.enableVertexAttribArray(1);
+    gl.vertexAttribPointer(1, 3, gl.FLOAT, false, 0, 0);
+    // per-vertex PBR: base_color rgb (loc 2) + metallic,roughness,alpha (loc 3),
+    // interleaved 6 floats (stride 24 bytes).
+    hasPBR = !!pbr;
+    if (hasPBR) {
+      gl.bindBuffer(gl.ARRAY_BUFFER, cbo);
+      gl.bufferData(gl.ARRAY_BUFFER, pbr, gl.STATIC_DRAW);
+      gl.enableVertexAttribArray(2);
+      gl.vertexAttribPointer(2, 3, gl.FLOAT, false, 24, 0);
+      gl.enableVertexAttribArray(3);
+      gl.vertexAttribPointer(3, 3, gl.FLOAT, false, 24, 12);
+    } else {
+      gl.disableVertexAttribArray(2);
+      gl.disableVertexAttribArray(3);
+    }
+    const idx = new Uint32Array(tris);
+    gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, ibo);
+    gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, idx, gl.STATIC_DRAW);
+    nIndices = idx.length;
+    // wireframe index buffer: 3 edges per triangle. A full per-triangle wireframe
+    // of a multi-million-triangle mesh is pathological — WebGL lines are min 1px
+    // wide, so sub-pixel triangles fill in as a solid mass, AND the buffer/draw
+    // gets so large (a 9M-tri mesh → a 216 MB buffer + 27M line segments) that it
+    // OOMs or stalls the GPU, losing the context and blanking the canvas. So we
+    // bound it to WIRE_BUDGET indices, striding whole triangles above that.
+    const WIRE_BUDGET = 12_000_000;               // ~6M segments, ~48 MB
+    const nTri = nIndices / 3;
+    wireStride = Math.max(1, Math.ceil(nTri * 6 / WIRE_BUDGET));
+    const wireIdx = new Uint32Array(Math.ceil(nTri / wireStride) * 6);
+    let o = 0;
+    for (let t = 0; t < nIndices; t += 3 * wireStride) {
+      wireIdx[o++] = idx[t];     wireIdx[o++] = idx[t + 1];
+      wireIdx[o++] = idx[t + 1]; wireIdx[o++] = idx[t + 2];
+      wireIdx[o++] = idx[t + 2]; wireIdx[o++] = idx[t];
+    }
+    gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, wireIbo);
+    gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, wireIdx.subarray(0, o), gl.STATIC_DRAW);
+    nWire = o;
+    gl.bindVertexArray(null);
+    renderMode = "mesh";
+  }
+
+  // Upload an occupied-voxel set (coords in [0,res)) for a live preview and
+  // switch to blocky voxel rendering. Camera is left untouched so previews and
+  // the final mesh share one continuous view (reset happens in clear()).
+  function setVoxels(res, coords, keepShowcase = false) {
+    if (!keepShowcase) disposeShowcaseMeshes();
+    const nv = coords.length / 3;
+    const centers = new Float32Array(nv * 3);
+    for (let i = 0; i < nv; i++) {
+      centers[i*3]   = (coords[i*3]   + 0.5) / res - 0.5;
+      centers[i*3+1] = (coords[i*3+1] + 0.5) / res - 0.5;
+      centers[i*3+2] = (coords[i*3+2] + 0.5) / res - 0.5;
+    }
+    gl.bindVertexArray(vvao);
+    gl.bindBuffer(gl.ARRAY_BUFFER, instBo);
+    gl.bufferData(gl.ARRAY_BUFFER, centers, gl.DYNAMIC_DRAW);
+    gl.bindVertexArray(null);
+    nVox = nv; voxSize = 1.0 / res;
+    renderMode = "voxel";
+  }
+
+  // Blank the view and recenter the camera for a new generation.
+  function clear() {
+    disposeShowcaseMeshes();
+    renderMode = "none";
+    rot = QBASE.slice(); dist = 1.8; panX = 0; panY = 0;
+  }
+
+  // Place every finished asset along a shared world-space row. Each object is
+  // rotated around its own origin; the camera focus then travels between the
+  // fixed station offsets, matching the Free-Splatter storyboard layout.
+  function setShowcaseAssets(assets, spacing) {
+    disposeShowcaseMeshes();
+    const center = (assets.length - 1) * 0.5;
+    showcaseMeshes = assets.map((mesh, i) =>
+      makeShowcaseMesh(mesh, (i - center) * spacing));
+    showcaseActive = showcaseMeshes.length ? 0 : -1;
+    showcaseStage = "final";
+    showcaseFocus = showcaseMeshes.length ? showcaseMeshes[0].offset : 0;
+    rot = QBASE.slice(); dist = 1.8; panX = 0; panY = 0;
+    renderMode = showcaseMeshes.length ? "showcase" : "none";
+    return showcaseMeshes.map(r => r.offset);
+  }
+
+  function setShowcaseFrame(index, stage) {
+    if (!showcaseMeshes[index]) return;
+    showcaseActive = index;
+    if (!stage || stage.kind === "final") {
+      showcaseStage = "final";
+    } else if (stage.kind === "hidden") {
+      showcaseStage = "hidden";
+    } else if (stage.kind === "voxel") {
+      setVoxels(stage.res, stage.coords, true);
+      showcaseStage = "voxel";
+    } else {
+      setMesh(stage.verts, stage.normals, stage.tris, stage.pbr, true);
+      showcaseStage = "mesh";
+    }
+    renderMode = "showcase";
+  }
+
+  function setShowcaseFocus(x) { showcaseFocus = x; }
+  function finishShowcase() {
+    if (showcaseMeshes.length) {
+      showcaseStage = "final";
+      renderMode = "showcase";
+    }
+  }
+  function clearShowcase() {
+    disposeShowcaseMeshes();
+    if (renderMode === "showcase") renderMode = "none";
+  }
+
+  /* minimal mat4 helpers (column-major) */
+  const M = {
+    mul(a, b) {
+      const o = new Float32Array(16);
+      for (let c = 0; c < 4; ++c) for (let r = 0; r < 4; ++r)
+        o[c*4+r] = a[r]*b[c*4] + a[4+r]*b[c*4+1] + a[8+r]*b[c*4+2] + a[12+r]*b[c*4+3];
+      return o;
+    },
+    persp(fov, asp, near, far) {
+      const f = 1 / Math.tan(fov / 2), o = new Float32Array(16);
+      o[0] = f / asp; o[5] = f;
+      o[10] = (far + near) / (near - far); o[11] = -1;
+      o[14] = 2 * far * near / (near - far);
+      return o;
+    },
+    trans(x, y, z) {
+      const o = new Float32Array(16);
+      o[0] = o[5] = o[10] = o[15] = 1;
+      o[12] = x; o[13] = y; o[14] = z;
+      return o;
+    },
+  };
+
+  /* input */
+  let dragging = false, panning = false, lx = 0, ly = 0;
+  canvas.addEventListener("mousedown", e => {
+    dragging = true;
+    panning = e.button === 2 || e.shiftKey;
+    lx = e.clientX; ly = e.clientY;
+  });
+  window.addEventListener("mouseup", () => dragging = false);
+  window.addEventListener("mousemove", e => {
+    if (!dragging) return;
+    const dx = e.clientX - lx, dy = e.clientY - ly;
+    lx = e.clientX; ly = e.clientY;
+    if (panning) {
+      panX += dx * 0.0015 * dist; panY -= dy * 0.0015 * dist;
+    } else {
+      // Compose screen-axis turns onto the current orientation (fixed camera
+      // frame): horizontal drag → about screen-up (Y), vertical → screen-right
+      // (X). Pre-multiplying keeps it screen-relative, so it never locks up.
+      const k = 0.008;
+      rot = Q.norm(Q.mul(Q.axisAngle(1, 0, 0, dy * k),
+                   Q.mul(Q.axisAngle(0, 1, 0, dx * k), rot)));
+      spin = false; $("tspin").classList.remove("on");
+    }
+  });
+  canvas.addEventListener("contextmenu", e => e.preventDefault());
+  canvas.addEventListener("wheel", e => {
+    e.preventDefault();
+    dist *= Math.exp(e.deltaY * 0.001);
+    dist = Math.max(0.3, Math.min(8, dist));
+  }, { passive: false });
+  // double-click: snap back to the upright default view
+  canvas.addEventListener("dblclick", () => { rot = QBASE.slice(); dist = 1.8; panX = panY = 0; });
+
+  $("twire").addEventListener("click", () => {
+    wire = !wire; $("twire").classList.toggle("on", wire);
+  });
+  $("tspin").addEventListener("click", () => {
+    spin = !spin; $("tspin").classList.toggle("on", spin);
+  });
+
+  gl.enable(gl.DEPTH_TEST);
+  gl.enable(gl.BLEND);
+  gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+  gl.clearColor(0.063, 0.078, 0.094, 1);
+
+  let last = performance.now();
+  function frame(now) {
+    const dt = (now - last) / 1000; last = now;
+    // auto-rotate: a slow turn about the screen-vertical axis (turntable feel)
+    if (spin) {
+      const spinRate = showcasePage ? 0.12 : 0.4;
+      rot = Q.norm(Q.mul(Q.axisAngle(0, 1, 0, dt * spinRate), rot));
+    }
+
+    const w = canvas.clientWidth, h = canvas.clientHeight;
+    if (canvas.width !== w * devicePixelRatio || canvas.height !== h * devicePixelRatio) {
+      canvas.width = w * devicePixelRatio; canvas.height = h * devicePixelRatio;
+    }
+    gl.viewport(0, 0, canvas.width, canvas.height);
+    gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
+
+    if (renderMode !== "none") {
+      const rotation = Q.toMat4(rot);
+      const focus = renderMode === "showcase" ? showcaseFocus : 0;
+      const view = M.trans(panX - focus, panY, -dist);
+      const proj = M.persp(0.9, w / h, 0.05, 100);
+      // Translation precedes each object's local rotation, so every showcase
+      // asset spins in place instead of the whole row orbiting around its centre.
+      const matricesAt = offset => {
+        const model = offset ? M.mul(M.trans(offset, 0, 0), rotation) : rotation;
+        const viewModel = M.mul(view, model);
+        return { viewModel, mvp: M.mul(proj, viewModel) };
+      };
+      const drawFilledMesh = (r, matrices) => {
+        gl.useProgram(prog);
+        gl.uniformMatrix4fv(uMVP, false, matrices.mvp);
+        gl.uniformMatrix4fv(uViewModel, false, matrices.viewModel);
+        gl.uniform1i(uWire, 0);
+        gl.uniform1i(uTextured, r.hasPBR ? 1 : 0);
+        gl.bindVertexArray(r.vao);
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, r.ibo);
+        gl.drawElements(gl.TRIANGLES, r.nIndices, gl.UNSIGNED_INT, 0);
+        gl.bindVertexArray(null);
+      };
+      const drawVoxels = matrices => {
+        if (!nVox) return;
+        gl.useProgram(vprog);
+        gl.uniformMatrix4fv(uvMVP, false, matrices.mvp);
+        gl.uniformMatrix4fv(uvViewModel, false, matrices.viewModel);
+        gl.uniform1f(uvSize, voxSize);
+        gl.bindVertexArray(vvao);
+        gl.drawElementsInstanced(gl.TRIANGLES, 36, gl.UNSIGNED_SHORT, 0, nVox);
+        gl.bindVertexArray(null);
+      };
+
+      if (renderMode === "showcase") {
+        // Every non-focused station remains as its finished mesh. The focused
+        // station is replaced by its recorded frame until it reaches final.
+        for (let i = 0; i < showcaseMeshes.length; i++) {
+          if (i === showcaseActive && showcaseStage !== "final") continue;
+          const r = showcaseMeshes[i];
+          drawFilledMesh(r, matricesAt(r.offset));
+        }
+        const active = showcaseMeshes[showcaseActive];
+        if (active && showcaseStage === "voxel") {
+          drawVoxels(matricesAt(active.offset));
+        } else if (active && showcaseStage === "mesh" && nIndices) {
+          drawFilledMesh({ vao, ibo, nIndices, hasPBR }, matricesAt(active.offset));
+        }
+      } else if (renderMode === "voxel") {
+        drawVoxels(matricesAt(0));
+      } else if (renderMode === "mesh" && nIndices) {
+        const matrices = matricesAt(0);
+        gl.useProgram(prog);
+        gl.uniformMatrix4fv(uMVP, false, matrices.mvp);
+        gl.uniformMatrix4fv(uViewModel, false, matrices.viewModel);
+        gl.bindVertexArray(vao);
+        if (wire) {
+          // hidden-line wireframe: a depth-only prepass (pushed back a hair via
+          // polygon offset) occludes back-facing edges, so you see the front
+          // surface's edges — the mesh form — instead of a see-through blob.
+          gl.enable(gl.POLYGON_OFFSET_FILL);
+          gl.polygonOffset(1.0, 1.0);
+          gl.colorMask(false, false, false, false);
+          gl.uniform1i(uWire, 0);
+          gl.uniform1i(uTextured, 0);
+          gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, ibo);
+          gl.drawElements(gl.TRIANGLES, nIndices, gl.UNSIGNED_INT, 0);
+          gl.colorMask(true, true, true, true);
+          gl.disable(gl.POLYGON_OFFSET_FILL);
+          gl.uniform1i(uWire, 1);
+          // Front-surface edges sit at ~equal depth to the offset-back fill, so
+          // LEQUAL lets them pass while occluded edges (greater depth) fail.
+          gl.depthFunc(gl.LEQUAL);
+          gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, wireIbo);
+          gl.drawElements(gl.LINES, nWire, gl.UNSIGNED_INT, 0);
+          gl.depthFunc(gl.LESS);
+        } else {
+          gl.uniform1i(uWire, 0);
+          gl.uniform1i(uTextured, hasPBR ? 1 : 0);
+          gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, ibo);
+          gl.drawElements(gl.TRIANGLES, nIndices, gl.UNSIGNED_INT, 0);
+        }
+        gl.bindVertexArray(null);
+      }
+    }
+    requestAnimationFrame(frame);
+  }
+  requestAnimationFrame(frame);
+
+  return {
+    setMesh, setVoxels, clear, setShowcaseAssets, setShowcaseFrame,
+    setShowcaseFocus, finishShowcase, clearShowcase,
+  };
+})();
+
+/* ── all-generation showcase ────────────────────────────────────────────────
+ * Finished assets occupy fixed stations in one scene. Focus glides between
+ * them; at each stop the finished mesh is temporarily replaced by the job's
+ * recorded voxel/mesh stages, then restored for a longer final-render linger.
+ * This only reads existing job data. Final meshes are loaded unchanged from
+ * the durable full-density assets; it never loads or runs an inference model. */
+const SHOWCASE_SPACING = 1.7;
+const SHOWCASE_MAX_VOXEL_FRAMES = 18;
+const SHOWCASE_FRAME_MS = 320;
+const SHOWCASE_FINAL_MS = 3200;
+const SHOWCASE_TRAVEL_MS = 1400;
+const SHOWCASE_IMAGE_HOLD_MS = 1800;
+const SHOWCASE_IMAGE_SHRINK_MS = 1200;
+
+let showcaseRunId = 0;
+let showcaseAbort = null;
+let showcaseRunning = false;
+let showcaseAutostarted = false;
+let showcaseAssets = [];
+let showcaseIndex = -1;
+let showcaseFocusValue = 0;
+let showcaseSourceId = "";
+
+function hideShowcaseSource(clear = false) {
+  const img = $("showcasesource");
+  img.classList.remove("visible");
+  if (clear) {
+    img.classList.remove("corner");
+    img.removeAttribute("src");
+    showcaseSourceId = "";
+  } else {
+    setTimeout(() => {
+      if (!img.classList.contains("visible")) {
+        img.classList.remove("corner");
+        img.removeAttribute("src");
+        showcaseSourceId = "";
+      }
+    }, 380);
+  }
+}
+
+async function loadShowcaseSource(asset, token) {
+  const img = $("showcasesource");
+  if (showcaseSourceId === asset.id && img.classList.contains("visible")) return true;
+  hideShowcaseSource(true);
+  const loaded = await new Promise(resolve => {
+    let finished = false, triedFallback = false;
+    const done = ok => { if (!finished) { finished = true; resolve(ok); } };
+    img.onload = () => done(true);
+    img.onerror = () => {
+      if (!triedFallback && asset.thumb) {
+        triedFallback = true;
+        img.src = asset.thumb; // older persisted jobs have only the 96px thumbnail
+      } else done(false);
+    };
+    img.src = `/api/source/${asset.id}`;
+    setTimeout(() => done(false), 5000);
+  });
+  if (!loaded || token !== showcaseRunId) return false;
+  showcaseSourceId = asset.id;
+  img.classList.remove("corner");
+  // Flush the centered state before fading in so a previous station cannot
+  // collapse the center→corner transition into a single layout update.
+  void img.offsetWidth;
+  img.classList.add("visible");
+  return true;
+}
+
+async function playShowcaseSourceIntro(asset, token) {
+  if (!await loadShowcaseSource(asset, token)) return token === showcaseRunId;
+  if (!await showcaseWait(SHOWCASE_IMAGE_HOLD_MS, token)) return false;
+  $("showcasesource").classList.add("corner");
+  return showcaseWait(SHOWCASE_IMAGE_SHRINK_MS, token);
+}
+
+function showcaseFrameSeqs(job) {
+  const n = Math.max(0, job.previewSeq || 0), meta = job.frames || [];
+  const meshes = [], voxels = [];
+  for (let i = 0; i < n; i++) {
+    if (meta[i] && meta[i].kind === "mesh") meshes.push(i);
+    else voxels.push(i);
+  }
+  const picked = new Set(meshes); // mesh keyframes are few and always worth keeping
+  if (voxels.length <= SHOWCASE_MAX_VOXEL_FRAMES) {
+    voxels.forEach(i => picked.add(i));
+  } else {
+    for (let i = 0; i < SHOWCASE_MAX_VOXEL_FRAMES; i++) {
+      const at = Math.round(i * (voxels.length - 1) / (SHOWCASE_MAX_VOXEL_FRAMES - 1));
+      picked.add(voxels[at]);
+    }
+  }
+  return [...picked].sort((a, b) => a - b).map(seq => ({ seq, meta: meta[seq] }));
+}
+
+async function fetchShowcaseFrame(id, ref, signal) {
+  const r = await fetch(`/api/preview/${id}?seq=${ref.seq}`, { signal });
+  if (!r.ok) return null;
+  const buf = await r.arrayBuffer();
+  const magic = new TextDecoder().decode(new Uint8Array(buf, 0, 6));
+  if (magic === "T2VOX0") {
+    const dv = new DataView(buf);
+    const res = dv.getUint32(8, true), nvox = dv.getUint32(12, true);
+    return { kind: "voxel", res, coords: new Uint16Array(buf, 16, nvox * 3), meta: ref.meta };
+  }
+  if (magic === "T2MESH") {
+    const m = parseMesh(buf);
+    return { kind: "mesh", verts: m.verts, normals: m.normals,
+             tris: m.tris, pbr: m.pbr, meta: ref.meta };
+  }
+  return null;
+}
+
+async function loadShowcaseAsset(h, position, total, signal) {
+  $("showcaselabel").textContent = `loading ${position}/${total} · ${h.quality || "generation"}`;
+  const jr = await fetch("/api/job/" + h.id, { signal });
+  if (!jr.ok) throw new Error("job unavailable");
+  const job = await jr.json();
+  if (job.state !== "done") throw new Error("job is not finished");
+
+  const mr = await fetch("/api/mesh/" + h.id, { signal });
+  if (!mr.ok) throw new Error("mesh unavailable");
+  const final = parseMesh(await mr.arrayBuffer());
+  return {
+    id: h.id, quality: h.quality || "generation", thumb: h.thumb,
+    refs: showcaseFrameSeqs(job), frames: null, final,
+  };
+}
+
+async function ensureShowcaseFrames(asset, token, signal) {
+  if (asset.frames) return asset.frames;
+  const frames = [];
+  for (let i = 0; i < asset.refs.length; i += 4) {
+    if (token !== showcaseRunId) return [];
+    $("showcaselabel").textContent =
+      `${showcaseIndex + 1}/${showcaseAssets.length} · loading recorded stages ${Math.min(i + 4, asset.refs.length)}/${asset.refs.length}`;
+    const batch = await Promise.all(asset.refs.slice(i, i + 4)
+      .map(ref => fetchShowcaseFrame(asset.id, ref, signal)));
+    batch.forEach(f => { if (f) frames.push(f); });
+  }
+  frames.sort((a, b) => frameRank(a) - frameRank(b));
+  asset.frames = frames;
+  return frames;
+}
+
+function showcaseWait(ms, token) {
+  return new Promise(resolve => setTimeout(() => resolve(token === showcaseRunId), ms));
+}
+
+function animateShowcaseFocus(target, duration, token) {
+  const from = showcaseFocusValue, started = performance.now();
+  return new Promise(resolve => {
+    const tick = now => {
+      if (token !== showcaseRunId) { resolve(false); return; }
+      const p = Math.min(1, (now - started) / Math.max(1, duration));
+      const smooth = p * p * (3 - 2 * p);
+      showcaseFocusValue = from + (target - from) * smooth;
+      viewer.setShowcaseFocus(showcaseFocusValue);
+      if (p < 1) requestAnimationFrame(tick);
+      else resolve(true);
+    };
+    requestAnimationFrame(tick);
+  });
+}
+
+function showcaseStageText(frame) {
+  const m = frame.meta || {};
+  let s = m.stage || (frame.kind === "mesh" ? "mesh keyframe" : "voxel structure");
+  if (m.total) s += ` ${m.step}/${m.total}`;
+  return s;
+}
+
+async function runShowcaseLoop(token, signal) {
+  while (token === showcaseRunId && showcaseAssets.length) {
+    for (let i = 0; i < showcaseAssets.length; i++) {
+      if (token !== showcaseRunId) return;
+      const asset = showcaseAssets[i];
+      showcaseIndex = i;
+      activeGen = asset.id; renderHistory();
+      if (showcaseSourceId !== asset.id) hideShowcaseSource();
+      viewer.setShowcaseFrame(i, { kind: "hidden" });
+      $("showcaselabel").textContent = `${i + 1}/${showcaseAssets.length} · moving to ${asset.quality}`;
+      const travel = i === 0 && Math.abs(showcaseFocusValue - asset.offset) < 1e-4
+        ? 250 : SHOWCASE_TRAVEL_MS;
+      if (!await animateShowcaseFocus(asset.offset, travel, token)) return;
+
+      $("showcaselabel").textContent = `${i + 1}/${showcaseAssets.length} · source image`;
+      if (!await playShowcaseSourceIntro(asset, token)) return;
+
+      let frames;
+      try {
+        frames = await ensureShowcaseFrames(asset, token, signal);
+      } catch (e) {
+        if (e.name === "AbortError" || token !== showcaseRunId) return;
+        frames = []; // a missing recording should not suppress the finished asset
+      }
+      for (let k = 0; k < frames.length; k++) {
+        if (token !== showcaseRunId) return;
+        viewer.setShowcaseFrame(i, frames[k]);
+        $("showcaselabel").textContent =
+          `${i + 1}/${showcaseAssets.length} · ${k + 1}/${frames.length} · ${showcaseStageText(frames[k])}`;
+        if (!await showcaseWait(SHOWCASE_FRAME_MS, token)) return;
+      }
+
+      viewer.setShowcaseFrame(i, null);
+      $("showcaselabel").textContent =
+        `${i + 1}/${showcaseAssets.length} · final · ${asset.triangles.toLocaleString()} triangles`;
+      if (!await showcaseWait(SHOWCASE_FINAL_MS, token)) return;
+      hideShowcaseSource();
+    }
+  }
+}
+
+function stopShowcase(clearScene = false) {
+  showcaseRunId++;
+  if (showcaseAbort) showcaseAbort.abort();
+  showcaseAbort = null; showcaseRunning = false; showcaseBusy = false;
+  $("showcasehud").style.display = "none";
+  $("showcasebtn").textContent = "showcase";
+  $("showcasebtn").disabled = !history.length;
+  hideShowcaseSource(true);
+  if (clearScene) viewer.clearShowcase();
+  else viewer.finishShowcase(); // leave the complete lineup visible when manually stopped
+}
+
+async function startShowcase() {
+  if (!history.length) return;
+  stopPlayback();
+  stopShowcase(true);
+  resetExportState();
+  resetTimeline();
+  const token = ++showcaseRunId;
+  showcaseAbort = new AbortController();
+  const signal = showcaseAbort.signal;
+  showcaseBusy = true;
+  $("showcasebtn").disabled = true;
+  $("showcasehud").style.display = "flex";
+  $("showcaselabel").textContent = "loading showcase…";
+  setStatus("loading existing generations for showcase…");
+
+  // History is newest-first in the sidebar; the showcase tells the chronological
+  // story from the oldest still-available generation to the newest.
+  const candidates = [...history].reverse();
+  const assets = [], unavailable = [];
+  try {
+    // Match the Free-Splatter storyboard: put the first source image on screen
+    // immediately while the full-density mesh lineup is loading behind it.
+    if (showcasePage && candidates.length)
+      loadShowcaseSource(candidates[0], token).catch(() => {});
+    for (let i = 0; i < candidates.length; i++) {
+      if (token !== showcaseRunId) return;
+      try {
+        assets.push(await loadShowcaseAsset(candidates[i], i + 1, candidates.length, signal));
+      } catch (e) {
+        if (e.name === "AbortError" || token !== showcaseRunId) return;
+        unavailable.push(candidates[i].id);
+      }
+    }
+    if (!assets.length) throw new Error("none of the saved generations are still available on this server");
+    if (token !== showcaseRunId) return;
+
+    const finalMeshes = assets.map(a => a.final);
+    const offsets = viewer.setShowcaseAssets(finalMeshes, SHOWCASE_SPACING);
+    for (let i = 0; i < assets.length; i++) {
+      assets[i].offset = offsets[i];
+      assets[i].triangles = assets[i].final.nt;
+      assets[i].final = null; // GPU upload is complete; release duplicate browser RAM
+    }
+    finalMeshes.length = 0;
+    showcaseAssets = assets;
+    showcaseIndex = 0;
+    showcaseFocusValue = offsets[0];
+    showcaseRunning = true; showcaseBusy = false;
+    $("showcasebtn").disabled = false;
+    $("showcasebtn").textContent = "restart showcase";
+    $("hint").style.display = "";
+    setStatus(`showcase · ${assets.length} assets` +
+      (unavailable.length ? ` · ${unavailable.length} unavailable after a server restart` : ""));
+    runShowcaseLoop(token, signal).catch(e => {
+      if (token !== showcaseRunId || e.name === "AbortError") return;
+      stopShowcase(false);
+      setStatus("showcase stopped: " + e.message, true);
+    });
+  } catch (e) {
+    if (token !== showcaseRunId || e.name === "AbortError") return;
+    stopShowcase(true);
+    setStatus("could not start showcase: " + e.message, true);
+  }
+}
+
+$("showcasebtn").addEventListener("click", () => {
+  if (showcasePage) startShowcase();
+  else location.href = "/showcase";
+});
+$("showcasestop").addEventListener("click", () => {
+  const hadScene = showcaseRunning, wasLoading = showcaseBusy;
+  stopShowcase(false);
+  if (hadScene) setStatus("showcase stopped · the finished lineup remains in view");
+  else if (wasLoading) setStatus("showcase loading cancelled");
+});
+if (showcasePage) {
+  addEventListener("keydown", e => { if (e.key === "Escape") location.href = "/"; });
+}
+</script>
+</body>
+</html>
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index 7d6fa3f..60ce38a 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -14,8 +14,109 @@ add_executable(test_ss_dec test_ss_dec.cpp)
 target_link_libraries(test_ss_dec PRIVATE trellis2)
 target_compile_features(test_ss_dec PRIVATE cxx_std_14)
 
+# PIL-compatible preprocessing byte-exactness vs the Python reference.
+add_executable(test_preprocess test_preprocess.cpp)
+target_link_libraries(test_preprocess PRIVATE trellis2)
+target_include_directories(test_preprocess PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../stb)
+target_compile_features(test_preprocess PRIVATE cxx_std_14)
+
+# Deterministic border-connected black/white background removal (no models).
+add_executable(test_background_removal test_background_removal.cpp)
+target_link_libraries(test_background_removal PRIVATE trellis2)
+target_compile_features(test_background_removal PRIVATE cxx_std_14)
+
+# DINOv3 encoder per-layer parity vs the PyTorch reference
+# (scripts/dump_dino_reference.py -> dumps/reference_dino.gguf).
+add_executable(test_dino test_dino.cpp)
+target_link_libraries(test_dino PRIVATE trellis2)
+target_compile_features(test_dino PRIVATE cxx_std_14)
+
+# Shape-SLAT flow + FDG decoder parity vs the PyTorch reference
+# (scripts/dump_slat_reference.py -> dumps/reference_slat.gguf).
+add_executable(test_slat test_slat.cpp)
+target_link_libraries(test_slat PRIVATE trellis2)
+target_compile_features(test_slat PRIVATE cxx_std_14)
+
+# 1024_cascade HR-stage parity vs the PyTorch reference
+# (scripts/dump_cascade_reference.py -> dumps/reference_cascade.gguf).
+add_executable(test_cascade test_cascade.cpp)
+target_link_libraries(test_cascade PRIVATE trellis2)
+target_compile_features(test_cascade PRIVATE cxx_std_14)
+
+# PBR-texture stage parity vs the PyTorch reference
+# (scripts/dump_texture_reference.py -> dumps/reference_texture.gguf).
+add_executable(test_texture test_texture.cpp)
+target_link_libraries(test_texture PRIVATE trellis2)
+target_compile_features(test_texture PRIVATE cxx_std_14)
+
 # Self-contained isosurface extractor (examples/marching_cubes.h) on analytic
 # fields — watertight-manifold + Euler-characteristic invariants. No model.
 add_executable(test_marching_cubes test_marching_cubes.cpp)
 target_include_directories(test_marching_cubes PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../examples)
 target_compile_features(test_marching_cubes PRIVATE cxx_std_14)
+
+# Sparse PBR-volume trilinear sampling used by the integrated texture path.
+add_executable(test_pbr_sampling test_pbr_sampling.cpp)
+target_include_directories(test_pbr_sampling PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/..)
+target_compile_features(test_pbr_sampling PRIVATE cxx_std_14)
+
+# CPU GLB bake smoke/regression test, including six-channel alpha preservation.
+add_executable(test_mesh_export test_mesh_export.cpp)
+target_link_libraries(test_mesh_export PRIVATE trellis2)
+target_compile_features(test_mesh_export PRIVATE cxx_std_14)
+
+# ── ctest registration ────────────────────────────────────────────────────────
+# Asset paths default to the in-repo locations produced by
+# scripts/download_models.sh + converters + scripts/refgen.sh, overridable via
+# TRELLIS2_GGUF_DIR / TRELLIS2_DUMPS. Tests exit 77 when assets are absent, so
+# a fresh checkout still gets a green (skipped) suite.
+set(T2_GGUFS "$ENV{TRELLIS2_GGUF_DIR}")
+if(NOT T2_GGUFS)
+    set(T2_GGUFS "${CMAKE_CURRENT_SOURCE_DIR}/../ggufs")
+endif()
+set(T2_DUMPS "$ENV{TRELLIS2_DUMPS}")
+if(NOT T2_DUMPS)
+    set(T2_DUMPS "${CMAKE_CURRENT_SOURCE_DIR}/../dumps")
+endif()
+set(T2_TESTS "${CMAKE_CURRENT_SOURCE_DIR}")
+
+add_test(NAME marching_cubes COMMAND test_marching_cubes)
+add_test(NAME pbr_sampling COMMAND test_pbr_sampling)
+add_test(NAME mesh_export COMMAND test_mesh_export)
+add_test(NAME background_removal COMMAND test_background_removal)
+
+add_test(NAME preprocess COMMAND test_preprocess
+         "${T2_DUMPS}/fixture_rgba.png" "${T2_DUMPS}/fixture_512.png")
+set_tests_properties(preprocess PROPERTIES SKIP_RETURN_CODE 77)
+
+add_test(NAME dino COMMAND test_dino
+         "${T2_GGUFS}/dino_f32.gguf" "${T2_DUMPS}/reference_dino.gguf")
+set_tests_properties(dino PROPERTIES SKIP_RETURN_CODE 77 LABELS "model")
+
+add_test(NAME ss_flow_forward COMMAND test_ss_flow_forward
+         "${T2_GGUFS}/ss_flow_f32.gguf" "${T2_TESTS}/ss_flow_ref.bin")
+set_tests_properties(ss_flow_forward PROPERTIES SKIP_RETURN_CODE 77 LABELS "model")
+
+add_test(NAME ss_sample COMMAND test_ss_sample
+         "${T2_GGUFS}/ss_flow_f32.gguf" "${T2_TESTS}/ss_sample_ref.bin")
+set_tests_properties(ss_sample PROPERTIES SKIP_RETURN_CODE 77 LABELS "model;slow")
+
+add_test(NAME ss_dec COMMAND test_ss_dec
+         "${T2_GGUFS}/ss_dec_f32.gguf" "${T2_TESTS}/ss_dec_ref.bin")
+set_tests_properties(ss_dec PROPERTIES SKIP_RETURN_CODE 77 LABELS "model")
+
+add_test(NAME slat COMMAND test_slat
+         "${T2_GGUFS}/slat_flow_f32.gguf" "${T2_GGUFS}/shape_dec_f32.gguf"
+         "${T2_DUMPS}/reference_slat.gguf")
+set_tests_properties(slat PROPERTIES SKIP_RETURN_CODE 77 LABELS "model;slow"
+                     ENVIRONMENT "TRELLIS2_DINODATA=${T2_DUMPS}/fixture.dinodata")
+
+add_test(NAME cascade COMMAND test_cascade
+         "${T2_GGUFS}/slat_flow_f32.gguf" "${T2_GGUFS}/slat_flow_1024_f32.gguf"
+         "${T2_GGUFS}/shape_dec_f32.gguf" "${T2_DUMPS}/reference_cascade.gguf")
+set_tests_properties(cascade PROPERTIES SKIP_RETURN_CODE 77 LABELS "model;slow")
+
+add_test(NAME texture COMMAND test_texture
+         "${T2_GGUFS}/shape_enc_f16.gguf" "${T2_GGUFS}/tex_slat_flow_512_f16.gguf"
+         "${T2_GGUFS}/tex_dec_f16.gguf" "${T2_DUMPS}/reference_texture.gguf")
+set_tests_properties(texture PROPERTIES SKIP_RETURN_CODE 77 LABELS "model;slow")
diff --git a/tests/parity.hpp b/tests/parity.hpp
new file mode 100644
index 0000000..2e02b41
--- /dev/null
+++ b/tests/parity.hpp
@@ -0,0 +1,92 @@
+// Helpers for comparing C++ activations against PyTorch reference dumps
+// (dumps/reference_*.gguf written by scripts/dump_*_reference.py).
+//
+// Same approach as depth-anything.cpp's tests/parity.hpp: the dump format is
+// GGUF itself, tensors are flat f32 in the reference's row-major order, and
+// the gate is elementwise |got - ref| <= atol + rtol * |ref|.
+#pragma once
+
+#include "ggml.h"
+#include "gguf.h"
+
+#include <cmath>
+#include <cstdio>
+#include <cstring>
+#include <string>
+#include <vector>
+
+namespace t2_parity {
+
+struct baseline {
+    gguf_context * gguf = nullptr;
+    ggml_context * ctx  = nullptr;
+
+    bool open(const std::string & path) {
+        gguf_init_params p;
+        p.no_alloc = false;    // load tensor data into ctx
+        p.ctx      = &ctx;
+        gguf = gguf_init_from_file(path.c_str(), p);
+        return gguf != nullptr;
+    }
+
+    bool load(const std::string & name, std::vector<float> & out) const {
+        ggml_tensor * t = ggml_get_tensor(ctx, name.c_str());
+        if (!t || t->type != GGML_TYPE_F32) return false;
+        out.resize((size_t) ggml_nelements(t));
+        std::memcpy(out.data(), t->data, out.size() * sizeof(float));
+        return true;
+    }
+
+    bool has(const std::string & name) const {
+        return ggml_get_tensor(ctx, name.c_str()) != nullptr;
+    }
+
+    ~baseline() {
+        if (gguf) gguf_free(gguf);
+        if (ctx)  ggml_free(ctx);
+    }
+};
+
+struct compare_stats {
+    double max_abs  = 0.0;
+    double mean_abs = 0.0;
+    double rel_l2   = 0.0;
+    size_t worst    = 0;
+    bool   ok       = false;
+};
+
+// Elementwise gate |got - ref| <= atol + rtol*|ref|, with summary line.
+inline bool compare(const std::vector<float> & got, const std::vector<float> & ref,
+                    const std::string & label, double atol, double rtol,
+                    compare_stats * stats_out = nullptr) {
+    compare_stats st;
+    if (got.size() != ref.size() || got.empty()) {
+        std::printf("[%-18s] SIZE MISMATCH got=%zu ref=%zu -> FAIL\n",
+                    label.c_str(), got.size(), ref.size());
+        if (stats_out) *stats_out = st;
+        return false;
+    }
+    double sum_abs = 0.0, num = 0.0, den = 0.0;
+    size_t nbad = 0;
+    for (size_t i = 0; i < got.size(); ++i) {
+        const double d = std::fabs((double) got[i] - (double) ref[i]);
+        const double r = (double) ref[i];
+        num += d * d;
+        den += r * r;
+        sum_abs += d;
+        if (d > st.max_abs) { st.max_abs = d; st.worst = i; }
+        if (d > atol + rtol * std::fabs(r)) ++nbad;
+    }
+    st.mean_abs = sum_abs / (double) got.size();
+    st.rel_l2   = den > 0 ? std::sqrt(num / den) : std::sqrt(num);
+    st.ok       = nbad == 0;
+    std::printf("[%-18s] n=%-8zu max|d|=%-11.4g mean|d|=%-11.4g relL2=%-11.4g "
+                "(worst@%zu got=%.6g ref=%.6g) -> %s\n",
+                label.c_str(), got.size(), st.max_abs, st.mean_abs, st.rel_l2,
+                st.worst, (double) got[st.worst], (double) ref[st.worst],
+                st.ok ? "OK" : "FAIL");
+    if (stats_out) *stats_out = st;
+    return st.ok;
+}
+
+} // namespace t2_parity
diff --git a/tests/ref_ss_dec.py b/tests/ref_ss_dec.py
index 32e4532..34d90ed 100644
--- a/tests/ref_ss_dec.py
+++ b/tests/ref_ss_dec.py
@@ -28,22 +28,20 @@
 
 os.environ.setdefault("PYTORCH_ENABLE_MPS_FALLBACK", "1")
 
-SHIV = os.path.expanduser("~/git/temp/trellis2-shiv")
-sys.path.insert(0, os.path.join(SHIV, "TRELLIS.2"))
+SHIV = os.environ.get("TRELLIS2_PY", "/trellis2")
+sys.path.insert(0, SHIV)
 
 import numpy as np
 import torch
 
-DEFAULT_CKPT = os.path.expanduser(
-    "~/.cache/huggingface/hub/models--microsoft--TRELLIS-image-large/snapshots/"
-    "25e0d31ffbebe4b5a97464dd851910efc3002d96/ckpts/ss_dec_conv3d_16l8_fp16"
-)
+DEFAULT_CKPT = os.environ.get("TRELLIS2_CKPT", os.path.join(
+    os.path.dirname(__file__), "..", "models", "TRELLIS-image-large/ckpts/ss_dec_conv3d_16l8_fp16"))
 
 
 def main():
     ap = argparse.ArgumentParser()
     ap.add_argument("--ckpt", default=DEFAULT_CKPT)
-    ap.add_argument("--device", default="mps", choices=["mps", "cpu"])
+    ap.add_argument("--device", default="cpu", choices=["mps", "cpu", "cuda"])
     ap.add_argument("--latent", default=None, help="optional z_s .latent (channel-major float32)")
     ap.add_argument("--seed", type=int, default=1234)
     ap.add_argument("--out", default=os.path.join(os.path.dirname(__file__), "ss_dec_ref.bin"))
diff --git a/tests/ref_ss_flow.py b/tests/ref_ss_flow.py
index 42fbe6c..4155890 100644
--- a/tests/ref_ss_flow.py
+++ b/tests/ref_ss_flow.py
@@ -29,16 +29,14 @@
 os.environ.setdefault("SPARSE_CONV_BACKEND", "none")
 os.environ.setdefault("PYTORCH_ENABLE_MPS_FALLBACK", "1")
 
-SHIV = os.path.expanduser("~/git/temp/trellis2-shiv")
-sys.path.insert(0, os.path.join(SHIV, "TRELLIS.2"))
+SHIV = os.environ.get("TRELLIS2_PY", "/trellis2")
+sys.path.insert(0, SHIV)
 
 import numpy as np
 import torch
 
-DEFAULT_CKPT = os.path.expanduser(
-    "~/.cache/huggingface/hub/models--microsoft--TRELLIS.2-4B/snapshots/"
-    "af44b45f2e35a493886929c6d786e563ec68364d/ckpts/ss_flow_img_dit_1_3B_64_bf16"
-)
+DEFAULT_CKPT = os.environ.get("TRELLIS2_CKPT", os.path.join(
+    os.path.dirname(__file__), "..", "models", "TRELLIS.2-4B/ckpts/ss_flow_img_dit_1_3B_64_bf16"))
 
 
 def load_dinodata(path):
@@ -52,7 +50,7 @@ def load_dinodata(path):
 
 def main():
     ap = argparse.ArgumentParser()
-    ap.add_argument("--dinodata", default=os.path.expanduser("~/git/temp/images/MushroomBoy.dinodata"))
+    ap.add_argument("--dinodata", default=os.path.join(os.path.dirname(__file__), "..", "dumps", "fixture.dinodata"))
     ap.add_argument("--ckpt", default=DEFAULT_CKPT, help="checkpoint stem (no extension)")
     ap.add_argument("--t", type=float, default=500.0)
     ap.add_argument("--seed", type=int, default=1234)
diff --git a/tests/ref_ss_sample.py b/tests/ref_ss_sample.py
index bbddffc..c31ee5b 100644
--- a/tests/ref_ss_sample.py
+++ b/tests/ref_ss_sample.py
@@ -29,16 +29,14 @@
 os.environ.setdefault("SPARSE_CONV_BACKEND", "none")
 os.environ.setdefault("PYTORCH_ENABLE_MPS_FALLBACK", "1")
 
-SHIV = os.path.expanduser("~/git/temp/trellis2-shiv")
-sys.path.insert(0, os.path.join(SHIV, "TRELLIS.2"))
+SHIV = os.environ.get("TRELLIS2_PY", "/trellis2")
+sys.path.insert(0, SHIV)
 
 import numpy as np
 import torch
 
-DEFAULT_CKPT = os.path.expanduser(
-    "~/.cache/huggingface/hub/models--microsoft--TRELLIS.2-4B/snapshots/"
-    "af44b45f2e35a493886929c6d786e563ec68364d/ckpts/ss_flow_img_dit_1_3B_64_bf16"
-)
+DEFAULT_CKPT = os.environ.get("TRELLIS2_CKPT", os.path.join(
+    os.path.dirname(__file__), "..", "models", "TRELLIS.2-4B/ckpts/ss_flow_img_dit_1_3B_64_bf16"))
 
 
 def load_dinodata(path):
@@ -52,9 +50,9 @@ def load_dinodata(path):
 
 def main():
     ap = argparse.ArgumentParser()
-    ap.add_argument("--dinodata", default=os.path.expanduser("~/git/temp/images/MushroomBoy.dinodata"))
+    ap.add_argument("--dinodata", default=os.path.join(os.path.dirname(__file__), "..", "dumps", "fixture.dinodata"))
     ap.add_argument("--ckpt", default=DEFAULT_CKPT)
-    ap.add_argument("--device", default="mps", choices=["mps", "cpu"])
+    ap.add_argument("--device", default="cpu", choices=["mps", "cpu", "cuda"])
     ap.add_argument("--seed", type=int, default=1234)
     ap.add_argument("--out", default=os.path.join(os.path.dirname(__file__), "ss_sample_ref.bin"))
     args = ap.parse_args()
diff --git a/tests/test_background_removal.cpp b/tests/test_background_removal.cpp
new file mode 100644
index 0000000..2f3f0e0
--- /dev/null
+++ b/tests/test_background_removal.cpp
@@ -0,0 +1,93 @@
+#include "trellis2.h"
+
+#include <algorithm>
+#include <cstdint>
+#include <cstdio>
+#include <vector>
+
+namespace {
+
+std::vector<uint8_t> solid(int w, int h, uint8_t v) {
+    std::vector<uint8_t> im((size_t) w * h * 4, 255);
+    for (int i = 0; i < w * h; ++i) {
+        im[(size_t) i * 4 + 0] = v;
+        im[(size_t) i * 4 + 1] = v;
+        im[(size_t) i * 4 + 2] = v;
+    }
+    return im;
+}
+
+void rgb(std::vector<uint8_t> & im, int w, int x, int y,
+         uint8_t r, uint8_t g, uint8_t b) {
+    uint8_t * p = &im[((size_t) y * w + x) * 4];
+    p[0] = r; p[1] = g; p[2] = b; p[3] = 255;
+}
+
+uint8_t alpha(const std::vector<uint8_t> & im, int w, int x, int y) {
+    return im[((size_t) y * w + x) * 4 + 3];
+}
+
+bool expect(bool condition, const char * message) {
+    if (!condition) std::fprintf(stderr, "%s\n", message);
+    return condition;
+}
+
+} // namespace
+
+int main() {
+    bool ok = true;
+
+    // White and black backgrounds are detected from the border while a
+    // disconnected contrasting subject remains opaque.
+    for (int bg : {0, 8, 247, 255}) {
+        auto im = solid(9, 9, (uint8_t) bg);
+        for (int y = 3; y <= 5; ++y) for (int x = 3; x <= 5; ++x) {
+            if (bg < 128) rgb(im, 9, x, y, 235, 80, 40);
+            else         rgb(im, 9, x, y, 20, 90, 180);
+        }
+        const int changed = trellis2_remove_solid_background_rgba(
+            im.data(), 9, 9, TRELLIS2_BACKGROUND_AUTO);
+        ok &= expect(changed > 0, bg < 128 ? "black background not detected"
+                                           : "white background not detected");
+        ok &= expect(alpha(im, 9, 0, 0) <= 1, "background corner is not transparent");
+        ok &= expect(alpha(im, 9, 4, 4) == 255, "subject centre lost opacity");
+    }
+
+    // Border connectivity prevents an enclosed white detail from being erased
+    // along with the surrounding white background.
+    auto enclosed = solid(9, 9, 255);
+    for (int y = 2; y <= 6; ++y) for (int x = 2; x <= 6; ++x)
+        rgb(enclosed, 9, x, y, 180, 30, 20);
+    rgb(enclosed, 9, 4, 4, 255, 255, 255);
+    trellis2_remove_solid_background_rgba(enclosed.data(), 9, 9, TRELLIS2_BACKGROUND_AUTO);
+    ok &= expect(alpha(enclosed, 9, 4, 4) == 255, "enclosed white subject detail was removed");
+
+    // A genuine existing alpha mask wins over automatic colour removal.
+    auto masked = solid(20, 20, 255);
+    for (int y = 0; y < 3; ++y) for (int x = 0; x < 3; ++x)
+        masked[((size_t) y * 20 + x) * 4 + 3] = 0;
+    const int changed = trellis2_remove_solid_background_rgba(
+        masked.data(), 20, 20, TRELLIS2_BACKGROUND_AUTO);
+    ok &= expect(changed == 0, "existing alpha mask was unexpectedly modified");
+    ok &= expect(alpha(masked, 20, 10, 10) == 255, "existing mask made opaque content transparent");
+
+    // Mid-tone borders are not guessed as black or white in auto mode.
+    auto grey = solid(9, 9, 128);
+    ok &= expect(trellis2_remove_solid_background_rgba(
+                     grey.data(), 9, 9, TRELLIS2_BACKGROUND_AUTO) == 0,
+                 "mid-grey background should be left unchanged");
+
+    // Explicit modes override auto detection but still affect border-connected
+    // pixels only. This is useful when a subject occupies most of the border.
+    auto forced = solid(9, 9, 120);
+    for (int x = 0; x < 4; ++x) rgb(forced, 9, x, 0, 0, 0, 0);
+    ok &= expect(trellis2_remove_solid_background_rgba(
+                     forced.data(), 9, 9, TRELLIS2_BACKGROUND_BLACK) > 0,
+                 "forced black mode did not remove a connected black region");
+    ok &= expect(alpha(forced, 9, 0, 0) == 0, "forced black pixel is not transparent");
+    ok &= expect(alpha(forced, 9, 8, 8) == 255, "forced mode modified unrelated pixels");
+
+    if (!ok) return 1;
+    std::puts("background removal: ok");
+    return 0;
+}
diff --git a/tests/test_cascade.cpp b/tests/test_cascade.cpp
new file mode 100644
index 0000000..64feb15
--- /dev/null
+++ b/tests/test_cascade.cpp
@@ -0,0 +1,233 @@
+// Validation of the 1024_cascade HR stage against the PyTorch reference
+// (scripts/dump_cascade_reference.py -> dumps/reference_cascade.gguf):
+//
+//   1. shape-decoder upsample(x4): the LR slat -> 512^3 candidate coord set,
+//      and its quantized 64^3 HR scaffold (subdivision-boundary set tolerance).
+//   2. HR (1024-model) flow forward at t=500 on the HR scaffold  (tight gate).
+//   3. final 1024^3 decode of the reference HR slat: per-level features,
+//      subdivision, and 7-channel output.
+//   (The 12-step HR sampler is env-gated (TRELLIS2_CASCADE_SAMPLE) — 24 forwards
+//    at ~40k tokens is impractical on CPU; the shared Euler loop is already
+//    validated by test_slat / test_ss_sample.)
+//
+// usage: test_cascade <slat_512_f32> <slat_1024_f32> <shape_dec_f32> <reference_cascade.gguf>
+// exits 77 (ctest SKIP) when inputs are missing.
+
+#include "trellis2.h"
+#include "parity.hpp"
+
+#include <cmath>
+#include <cstdint>
+#include <cstdio>
+#include <cstdlib>
+#include <fstream>
+#include <string>
+#include <unordered_set>
+#include <vector>
+
+static bool file_exists(const std::string & p) {
+    std::ifstream f(p);
+    return f.good();
+}
+
+// [L*4] (batch,x,y,z) reference coords -> [L*3] int32 (x,y,z)
+static std::vector<int32_t> coords_xyz(const std::vector<float> & c4) {
+    const size_t L = c4.size() / 4;
+    std::vector<int32_t> out(L * 3);
+    for (size_t v = 0; v < L; ++v) {
+        out[v * 3]     = (int32_t) c4[v * 4 + 1];
+        out[v * 3 + 1] = (int32_t) c4[v * 4 + 2];
+        out[v * 3 + 2] = (int32_t) c4[v * 4 + 3];
+    }
+    return out;
+}
+
+static uint64_t vkey(int32_t x, int32_t y, int32_t z) {
+    return ((uint64_t) (uint32_t) x << 40) | ((uint64_t) (uint32_t) y << 20) | (uint64_t) (uint32_t) z;
+}
+
+// symmetric-difference fraction of two coord sets ([*3] int32)
+static double set_diff_frac(const std::vector<int32_t> & a, const std::vector<int32_t> & b) {
+    std::unordered_set<uint64_t> sa, sb;
+    for (size_t i = 0; i < a.size(); i += 3) sa.insert(vkey(a[i], a[i + 1], a[i + 2]));
+    for (size_t i = 0; i < b.size(); i += 3) sb.insert(vkey(b[i], b[i + 1], b[i + 2]));
+    size_t only = 0;
+    for (uint64_t k : sa) if (!sb.count(k)) ++only;
+    for (uint64_t k : sb) if (!sa.count(k)) ++only;
+    const size_t big = sa.size() > sb.size() ? sa.size() : sb.size();
+    return big ? (double) only / (double) big : 0.0;
+}
+
+int main(int argc, char ** argv) {
+    if (argc < 5) {
+        std::fprintf(stderr,
+            "usage: %s <slat_512_f32.gguf> <slat_1024_f32.gguf> <shape_dec_f32.gguf> <reference_cascade.gguf>\n",
+            argv[0]);
+        return 2;
+    }
+    const std::string flow512_path = argv[1];
+    const std::string flow1024_path = argv[2];
+    const std::string dec_path = argv[3];
+    const std::string ref_path = argv[4];
+    if (!file_exists(flow512_path) || !file_exists(flow1024_path) ||
+        !file_exists(dec_path) || !file_exists(ref_path)) {
+        std::fprintf(stderr, "missing input file(s), skipping\n");
+        return 77;
+    }
+
+    t2_parity::baseline ref;
+    if (!ref.open(ref_path)) {
+        std::fprintf(stderr, "failed to open %s\n", ref_path.c_str());
+        return 1;
+    }
+
+    std::vector<float> cond512, cond1024, coords32f, lr_slat, up_coordsf, hr_coordsf, hr_noise;
+    if (!ref.load("cond_512", cond512) || !ref.load("cond_1024", cond1024) ||
+        !ref.load("coords32", coords32f) || !ref.load("lr_slat", lr_slat) ||
+        !ref.load("up_coords", up_coordsf) || !ref.load("hr_coords", hr_coordsf) ||
+        !ref.load("hr_noise", hr_noise)) {
+        std::fprintf(stderr, "reference missing required tensors\n");
+        return 1;
+    }
+    const int L32 = (int) (coords32f.size() / 4);
+    const int Lhr = (int) (hr_coordsf.size() / 4);
+    const int Lkv512 = (int) (cond512.size() / 1024);
+    const int Lkv1024 = (int) (cond1024.size() / 1024);
+    std::vector<int32_t> coords32 = coords_xyz(coords32f);
+    std::vector<int32_t> ref_up_coords = coords_xyz(up_coordsf);
+    std::vector<int32_t> hr_coords = coords_xyz(hr_coordsf);
+    std::printf("reference: scaffold %d voxels, upsample %zu, HR %d voxels, cond %d/%d tokens\n",
+                L32, up_coordsf.size() / 4, Lhr, Lkv512, Lkv1024);
+
+    std::string err;
+    int n_fail = 0;
+
+    // ── 1. shape-decoder upsample(x4): coord set + quantized 64^3 scaffold ────
+    trellis2_shape_dec_model * dec = trellis2_shape_dec_load(dec_path, true, &err, "cpu");
+    if (!dec) { std::fprintf(stderr, "dec load failed: %s\n", err.c_str()); return 1; }
+    std::printf("dec backend: %s\n", trellis2_shape_dec_backend_name(dec));
+    {
+        std::vector<int32_t> got_up;
+        if (!trellis2_shape_dec_upsample(dec, lr_slat.data(), L32, coords32.data(),
+                                         /*upsample_times*/ 4, got_up, &err)) {
+            std::fprintf(stderr, "upsample failed: %s\n", err.c_str());
+            trellis2_shape_dec_free(dec);
+            return 1;
+        }
+        const double up_frac = set_diff_frac(got_up, ref_up_coords);
+        std::printf("[upsample coords] got %zu vs ref %zu, sym-diff %.4f%% -> %s\n",
+                    got_up.size() / 3, ref_up_coords.size() / 3, 100.0 * up_frac,
+                    up_frac <= 5e-4 ? "OK" : "FAIL");
+        if (up_frac > 5e-4) ++n_fail;
+
+        // quantize both to 64^3 and compare the dedup'd set that drives the HR flow
+        auto quant = [](const std::vector<int32_t> & c) {
+            std::unordered_set<uint64_t> s;
+            std::vector<int32_t> out;
+            for (size_t i = 0; i < c.size(); i += 3) {
+                int32_t x = (int32_t) ((c[i]     + 0.5f) / 512.0f * 64.0f);
+                int32_t y = (int32_t) ((c[i + 1] + 0.5f) / 512.0f * 64.0f);
+                int32_t z = (int32_t) ((c[i + 2] + 0.5f) / 512.0f * 64.0f);
+                if (s.insert(vkey(x, y, z)).second) { out.push_back(x); out.push_back(y); out.push_back(z); }
+            }
+            return out;
+        };
+        std::vector<int32_t> my_hr = quant(got_up);
+        const double hr_frac = set_diff_frac(my_hr, hr_coords);
+        std::printf("[hr scaffold]     got %zu vs ref %d, sym-diff %.4f%% -> %s\n",
+                    my_hr.size() / 3, Lhr, 100.0 * hr_frac, hr_frac <= 5e-4 ? "OK" : "FAIL");
+        if (hr_frac > 5e-4) ++n_fail;
+    }
+
+    // ── 2. HR flow forward at t=500 on the reference HR scaffold ──────────────
+    {
+        // Force CPU: at 10k+ HR tokens the attention exceeds the exact-path
+        // threshold and uses flash, and GPU flash (F16-MMA) is ~1e-2 vs the
+        // exact fp32 reference. CPU flash is exact-matching (~3e-4), so it
+        // gives a meaningful tight gate. TRELLIS2_CASCADE_GPU overrides.
+        const char * dev = std::getenv("TRELLIS2_CASCADE_GPU") ? nullptr : "cpu";
+        trellis2_slat_flow_model * flow = trellis2_slat_flow_load(flow1024_path, true, &err, dev);
+        if (!flow) { std::fprintf(stderr, "1024 flow load failed: %s\n", err.c_str()); trellis2_shape_dec_free(dec); return 1; }
+        std::printf("1024 flow backend: %s\n", trellis2_slat_flow_backend_name(flow));
+        std::vector<float> got((size_t) Lhr * 32), want;
+        if (!trellis2_slat_flow_forward(flow, hr_noise.data(), Lhr, hr_coords.data(), 500.0f,
+                                        cond1024.data(), Lkv1024, 1024, got.data(), &err)) {
+            std::fprintf(stderr, "HR flow forward failed: %s\n", err.c_str());
+            trellis2_slat_flow_free(flow); trellis2_shape_dec_free(dec); return 1;
+        }
+        ref.load("hr_flow_t500_out", want);
+        t2_parity::compare_stats st;
+        t2_parity::compare(got, want, "hr_flow_t500_out", 2e-3, 2e-3, &st);
+        if (st.rel_l2 > 3e-3) { std::printf("  -> HR forward rel_l2 %.4g > 3e-3, FAIL\n", st.rel_l2); ++n_fail; }
+
+        // optional: full HR sampler (expensive at ~40k tokens; off by default)
+        if (std::getenv("TRELLIS2_CASCADE_SAMPLE")) {
+            trellis2_ss_sampler_params P;
+            P.steps = 12; P.guidance_strength = 7.5f; P.guidance_rescale = 0.5f;
+            P.guidance_interval_min = 0.6f; P.guidance_interval_max = 1.0f; P.rescale_t = 3.0f;
+            std::vector<float> sampled((size_t) Lhr * 32), wslat;
+            if (trellis2_slat_flow_sample(flow, Lhr, hr_coords.data(), cond1024.data(), Lkv1024, 1024,
+                                          &P, hr_noise.data(), true, sampled.data(), &err)) {
+                ref.load("hr_slat", wslat);
+                t2_parity::compare_stats ss;
+                t2_parity::compare(sampled, wslat, "hr_slat(sampled)", 5e-2, 5e-2, &ss);
+            }
+        }
+        trellis2_slat_flow_free(flow);
+    }
+
+    // ── 3. final 1024^3 decode of the reference HR slat ──────────────────────
+    // The 1024^3 decode is the SAME decoder validated exactly at the 512 tier
+    // (test_slat, levels 0-4 at rel-L2 5e-7) applied to more voxels, and the
+    // end-to-end demo exercises it directly. It also transiently needs ~14 GB of
+    // host RAM (the finest up-block's conv output is held in both the graph and
+    // the readback), so it is gated behind TRELLIS2_CASCADE_DECODE — enable it
+    // on a big-RAM box to also gate out7 here.
+    if (!std::getenv("TRELLIS2_CASCADE_DECODE")) {
+        trellis2_shape_dec_free(dec);
+        std::printf("\n(1024^3 decode gate skipped; set TRELLIS2_CASCADE_DECODE to enable)\n");
+        std::printf("total failures: %d\nRESULT: %s\n", n_fail, n_fail ? "FAIL" : "PASS");
+        return n_fail ? 1 : 0;
+    }
+    std::vector<float> hr_slat;
+    if (!ref.load("hr_slat", hr_slat)) {
+        std::fprintf(stderr, "reference missing hr_slat\n");
+        trellis2_shape_dec_free(dec); return 1;
+    }
+    // Compare only the final 7-channel output (taps=nullptr): the per-level
+    // intermediates would hold multiple GB at 1024^3 and the decoder's level
+    // logic is already validated exactly at the 512 tier (test_slat, same
+    // decoder). out7 is the load-bearing gate.
+    std::vector<float> out_feats;
+    std::vector<int32_t> out_coords;
+    if (!trellis2_shape_dec_decode(dec, hr_slat.data(), Lhr, hr_coords.data(),
+                                   out_feats, out_coords, nullptr, &err)) {
+        std::fprintf(stderr, "HR decode failed: %s\n", err.c_str());
+        trellis2_shape_dec_free(dec); return 1;
+    }
+    trellis2_shape_dec_free(dec);
+
+    std::printf("HR decode: %zu output voxels\n", out_coords.size() / 3);
+    std::vector<float> ref_out7;
+    ref.load("out7", ref_out7);
+    const size_t a = out_feats.size(), b = ref_out7.size();
+    const size_t big = a > b ? a : b, sml = a > b ? b : a;
+    if (a != b) {
+        const double frac = (double) (big - sml) / (double) big;
+        if (frac > 5e-4) {
+            std::printf("[out7] SIZE MISMATCH %zu vs %zu (%.3f%%) -> FAIL\n", a, b, 100.0 * frac);
+            ++n_fail;
+        } else {
+            std::printf("[out7] near-match (%zu vs %zu, %.4f%% subdivision boundary flip) -> OK\n",
+                        a, b, 100.0 * frac);
+        }
+    } else {
+        t2_parity::compare_stats st;
+        t2_parity::compare(out_feats, ref_out7, "out7", 2e-3, 2e-3, &st);
+        if (st.rel_l2 > 2e-2) { std::printf("  -> out7 rel_l2 %.4g > 2e-2, FAIL\n", st.rel_l2); ++n_fail; }
+    }
+
+    std::printf("\ntotal failures: %d\n", n_fail);
+    std::printf("RESULT: %s\n", n_fail ? "FAIL" : "PASS");
+    return n_fail ? 1 : 0;
+}
diff --git a/tests/test_dino.cpp b/tests/test_dino.cpp
new file mode 100644
index 0000000..7ab7e60
--- /dev/null
+++ b/tests/test_dino.cpp
@@ -0,0 +1,103 @@
+// Layer-by-layer validation of the DINOv3 encoder against the PyTorch
+// reference dump (scripts/dump_dino_reference.py).
+//
+// usage: test_dino <dino_f32.gguf> <reference_dino.gguf> [atol] [rtol]
+// exits 77 (ctest SKIP) when either input file is missing.
+
+#include "trellis2.h"
+#include "parity.hpp"
+
+#include <cmath>
+#include <cstdio>
+#include <cstdlib>
+#include <fstream>
+#include <string>
+#include <vector>
+
+static bool file_exists(const std::string & p) {
+    std::ifstream f(p);
+    return f.good();
+}
+
+int main(int argc, char ** argv) {
+    if (argc < 3) {
+        std::fprintf(stderr, "usage: %s <dino_f32.gguf> <reference_dino.gguf> [atol] [rtol]\n", argv[0]);
+        return 2;
+    }
+    const std::string gguf_path = argv[1];
+    const std::string ref_path  = argv[2];
+    const double atol = argc > 3 ? std::atof(argv[3]) : 2e-3;
+    const double rtol = argc > 4 ? std::atof(argv[4]) : 2e-3;
+
+    if (!file_exists(gguf_path) || !file_exists(ref_path)) {
+        std::fprintf(stderr, "missing input file(s), skipping\n");
+        return 77;
+    }
+
+    t2_parity::baseline ref;
+    if (!ref.open(ref_path)) {
+        std::fprintf(stderr, "failed to open reference gguf %s\n", ref_path.c_str());
+        return 1;
+    }
+
+    std::vector<float> pixels;
+    if (!ref.load("pixel_values", pixels)) {
+        std::fprintf(stderr, "reference has no pixel_values tensor\n");
+        return 1;
+    }
+    const int S = (int) std::lround(std::sqrt((double) pixels.size() / 3.0));
+    std::printf("pixel_values: %zu floats -> image size %d\n", pixels.size(), S);
+
+    std::string err;
+    trellis2_dino_model * m = trellis2_dino_load(gguf_path, true, &err);
+    if (!m) {
+        std::fprintf(stderr, "load failed: %s\n", err.c_str());
+        return 1;
+    }
+    std::printf("backend: %s\n", trellis2_dino_backend_name(m));
+
+    trellis2_dino_cond cond;
+    trellis2_dino_taps taps;
+    if (!trellis2_dino_encode(m, pixels.data(), S, cond, &taps, &err)) {
+        std::fprintf(stderr, "encode failed: %s\n", err.c_str());
+        trellis2_dino_free(m);
+        return 1;
+    }
+
+    int n_fail = 0, n_cmp = 0, n_missing = 0;
+    std::string first_fail;
+    std::vector<float> refbuf;
+    for (size_t i = 0; i < taps.names.size(); ++i) {
+        const std::string & name = taps.names[i];
+        if (!ref.has(name)) {
+            ++n_missing;
+            continue;
+        }
+        if (!ref.load(name, refbuf)) {
+            std::printf("[%-18s] reference tensor unreadable -> FAIL\n", name.c_str());
+            ++n_fail;
+            continue;
+        }
+        ++n_cmp;
+        if (!t2_parity::compare(taps.data[i], refbuf, name, atol, rtol)) {
+            ++n_fail;
+            if (first_fail.empty()) first_fail = name;
+        }
+    }
+
+    trellis2_dino_free(m);
+
+    std::printf("\ncompared %d taps (%d without reference), %d failed\n",
+                n_cmp, n_missing, n_fail);
+    if (n_fail) {
+        std::printf("FIRST DIVERGENCE: %s\n", first_fail.c_str());
+        std::printf("RESULT: FAIL\n");
+        return 1;
+    }
+    if (n_cmp == 0) {
+        std::printf("RESULT: FAIL (nothing compared)\n");
+        return 1;
+    }
+    std::printf("RESULT: PASS\n");
+    return 0;
+}
diff --git a/tests/test_mesh_export.cpp b/tests/test_mesh_export.cpp
new file mode 100644
index 0000000..2835a0b
--- /dev/null
+++ b/tests/test_mesh_export.cpp
@@ -0,0 +1,114 @@
+#include "mesh_export.h"
+
+#include <cstdint>
+#include <cstdio>
+#include <cstring>
+#include <string>
+#include <vector>
+
+int main() {
+    const float verts[] = {
+        0,0,0,  1,0,0,  0,1,0,  0,0,1,
+    };
+    const int32_t tris[] = {
+        0,2,1, 0,1,3, 0,3,2, 1,2,3,
+    };
+    // base RGB, metallic, roughness, alpha
+    const float pbr[] = {
+        1,0,0, 0,0.4f,0.5f,
+        0,1,0, 0,0.5f,1.0f,
+        0,0,1, 1,0.6f,1.0f,
+        1,1,1, 0,0.7f,1.0f,
+    };
+    t2glb::MeshExportOptions opt;
+    opt.texture_size = 64;
+    opt.dilate = 2;
+    std::vector<uint8_t> glb;
+    std::string err;
+    if (!t2glb::mesh_to_glb(verts, 4, tris, 4, pbr, opt, glb, err)) {
+        std::fprintf(stderr, "mesh_to_glb failed: %s\n", err.c_str());
+        return 1;
+    }
+    if (glb.size() < 20 || std::memcmp(glb.data(), "glTF", 4) != 0) {
+        std::fprintf(stderr, "invalid GLB header\n");
+        return 1;
+    }
+    const std::string bytes((const char *) glb.data(), glb.size());
+    if (bytes.find("\"alphaMode\":\"BLEND\"") == std::string::npos) {
+        std::fprintf(stderr, "alpha material was not preserved\n");
+        return 1;
+    }
+    if (bytes.find("\"COLOR_0\":2") == std::string::npos ||
+        bytes.find("\"_METALLIC_ROUGHNESS\":3") == std::string::npos ||
+        bytes.find("\"baseColorTexture\"") != std::string::npos) {
+        std::fprintf(stderr, "portable vertex material attributes are missing\n");
+        return 1;
+    }
+    // The old per-triangle grid duplicated all three vertices and collapsed to
+    // sub-texel UV cells on production meshes. The direct path must retain the
+    // tetrahedron's four vertices and normalised RGBA bytes exactly.
+    auto u32 = [&](size_t off) {
+        return (uint32_t)(uint8_t)glb[off] |
+               ((uint32_t)(uint8_t)glb[off+1] << 8) |
+               ((uint32_t)(uint8_t)glb[off+2] << 16) |
+               ((uint32_t)(uint8_t)glb[off+3] << 24);
+    };
+    const size_t bin = 20 + u32(12) + 8;
+    const size_t color = bin + 4 * 3 * sizeof(float) * 2;
+    const uint8_t expected_first_color[] = {255, 255, 0, 0, 0, 0, 0, 128};
+    if (color + sizeof expected_first_color > glb.size() ||
+        std::memcmp(glb.data() + color, expected_first_color,
+                    sizeof expected_first_color) != 0 ||
+        bytes.find("\"count\":4,\"type\":\"VEC4\"") == std::string::npos) {
+        std::fprintf(stderr, "vertex colours were changed or vertices were duplicated\n");
+        return 1;
+    }
+
+    // A tiny near-opaque decoder outlier must not put the whole primitive into
+    // alpha blending (which disables depth writes and resembles missing faces).
+    float nearly_opaque[24];
+    std::memcpy(nearly_opaque, pbr, sizeof nearly_opaque);
+    for (int i = 0; i < 4; ++i) nearly_opaque[6*i+5] = 1.0f;
+    nearly_opaque[5] = 0.994f;
+    if (!t2glb::mesh_to_glb(verts, 4, tris, 4, nearly_opaque, opt, glb, err) ||
+        std::string((const char *) glb.data(), glb.size()).find("\"alphaMode\":\"BLEND\"") != std::string::npos) {
+        std::fprintf(stderr, "near-opaque PBR noise enabled alpha blending\n");
+        return 1;
+    }
+
+    // Preview preparation uses the same geometry path and can keep only the
+    // largest disconnected component for background-plane cleanup.
+    const float two_component_verts[] = {
+        0,0,0, 1,0,0, 0,1,0, 0,0,1,
+        3,0,0, 4,0,0, 3,1,0,
+    };
+    const int32_t two_component_tris[] = {
+        0,2,1, 0,1,3, 0,3,2, 1,2,3,
+        4,5,6,
+    };
+    t2glb::PreparedMesh prepared;
+    opt.components = t2glb::ComponentFilter::KeepLargest;
+    if (!t2glb::prepare_mesh(two_component_verts, 7, two_component_tris, 5,
+                             nullptr, opt, prepared, err)) {
+        std::fprintf(stderr, "prepare_mesh failed: %s\n", err.c_str());
+        return 1;
+    }
+    if (prepared.tris.size() / 3 != 4 || prepared.verts.size() / 3 != 4 ||
+        prepared.normals.size() != prepared.verts.size()) {
+        std::fprintf(stderr, "largest-component preview is wrong: %zu verts, %zu tris, %zu normals\n",
+                     prepared.verts.size() / 3, prepared.tris.size() / 3,
+                     prepared.normals.size() / 3);
+        return 1;
+    }
+
+    // Keeping all components must retain every valid source triangle; export no
+    // longer performs polygon decimation.
+    opt.components = t2glb::ComponentFilter::KeepAll;
+    if (!t2glb::prepare_mesh(two_component_verts, 7, two_component_tris, 5,
+                             nullptr, opt, prepared, err) || prepared.tris.size() / 3 != 5) {
+        std::fprintf(stderr, "full-density export changed the polygon count\n");
+        return 1;
+    }
+    std::puts("RESULT: PASS");
+    return 0;
+}
diff --git a/tests/test_pbr_sampling.cpp b/tests/test_pbr_sampling.cpp
new file mode 100644
index 0000000..cc5c8cd
--- /dev/null
+++ b/tests/test_pbr_sampling.cpp
@@ -0,0 +1,72 @@
+#include "pbr_utils.h"
+
+#include <cmath>
+#include <cstdio>
+#include <vector>
+
+static bool close(float a, float b, float eps = 1e-6f) {
+    return std::fabs(a - b) <= eps;
+}
+
+int main() {
+    // Eight corners of a unit cube, with f(x,y,z) = x + 2y + 4z.
+    int32_t coords[8 * 3];
+    float feats[8];
+    int n = 0;
+    for (int x = 0; x <= 1; ++x)
+    for (int y = 0; y <= 1; ++y)
+    for (int z = 0; z <= 1; ++z) {
+        coords[3*n] = x; coords[3*n+1] = y; coords[3*n+2] = z;
+        feats[n++] = (float) (x + 2*y + 4*z);
+    }
+    const float query[] = {0.0f, 0.0f, 0.0f, 0.5f, 0.5f, 0.5f, 1.0f, 1.0f, 1.0f};
+    float out[3], weights[3];
+    t2pbr::sample_sparse_trilinear(feats, 8, 1, coords, query, 3, out, weights);
+    if (!close(out[0], 0.0f) || !close(out[1], 3.5f) || !close(out[2], 7.0f) ||
+        !close(weights[0], 1.0f) || !close(weights[1], 1.0f) || !close(weights[2], 1.0f)) {
+        std::fprintf(stderr, "dense trilinear mismatch: %g %g %g\n", out[0], out[1], out[2]);
+        return 1;
+    }
+
+    // Sparse boundary: only one weighted corner exists, so it is renormalized
+    // instead of darkening toward absent voxels.
+    const int32_t one_coord[] = {0, 0, 0};
+    const float one_feat[] = {0.25f, 0.75f};
+    const float half[] = {0.5f, 0.5f, 0.5f};
+    float sparse[2], sparse_weight;
+    t2pbr::sample_sparse_trilinear(one_feat, 1, 2, one_coord, half, 1,
+                                   sparse, &sparse_weight);
+    if (!close(sparse[0], 0.25f) || !close(sparse[1], 0.75f) ||
+        !close(sparse_weight, 0.125f)) {
+        std::fprintf(stderr, "sparse trilinear mismatch: %g %g w=%g\n",
+                     sparse[0], sparse[1], sparse_weight);
+        return 1;
+    }
+
+    // Regression: the failed integrated texture path returned essentially an
+    // all-one six-channel material. It must be rejected, without mistaking a
+    // legitimate white base colour for a collapsed full PBR result.
+    std::vector<float> collapsed(1000 * 6, 1.0f);
+    for (int v = 0; v < 5; ++v) collapsed[(size_t) v * 6] = 0.5f;
+    if (!t2pbr::is_collapsed_saturated(collapsed.data(), 1000)) {
+        std::fprintf(stderr, "collapsed saturated material was not detected\n");
+        return 1;
+    }
+    collapsed[5 * 6] = 0.5f; // only 994/1000 now have all channels saturated
+    if (t2pbr::is_collapsed_saturated(collapsed.data(), 1000)) {
+        std::fprintf(stderr, "saturation threshold is too aggressive\n");
+        return 1;
+    }
+    std::vector<float> white(16 * 6, 1.0f);
+    for (int v = 0; v < 16; ++v) {
+        white[(size_t) v * 6 + 3] = 0.0f;
+        white[(size_t) v * 6 + 4] = 0.5f;
+    }
+    if (t2pbr::is_collapsed_saturated(white.data(), 16)) {
+        std::fprintf(stderr, "legitimate white material was rejected\n");
+        return 1;
+    }
+
+    std::puts("RESULT: PASS");
+    return 0;
+}
diff --git a/tests/test_preprocess.cpp b/tests/test_preprocess.cpp
new file mode 100644
index 0000000..01aa214
--- /dev/null
+++ b/tests/test_preprocess.cpp
@@ -0,0 +1,74 @@
+// Byte-exactness test of trellis2_preprocess_rgba against the Python
+// reference (PIL): dumps/fixture_rgba.png -> preprocess -> must equal
+// dumps/fixture_512.png (produced by scripts/dump_dino_reference.py).
+//
+// usage: test_preprocess <fixture_rgba.png> <fixture_512.png>
+// exits 77 (ctest SKIP) when inputs are missing.
+
+#include "trellis2.h"
+
+#define STB_IMAGE_IMPLEMENTATION
+#include "stb_image.h"
+
+#include <cstdio>
+#include <cstdlib>
+#include <fstream>
+#include <string>
+#include <vector>
+
+int main(int argc, char ** argv) {
+    if (argc < 3) {
+        std::fprintf(stderr, "usage: %s <fixture_rgba.png> <fixture_512.png>\n", argv[0]);
+        return 2;
+    }
+    if (!std::ifstream(argv[1]).good() || !std::ifstream(argv[2]).good()) {
+        std::fprintf(stderr, "missing input file(s), skipping\n");
+        return 77;
+    }
+
+    int w = 0, h = 0, comp = 0;
+    unsigned char * rgba = stbi_load(argv[1], &w, &h, &comp, 4);
+    if (!rgba) {
+        std::fprintf(stderr, "decode failed: %s\n", stbi_failure_reason());
+        return 1;
+    }
+
+    int rw = 0, rh = 0, rc = 0;
+    unsigned char * ref = stbi_load(argv[2], &rw, &rh, &rc, 3);
+    if (!ref) {
+        std::fprintf(stderr, "decode failed: %s\n", stbi_failure_reason());
+        stbi_image_free(rgba);
+        return 1;
+    }
+
+    std::string err;
+    std::vector<uint8_t> got;
+    if (!trellis2_preprocess_rgba(rgba, w, h, rw, got, &err)) {
+        std::fprintf(stderr, "preprocess failed: %s\n", err.c_str());
+        return 1;
+    }
+
+    const size_t n = (size_t) rw * rh * 3;
+    size_t n_diff = 0, max_diff = 0, first = 0;
+    for (size_t i = 0; i < n; ++i) {
+        const int d = std::abs((int) got[i] - (int) ref[i]);
+        if (d) {
+            if (!n_diff) first = i;
+            ++n_diff;
+            if ((size_t) d > max_diff) max_diff = (size_t) d;
+        }
+    }
+
+    std::printf("preprocess %dx%d -> %dx%d: %zu/%zu bytes differ (max %zu)\n",
+                w, h, rw, rh, n_diff, n, max_diff);
+    stbi_image_free(rgba);
+    stbi_image_free(ref);
+
+    // Byte-exact is the goal; tolerate nothing so regressions are loud.
+    if (n_diff != 0) {
+        std::printf("first diff at byte %zu\nRESULT: FAIL\n", first);
+        return 1;
+    }
+    std::printf("RESULT: PASS\n");
+    return 0;
+}
diff --git a/tests/test_slat.cpp b/tests/test_slat.cpp
new file mode 100644
index 0000000..c760dd9
--- /dev/null
+++ b/tests/test_slat.cpp
@@ -0,0 +1,214 @@
+// Validation of the shape-SLAT stage against the PyTorch reference
+// (scripts/dump_slat_reference.py -> dumps/reference_slat.gguf):
+//
+//   1. SLAT flow forward at t=500 on the reference voxel set   (tight gate)
+//   2. full 12-step CFG sampler + denormalization              (loose gate)
+//   3. FDG decoder: per-level features, subdivision decisions,
+//      final 7-channel output + coords                          (tight gate,
+//      but only meaningful if the subdivision sets match exactly)
+//
+// usage: test_slat <slat_flow_f32.gguf> <shape_dec_f32.gguf> <reference_slat.gguf>
+// exits 77 (ctest SKIP) when inputs are missing.
+
+#include "trellis2.h"
+#include "parity.hpp"
+
+#include <cmath>
+#include <cstdio>
+#include <cstdlib>
+#include <fstream>
+#include <string>
+#include <vector>
+
+static bool file_exists(const std::string & p) {
+    std::ifstream f(p);
+    return f.good();
+}
+
+int main(int argc, char ** argv) {
+    if (argc < 4) {
+        std::fprintf(stderr,
+            "usage: %s <slat_flow_f32.gguf> <shape_dec_f32.gguf> <reference_slat.gguf>\n", argv[0]);
+        return 2;
+    }
+    const std::string flow_path = argv[1];
+    const std::string dec_path  = argv[2];
+    const std::string ref_path  = argv[3];
+
+    if (!file_exists(flow_path) || !file_exists(dec_path) || !file_exists(ref_path)) {
+        std::fprintf(stderr, "missing input file(s), skipping\n");
+        return 77;
+    }
+
+    t2_parity::baseline ref;
+    if (!ref.open(ref_path)) {
+        std::fprintf(stderr, "failed to open %s\n", ref_path.c_str());
+        return 1;
+    }
+
+    std::vector<float> coords_f, noise, cond;
+    if (!ref.load("coords", coords_f) || !ref.load("slat_noise", noise)) {
+        std::fprintf(stderr, "reference missing coords/slat_noise\n");
+        return 1;
+    }
+    const int L = (int) (coords_f.size() / 4);
+    std::vector<int32_t> coords((size_t) L * 3);
+    for (int v = 0; v < L; ++v) {
+        coords[(size_t) v * 3]     = (int32_t) coords_f[(size_t) v * 4 + 1];
+        coords[(size_t) v * 3 + 1] = (int32_t) coords_f[(size_t) v * 4 + 2];
+        coords[(size_t) v * 3 + 2] = (int32_t) coords_f[(size_t) v * 4 + 3];
+    }
+    std::printf("reference: %d voxels\n", L);
+
+    // conditioning comes from the shared fixture
+    {
+        trellis2_dino_cond c;
+        std::string err;
+        const char * dinodata = std::getenv("TRELLIS2_DINODATA");
+        std::string path = dinodata ? dinodata : "dumps/fixture.dinodata";
+        if (!trellis2_load_dinodata(path, c, &err)) {
+            std::fprintf(stderr, "cannot load %s (%s), skipping\n", path.c_str(), err.c_str());
+            return 77;
+        }
+        cond = std::move(c.data);
+    }
+    const int Lkv = (int) (cond.size() / 1024);
+
+    std::string err;
+    trellis2_slat_flow_model * flow = trellis2_slat_flow_load(flow_path, true, &err);
+    if (!flow) { std::fprintf(stderr, "flow load failed: %s\n", err.c_str()); return 1; }
+    std::printf("flow backend: %s\n", trellis2_slat_flow_backend_name(flow));
+
+    int n_fail = 0;
+
+    // ── 1. forward parity at t=500 ───────────────────────────────────────────
+    {
+        std::vector<float> got((size_t) L * 32), want;
+        if (!trellis2_slat_flow_forward(flow, noise.data(), L, coords.data(), 500.0f,
+                                        cond.data(), Lkv, 1024, got.data(), &err)) {
+            std::fprintf(stderr, "flow forward failed: %s\n", err.c_str());
+            return 1;
+        }
+        ref.load("flow_t500_out", want);
+        // rel-L2 gate (matches the SS-flow tests): per-element noise from
+        // CPU-vs-CUDA fp32 reduction order is expected, the trajectory is not.
+        t2_parity::compare_stats st;
+        t2_parity::compare(got, want, "flow_t500_out", 2e-3, 2e-3, &st);
+        if (st.rel_l2 > 3e-3) { std::printf("  -> forward rel_l2 %.4g > 3e-3, FAIL\n", st.rel_l2); ++n_fail; }
+    }
+
+    // ── 2. full sampler + denormalization ────────────────────────────────────
+    std::vector<float> slat((size_t) L * 32);
+    {
+        trellis2_ss_sampler_params P;
+        P.steps = 12;
+        P.guidance_strength = 7.5f;
+        P.guidance_rescale = 0.5f;
+        P.guidance_interval_min = 0.6f;
+        P.guidance_interval_max = 1.0f;
+        P.rescale_t = 3.0f;
+        P.verbose = true;
+        if (!trellis2_slat_flow_sample(flow, L, coords.data(),
+                                       cond.data(), Lkv, 1024,
+                                       &P, noise.data(), /*denormalize*/ true,
+                                       slat.data(), &err)) {
+            std::fprintf(stderr, "flow sample failed: %s\n", err.c_str());
+            return 1;
+        }
+        std::vector<float> want;
+        ref.load("slat", want);
+        // The 12-step Euler sampler with CFG-rescale chaotically amplifies the
+        // per-step fp difference between backends (the same effect the SS
+        // sampler shows: tight on CPU, ~0.1 rel-L2 on GPU). Gate loosely on the
+        // trajectory here; the SS-sampler test already validates the shared
+        // Euler loop tightly on CPU. TRELLIS2_SLAT_STRICT tightens it for a CPU
+        // run.
+        t2_parity::compare_stats st;
+        t2_parity::compare(slat, want, "slat(sampled)", 5e-2, 5e-2, &st);
+        const double samp_gate = std::getenv("TRELLIS2_SLAT_STRICT") ? 2e-2 : 2e-1;
+        if (st.rel_l2 > samp_gate) {
+            std::printf("  -> sampler rel_l2 %.4g > %.0e, FAIL\n", st.rel_l2, samp_gate);
+            ++n_fail;
+        }
+        // Decode the REFERENCE slat so decoder parity is independent of the
+        // sampler trajectory noise.
+        slat = want;
+    }
+    trellis2_slat_flow_free(flow);
+
+    // ── 3. decoder (CPU: ggml has no CUDA CONV_3D / sparse-conv kernel) ──────
+    trellis2_shape_dec_model * dec = trellis2_shape_dec_load(dec_path, true, &err, "cpu");
+    if (!dec) { std::fprintf(stderr, "dec load failed: %s\n", err.c_str()); return 1; }
+    std::printf("dec backend: %s\n", trellis2_shape_dec_backend_name(dec));
+
+    std::vector<float> out_feats;
+    std::vector<int32_t> out_coords;
+    std::vector<trellis2_subdiv_level> subs;
+    trellis2_shape_dec_taps taps;
+    if (!trellis2_shape_dec_decode_with_subs(dec, slat.data(), L, coords.data(),
+                                             out_feats, out_coords, subs, &taps, &err)) {
+        std::fprintf(stderr, "decode failed: %s\n", err.c_str());
+        trellis2_shape_dec_free(dec);
+        return 1;
+    }
+    trellis2_shape_dec_free(dec);
+
+    // Integrated texture generation replays these exact decoder decisions in
+    // the texture VAE. Guard their order/shape independently of activation taps.
+    if (subs.size() != 4) {
+        std::printf("  -> subdivision guide has %zu levels, expected 4, FAIL\n", subs.size());
+        ++n_fail;
+    } else {
+        for (size_t lvl = 0; lvl < subs.size(); ++lvl) {
+            if (subs[lvl].fine_coords.size() != subs[lvl].cidx.size() * 3) {
+                std::printf("  -> subdivision level %zu coord/index size mismatch, FAIL\n", lvl);
+                ++n_fail;
+            }
+        }
+        if (subs.back().fine_coords != out_coords) {
+            std::printf("  -> final subdivision guide does not reproduce decoder coords, FAIL\n");
+            ++n_fail;
+        }
+    }
+
+    // The decoder's per-level active set is chosen by subdivision-logit signs;
+    // if my logits match the reference's, every level's voxel set (hence tap
+    // size) matches exactly. A size mismatch therefore means a real sign flip,
+    // which is a hard fail. Numerically, deep sparse-conv accumulates fp noise,
+    // so gate features on rel-L2 rather than per-element.
+    std::vector<float> refbuf;
+    int n_cmp = 0;
+    for (size_t i = 0; i < taps.names.size(); ++i) {
+        const std::string & name = taps.names[i];
+        if (!ref.has(name)) continue;
+        ref.load(name, refbuf);
+        ++n_cmp;
+        t2_parity::compare_stats st;
+        t2_parity::compare(taps.data[i], refbuf, name, 2e-3, 2e-3, &st);
+        const double gate = 2e-2;   // rel-L2
+        // A few voxels whose subdivision logit sits within fp-noise of zero
+        // flip the >0 threshold, so the final active set can differ by a
+        // handful out of millions. Tolerate a <0.05% set-size difference; a
+        // larger divergence is a real bug.
+        const size_t a = taps.data[i].size(), b = refbuf.size();
+        const size_t big = a > b ? a : b, sml = a > b ? b : a;
+        if (a != b) {
+            const double frac = (double) (big - sml) / (double) big;
+            if (frac > 5e-4) {
+                std::printf("  -> %s SIZE MISMATCH %zu vs %zu (%.3f%%), FAIL\n",
+                            name.c_str(), a, b, 100.0 * frac);
+                ++n_fail;
+            } else {
+                std::printf("  -> %s near-match (%zu vs %zu, %.4f%% subdivision boundary flip) OK\n",
+                            name.c_str(), a, b, 100.0 * frac);
+            }
+        } else if (st.rel_l2 > gate) {
+            std::printf("  -> %s rel_l2 %.4g > %.0e, FAIL\n", name.c_str(), st.rel_l2, gate);
+            ++n_fail;
+        }
+    }
+
+    std::printf("\ndecoder taps compared: %d, total failures: %d\n", n_cmp, n_fail);
+    std::printf("RESULT: %s\n", n_fail ? "FAIL" : "PASS");
+    return n_fail ? 1 : 0;
+}
diff --git a/tests/test_ss_dec.cpp b/tests/test_ss_dec.cpp
index 61c7771..b66f708 100644
--- a/tests/test_ss_dec.cpp
+++ b/tests/test_ss_dec.cpp
@@ -28,6 +28,14 @@ int main(int argc, char ** argv) {
         return 2;
     }
     const std::string gguf_path = argv[1], ref_path = argv[2];
+
+    {
+        std::ifstream _a(gguf_path), _b(ref_path);
+        if (!_a.good() || !_b.good()) {
+            std::fprintf(stderr, "missing input file(s), skipping\n");
+            return 77;
+        }
+    }
     const double rel_tol = (argc > 3) ? std::atof(argv[3]) : 3e-2;
 
     std::ifstream f(ref_path, std::ios::binary);
diff --git a/tests/test_ss_flow_forward.cpp b/tests/test_ss_flow_forward.cpp
index 4fce8bd..5e5caac 100644
--- a/tests/test_ss_flow_forward.cpp
+++ b/tests/test_ss_flow_forward.cpp
@@ -28,6 +28,14 @@ int main(int argc, char ** argv) {
     }
     const std::string gguf_path = argv[1];
     const std::string ref_path  = argv[2];
+
+    {
+        std::ifstream _a(gguf_path), _b(ref_path);
+        if (!_a.good() || !_b.good()) {
+            std::fprintf(stderr, "missing input file(s), skipping\n");
+            return 77;
+        }
+    }
     const double rel_tol = (argc > 3) ? std::atof(argv[3]) : 2e-3;
 
     // ── read the reference bundle ────────────────────────────────────────────
diff --git a/tests/test_ss_sample.cpp b/tests/test_ss_sample.cpp
index c9002eb..00d6b20 100644
--- a/tests/test_ss_sample.cpp
+++ b/tests/test_ss_sample.cpp
@@ -28,6 +28,14 @@ int main(int argc, char ** argv) {
         return 2;
     }
     const std::string gguf_path = argv[1], ref_path = argv[2];
+
+    {
+        std::ifstream _a(gguf_path), _b(ref_path);
+        if (!_a.good() || !_b.good()) {
+            std::fprintf(stderr, "missing input file(s), skipping\n");
+            return 77;
+        }
+    }
     const double rel_tol = (argc > 3) ? std::atof(argv[3]) : 3e-2;
 
     std::ifstream f(ref_path, std::ios::binary);
diff --git a/tests/test_texture.cpp b/tests/test_texture.cpp
new file mode 100644
index 0000000..142e039
--- /dev/null
+++ b/tests/test_texture.cpp
@@ -0,0 +1,242 @@
+// Validation of the PBR-texture stages against the PyTorch reference
+// (scripts/dump_texture_reference.py -> dumps/reference_texture.gguf):
+//
+//   1. shape encoder: dual grid -> shape SLAT (32ch)          (coord-matched)
+//   2. tex flow forward at t=500 with concat_cond             (tight gate)
+//   3. tex flow full sampler + denorm                         (loose gate)
+//   4. tex decoder: tex SLAT -> 6ch PBR, replaying the         (coord-matched)
+//      encoder's subdivision
+//
+// usage: test_texture <shape_enc.gguf> <tex_flow_512.gguf> <tex_dec.gguf> <reference_texture.gguf>
+// exits 77 (ctest SKIP) when inputs are missing.
+
+#include "trellis2.h"
+#include "parity.hpp"
+
+#include <cmath>
+#include <cstdint>
+#include <cstdio>
+#include <cstdlib>
+#include <fstream>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+static bool file_exists(const std::string & p) { std::ifstream f(p); return f.good(); }
+
+static uint64_t vkey(int32_t x, int32_t y, int32_t z) {
+    return ((uint64_t) (uint32_t) x << 42) | ((uint64_t) (uint32_t) y << 21) | (uint64_t) (uint32_t) z;
+}
+
+// coords4 is the reference [N,4] (batch,x,y,z) dump; build key->row.
+static std::unordered_map<uint64_t,int> coord_map(const std::vector<float> & c4) {
+    std::unordered_map<uint64_t,int> m;
+    const int n = (int) (c4.size() / 4);
+    m.reserve((size_t) n * 2);
+    for (int v = 0; v < n; ++v)
+        m[vkey((int32_t) c4[(size_t) v*4+1], (int32_t) c4[(size_t) v*4+2], (int32_t) c4[(size_t) v*4+3])] = v;
+    return m;
+}
+
+// Reorder `got` (rows in `got_coords3` order) into the reference row order given
+// by `ref_coords4`, returning the aligned buffer; reports set mismatches.
+static bool align_to_ref(const std::vector<float> & got, const std::vector<int32_t> & got_coords3,
+                         const std::vector<float> & ref_coords4, int ch,
+                         std::vector<float> & out, const char * label) {
+    const int ng = (int) (got_coords3.size() / 3);
+    const int nr = (int) (ref_coords4.size() / 4);
+    if (ng != nr) {
+        std::printf("[%-16s] VOXEL COUNT got=%d ref=%d -> FAIL\n", label, ng, nr);
+        return false;
+    }
+    std::unordered_map<uint64_t,int> gm;
+    gm.reserve((size_t) ng * 2);
+    for (int v = 0; v < ng; ++v)
+        gm[vkey(got_coords3[(size_t) v*3], got_coords3[(size_t) v*3+1], got_coords3[(size_t) v*3+2])] = v;
+    out.resize((size_t) nr * ch);
+    int miss = 0;
+    for (int r = 0; r < nr; ++r) {
+        auto it = gm.find(vkey((int32_t) ref_coords4[(size_t) r*4+1],
+                               (int32_t) ref_coords4[(size_t) r*4+2],
+                               (int32_t) ref_coords4[(size_t) r*4+3]));
+        if (it == gm.end()) { ++miss; continue; }
+        std::memcpy(out.data() + (size_t) r * ch, got.data() + (size_t) it->second * ch, (size_t) ch * sizeof(float));
+    }
+    if (miss) { std::printf("[%-16s] %d/%d ref voxels absent in got -> FAIL\n", label, miss, nr); return false; }
+    return true;
+}
+
+int main(int argc, char ** argv) {
+    if (argc < 5) {
+        std::fprintf(stderr, "usage: %s <shape_enc.gguf> <tex_flow_512.gguf> <tex_dec.gguf> <reference_texture.gguf>\n", argv[0]);
+        return 2;
+    }
+    const std::string enc_path = argv[1], flow_path = argv[2], dec_path = argv[3], ref_path = argv[4];
+    if (!file_exists(enc_path) || !file_exists(flow_path) || !file_exists(dec_path) || !file_exists(ref_path)) {
+        std::fprintf(stderr, "missing input file(s), skipping\n");
+        return 77;
+    }
+
+    t2_parity::baseline ref;
+    if (!ref.open(ref_path)) { std::fprintf(stderr, "failed to open %s\n", ref_path.c_str()); return 1; }
+
+    std::vector<float> enc_vert, enc_inter, enc_coords4, cond;
+    std::vector<float> shape_slat_ref, shape_coords4, tex_noise, tex_slat_ref, pbr_ref, pbr_coords4;
+    if (!ref.load("enc_vert", enc_vert) || !ref.load("enc_inter", enc_inter) ||
+        !ref.load("enc_coords", enc_coords4) || !ref.load("cond", cond) ||
+        !ref.load("shape_slat", shape_slat_ref) || !ref.load("shape_coords", shape_coords4) ||
+        !ref.load("tex_noise", tex_noise) || !ref.load("tex_slat", tex_slat_ref) ||
+        !ref.load("pbr", pbr_ref) || !ref.load("pbr_coords", pbr_coords4)) {
+        std::fprintf(stderr, "reference missing a required tensor\n");
+        return 1;
+    }
+    const int N = (int) (enc_coords4.size() / 4);      // fine voxels (encoder input)
+    const int Nl = (int) (shape_coords4.size() / 4);   // latent voxels
+    const int Lkv = (int) (cond.size() / 1024);
+    std::printf("reference: %d dual-grid voxels, %d latent voxels, %d cond tokens\n", N, Nl, Lkv);
+
+    std::vector<int32_t> enc_coords((size_t) N * 3);
+    std::vector<float>   in6((size_t) N * 6);
+    for (int v = 0; v < N; ++v) {
+        enc_coords[(size_t) v*3]   = (int32_t) enc_coords4[(size_t) v*4+1];
+        enc_coords[(size_t) v*3+1] = (int32_t) enc_coords4[(size_t) v*4+2];
+        enc_coords[(size_t) v*3+2] = (int32_t) enc_coords4[(size_t) v*4+3];
+        for (int c = 0; c < 3; ++c) {
+            in6[(size_t) v*6 + c]     = enc_vert[(size_t) v*3 + c];
+            in6[(size_t) v*6 + 3 + c] = enc_inter[(size_t) v*3 + c];
+        }
+    }
+    std::vector<int32_t> lat_coords((size_t) Nl * 3);
+    for (int v = 0; v < Nl; ++v) {
+        lat_coords[(size_t) v*3]   = (int32_t) shape_coords4[(size_t) v*4+1];
+        lat_coords[(size_t) v*3+1] = (int32_t) shape_coords4[(size_t) v*4+2];
+        lat_coords[(size_t) v*3+2] = (int32_t) shape_coords4[(size_t) v*4+3];
+    }
+
+    std::string err;
+    int n_fail = 0;
+
+    // ── 1. shape encoder ─────────────────────────────────────────────────────
+    trellis2_shape_enc_model * enc = trellis2_shape_enc_load(enc_path, true, &err);
+    if (!enc) { std::fprintf(stderr, "enc load failed: %s\n", err.c_str()); return 1; }
+    std::printf("enc backend: %s\n", trellis2_shape_enc_backend_name(enc));
+
+    std::vector<float> shape_slat;
+    std::vector<int32_t> shape_coords;
+    std::vector<trellis2_subdiv_level> subs;
+    if (!trellis2_shape_enc_encode(enc, in6.data(), N, enc_coords.data(),
+                                   shape_slat, shape_coords, subs, nullptr, &err)) {
+        std::fprintf(stderr, "encode failed: %s\n", err.c_str());
+        trellis2_shape_enc_free(enc); return 1;
+    }
+    trellis2_shape_enc_free(enc);
+    std::printf("encoder out: %zu latent voxels\n", shape_coords.size() / 3);
+    {
+        std::vector<float> aligned;
+        if (!align_to_ref(shape_slat, shape_coords, shape_coords4, 32, aligned, "shape_slat")) {
+            ++n_fail;
+        } else {
+            t2_parity::compare_stats st;
+            t2_parity::compare(aligned, shape_slat_ref, "shape_slat", 5e-3, 5e-3, &st);
+            if (st.rel_l2 > 3e-2) { std::printf("  -> shape_slat rel_l2 %.4g > 3e-2, FAIL\n", st.rel_l2); ++n_fail; }
+        }
+    }
+
+    // ── 2 & 3. tex flow (concat_cond) ────────────────────────────────────────
+    trellis2_slat_flow_model * flow = trellis2_slat_flow_load(flow_path, true, &err);
+    if (!flow) { std::fprintf(stderr, "flow load failed: %s\n", err.c_str()); return 1; }
+    const trellis2_slat_flow_hparams & fhp = trellis2_slat_flow_hparams_of(flow);
+    std::printf("flow backend: %s (in=%d out=%d concat=%d)\n", trellis2_slat_flow_backend_name(flow),
+                fhp.in_channels, fhp.out_channels, fhp.concat_cond_channels);
+
+    // 2. forward @ t=500: build [noise(32) | normalized shape_slat(32)] manually.
+    {
+        std::vector<float> xin((size_t) Nl * fhp.in_channels), got((size_t) Nl * 32), want;
+        for (int v = 0; v < Nl; ++v) {
+            for (int c = 0; c < 32; ++c) xin[(size_t) v*64 + c] = tex_noise[(size_t) v*32 + c];
+            for (int c = 0; c < 32; ++c)
+                xin[(size_t) v*64 + 32 + c] =
+                    (shape_slat_ref[(size_t) v*32 + c] - fhp.concat_norm_mean[c]) / fhp.concat_norm_std[c];
+        }
+        if (!trellis2_slat_flow_forward(flow, xin.data(), Nl, lat_coords.data(), 500.0f,
+                                        cond.data(), Lkv, 1024, got.data(), &err)) {
+            std::fprintf(stderr, "flow forward failed: %s\n", err.c_str());
+            return 1;
+        }
+        ref.load("tex_flow_t500", want);
+        t2_parity::compare_stats st;
+        t2_parity::compare(got, want, "tex_flow_t500", 2e-3, 2e-3, &st);
+        if (st.rel_l2 > 5e-3) { std::printf("  -> forward rel_l2 %.4g > 5e-3, FAIL\n", st.rel_l2); ++n_fail; }
+    }
+
+    // 3. full tex sampler.
+    {
+        // Texture sampler params (texturing_pipeline.json tex_slat_sampler):
+        // guidance_strength 1.0 (no CFG amplification), rescale 0, interval [0.6,0.9].
+        trellis2_ss_sampler_params P;
+        P.steps = 12; P.guidance_strength = 1.0f; P.guidance_rescale = 0.0f;
+        P.guidance_interval_min = 0.6f; P.guidance_interval_max = 0.9f; P.rescale_t = 3.0f;
+        P.verbose = true;
+        std::vector<float> got((size_t) Nl * 32), want;
+        if (!trellis2_slat_flow_sample_tex(flow, Nl, lat_coords.data(), cond.data(), Lkv, 1024,
+                                           shape_slat_ref.data(), &P, tex_noise.data(),
+                                           /*denormalize*/ true, got.data(), &err)) {
+            std::fprintf(stderr, "tex sample failed: %s\n", err.c_str());
+            return 1;
+        }
+        ref.load("tex_slat", want);
+        t2_parity::compare_stats st;
+        t2_parity::compare(got, want, "tex_slat(sampled)", 5e-2, 5e-2, &st);
+        const double gate = std::getenv("TRELLIS2_SLAT_STRICT") ? 2e-2 : 2e-1;
+        if (st.rel_l2 > gate) { std::printf("  -> tex sampler rel_l2 %.4g > %.0e, FAIL\n", st.rel_l2, gate); ++n_fail; }
+    }
+    trellis2_slat_flow_free(flow);
+
+    // ── 4. tex decoder: decode the REFERENCE tex SLAT (isolate from sampler) ──
+    // Align the reference tex SLAT into the encoder's latent order, then decode
+    // with the encoder's subdivisions.
+    std::vector<float> tex_slat_aligned;
+    if (!align_to_ref(tex_slat_ref, lat_coords, shape_coords4, 32, tex_slat_aligned, "tex_slat_align")) {
+        // reference latent order should already match ours; if not, fail loudly
+        std::printf("  -> could not align tex SLAT to encoder latent order, FAIL\n");
+        return ++n_fail, (n_fail ? 1 : 0);
+    }
+    // aligned is in reference order; but the decoder wants it in the encoder's
+    // order (shape_coords). Reorder reference->encoder via the encoder coords.
+    std::vector<float> tex_slat_enc((size_t) Nl * 32);
+    {
+        std::unordered_map<uint64_t,int> rm = coord_map(shape_coords4);
+        for (int v = 0; v < Nl; ++v) {
+            auto it = rm.find(vkey(shape_coords[(size_t) v*3], shape_coords[(size_t) v*3+1], shape_coords[(size_t) v*3+2]));
+            const int rr = (it == rm.end()) ? v : it->second;
+            std::memcpy(tex_slat_enc.data() + (size_t) v*32, tex_slat_ref.data() + (size_t) rr*32, 32*sizeof(float));
+        }
+    }
+
+    trellis2_shape_dec_model * texdec = trellis2_tex_dec_load(dec_path, true, &err);
+    if (!texdec) { std::fprintf(stderr, "tex_dec load failed: %s\n", err.c_str()); return 1; }
+    std::printf("tex_dec backend: %s\n", trellis2_shape_dec_backend_name(texdec));
+
+    std::vector<float> pbr;
+    std::vector<int32_t> pbr_coords;
+    if (!trellis2_tex_dec_decode(texdec, tex_slat_enc.data(), Nl, shape_coords.data(),
+                                 subs, pbr, pbr_coords, &err)) {
+        std::fprintf(stderr, "tex decode failed: %s\n", err.c_str());
+        trellis2_shape_dec_free(texdec); return 1;
+    }
+    trellis2_shape_dec_free(texdec);
+    std::printf("tex decode out: %zu PBR voxels\n", pbr_coords.size() / 3);
+    {
+        std::vector<float> aligned;
+        if (!align_to_ref(pbr, pbr_coords, pbr_coords4, 6, aligned, "pbr")) {
+            ++n_fail;
+        } else {
+            t2_parity::compare_stats st;
+            t2_parity::compare(aligned, pbr_ref, "pbr", 5e-3, 5e-3, &st);
+            if (st.rel_l2 > 3e-2) { std::printf("  -> pbr rel_l2 %.4g > 3e-2, FAIL\n", st.rel_l2); ++n_fail; }
+        }
+    }
+
+    std::printf("\nRESULT: %s (failures: %d)\n", n_fail ? "FAIL" : "PASS", n_fail);
+    return n_fail ? 1 : 0;
+}
diff --git a/third_party/meshoptimizer/allocator.cpp b/third_party/meshoptimizer/allocator.cpp
new file mode 100644
index 0000000..058fbf3
--- /dev/null
+++ b/third_party/meshoptimizer/allocator.cpp
@@ -0,0 +1,21 @@
+// This file is part of meshoptimizer library; see meshoptimizer.h for version/license details
+#include "meshoptimizer.h"
+
+#include <assert.h>
+
+#ifdef MESHOPTIMIZER_ALLOC_EXPORT
+meshopt_Allocator::Storage& meshopt_Allocator::storage()
+{
+	static Storage s = {::operator new, ::operator delete };
+	return s;
+}
+#endif
+
+void meshopt_setAllocator(void* (MESHOPTIMIZER_ALLOC_CALLCONV* allocate)(size_t), void (MESHOPTIMIZER_ALLOC_CALLCONV* deallocate)(void*))
+{
+	assert(allocate && deallocate);
+
+	meshopt_Allocator::Storage& s = meshopt_Allocator::storage();
+	s.allocate = allocate;
+	s.deallocate = deallocate;
+}
diff --git a/third_party/meshoptimizer/indexgenerator.cpp b/third_party/meshoptimizer/indexgenerator.cpp
new file mode 100644
index 0000000..1b707bb
--- /dev/null
+++ b/third_party/meshoptimizer/indexgenerator.cpp
@@ -0,0 +1,817 @@
+// This file is part of meshoptimizer library; see meshoptimizer.h for version/license details
+#include "meshoptimizer.h"
+
+#include <assert.h>
+#include <string.h>
+
+// This work is based on:
+// Matthias Teschner, Bruno Heidelberger, Matthias Mueller, Danat Pomeranets, Markus Gross. Optimized Spatial Hashing for Collision Detection of Deformable Objects. 2003
+// John McDonald, Mark Kilgard. Crack-Free Point-Normal Triangles using Adjacent Edge Normals. 2010
+// John Hable. Variable Rate Shading with Visibility Buffer Rendering. 2024
+namespace meshopt
+{
+
+static unsigned int hashUpdate4(unsigned int h, const unsigned char* key, size_t len)
+{
+	// MurmurHash2
+	const unsigned int m = 0x5bd1e995;
+	const int r = 24;
+
+	while (len >= 4)
+	{
+		unsigned int k = *reinterpret_cast<const unsigned int*>(key);
+
+		k *= m;
+		k ^= k >> r;
+		k *= m;
+
+		h *= m;
+		h ^= k;
+
+		key += 4;
+		len -= 4;
+	}
+
+	return h;
+}
+
+struct VertexHasher
+{
+	const unsigned char* vertices;
+	size_t vertex_size;
+	size_t vertex_stride;
+
+	size_t hash(unsigned int index) const
+	{
+		return hashUpdate4(0, vertices + index * vertex_stride, vertex_size);
+	}
+
+	bool equal(unsigned int lhs, unsigned int rhs) const
+	{
+		return memcmp(vertices + lhs * vertex_stride, vertices + rhs * vertex_stride, vertex_size) == 0;
+	}
+};
+
+struct VertexStreamHasher
+{
+	const meshopt_Stream* streams;
+	size_t stream_count;
+
+	size_t hash(unsigned int index) const
+	{
+		unsigned int h = 0;
+
+		for (size_t i = 0; i < stream_count; ++i)
+		{
+			const meshopt_Stream& s = streams[i];
+			const unsigned char* data = static_cast<const unsigned char*>(s.data);
+
+			h = hashUpdate4(h, data + index * s.stride, s.size);
+		}
+
+		return h;
+	}
+
+	bool equal(unsigned int lhs, unsigned int rhs) const
+	{
+		for (size_t i = 0; i < stream_count; ++i)
+		{
+			const meshopt_Stream& s = streams[i];
+			const unsigned char* data = static_cast<const unsigned char*>(s.data);
+
+			if (memcmp(data + lhs * s.stride, data + rhs * s.stride, s.size) != 0)
+				return false;
+		}
+
+		return true;
+	}
+};
+
+struct VertexCustomHasher
+{
+	const float* vertex_positions;
+	size_t vertex_stride_float;
+
+	int (*callback)(void*, unsigned int, unsigned int);
+	void* context;
+
+	size_t hash(unsigned int index) const
+	{
+		const unsigned int* key = reinterpret_cast<const unsigned int*>(vertex_positions + index * vertex_stride_float);
+
+		unsigned int x = key[0], y = key[1], z = key[2];
+
+		// replace negative zero with zero
+		x = (x == 0x80000000) ? 0 : x;
+		y = (y == 0x80000000) ? 0 : y;
+		z = (z == 0x80000000) ? 0 : z;
+
+		// scramble bits to make sure that integer coordinates have entropy in lower bits
+		x ^= x >> 17;
+		y ^= y >> 17;
+		z ^= z >> 17;
+
+		// Optimized Spatial Hashing for Collision Detection of Deformable Objects
+		return (x * 73856093) ^ (y * 19349663) ^ (z * 83492791);
+	}
+
+	bool equal(unsigned int lhs, unsigned int rhs) const
+	{
+		const float* lp = vertex_positions + lhs * vertex_stride_float;
+		const float* rp = vertex_positions + rhs * vertex_stride_float;
+
+		if (lp[0] != rp[0] || lp[1] != rp[1] || lp[2] != rp[2])
+			return false;
+
+		return callback ? callback(context, lhs, rhs) : true;
+	}
+};
+
+struct TriangleKey
+{
+	unsigned int a, b, c;
+
+	bool operator==(const TriangleKey& other) const
+	{
+		return a == other.a && b == other.b && c == other.c;
+	}
+};
+
+struct TriangleKeyHasher
+{
+	size_t hash(const TriangleKey& k) const
+	{
+		// Optimized Spatial Hashing for Collision Detection of Deformable Objects
+		return (k.a * 73856093) ^ (k.b * 19349663) ^ (k.c * 83492791);
+	}
+
+	bool equal(const TriangleKey& lhs, const TriangleKey& rhs) const
+	{
+		return lhs == rhs;
+	}
+};
+
+struct EdgeHasher
+{
+	const unsigned int* remap;
+
+	size_t hash(unsigned long long edge) const
+	{
+		unsigned int e0 = unsigned(edge >> 32);
+		unsigned int e1 = unsigned(edge);
+
+		unsigned int h1 = remap[e0];
+		unsigned int h2 = remap[e1];
+
+		const unsigned int m = 0x5bd1e995;
+
+		// MurmurHash64B finalizer
+		h1 ^= h2 >> 18;
+		h1 *= m;
+		h2 ^= h1 >> 22;
+		h2 *= m;
+		h1 ^= h2 >> 17;
+		h1 *= m;
+		h2 ^= h1 >> 19;
+		h2 *= m;
+
+		return h2;
+	}
+
+	bool equal(unsigned long long lhs, unsigned long long rhs) const
+	{
+		unsigned int l0 = unsigned(lhs >> 32);
+		unsigned int l1 = unsigned(lhs);
+
+		unsigned int r0 = unsigned(rhs >> 32);
+		unsigned int r1 = unsigned(rhs);
+
+		return remap[l0] == remap[r0] && remap[l1] == remap[r1];
+	}
+};
+
+static size_t hashBuckets(size_t count)
+{
+	size_t buckets = 1;
+	while (buckets < count + count / 4)
+		buckets *= 2;
+
+	return buckets;
+}
+
+template <typename T, typename Hash>
+static T* hashLookup(T* table, size_t buckets, const Hash& hash, const T& key, const T& empty)
+{
+	assert(buckets > 0);
+	assert((buckets & (buckets - 1)) == 0);
+
+	size_t hashmod = buckets - 1;
+	size_t bucket = hash.hash(key) & hashmod;
+
+	for (size_t probe = 0; probe <= hashmod; ++probe)
+	{
+		T& item = table[bucket];
+
+		if (item == empty)
+			return &item;
+
+		if (hash.equal(item, key))
+			return &item;
+
+		// hash collision, quadratic probing
+		bucket = (bucket + probe + 1) & hashmod;
+	}
+
+	assert(false && "Hash table is full"); // unreachable
+	return NULL;
+}
+
+static void buildPositionRemap(unsigned int* remap, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, meshopt_Allocator& allocator)
+{
+	VertexHasher vertex_hasher = {reinterpret_cast<const unsigned char*>(vertex_positions), 3 * sizeof(float), vertex_positions_stride};
+
+	size_t vertex_table_size = hashBuckets(vertex_count);
+	unsigned int* vertex_table = allocator.allocate<unsigned int>(vertex_table_size);
+	memset(vertex_table, -1, vertex_table_size * sizeof(unsigned int));
+
+	for (size_t i = 0; i < vertex_count; ++i)
+	{
+		unsigned int index = unsigned(i);
+		unsigned int* entry = hashLookup(vertex_table, vertex_table_size, vertex_hasher, index, ~0u);
+
+		if (*entry == ~0u)
+			*entry = index;
+
+		remap[index] = *entry;
+	}
+
+	allocator.deallocate(vertex_table);
+}
+
+template <typename Hash>
+static size_t generateVertexRemap(unsigned int* remap, const unsigned int* indices, size_t index_count, size_t vertex_count, const Hash& hash, meshopt_Allocator& allocator)
+{
+	memset(remap, -1, vertex_count * sizeof(unsigned int));
+
+	size_t table_size = hashBuckets(vertex_count);
+	unsigned int* table = allocator.allocate<unsigned int>(table_size);
+	memset(table, -1, table_size * sizeof(unsigned int));
+
+	unsigned int next_vertex = 0;
+
+	for (size_t i = 0; i < index_count; ++i)
+	{
+		unsigned int index = indices ? indices[i] : unsigned(i);
+		assert(index < vertex_count);
+
+		if (remap[index] != ~0u)
+			continue;
+
+		unsigned int* entry = hashLookup(table, table_size, hash, index, ~0u);
+
+		if (*entry == ~0u)
+		{
+			*entry = index;
+			remap[index] = next_vertex++;
+		}
+		else
+		{
+			assert(remap[*entry] != ~0u);
+			remap[index] = remap[*entry];
+		}
+	}
+
+	assert(next_vertex <= vertex_count);
+	return next_vertex;
+}
+
+template <size_t BlockSize>
+static void remapVertices(void* destination, const void* vertices, size_t vertex_count, size_t vertex_size, const unsigned int* remap)
+{
+	size_t block_size = BlockSize == 0 ? vertex_size : BlockSize;
+	assert(block_size == vertex_size);
+
+	for (size_t i = 0; i < vertex_count; ++i)
+		if (remap[i] != ~0u)
+		{
+			assert(remap[i] < vertex_count);
+			memcpy(static_cast<unsigned char*>(destination) + remap[i] * block_size, static_cast<const unsigned char*>(vertices) + i * block_size, block_size);
+		}
+}
+
+template <typename Hash>
+static void generateShadowBuffer(unsigned int* destination, const unsigned int* indices, size_t index_count, size_t vertex_count, const Hash& hash, meshopt_Allocator& allocator)
+{
+	unsigned int* remap = allocator.allocate<unsigned int>(vertex_count);
+	memset(remap, -1, vertex_count * sizeof(unsigned int));
+
+	size_t table_size = hashBuckets(vertex_count);
+	unsigned int* table = allocator.allocate<unsigned int>(table_size);
+	memset(table, -1, table_size * sizeof(unsigned int));
+
+	for (size_t i = 0; i < index_count; ++i)
+	{
+		unsigned int index = indices[i];
+		assert(index < vertex_count);
+
+		if (remap[index] == ~0u)
+		{
+			unsigned int* entry = hashLookup(table, table_size, hash, index, ~0u);
+
+			if (*entry == ~0u)
+				*entry = index;
+
+			remap[index] = *entry;
+		}
+
+		destination[i] = remap[index];
+	}
+}
+
+static size_t filterIndexBuffer(unsigned int* destination, const unsigned int* indices, size_t index_count, const unsigned int* remap, size_t vertex_count, meshopt_Allocator& allocator)
+{
+	(void)vertex_count;
+
+	TriangleKeyHasher hasher = {};
+	TriangleKey empty = {~0u, ~0u, ~0u};
+
+	size_t face_count = index_count / 3;
+	size_t table_size = hashBuckets(face_count);
+	TriangleKey* table = allocator.allocate<TriangleKey>(table_size);
+	memset(table, -1, table_size * sizeof(TriangleKey));
+
+	size_t write = 0;
+
+	for (size_t i = 0; i < face_count; ++i)
+	{
+		unsigned int a = indices[i * 3 + 0], b = indices[i * 3 + 1], c = indices[i * 3 + 2];
+		assert(a < vertex_count && b < vertex_count && c < vertex_count);
+
+		unsigned int ra = remap[a], rb = remap[b], rc = remap[c];
+
+		// degenerate triangle
+		if (ra == rb || ra == rc || rb == rc)
+			continue;
+
+		// canonicalize triangle wrt winding preserving rotation
+		if (rb < ra && rb < rc)
+		{
+			// abc -> bca
+			unsigned int t = ra;
+			ra = rb, rb = rc, rc = t;
+		}
+		else if (rc < ra && rc < rb)
+		{
+			// abc -> cab
+			unsigned int t = rc;
+			rc = rb, rb = ra, ra = t;
+		}
+
+		TriangleKey key = {ra, rb, rc};
+		TriangleKey* entry = hashLookup(table, table_size, hasher, key, empty);
+
+		// duplicate triangle
+		if (entry->a != ~0u)
+			continue;
+
+		*entry = key;
+
+		destination[write + 0] = a;
+		destination[write + 1] = b;
+		destination[write + 2] = c;
+		write += 3;
+	}
+
+	return write;
+}
+
+} // namespace meshopt
+
+size_t meshopt_generateVertexRemap(unsigned int* destination, const unsigned int* indices, size_t index_count, const void* vertices, size_t vertex_count, size_t vertex_size)
+{
+	using namespace meshopt;
+
+	assert(indices || index_count == vertex_count);
+	assert(vertex_size > 0 && vertex_size <= 256);
+
+	meshopt_Allocator allocator;
+	VertexHasher hasher = {static_cast<const unsigned char*>(vertices), vertex_size, vertex_size};
+
+	return generateVertexRemap(destination, indices, index_count, vertex_count, hasher, allocator);
+}
+
+size_t meshopt_generateVertexRemapMulti(unsigned int* destination, const unsigned int* indices, size_t index_count, size_t vertex_count, const struct meshopt_Stream* streams, size_t stream_count)
+{
+	using namespace meshopt;
+
+	assert(indices || index_count == vertex_count);
+	assert(stream_count > 0 && stream_count <= 16);
+
+	for (size_t i = 0; i < stream_count; ++i)
+	{
+		assert(streams[i].size > 0 && streams[i].size <= 256);
+		assert(streams[i].size <= streams[i].stride);
+	}
+
+	meshopt_Allocator allocator;
+	VertexStreamHasher hasher = {streams, stream_count};
+
+	return generateVertexRemap(destination, indices, index_count, vertex_count, hasher, allocator);
+}
+
+size_t meshopt_generateVertexRemapCustom(unsigned int* destination, const unsigned int* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, int (*callback)(void*, unsigned int, unsigned int), void* context)
+{
+	using namespace meshopt;
+
+	assert(indices || index_count == vertex_count);
+	assert(vertex_positions_stride >= 12 && vertex_positions_stride <= 256);
+	assert(vertex_positions_stride % sizeof(float) == 0);
+
+	meshopt_Allocator allocator;
+	VertexCustomHasher hasher = {vertex_positions, vertex_positions_stride / sizeof(float), callback, context};
+
+	return generateVertexRemap(destination, indices, index_count, vertex_count, hasher, allocator);
+}
+
+void meshopt_remapVertexBuffer(void* destination, const void* vertices, size_t vertex_count, size_t vertex_size, const unsigned int* remap)
+{
+	using namespace meshopt;
+
+	assert(vertex_size > 0 && vertex_size <= 256);
+
+	meshopt_Allocator allocator;
+
+	// support in-place remap
+	if (destination == vertices)
+	{
+		unsigned char* vertices_copy = allocator.allocate<unsigned char>(vertex_count * vertex_size);
+		memcpy(vertices_copy, vertices, vertex_count * vertex_size);
+		vertices = vertices_copy;
+	}
+
+	// specialize the loop for common vertex sizes to ensure memcpy is compiled as an inlined intrinsic
+	switch (vertex_size)
+	{
+	case 4:
+		return remapVertices<4>(destination, vertices, vertex_count, vertex_size, remap);
+
+	case 8:
+		return remapVertices<8>(destination, vertices, vertex_count, vertex_size, remap);
+
+	case 12:
+		return remapVertices<12>(destination, vertices, vertex_count, vertex_size, remap);
+
+	case 16:
+		return remapVertices<16>(destination, vertices, vertex_count, vertex_size, remap);
+
+	default:
+		return remapVertices<0>(destination, vertices, vertex_count, vertex_size, remap);
+	}
+}
+
+void meshopt_remapIndexBuffer(unsigned int* destination, const unsigned int* indices, size_t index_count, const unsigned int* remap)
+{
+	for (size_t i = 0; i < index_count; ++i)
+	{
+		unsigned int index = indices ? indices[i] : unsigned(i);
+		assert(remap[index] != ~0u);
+
+		destination[i] = remap[index];
+	}
+}
+
+size_t meshopt_filterIndexBuffer(unsigned int* destination, const unsigned int* indices, size_t index_count, const void* vertices, size_t vertex_count, size_t vertex_size, size_t vertex_stride)
+{
+	using namespace meshopt;
+
+	assert(index_count % 3 == 0);
+	assert(vertex_size > 0 && vertex_size <= 256);
+	assert(vertex_size <= vertex_stride);
+
+	meshopt_Allocator allocator;
+	VertexHasher hasher = {static_cast<const unsigned char*>(vertices), vertex_size, vertex_stride};
+
+	unsigned int* remap = allocator.allocate<unsigned int>(vertex_count);
+	generateVertexRemap(remap, indices, index_count, vertex_count, hasher, allocator);
+
+	return filterIndexBuffer(destination, indices, index_count, remap, vertex_count, allocator);
+}
+
+size_t meshopt_filterIndexBufferMulti(unsigned int* destination, const unsigned int* indices, size_t index_count, size_t vertex_count, const struct meshopt_Stream* streams, size_t stream_count)
+{
+	using namespace meshopt;
+
+	assert(index_count % 3 == 0);
+	assert(stream_count > 0 && stream_count <= 16);
+
+	for (size_t i = 0; i < stream_count; ++i)
+	{
+		assert(streams[i].size > 0 && streams[i].size <= 256);
+		assert(streams[i].size <= streams[i].stride);
+	}
+
+	meshopt_Allocator allocator;
+	VertexStreamHasher hasher = {streams, stream_count};
+
+	unsigned int* remap = allocator.allocate<unsigned int>(vertex_count);
+	generateVertexRemap(remap, indices, index_count, vertex_count, hasher, allocator);
+
+	return filterIndexBuffer(destination, indices, index_count, remap, vertex_count, allocator);
+}
+
+void meshopt_generateShadowIndexBuffer(unsigned int* destination, const unsigned int* indices, size_t index_count, const void* vertices, size_t vertex_count, size_t vertex_size, size_t vertex_stride)
+{
+	using namespace meshopt;
+
+	assert(index_count % 3 == 0);
+	assert(vertex_size > 0 && vertex_size <= 256);
+	assert(vertex_size <= vertex_stride);
+
+	meshopt_Allocator allocator;
+	VertexHasher hasher = {static_cast<const unsigned char*>(vertices), vertex_size, vertex_stride};
+
+	generateShadowBuffer(destination, indices, index_count, vertex_count, hasher, allocator);
+}
+
+void meshopt_generateShadowIndexBufferMulti(unsigned int* destination, const unsigned int* indices, size_t index_count, size_t vertex_count, const struct meshopt_Stream* streams, size_t stream_count)
+{
+	using namespace meshopt;
+
+	assert(index_count % 3 == 0);
+	assert(stream_count > 0 && stream_count <= 16);
+
+	for (size_t i = 0; i < stream_count; ++i)
+	{
+		assert(streams[i].size > 0 && streams[i].size <= 256);
+		assert(streams[i].size <= streams[i].stride);
+	}
+
+	meshopt_Allocator allocator;
+	VertexStreamHasher hasher = {streams, stream_count};
+
+	generateShadowBuffer(destination, indices, index_count, vertex_count, hasher, allocator);
+}
+
+void meshopt_generatePositionRemap(unsigned int* destination, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride)
+{
+	using namespace meshopt;
+
+	assert(vertex_positions_stride >= 12 && vertex_positions_stride <= 256);
+	assert(vertex_positions_stride % sizeof(float) == 0);
+
+	meshopt_Allocator allocator;
+	VertexCustomHasher hasher = {vertex_positions, vertex_positions_stride / sizeof(float), NULL, NULL};
+
+	size_t table_size = hashBuckets(vertex_count);
+	unsigned int* table = allocator.allocate<unsigned int>(table_size);
+	memset(table, -1, table_size * sizeof(unsigned int));
+
+	for (size_t i = 0; i < vertex_count; ++i)
+	{
+		unsigned int* entry = hashLookup(table, table_size, hasher, unsigned(i), ~0u);
+
+		if (*entry == ~0u)
+			*entry = unsigned(i);
+
+		destination[i] = *entry;
+	}
+}
+
+void meshopt_generateAdjacencyIndexBuffer(unsigned int* destination, const unsigned int* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride)
+{
+	using namespace meshopt;
+
+	assert(index_count % 3 == 0);
+	assert(vertex_positions_stride >= 12 && vertex_positions_stride <= 256);
+	assert(vertex_positions_stride % sizeof(float) == 0);
+
+	meshopt_Allocator allocator;
+
+	static const int next[4] = {1, 2, 0, 1};
+
+	// build position remap: for each vertex, which other (canonical) vertex does it map to?
+	unsigned int* remap = allocator.allocate<unsigned int>(vertex_count);
+	buildPositionRemap(remap, vertex_positions, vertex_count, vertex_positions_stride, allocator);
+
+	// build edge set; this stores all triangle edges but we can look these up by any other wedge
+	EdgeHasher edge_hasher = {remap};
+
+	size_t edge_table_size = hashBuckets(index_count);
+	unsigned long long* edge_table = allocator.allocate<unsigned long long>(edge_table_size);
+	unsigned int* edge_vertex_table = allocator.allocate<unsigned int>(edge_table_size);
+
+	memset(edge_table, -1, edge_table_size * sizeof(unsigned long long));
+	memset(edge_vertex_table, -1, edge_table_size * sizeof(unsigned int));
+
+	for (size_t i = 0; i < index_count; i += 3)
+	{
+		for (int e = 0; e < 3; ++e)
+		{
+			unsigned int i0 = indices[i + e];
+			unsigned int i1 = indices[i + next[e]];
+			unsigned int i2 = indices[i + next[e + 1]];
+			assert(i0 < vertex_count && i1 < vertex_count && i2 < vertex_count);
+
+			unsigned long long edge = ((unsigned long long)i0 << 32) | i1;
+			unsigned long long* entry = hashLookup(edge_table, edge_table_size, edge_hasher, edge, ~0ull);
+
+			if (*entry == ~0ull)
+			{
+				*entry = edge;
+
+				// store vertex opposite to the edge
+				edge_vertex_table[entry - edge_table] = i2;
+			}
+		}
+	}
+
+	// build resulting index buffer: 6 indices for each input triangle
+	for (size_t i = 0; i < index_count; i += 3)
+	{
+		unsigned int patch[6];
+
+		for (int e = 0; e < 3; ++e)
+		{
+			unsigned int i0 = indices[i + e];
+			unsigned int i1 = indices[i + next[e]];
+			assert(i0 < vertex_count && i1 < vertex_count);
+
+			// note: this refers to the opposite edge!
+			unsigned long long edge = ((unsigned long long)i1 << 32) | i0;
+			unsigned long long* oppe = hashLookup(edge_table, edge_table_size, edge_hasher, edge, ~0ull);
+
+			patch[e * 2 + 0] = i0;
+			patch[e * 2 + 1] = (*oppe == ~0ull) ? i0 : edge_vertex_table[oppe - edge_table];
+		}
+
+		memcpy(destination + i * 2, patch, sizeof(patch));
+	}
+}
+
+void meshopt_generateTessellationIndexBuffer(unsigned int* destination, const unsigned int* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride)
+{
+	using namespace meshopt;
+
+	assert(index_count % 3 == 0);
+	assert(vertex_positions_stride >= 12 && vertex_positions_stride <= 256);
+	assert(vertex_positions_stride % sizeof(float) == 0);
+
+	meshopt_Allocator allocator;
+
+	static const int next[3] = {1, 2, 0};
+
+	// build position remap: for each vertex, which other (canonical) vertex does it map to?
+	unsigned int* remap = allocator.allocate<unsigned int>(vertex_count);
+	buildPositionRemap(remap, vertex_positions, vertex_count, vertex_positions_stride, allocator);
+
+	// build edge set; this stores all triangle edges but we can look these up by any other wedge
+	EdgeHasher edge_hasher = {remap};
+
+	size_t edge_table_size = hashBuckets(index_count);
+	unsigned long long* edge_table = allocator.allocate<unsigned long long>(edge_table_size);
+	memset(edge_table, -1, edge_table_size * sizeof(unsigned long long));
+
+	for (size_t i = 0; i < index_count; i += 3)
+	{
+		for (int e = 0; e < 3; ++e)
+		{
+			unsigned int i0 = indices[i + e];
+			unsigned int i1 = indices[i + next[e]];
+			assert(i0 < vertex_count && i1 < vertex_count);
+
+			unsigned long long edge = ((unsigned long long)i0 << 32) | i1;
+			unsigned long long* entry = hashLookup(edge_table, edge_table_size, edge_hasher, edge, ~0ull);
+
+			if (*entry == ~0ull)
+				*entry = edge;
+		}
+	}
+
+	// build resulting index buffer: 12 indices for each input triangle
+	for (size_t i = 0; i < index_count; i += 3)
+	{
+		unsigned int patch[12];
+
+		for (int e = 0; e < 3; ++e)
+		{
+			unsigned int i0 = indices[i + e];
+			unsigned int i1 = indices[i + next[e]];
+			assert(i0 < vertex_count && i1 < vertex_count);
+
+			// note: this refers to the opposite edge!
+			unsigned long long edge = ((unsigned long long)i1 << 32) | i0;
+			unsigned long long oppe = *hashLookup(edge_table, edge_table_size, edge_hasher, edge, ~0ull);
+
+			// use the same edge if opposite edge doesn't exist (border)
+			oppe = (oppe == ~0ull) ? edge : oppe;
+
+			// triangle index (0, 1, 2)
+			patch[e] = i0;
+
+			// opposite edge (3, 4; 5, 6; 7, 8)
+			patch[3 + e * 2 + 0] = unsigned(oppe);
+			patch[3 + e * 2 + 1] = unsigned(oppe >> 32);
+
+			// dominant vertex (9, 10, 11)
+			patch[9 + e] = remap[i0];
+		}
+
+		memcpy(destination + i * 4, patch, sizeof(patch));
+	}
+}
+
+size_t meshopt_generateProvokingIndexBuffer(unsigned int* destination, unsigned int* reorder, const unsigned int* indices, size_t index_count, size_t vertex_count)
+{
+	assert(index_count % 3 == 0);
+
+	meshopt_Allocator allocator;
+
+	unsigned int* remap = allocator.allocate<unsigned int>(vertex_count);
+	memset(remap, -1, vertex_count * sizeof(unsigned int));
+
+	// compute vertex valence; this is used to prioritize least used corner
+	// note: we use 8-bit counters for performance; for outlier vertices the valence is incorrect but that just affects the heuristic
+	unsigned char* valence = allocator.allocate<unsigned char>(vertex_count);
+	memset(valence, 0, vertex_count);
+
+	for (size_t i = 0; i < index_count; ++i)
+	{
+		unsigned int index = indices[i];
+		assert(index < vertex_count);
+
+		valence[index]++;
+	}
+
+	unsigned int reorder_offset = 0;
+
+	// assign provoking vertices; leave the rest for the next pass
+	for (size_t i = 0; i < index_count; i += 3)
+	{
+		unsigned int a = indices[i + 0], b = indices[i + 1], c = indices[i + 2];
+		assert(a < vertex_count && b < vertex_count && c < vertex_count);
+
+		// try to rotate triangle such that provoking vertex hasn't been seen before
+		// if multiple vertices are new, prioritize the one with least valence
+		// this reduces the risk that a future triangle will have all three vertices seen
+		unsigned int va = remap[a] == ~0u ? valence[a] : ~0u;
+		unsigned int vb = remap[b] == ~0u ? valence[b] : ~0u;
+		unsigned int vc = remap[c] == ~0u ? valence[c] : ~0u;
+
+		if (vb != ~0u && vb <= va && vb <= vc)
+		{
+			// abc -> bca
+			unsigned int t = a;
+			a = b, b = c, c = t;
+		}
+		else if (vc != ~0u && vc <= va && vc <= vb)
+		{
+			// abc -> cab
+			unsigned int t = c;
+			c = b, b = a, a = t;
+		}
+
+		unsigned int newidx = reorder_offset;
+
+		// now remap[a] = ~0u or all three vertices are old
+		// recording remap[a] makes it possible to remap future references to the same index, conserving space
+		if (remap[a] == ~0u)
+			remap[a] = newidx;
+
+		// we need to clone the provoking vertex to get a unique index
+		// if all three are used the choice is arbitrary since no future triangle will be able to reuse any of these
+		reorder[reorder_offset++] = a;
+
+		// note: first vertex is final, the other two will be fixed up in next pass
+		destination[i + 0] = newidx;
+		destination[i + 1] = b;
+		destination[i + 2] = c;
+
+		// update vertex valences for corner heuristic
+		valence[a]--;
+		valence[b]--;
+		valence[c]--;
+	}
+
+	// remap or clone non-provoking vertices (iterating to skip provoking vertices)
+	int step = 1;
+
+	for (size_t i = 1; i < index_count; i += step, step ^= 3)
+	{
+		unsigned int index = destination[i];
+
+		if (remap[index] == ~0u)
+		{
+			// we haven't seen the vertex before as a provoking vertex
+			// to maintain the reference to the original vertex we need to clone it
+			unsigned int newidx = reorder_offset;
+
+			remap[index] = newidx;
+			reorder[reorder_offset++] = index;
+		}
+
+		destination[i] = remap[index];
+	}
+
+	assert(reorder_offset <= vertex_count + index_count / 3);
+	return reorder_offset;
+}
diff --git a/third_party/meshoptimizer/meshoptimizer.h b/third_party/meshoptimizer/meshoptimizer.h
new file mode 100644
index 0000000..e6aa58e
--- /dev/null
+++ b/third_party/meshoptimizer/meshoptimizer.h
@@ -0,0 +1,1660 @@
+/**
+ * meshoptimizer - version 1.2
+ *
+ * Copyright (C) 2016-2026, by Arseny Kapoulkine (arseny.kapoulkine@gmail.com)
+ * Report bugs and download new versions at https://github.com/zeux/meshoptimizer
+ *
+ * This library is distributed under the MIT License. See notice at the end of this file.
+ */
+#pragma once
+
+#include <assert.h>
+#include <stddef.h>
+
+/* Version macro; major * 1000 + minor * 10 + patch */
+#define MESHOPTIMIZER_VERSION 1020 /* 1.2 */
+
+/* If no API is defined, assume default */
+#ifndef MESHOPTIMIZER_API
+#define MESHOPTIMIZER_API
+#endif
+
+/* Set the calling-convention for alloc/dealloc function pointers */
+#ifndef MESHOPTIMIZER_ALLOC_CALLCONV
+#ifdef _MSC_VER
+#define MESHOPTIMIZER_ALLOC_CALLCONV __cdecl
+#else
+#define MESHOPTIMIZER_ALLOC_CALLCONV
+#endif
+#endif
+
+/* Experimental APIs have unstable interface and might have implementation that's not fully tested or optimized */
+#ifndef MESHOPTIMIZER_EXPERIMENTAL
+#define MESHOPTIMIZER_EXPERIMENTAL MESHOPTIMIZER_API
+#endif
+
+/* C interface */
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+/**
+ * Vertex attribute stream
+ * Each element takes size bytes, beginning at data, with stride controlling the spacing between successive elements (stride >= size).
+ */
+struct meshopt_Stream
+{
+	const void* data;
+	size_t size;
+	size_t stride;
+};
+
+/**
+ * Generates a vertex remap table from the vertex buffer and an optional index buffer and returns number of unique vertices
+ * As a result, all vertices that are binary equivalent map to the same (new) location, with no gaps in the resulting sequence.
+ * Resulting remap table maps old vertices to new vertices and can be used in meshopt_remapVertexBuffer/meshopt_remapIndexBuffer.
+ * Note that binary equivalence considers all vertex_size bytes, including padding which should be zero-initialized.
+ *
+ * destination must contain enough space for the resulting remap table (vertex_count elements)
+ * indices can be NULL if the input is unindexed
+ */
+MESHOPTIMIZER_API size_t meshopt_generateVertexRemap(unsigned int* destination, const unsigned int* indices, size_t index_count, const void* vertices, size_t vertex_count, size_t vertex_size);
+
+/**
+ * Generates a vertex remap table from multiple vertex streams and an optional index buffer and returns number of unique vertices
+ * As a result, all vertices that are binary equivalent map to the same (new) location, with no gaps in the resulting sequence.
+ * Resulting remap table maps old vertices to new vertices and can be used in meshopt_remapVertexBuffer/meshopt_remapIndexBuffer.
+ * To remap vertex buffers, you will need to call meshopt_remapVertexBuffer for each vertex stream.
+ * Note that binary equivalence considers all size bytes in each stream, including padding which should be zero-initialized.
+ *
+ * destination must contain enough space for the resulting remap table (vertex_count elements)
+ * indices can be NULL if the input is unindexed
+ * stream_count must be <= 16
+ */
+MESHOPTIMIZER_API size_t meshopt_generateVertexRemapMulti(unsigned int* destination, const unsigned int* indices, size_t index_count, size_t vertex_count, const struct meshopt_Stream* streams, size_t stream_count);
+
+/**
+ * Generates a vertex remap table from the vertex buffer and an optional index buffer and returns number of unique vertices
+ * As a result, all vertices that are equivalent map to the same (new) location, with no gaps in the resulting sequence.
+ * Equivalence is checked in two steps: vertex positions are compared for equality, and then the user-specified equality function is called (if provided).
+ * Resulting remap table maps old vertices to new vertices and can be used in meshopt_remapVertexBuffer/meshopt_remapIndexBuffer.
+ *
+ * destination must contain enough space for the resulting remap table (vertex_count elements)
+ * indices can be NULL if the input is unindexed
+ * vertex_positions should have float3 position in the first 12 bytes of each vertex
+ * callback can be NULL if no additional equality check is needed; otherwise, it should return 1 if vertices with specified indices are equivalent and 0 if they are not
+ */
+MESHOPTIMIZER_API size_t meshopt_generateVertexRemapCustom(unsigned int* destination, const unsigned int* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, int (*callback)(void*, unsigned int, unsigned int), void* context);
+
+/**
+ * Generates vertex buffer from the source vertex buffer and remap table generated by meshopt_generateVertexRemap
+ *
+ * destination must contain enough space for the resulting vertex buffer (unique_vertex_count elements, returned by meshopt_generateVertexRemap)
+ * vertex_count should be the initial vertex count and not the value returned by meshopt_generateVertexRemap
+ */
+MESHOPTIMIZER_API void meshopt_remapVertexBuffer(void* destination, const void* vertices, size_t vertex_count, size_t vertex_size, const unsigned int* remap);
+
+/**
+ * Generate index buffer from the source index buffer and remap table generated by meshopt_generateVertexRemap
+ *
+ * destination must contain enough space for the resulting index buffer (index_count elements)
+ * indices can be NULL if the input is unindexed
+ */
+MESHOPTIMIZER_API void meshopt_remapIndexBuffer(unsigned int* destination, const unsigned int* indices, size_t index_count, const unsigned int* remap);
+
+/**
+ * Experimental: Filter out redundant triangles from the index buffer and return the number of remaining indices
+ * Triangles are considered redundant if they are degenerate (two vertices have the same vertex key) or duplicate (matching triangle was present earlier).
+ * First vertex_size bytes of every vertex are compared for equality; typically vertex_size should be set to the size of the position attribute.
+ * Note that duplicate triangles with opposite windings are preserved, as they may be needed for double-sided rendering.
+ *
+ * destination must contain enough space for the resulting index buffer (index_count elements)
+ */
+MESHOPTIMIZER_EXPERIMENTAL size_t meshopt_filterIndexBuffer(unsigned int* destination, const unsigned int* indices, size_t index_count, const void* vertices, size_t vertex_count, size_t vertex_size, size_t vertex_stride);
+
+/**
+ * Experimental: Filter out redundant triangles from the index buffer and return the number of remaining indices
+ * Triangles are considered redundant if they are degenerate (two vertices have the same vertex key) or duplicate (matching triangle was present earlier).
+ * All bytes in specified streams are compared for equality; streams should include attributes relevant for position transform (e.g. bone influences).
+ * Note that duplicate triangles with opposite windings are preserved, as they may be needed for double-sided rendering.
+ *
+ * destination must contain enough space for the resulting index buffer (index_count elements)
+ * stream_count must be <= 16
+ */
+MESHOPTIMIZER_EXPERIMENTAL size_t meshopt_filterIndexBufferMulti(unsigned int* destination, const unsigned int* indices, size_t index_count, size_t vertex_count, const struct meshopt_Stream* streams, size_t stream_count);
+
+/**
+ * Generate index buffer that can be used for more efficient rendering when only a subset of the vertex attributes is necessary
+ * All vertices that are binary equivalent (wrt first vertex_size bytes) map to the first vertex in the original vertex buffer.
+ * This makes it possible to use the index buffer for Z pre-pass or shadowmap rendering, while using the original index buffer for regular rendering.
+ * Note that binary equivalence considers all vertex_size bytes, including padding which should be zero-initialized.
+ *
+ * destination must contain enough space for the resulting index buffer (index_count elements)
+ */
+MESHOPTIMIZER_API void meshopt_generateShadowIndexBuffer(unsigned int* destination, const unsigned int* indices, size_t index_count, const void* vertices, size_t vertex_count, size_t vertex_size, size_t vertex_stride);
+
+/**
+ * Generate index buffer that can be used for more efficient rendering when only a subset of the vertex attributes is necessary
+ * All vertices that are binary equivalent (wrt specified streams) map to the first vertex in the original vertex buffer.
+ * This makes it possible to use the index buffer for Z pre-pass or shadowmap rendering, while using the original index buffer for regular rendering.
+ * Note that binary equivalence considers all size bytes in each stream, including padding which should be zero-initialized.
+ *
+ * destination must contain enough space for the resulting index buffer (index_count elements)
+ * stream_count must be <= 16
+ */
+MESHOPTIMIZER_API void meshopt_generateShadowIndexBufferMulti(unsigned int* destination, const unsigned int* indices, size_t index_count, size_t vertex_count, const struct meshopt_Stream* streams, size_t stream_count);
+
+/**
+ * Generates a remap table that maps all vertices with the same position to the same (existing) index.
+ * Similarly to meshopt_generateShadowIndexBuffer, this can be helpful to pre-process meshes for position-only rendering.
+ * This can also be used to implement algorithms that require positional-only connectivity, such as hierarchical simplification.
+ *
+ * destination must contain enough space for the resulting remap table (vertex_count elements)
+ * vertex_positions should have float3 position in the first 12 bytes of each vertex
+ */
+MESHOPTIMIZER_API void meshopt_generatePositionRemap(unsigned int* destination, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride);
+
+/**
+ * Generate index buffer that can be used as a geometry shader input with triangle adjacency topology
+ * Each triangle is converted into a 6-vertex patch with the following layout:
+ * - 0, 2, 4: original triangle vertices
+ * - 1, 3, 5: vertices adjacent to edges 02, 24 and 40
+ * The resulting patch can be rendered with geometry shaders using e.g. VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST_WITH_ADJACENCY.
+ * This can be used to implement algorithms like silhouette detection/expansion and other forms of GS-driven rendering.
+ *
+ * destination must contain enough space for the resulting index buffer (index_count*2 elements)
+ * vertex_positions should have float3 position in the first 12 bytes of each vertex
+ */
+MESHOPTIMIZER_API void meshopt_generateAdjacencyIndexBuffer(unsigned int* destination, const unsigned int* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride);
+
+/**
+ * Generate index buffer that can be used for PN-AEN tessellation with crack-free displacement
+ * Each triangle is converted into a 12-vertex patch with the following layout:
+ * - 0, 1, 2: original triangle vertices
+ * - 3, 4: opposing edge for edge 0, 1
+ * - 5, 6: opposing edge for edge 1, 2
+ * - 7, 8: opposing edge for edge 2, 0
+ * - 9, 10, 11: dominant vertices for corners 0, 1, 2
+ * The resulting patch can be rendered with hardware tessellation using PN-AEN and displacement mapping.
+ * See "Tessellation on Any Budget" (John McDonald, GDC 2011) for implementation details.
+ *
+ * destination must contain enough space for the resulting index buffer (index_count*4 elements)
+ * vertex_positions should have float3 position in the first 12 bytes of each vertex
+ */
+MESHOPTIMIZER_API void meshopt_generateTessellationIndexBuffer(unsigned int* destination, const unsigned int* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride);
+
+/**
+ * Generate index buffer that can be used for visibility buffer rendering and returns the size of the reorder table
+ * Each triangle's provoking vertex index is equal to primitive id; this allows passing it to the fragment shader using flat/nointerpolation attribute.
+ * This is important for performance on hardware where primitive id can't be accessed efficiently in fragment shader.
+ * The reorder table stores the original vertex id for each vertex in the new index buffer, and should be used in the vertex shader to load vertex data.
+ * The provoking vertex is assumed to be the first vertex in the triangle; if this is not the case (OpenGL), rotate each triangle (abc -> bca) before rendering.
+ * For maximum efficiency the input index buffer should be optimized for vertex cache first.
+ *
+ * destination must contain enough space for the resulting index buffer (index_count elements)
+ * reorder must contain enough space for the worst case reorder table (vertex_count + index_count/3 elements)
+ */
+MESHOPTIMIZER_API size_t meshopt_generateProvokingIndexBuffer(unsigned int* destination, unsigned int* reorder, const unsigned int* indices, size_t index_count, size_t vertex_count);
+
+/**
+ * Vertex transform cache optimizer
+ * Reorders indices to reduce the number of GPU vertex shader invocations
+ * If index buffer contains multiple ranges for multiple draw calls, this function needs to be called on each range individually.
+ *
+ * destination must contain enough space for the resulting index buffer (index_count elements)
+ */
+MESHOPTIMIZER_API void meshopt_optimizeVertexCache(unsigned int* destination, const unsigned int* indices, size_t index_count, size_t vertex_count);
+
+/**
+ * Vertex transform cache optimizer for strip-like caches
+ * Produces inferior results to meshopt_optimizeVertexCache from the GPU vertex cache perspective
+ * However, the resulting index order is more optimal if the goal is to reduce the triangle strip length or improve compression efficiency
+ *
+ * destination must contain enough space for the resulting index buffer (index_count elements)
+ */
+MESHOPTIMIZER_API void meshopt_optimizeVertexCacheStrip(unsigned int* destination, const unsigned int* indices, size_t index_count, size_t vertex_count);
+
+/**
+ * Vertex transform cache optimizer for FIFO caches
+ * Reorders indices to reduce the number of GPU vertex shader invocations
+ * Generally takes ~3x less time to optimize meshes but produces inferior results compared to meshopt_optimizeVertexCache
+ * If index buffer contains multiple ranges for multiple draw calls, this function needs to be called on each range individually.
+ *
+ * destination must contain enough space for the resulting index buffer (index_count elements)
+ * cache_size should be less than the actual GPU cache size to avoid cache thrashing
+ */
+MESHOPTIMIZER_API void meshopt_optimizeVertexCacheFifo(unsigned int* destination, const unsigned int* indices, size_t index_count, size_t vertex_count, unsigned int cache_size);
+
+/**
+ * Overdraw optimizer
+ * Reorders indices to reduce the number of GPU vertex shader invocations and the pixel overdraw
+ * If index buffer contains multiple ranges for multiple draw calls, this function needs to be called on each range individually.
+ *
+ * destination must contain enough space for the resulting index buffer (index_count elements)
+ * indices must contain index data that is the result of meshopt_optimizeVertexCache (*not* the original mesh indices!)
+ * vertex_positions should have float3 position in the first 12 bytes of each vertex
+ * threshold indicates how much the overdraw optimizer can degrade vertex cache efficiency (1.05 = up to 5%) to reduce overdraw more efficiently
+ */
+MESHOPTIMIZER_API void meshopt_optimizeOverdraw(unsigned int* destination, const unsigned int* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, float threshold);
+
+/**
+ * Vertex fetch cache optimizer
+ * Reorders vertices and changes indices to reduce the amount of GPU memory fetches during vertex processing
+ * Returns the number of unique vertices, which is the same as input vertex count unless some vertices are unused
+ * This function works for a single vertex stream; for multiple vertex streams, use meshopt_optimizeVertexFetchRemap + meshopt_remapVertexBuffer for each stream.
+ *
+ * destination must contain enough space for the resulting vertex buffer (vertex_count elements)
+ * indices is used both as an input and as an output index buffer
+ */
+MESHOPTIMIZER_API size_t meshopt_optimizeVertexFetch(void* destination, unsigned int* indices, size_t index_count, const void* vertices, size_t vertex_count, size_t vertex_size);
+
+/**
+ * Vertex fetch cache optimizer
+ * Generates vertex remap to reduce the amount of GPU memory fetches during vertex processing
+ * Returns the number of unique vertices, which is the same as input vertex count unless some vertices are unused
+ * The resulting remap table should be used to reorder vertex/index buffers using meshopt_remapVertexBuffer/meshopt_remapIndexBuffer
+ *
+ * destination must contain enough space for the resulting remap table (vertex_count elements)
+ */
+MESHOPTIMIZER_API size_t meshopt_optimizeVertexFetchRemap(unsigned int* destination, const unsigned int* indices, size_t index_count, size_t vertex_count);
+
+/**
+ * Index buffer encoder
+ * Encodes index data into an array of bytes that is generally much smaller (<1.5 bytes/triangle) and compresses better (<1 bytes/triangle) compared to original.
+ * Input index buffer must represent a triangle list.
+ * Returns encoded data size on success, 0 on error; the only error condition is if buffer doesn't have enough space
+ * For maximum efficiency the index buffer being encoded has to be optimized for vertex cache and vertex fetch first.
+ *
+ * buffer must contain enough space for the encoded index buffer (use meshopt_encodeIndexBufferBound to compute worst case size)
+ */
+MESHOPTIMIZER_API size_t meshopt_encodeIndexBuffer(unsigned char* buffer, size_t buffer_size, const unsigned int* indices, size_t index_count);
+MESHOPTIMIZER_API size_t meshopt_encodeIndexBufferBound(size_t index_count, size_t vertex_count);
+
+/**
+ * Set index encoder format version (defaults to 1)
+ * This function is not thread safe and must not be called concurrently with meshopt_encodeIndexBuffer/meshopt_encodeIndexSequence.
+ *
+ * version must specify the data format version to encode; valid values are 0 (decodable by all library versions) and 1 (decodable by 0.14+)
+ */
+MESHOPTIMIZER_API void meshopt_encodeIndexVersion(int version);
+
+/**
+ * Index buffer decoder
+ * Decodes index data from an array of bytes generated by meshopt_encodeIndexBuffer
+ * Returns 0 if decoding was successful, and an error code otherwise
+ * The decoder is safe to use for untrusted input, but it may produce garbage data (e.g. out of range indices).
+ *
+ * destination must contain enough space for the resulting index buffer (index_count elements)
+ */
+MESHOPTIMIZER_API int meshopt_decodeIndexBuffer(void* destination, size_t index_count, size_t index_size, const unsigned char* buffer, size_t buffer_size);
+
+/**
+ * Get encoded index format version
+ * Returns format version of the encoded index buffer/sequence, or -1 if the buffer header is invalid
+ * Note that a non-negative value doesn't guarantee that the buffer will be decoded correctly if the input is malformed.
+ */
+MESHOPTIMIZER_API int meshopt_decodeIndexVersion(const unsigned char* buffer, size_t buffer_size);
+
+/**
+ * Index sequence encoder
+ * Encodes index sequence into an array of bytes that is generally smaller and compresses better compared to original.
+ * Input index sequence can represent arbitrary topology; for triangle lists meshopt_encodeIndexBuffer is likely to be better.
+ * Returns encoded data size on success, 0 on error; the only error condition is if buffer doesn't have enough space
+ *
+ * buffer must contain enough space for the encoded index sequence (use meshopt_encodeIndexSequenceBound to compute worst case size)
+ */
+MESHOPTIMIZER_API size_t meshopt_encodeIndexSequence(unsigned char* buffer, size_t buffer_size, const unsigned int* indices, size_t index_count);
+MESHOPTIMIZER_API size_t meshopt_encodeIndexSequenceBound(size_t index_count, size_t vertex_count);
+
+/**
+ * Index sequence decoder
+ * Decodes index data from an array of bytes generated by meshopt_encodeIndexSequence
+ * Returns 0 if decoding was successful, and an error code otherwise
+ * The decoder is safe to use for untrusted input, but it may produce garbage data (e.g. out of range indices).
+ *
+ * destination must contain enough space for the resulting index sequence (index_count elements)
+ */
+MESHOPTIMIZER_API int meshopt_decodeIndexSequence(void* destination, size_t index_count, size_t index_size, const unsigned char* buffer, size_t buffer_size);
+
+/**
+ * Meshlet encoder
+ * Encodes meshlet data into an array of bytes that is generally smaller and compresses better compared to original.
+ * Returns encoded data size on success, 0 on error; the only error condition is if buffer doesn't have enough space
+ * This function encodes a single meshlet; when encoding multiple meshlets, additional headers may be necessary to store vertex/triangle count and encoded size.
+ * For maximum efficiency the meshlet being encoded should be optimized using meshopt_optimizeMeshletLevel with level 1+ (3 recommended); additionally, vertex reference data should be optimized for locality (fetch).
+ *
+ * buffer must contain enough space for the encoded meshlet (use meshopt_encodeMeshletBound to compute worst case size)
+ * vertices may be NULL, in which case vertex_count must be 0 and only triangle data is encoded
+ * vertex_count and triangle_count must be <= 256.
+ */
+MESHOPTIMIZER_API size_t meshopt_encodeMeshlet(unsigned char* buffer, size_t buffer_size, const unsigned int* vertices, size_t vertex_count, const unsigned char* triangles, size_t triangle_count);
+MESHOPTIMIZER_API size_t meshopt_encodeMeshletBound(size_t max_vertices, size_t max_triangles);
+
+/**
+ * Meshlet decoder
+ * Decodes meshlet data from an array of bytes generated by meshopt_encodeMeshlet
+ * Returns 0 if decoding was successful, and an error code otherwise
+ * The decoder is safe to use for untrusted input, but it may produce garbage data.
+ *
+ * vertices must contain enough space for the resulting vertex data, aligned to 4 bytes (align(vertex_count * vertex_size, 4) bytes)
+ * vertex_size must be 2 (16-bit vertex references) or 4 (32-bit vertex references)
+ * triangles must contain enough space for the resulting triangle data, aligned to 4 bytes (align(triangle_count * triangle_size, 4) bytes)
+ * triangle_size must be 3 (8-bit triangle indices) or 4 (32-bit packed triangles, stored as (a) | (b << 8) | (c << 16))
+ * vertex_count, triangle_count match those used during encoding exactly; buffer_size must be equal to the encoded size returned by meshopt_encodeMeshlet.
+ * vertices may be NULL, in which case vertex_count must be 0 and the meshlet must contain just triangle data
+ *
+ * When using "raw" decoding (meshopt_decodeMeshletRaw), both vertices and triangles should have available space further aligned to 16 bytes for efficient SIMD decoding.
+ */
+MESHOPTIMIZER_API int meshopt_decodeMeshlet(void* vertices, size_t vertex_count, size_t vertex_size, void* triangles, size_t triangle_count, size_t triangle_size, const unsigned char* buffer, size_t buffer_size);
+MESHOPTIMIZER_API int meshopt_decodeMeshletRaw(unsigned int* vertices, size_t vertex_count, unsigned int* triangles, size_t triangle_count, const unsigned char* buffer, size_t buffer_size);
+
+/**
+ * Vertex buffer encoder
+ * Encodes vertex data into an array of bytes that is generally smaller and compresses better compared to original.
+ * Returns encoded data size on success, 0 on error; the only error condition is if buffer doesn't have enough space
+ * This function works for a single vertex stream; for multiple vertex streams, call meshopt_encodeVertexBuffer for each stream.
+ * Note that all vertex_size bytes of each vertex are encoded verbatim, including padding which should be zero-initialized.
+ * For maximum efficiency the vertex buffer being encoded has to be quantized and optimized for locality of reference (cache/fetch) first.
+ *
+ * buffer must contain enough space for the encoded vertex buffer (use meshopt_encodeVertexBufferBound to compute worst case size)
+ * vertex_size must be a multiple of 4 (and <= 256)
+ */
+MESHOPTIMIZER_API size_t meshopt_encodeVertexBuffer(unsigned char* buffer, size_t buffer_size, const void* vertices, size_t vertex_count, size_t vertex_size);
+MESHOPTIMIZER_API size_t meshopt_encodeVertexBufferBound(size_t vertex_count, size_t vertex_size);
+
+/**
+ * Vertex buffer encoder
+ * Encodes vertex data just like meshopt_encodeVertexBuffer, but allows to override compression level.
+ * For compression level to take effect, the vertex encoding version must be set to 1.
+ * The default compression level implied by meshopt_encodeVertexBuffer is 2.
+ *
+ * buffer must contain enough space for the encoded vertex buffer (use meshopt_encodeVertexBufferBound to compute worst case size)
+ * vertex_size must be a multiple of 4 (and <= 256)
+ * level should be in the range [0, 3] with 0 being the fastest and 3 being the slowest and producing the best compression ratio.
+ * version should be -1 to use the default version (specified via meshopt_encodeVertexVersion), or 0/1 to override the version; per above, level won't take effect if version is 0.
+ */
+MESHOPTIMIZER_API size_t meshopt_encodeVertexBufferLevel(unsigned char* buffer, size_t buffer_size, const void* vertices, size_t vertex_count, size_t vertex_size, int level, int version);
+
+/**
+ * Set vertex encoder format version (defaults to 1)
+ * This function is not thread safe and must not be called concurrently with meshopt_encodeVertexBuffer/meshopt_encodeVertexBufferLevel.
+ *
+ * version must specify the data format version to encode; valid values are 0 (decodable by all library versions) and 1 (decodable by 0.23+)
+ */
+MESHOPTIMIZER_API void meshopt_encodeVertexVersion(int version);
+
+/**
+ * Vertex buffer decoder
+ * Decodes vertex data from an array of bytes generated by meshopt_encodeVertexBuffer
+ * Returns 0 if decoding was successful, and an error code otherwise
+ * The decoder is safe to use for untrusted input, but it may produce garbage data.
+ *
+ * destination must contain enough space for the resulting vertex buffer (vertex_count * vertex_size bytes)
+ * vertex_size must be a multiple of 4 (and <= 256)
+ */
+MESHOPTIMIZER_API int meshopt_decodeVertexBuffer(void* destination, size_t vertex_count, size_t vertex_size, const unsigned char* buffer, size_t buffer_size);
+
+/**
+ * Get encoded vertex format version
+ * Returns format version of the encoded vertex buffer, or -1 if the buffer header is invalid
+ * Note that a non-negative value doesn't guarantee that the buffer will be decoded correctly if the input is malformed.
+ */
+MESHOPTIMIZER_API int meshopt_decodeVertexVersion(const unsigned char* buffer, size_t buffer_size);
+
+/**
+ * Vertex buffer filters
+ * These functions can be used to filter output of meshopt_decodeVertexBuffer in-place.
+ *
+ * meshopt_decodeFilterOct decodes octahedral encoding of a unit vector with K-bit signed X/Y as an input; Z must store 1.0f.
+ * Each component is stored as an 8-bit or 16-bit normalized integer; stride must be equal to 4 or 8. W is preserved as is.
+ *
+ * meshopt_decodeFilterQuat decodes 3-component quaternion encoding with K-bit component encoding and a 2-bit component index indicating which component to reconstruct.
+ * Each component is stored as a 16-bit integer; stride must be equal to 8.
+ *
+ * meshopt_decodeFilterExp decodes exponential encoding of floating-point data with 8-bit exponent and 24-bit integer mantissa as 2^E*M.
+ * Each 32-bit component is decoded in isolation; stride must be divisible by 4.
+ *
+ * meshopt_decodeFilterColor decodes RGBA colors from YCoCg (+A) color encoding where RGB is converted to YCoCg space with K-bit component encoding, and A is stored using K-1 bits.
+ * Each component is stored as an 8-bit or 16-bit normalized integer; stride must be equal to 4 or 8.
+ */
+MESHOPTIMIZER_API void meshopt_decodeFilterOct(void* buffer, size_t count, size_t stride);
+MESHOPTIMIZER_API void meshopt_decodeFilterQuat(void* buffer, size_t count, size_t stride);
+MESHOPTIMIZER_API void meshopt_decodeFilterExp(void* buffer, size_t count, size_t stride);
+MESHOPTIMIZER_API void meshopt_decodeFilterColor(void* buffer, size_t count, size_t stride);
+
+/**
+ * Vertex buffer filter encoders
+ * These functions can be used to encode data in a format that meshopt_decodeFilter can decode
+ *
+ * meshopt_encodeFilterOct encodes unit vectors with K-bit (2 <= K <= 16) signed X/Y as an output.
+ * Each component is stored as an 8-bit or 16-bit normalized integer; stride must be equal to 4 (K <= 8) or 8 (K <= 16). Z will store 1.0f, W is preserved as is.
+ * Input data must contain 4 floats for every vector (count*4 total).
+ *
+ * meshopt_encodeFilterQuat encodes unit quaternions with K-bit (4 <= K <= 16) component encoding.
+ * Each component is stored as a 16-bit integer; stride must be equal to 8.
+ * Input data must contain 4 floats for every quaternion (count*4 total).
+ *
+ * meshopt_encodeFilterExp encodes arbitrary (finite) floating-point data with 8-bit exponent and K-bit integer mantissa (1 <= K <= 24).
+ * Exponent can be shared between all components of a given vector as defined by stride or all values of a given component; stride must be divisible by 4 (and <= 256).
+ * Input data must contain stride/4 floats for every vector (count*stride/4 total).
+ *
+ * meshopt_encodeFilterColor encodes RGBA color data by converting RGB to YCoCg color space with K-bit (2 <= K <= 16) component encoding; A is stored using K-1 bits.
+ * Each component is stored as an 8-bit or 16-bit integer; stride must be equal to 4 (K <= 8) or 8 (K <= 16).
+ * Input data must contain 4 floats for every color (count*4 total).
+ */
+enum meshopt_EncodeExpMode
+{
+	/* When encoding exponents, use separate values for each component (maximum quality) */
+	meshopt_EncodeExpSeparate,
+	/* When encoding exponents, use shared value for all components of each vector (better compression) */
+	meshopt_EncodeExpSharedVector,
+	/* When encoding exponents, use shared value for each component of all vectors (best compression) */
+	meshopt_EncodeExpSharedComponent,
+	/* When encoding exponents, use separate values for each component, but clamp to 0 (good quality if very small values are not important) */
+	meshopt_EncodeExpClamped,
+};
+
+MESHOPTIMIZER_API void meshopt_encodeFilterOct(void* destination, size_t count, size_t stride, int bits, const float* data);
+MESHOPTIMIZER_API void meshopt_encodeFilterQuat(void* destination, size_t count, size_t stride, int bits, const float* data);
+MESHOPTIMIZER_API void meshopt_encodeFilterExp(void* destination, size_t count, size_t stride, int bits, const float* data, enum meshopt_EncodeExpMode mode);
+MESHOPTIMIZER_API void meshopt_encodeFilterColor(void* destination, size_t count, size_t stride, int bits, const float* data);
+
+/**
+ * Simplification options
+ */
+enum
+{
+	/* Do not move vertices that are located on the topological border (vertices on triangle edges that don't have a paired triangle). Useful for simplifying portions of the larger mesh. */
+	meshopt_SimplifyLockBorder = 1 << 0,
+	/* Improve simplification performance assuming input indices are a sparse subset of the mesh. Note that error becomes relative to subset extents. */
+	meshopt_SimplifySparse = 1 << 1,
+	/* Treat error limit and resulting error as absolute instead of relative to mesh extents. */
+	meshopt_SimplifyErrorAbsolute = 1 << 2,
+	/* Remove disconnected parts of the mesh during simplification incrementally, regardless of the topological restrictions inside components. */
+	meshopt_SimplifyPrune = 1 << 3,
+	/* Produce more regular triangle sizes and shapes during simplification, at some cost to geometric and attribute quality. */
+	meshopt_SimplifyRegularize = 1 << 4,
+	/* Experimental: Allow collapses across attribute discontinuities, except for vertices that are tagged with meshopt_SimplifyVertex_Protect in vertex_lock. */
+	meshopt_SimplifyPermissive = 1 << 5,
+	/* Produce more regular triangle sizes and shapes during simplification, at a small cost to geometric and attribute quality. */
+	meshopt_SimplifyRegularizeLight = 1 << 6,
+};
+
+/**
+ * Simplification vertex flags/locks, for use in `vertex_lock` arrays in simplification APIs
+ */
+enum
+{
+	/* Do not move this vertex. */
+	meshopt_SimplifyVertex_Lock = 1 << 0,
+	/* Protect attribute discontinuity at this vertex; must be used together with meshopt_SimplifyPermissive option. */
+	meshopt_SimplifyVertex_Protect = 1 << 1,
+	/* Increase priority for this vertex, making it more likely that it's preserved during simplification. */
+	meshopt_SimplifyVertex_Priority = 1 << 2,
+};
+
+/**
+ * Mesh simplifier
+ * Reduces the number of triangles in the mesh, attempting to preserve mesh appearance as much as possible
+ * The algorithm tries to preserve mesh topology and can stop short of the target goal based on topology constraints or target error.
+ * If not all attributes from the input mesh are needed, it's recommended to reindex the mesh without them prior to simplification.
+ * Returns the number of indices after simplification, with destination containing new index data
+ *
+ * The resulting index buffer references vertices from the original vertex buffer.
+ * If the original vertex data isn't needed, creating a compact vertex buffer using meshopt_optimizeVertexFetch is recommended.
+ *
+ * destination must contain enough space for the target index buffer, worst case is index_count elements (*not* target_index_count)!
+ * vertex_positions should have float3 position in the first 12 bytes of each vertex
+ * target_error represents the error relative to mesh extents that can be tolerated, e.g. 0.01 = 1% deformation (unless absolute error option is used)
+ * options must be a bitmask composed of meshopt_SimplifyX options; 0 is a safe default
+ * result_error can be NULL; when it's not NULL, it will contain the resulting (relative/absolute) error after simplification
+ */
+MESHOPTIMIZER_API size_t meshopt_simplify(unsigned int* destination, const unsigned int* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, size_t target_index_count, float target_error, unsigned int options, float* result_error);
+
+/**
+ * Mesh simplifier with attribute metric
+ * Reduces the number of triangles in the mesh, attempting to preserve mesh appearance as much as possible.
+ * Similar to meshopt_simplify, but incorporates attribute values into the error metric used to prioritize simplification order.
+ * The algorithm tries to preserve mesh topology and can stop short of the target goal based on topology constraints or target error.
+ * If not all attributes from the input mesh are needed, it's recommended to reindex the mesh without them prior to simplification.
+ * Returns the number of indices after simplification, with destination containing new index data
+ *
+ * The resulting index buffer references vertices from the original vertex buffer.
+ * If the original vertex data isn't needed, creating a compact vertex buffer using meshopt_optimizeVertexFetch is recommended.
+ * Note that the number of attributes with non-zero weights affects memory requirements and running time.
+ *
+ * destination must contain enough space for the target index buffer, worst case is index_count elements (*not* target_index_count)!
+ * vertex_positions should have float3 position in the first 12 bytes of each vertex
+ * vertex_attributes should have attribute_count floats for each vertex
+ * attribute_weights should have attribute_count floats in total; the weights determine relative priority of attributes between each other and wrt position
+ * attribute_count must be <= 32
+ * vertex_lock can be NULL; when it's not NULL, it should have a value for each vertex composed of meshopt_SimplifyVertex_* flags
+ * target_error represents the error relative to mesh extents that can be tolerated, e.g. 0.01 = 1% deformation (unless absolute error option is used)
+ * options must be a bitmask composed of meshopt_SimplifyX options; 0 is a safe default
+ * result_error can be NULL; when it's not NULL, it will contain the resulting (relative/absolute) error after simplification
+ */
+MESHOPTIMIZER_API size_t meshopt_simplifyWithAttributes(unsigned int* destination, const unsigned int* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, const float* vertex_attributes, size_t vertex_attributes_stride, const float* attribute_weights, size_t attribute_count, const unsigned char* vertex_lock, size_t target_index_count, float target_error, unsigned int options, float* result_error);
+
+/**
+ * Mesh simplifier with position/attribute update
+ * Reduces the number of triangles in the mesh, attempting to preserve mesh appearance as much as possible.
+ * Similar to meshopt_simplifyWithAttributes, but destructively updates positions and attribute values for optimal appearance.
+ * The algorithm tries to preserve mesh topology and can stop short of the target goal based on topology constraints or target error.
+ * If not all attributes from the input mesh are needed, it's recommended to reindex the mesh without them prior to simplification.
+ * Returns the number of indices after simplification, indices are destructively updated with new index data
+ *
+ * The updated index buffer references vertices from the original vertex buffer, however the vertex positions and attributes are updated in-place.
+ * Creating a compact vertex buffer using meshopt_optimizeVertexFetch is recommended; if the original vertex data is needed, it should be copied before simplification.
+ * Note that the number of attributes with non-zero weights affects memory requirements and running time. Attributes with zero weights are not updated.
+ *
+ * vertex_positions should have float3 position in the first 12 bytes of each vertex
+ * vertex_attributes should have attribute_count floats for each vertex
+ * attribute_weights should have attribute_count floats in total; the weights determine relative priority of attributes between each other and wrt position
+ * attribute_count must be <= 32
+ * vertex_lock can be NULL; when it's not NULL, it should have a value for each vertex composed of meshopt_SimplifyVertex_* flags
+ * target_error represents the error relative to mesh extents that can be tolerated, e.g. 0.01 = 1% deformation (unless absolute error option is used)
+ * options must be a bitmask composed of meshopt_SimplifyX options; 0 is a safe default
+ * result_error can be NULL; when it's not NULL, it will contain the resulting (relative/absolute) error after simplification
+ */
+MESHOPTIMIZER_API size_t meshopt_simplifyWithUpdate(unsigned int* indices, size_t index_count, float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, float* vertex_attributes, size_t vertex_attributes_stride, const float* attribute_weights, size_t attribute_count, const unsigned char* vertex_lock, size_t target_index_count, float target_error, unsigned int options, float* result_error);
+
+/**
+ * Mesh simplifier (sloppy)
+ * Reduces the number of triangles in the mesh, sacrificing mesh appearance for simplification performance
+ * The algorithm doesn't preserve mesh topology but can stop short of the target goal based on target error.
+ * Returns the number of indices after simplification, with destination containing new index data
+ * The resulting index buffer references vertices from the original vertex buffer.
+ * If the original vertex data isn't needed, creating a compact vertex buffer using meshopt_optimizeVertexFetch is recommended.
+ *
+ * destination must contain enough space for the target index buffer, worst case is index_count elements (*not* target_index_count)!
+ * vertex_positions should have float3 position in the first 12 bytes of each vertex
+ * vertex_lock can be NULL; when it's not NULL, it should have a value for each vertex; vertices that can't be moved should set 1 consistently for all indices with the same position
+ * target_error represents the error relative to mesh extents that can be tolerated, e.g. 0.01 = 1% deformation; value range [0..1]
+ * result_error can be NULL; when it's not NULL, it will contain the resulting (relative) error after simplification
+ */
+MESHOPTIMIZER_API size_t meshopt_simplifySloppy(unsigned int* destination, const unsigned int* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, const unsigned char* vertex_lock, size_t target_index_count, float target_error, float* result_error);
+
+/**
+ * Mesh simplifier (pruner)
+ * Reduces the number of triangles in the mesh by removing small isolated parts of the mesh
+ * Returns the number of indices after simplification, with destination containing new index data
+ * The resulting index buffer references vertices from the original vertex buffer.
+ * If the original vertex data isn't needed, creating a compact vertex buffer using meshopt_optimizeVertexFetch is recommended.
+ *
+ * destination must contain enough space for the target index buffer, worst case is index_count elements
+ * vertex_positions should have float3 position in the first 12 bytes of each vertex
+ * target_error represents the error relative to mesh extents that can be tolerated, e.g. 0.01 = 1% deformation; value range [0..1]
+ */
+MESHOPTIMIZER_API size_t meshopt_simplifyPrune(unsigned int* destination, const unsigned int* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, float target_error);
+
+/**
+ * Point cloud simplifier
+ * Reduces the number of points in the cloud to reach the given target
+ * Returns the number of points after simplification, with destination containing new index data
+ * The resulting index buffer references vertices from the original vertex buffer.
+ * If the original vertex data isn't needed, creating a compact vertex buffer using meshopt_optimizeVertexFetch is recommended.
+ *
+ * destination must contain enough space for the target index buffer (target_vertex_count elements)
+ * vertex_positions should have float3 position in the first 12 bytes of each vertex
+ * vertex_colors can be NULL; when it's not NULL, it should have float3 color in the first 12 bytes of each vertex
+ * color_weight determines relative priority of color wrt position; 1.0 is a safe default
+ */
+MESHOPTIMIZER_API size_t meshopt_simplifyPoints(unsigned int* destination, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, const float* vertex_colors, size_t vertex_colors_stride, float color_weight, size_t target_vertex_count);
+
+/**
+ * Returns the error scaling factor used by the simplifier to convert between absolute and relative extents
+ *
+ * Absolute error must be *divided* by the scaling factor before passing it to meshopt_simplify as target_error
+ * Relative error returned by meshopt_simplify via result_error must be *multiplied* by the scaling factor to get absolute error.
+ */
+MESHOPTIMIZER_API float meshopt_simplifyScale(const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride);
+
+/**
+ * Mesh stripifier
+ * Converts a previously vertex cache optimized triangle list to triangle strip, stitching strips using restart index or degenerate triangles
+ * Returns the number of indices in the resulting strip, with destination containing new index data
+ * For maximum efficiency the index buffer being converted has to be optimized for vertex cache first.
+ * Using restart indices can result in ~10% smaller index buffers, but on some GPUs restart indices may result in decreased performance.
+ *
+ * destination must contain enough space for the target index buffer, worst case can be computed with meshopt_stripifyBound
+ * restart_index should be 0xffff or 0xffffffff depending on index size, or 0 to use degenerate triangles
+ */
+MESHOPTIMIZER_API size_t meshopt_stripify(unsigned int* destination, const unsigned int* indices, size_t index_count, size_t vertex_count, unsigned int restart_index);
+MESHOPTIMIZER_API size_t meshopt_stripifyBound(size_t index_count);
+
+/**
+ * Mesh unstripifier
+ * Converts a triangle strip to a triangle list
+ * Returns the number of indices in the resulting list, with destination containing new index data
+ *
+ * destination must contain enough space for the target index buffer, worst case can be computed with meshopt_unstripifyBound
+ */
+MESHOPTIMIZER_API size_t meshopt_unstripify(unsigned int* destination, const unsigned int* indices, size_t index_count, unsigned int restart_index);
+MESHOPTIMIZER_API size_t meshopt_unstripifyBound(size_t index_count);
+
+struct meshopt_VertexCacheStatistics
+{
+	unsigned int vertices_transformed;
+	unsigned int warps_executed;
+	float acmr; /* transformed vertices / triangle count; best case 0.5, worst case 3.0, optimum depends on topology */
+	float atvr; /* transformed vertices / vertex count; best case 1.0, worst case 6.0, optimum is 1.0 (each vertex is transformed once) */
+};
+
+/**
+ * Vertex transform cache analyzer
+ * Returns cache hit statistics using a simplified FIFO model
+ * Results may not match actual GPU performance
+ */
+MESHOPTIMIZER_API struct meshopt_VertexCacheStatistics meshopt_analyzeVertexCache(const unsigned int* indices, size_t index_count, size_t vertex_count, unsigned int cache_size, unsigned int warp_size, unsigned int primgroup_size);
+
+struct meshopt_VertexFetchStatistics
+{
+	unsigned int bytes_fetched;
+	float overfetch; /* fetched bytes / vertex buffer size; best case 1.0 (each byte is fetched once) */
+};
+
+/**
+ * Vertex fetch cache analyzer
+ * Returns cache hit statistics using a simplified direct mapped model
+ * Results may not match actual GPU performance
+ */
+MESHOPTIMIZER_API struct meshopt_VertexFetchStatistics meshopt_analyzeVertexFetch(const unsigned int* indices, size_t index_count, size_t vertex_count, size_t vertex_size);
+
+struct meshopt_OverdrawStatistics
+{
+	unsigned int pixels_covered;
+	unsigned int pixels_shaded;
+	float overdraw; /* shaded pixels / covered pixels; best case 1.0 */
+};
+
+/**
+ * Overdraw analyzer
+ * Returns overdraw statistics using a software rasterizer
+ * Results may not match actual GPU performance
+ *
+ * vertex_positions should have float3 position in the first 12 bytes of each vertex
+ */
+MESHOPTIMIZER_API struct meshopt_OverdrawStatistics meshopt_analyzeOverdraw(const unsigned int* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride);
+
+struct meshopt_CoverageStatistics
+{
+	float coverage[3];
+	float extent; /* viewport size in mesh coordinates */
+};
+
+/**
+ * Coverage analyzer
+ * Returns coverage statistics (ratio of viewport pixels covered from each axis) using a software rasterizer
+ *
+ * vertex_positions should have float3 position in the first 12 bytes of each vertex
+ */
+MESHOPTIMIZER_API struct meshopt_CoverageStatistics meshopt_analyzeCoverage(const unsigned int* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride);
+
+/**
+ * Meshlet is a small mesh cluster (subset) that consists of:
+ * - triangles, an 8-bit micro triangle (index) buffer, that for each triangle specifies three local vertices to use;
+ * - vertices, a 32-bit vertex indirection buffer, that for each local vertex specifies which mesh vertex to fetch vertex attributes from.
+ *
+ * For efficiency, meshlet triangles and vertices are packed into two large arrays; this structure contains offsets and counts to access the data.
+ */
+struct meshopt_Meshlet
+{
+	/* offsets within meshlet_vertices and meshlet_triangles arrays with meshlet data */
+	unsigned int vertex_offset;
+	unsigned int triangle_offset;
+
+	/* number of vertices and triangles used in the meshlet; data is stored in consecutive range [offset..offset+count) for vertices and [offset..offset+count*3) for triangles */
+	unsigned int vertex_count;
+	unsigned int triangle_count;
+};
+
+/**
+ * Meshlet builder
+ * Splits the mesh into a set of meshlets where each meshlet has a micro index buffer indexing into meshlet vertices that refer to the original vertex buffer
+ * The resulting data can be used to render meshes using NVidia programmable mesh shading pipeline, or in other cluster-based renderers.
+ * When targeting mesh shading hardware, for maximum efficiency meshlets should be further optimized using meshopt_optimizeMeshlet.
+ * When using buildMeshlets, vertex positions need to be provided to minimize the size of the resulting clusters.
+ * When using buildMeshletsScan, for maximum efficiency the index buffer being converted has to be optimized for vertex cache first.
+ *
+ * meshlets must contain enough space for all meshlets, worst case size can be computed with meshopt_buildMeshletsBound
+ * meshlet_vertices must contain enough space for all meshlets, worst case is index_count elements (*not* vertex_count!)
+ * meshlet_triangles must contain enough space for all meshlets, worst case is index_count elements
+ * vertex_positions should have float3 position in the first 12 bytes of each vertex
+ * max_vertices and max_triangles must not exceed implementation limits (max_vertices <= 256, max_triangles <= 512)
+ * cone_weight should be set to 0 when cone culling is not used, and a value between 0 and 1 otherwise to balance between cluster size and cone culling efficiency
+ */
+MESHOPTIMIZER_API size_t meshopt_buildMeshlets(struct meshopt_Meshlet* meshlets, unsigned int* meshlet_vertices, unsigned char* meshlet_triangles, const unsigned int* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, size_t max_vertices, size_t max_triangles, float cone_weight);
+MESHOPTIMIZER_API size_t meshopt_buildMeshletsScan(struct meshopt_Meshlet* meshlets, unsigned int* meshlet_vertices, unsigned char* meshlet_triangles, const unsigned int* indices, size_t index_count, size_t vertex_count, size_t max_vertices, size_t max_triangles);
+MESHOPTIMIZER_API size_t meshopt_buildMeshletsBound(size_t index_count, size_t max_vertices, size_t max_triangles);
+
+/**
+ * Meshlet builder with flexible cluster sizes
+ * Splits the mesh into a set of meshlets, similarly to meshopt_buildMeshlets, but allows to specify minimum and maximum number of triangles per meshlet.
+ * Clusters between min and max triangle counts are split when the cluster size would have exceeded the expected cluster size by more than split_factor.
+ *
+ * meshlets must contain enough space for all meshlets, worst case size can be computed with meshopt_buildMeshletsBound using min_triangles (*not* max!)
+ * meshlet_vertices must contain enough space for all meshlets, worst case is index_count elements (*not* vertex_count!)
+ * meshlet_triangles must contain enough space for all meshlets, worst case is index_count elements
+ * vertex_positions should have float3 position in the first 12 bytes of each vertex
+ * max_vertices, min_triangles and max_triangles must not exceed implementation limits (max_vertices <= 256, max_triangles <= 512; min_triangles <= max_triangles)
+ * cone_weight should be set to 0 when cone culling is not used, and a value between 0 and 1 otherwise to balance between cluster size and cone culling efficiency
+ * split_factor should be set to a non-negative value; when greater than 0, clusters that have large bounds may be split unless they are under the min_triangles threshold
+ */
+MESHOPTIMIZER_API size_t meshopt_buildMeshletsFlex(struct meshopt_Meshlet* meshlets, unsigned int* meshlet_vertices, unsigned char* meshlet_triangles, const unsigned int* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, size_t max_vertices, size_t min_triangles, size_t max_triangles, float cone_weight, float split_factor);
+
+/**
+ * Meshlet builder that produces clusters optimized for raytracing
+ * Splits the mesh into a set of meshlets, similarly to meshopt_buildMeshlets, but optimizes cluster subdivision for raytracing and allows to specify minimum and maximum number of triangles per meshlet.
+ *
+ * meshlets must contain enough space for all meshlets, worst case size can be computed with meshopt_buildMeshletsBound using min_triangles (*not* max!)
+ * meshlet_vertices must contain enough space for all meshlets, worst case is index_count elements (*not* vertex_count!)
+ * meshlet_triangles must contain enough space for all meshlets, worst case is index_count elements
+ * vertex_positions should have float3 position in the first 12 bytes of each vertex
+ * max_vertices, min_triangles and max_triangles must not exceed implementation limits (max_vertices <= 256, max_triangles <= 512; min_triangles <= max_triangles)
+ * fill_weight allows to prioritize clusters that are closer to maximum size at some cost to SAH quality; 0.5 is a safe default
+ */
+MESHOPTIMIZER_API size_t meshopt_buildMeshletsSpatial(struct meshopt_Meshlet* meshlets, unsigned int* meshlet_vertices, unsigned char* meshlet_triangles, const unsigned int* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, size_t max_vertices, size_t min_triangles, size_t max_triangles, float fill_weight);
+
+/**
+ * Meshlet optimizer
+ * Reorders meshlet vertices and triangles to maximize locality which can improve rasterizer throughput or ray tracing performance when using fast-build modes.
+ *
+ * meshlet_triangles and meshlet_vertices must refer to meshlet data; when buildMeshlets* is used, these need to be computed from meshlet's vertex_offset and triangle_offset
+ * triangle_count and vertex_count must not exceed implementation limits (vertex_count <= 256, triangle_count <= 512)
+ */
+MESHOPTIMIZER_API void meshopt_optimizeMeshlet(unsigned int* meshlet_vertices, unsigned char* meshlet_triangles, size_t triangle_count, size_t vertex_count);
+
+/**
+ * Meshlet optimizer
+ * Reorders meshlet vertices and triangles to maximize locality, with higher levels resulting in smaller compressed size at the cost of optimization time.
+ * At level 0 the result is equivalent to meshopt_optimizeMeshlet; levels >= 1 may rotate triangle corners to improve compression (which can change provoking vertex and affect OMM data).
+ *
+ * level should be in the range [0, 9] with 0 equivalent to meshopt_optimizeMeshlet and 9 being the slowest; the sweet spot for compression ratio is around 3
+ */
+MESHOPTIMIZER_API void meshopt_optimizeMeshletLevel(unsigned int* meshlet_vertices, size_t vertex_count, unsigned char* meshlet_triangles, size_t triangle_count, int level);
+
+struct meshopt_Bounds
+{
+	/* bounding sphere, useful for frustum and occlusion culling */
+	float center[3];
+	float radius;
+
+	/* normal cone, useful for backface culling */
+	float cone_apex[3];
+	float cone_axis[3];
+	float cone_cutoff; /* = cos(angle/2) */
+
+	/* normal cone axis and cutoff, stored in 8-bit SNORM format; decode using x/127.0 */
+	signed char cone_axis_s8[3];
+	signed char cone_cutoff_s8;
+};
+
+/**
+ * Cluster bounds generator
+ * Creates bounding volumes that can be used for frustum, backface and occlusion culling.
+ *
+ * For backface culling with orthographic projection, use the following formula to reject backfacing clusters:
+ *   dot(view, cone_axis) >= cone_cutoff
+ *
+ * For perspective projection, you can use the formula that needs cone apex in addition to axis & cutoff:
+ *   dot(normalize(cone_apex - camera_position), cone_axis) >= cone_cutoff
+ *
+ * Alternatively, you can use the formula that doesn't need cone apex and uses bounding sphere instead:
+ *   dot(normalize(center - camera_position), cone_axis) >= cone_cutoff + radius / length(center - camera_position)
+ * or an equivalent formula that doesn't have a singularity at center = camera_position:
+ *   dot(center - camera_position, cone_axis) >= cone_cutoff * length(center - camera_position) + radius
+ *
+ * The formula that uses the apex is slightly more accurate but needs the apex; if you are already using bounding sphere
+ * to do frustum/occlusion culling, the formula that doesn't use the apex may be preferable (for derivation see
+ * Real-Time Rendering 4th Edition, section 19.3).
+ *
+ * vertex_positions should have float3 position in the first 12 bytes of each vertex
+ * vertex_count should specify the number of vertices in the entire mesh, not cluster or meshlet
+ * indices should have at most 256 unique vertex indices
+ * index_count/3 and triangle_count must not exceed implementation limits (<= 512)
+ */
+MESHOPTIMIZER_API struct meshopt_Bounds meshopt_computeClusterBounds(const unsigned int* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride);
+MESHOPTIMIZER_API struct meshopt_Bounds meshopt_computeMeshletBounds(const unsigned int* meshlet_vertices, const unsigned char* meshlet_triangles, size_t triangle_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride);
+
+/**
+ * Sphere bounds generator
+ * Creates bounding sphere around a set of points or a set of spheres; returns the center and radius of the sphere, with other fields of the result set to 0.
+ *
+ * positions should have float3 position in the first 12 bytes of each element
+ * radii can be NULL; when it's not NULL, it should have a non-negative float radius in the first 4 bytes of each element
+ */
+MESHOPTIMIZER_API struct meshopt_Bounds meshopt_computeSphereBounds(const float* positions, size_t count, size_t positions_stride, const float* radii, size_t radii_stride);
+
+/**
+ * Extract meshlet-local vertex and triangle indices from absolute cluster indices.
+ * Fills triangles[] and vertices[] such that vertices[triangles[i]] == indices[i], and returns the number of unique vertices.
+ *
+ * vertices must contain enough space for the resulting references (up to 256 elements)
+ * triangles must contain enough space for local indices (index_count elements)
+ * indices should have at most 256 unique vertex indices
+ * index_count/3 must not exceed implementation limits (<= 512)
+ */
+MESHOPTIMIZER_API size_t meshopt_extractMeshletIndices(unsigned int* vertices, unsigned char* triangles, const unsigned int* indices, size_t index_count);
+
+/**
+ * Cluster partitioner
+ * Partitions clusters into groups of similar size, prioritizing grouping clusters that share vertices or are close to each other.
+ * When vertex positions are not provided, only clusters that share vertices will be grouped together, which may result in small partitions for some inputs.
+ *
+ * destination must contain enough space for the resulting partition data (cluster_count elements)
+ * destination[i] will contain the partition id for cluster i, with the total number of partitions returned by the function
+ * cluster_indices should have the vertex indices referenced by each cluster, stored sequentially
+ * cluster_index_counts should have the number of indices in each cluster; sum of all cluster_index_counts must be equal to total_index_count
+ * vertex_positions can be NULL; when it's not NULL, it should have float3 position in the first 12 bytes of each vertex
+ * target_partition_size is a target size for each partition, in clusters; the resulting partitions may be smaller or larger (up to target + target/3)
+ */
+MESHOPTIMIZER_API size_t meshopt_partitionClusters(unsigned int* destination, const unsigned int* cluster_indices, size_t total_index_count, const unsigned int* cluster_index_counts, size_t cluster_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, size_t target_partition_size);
+
+/**
+ * Spatial sorter
+ * Generates a remap table that can be used to reorder points for spatial locality.
+ * Resulting remap table maps old vertices to new vertices and can be used in meshopt_remapVertexBuffer.
+ *
+ * destination must contain enough space for the resulting remap table (vertex_count elements)
+ * vertex_positions should have float3 position in the first 12 bytes of each vertex
+ */
+MESHOPTIMIZER_API void meshopt_spatialSortRemap(unsigned int* destination, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride);
+
+/**
+ * Spatial sorter
+ * Reorders triangles for spatial locality, and generates a new index buffer. The resulting index buffer can be used with other functions like optimizeVertexCache.
+ *
+ * destination must contain enough space for the resulting index buffer (index_count elements)
+ * vertex_positions should have float3 position in the first 12 bytes of each vertex
+ */
+MESHOPTIMIZER_API void meshopt_spatialSortTriangles(unsigned int* destination, const unsigned int* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride);
+
+/**
+ * Spatial clusterizer
+ * Reorders points into clusters optimized for spatial locality, and generates a new index buffer.
+ * Ensures the output can be split into cluster_size chunks where each chunk has good positional locality. Only the last chunk will be smaller than cluster_size.
+ *
+ * destination must contain enough space for the resulting index buffer (vertex_count elements)
+ * vertex_positions should have float3 position in the first 12 bytes of each vertex
+ */
+MESHOPTIMIZER_API void meshopt_spatialClusterPoints(unsigned int* destination, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, size_t cluster_size);
+
+/**
+ * Experimental: Opacity micromap generator (measure)
+ * Computes a subdivision level for each input triangle, as well as deduplicating the triangles that reference the same UVs to reduce rasterization requests.
+ * Returns the number of OMM entries.
+ *
+ * levels and sources must contain enough space for the worst case output (index_count/3 elements, one per resulting OMM entry)
+ * levels[i] will contain the subdivision level for entry i, with the total number of entries returned by the function; each entry should be rasterized from triangle index sources[i]
+ * omm_indices must contain enough space for the resulting OMM indices (index_count/3 elements, one per triangle)
+ * vertex_uvs should have float2 texture coordinate in the first 8 bytes of each vertex
+ * max_level specifies the maximum subdivision level (0..12)
+ * target_edge can be 0; when >0, triangle subdivision is adaptive and targets target_edge^2 texel area
+ */
+MESHOPTIMIZER_EXPERIMENTAL size_t meshopt_opacityMapMeasure(unsigned char* levels, unsigned int* sources, int* omm_indices, const unsigned int* indices, size_t index_count, const float* vertex_uvs, size_t vertex_count, size_t vertex_uvs_stride, unsigned int texture_width, unsigned int texture_height, int max_level, float target_edge);
+
+/**
+ * Experimental: Opacity micromap generator (rasterize)
+ * Rasterizes opacity state for a single triangle entry by sampling the alpha texture, using bilinear filtering and 0.5 alpha cutoff.
+ *
+ * result should contain enough space for the output opacity data (which can be computed using meshopt_opacityMapEntrySize)
+ * level specifies the subdivision level (0..12)
+ * states should be 2 for 2-state format (opaque/transparent) and 4 for 4-state format (opaque/transparent/unknown)
+ * uv0/uv1/uv2 should refer to a float2 texture coordinate for each triangle corner; note that micromap data is sensitive to the corner order
+ * texture_data should point to the alpha channel of the first pixel, encoded as UNORM8
+ * texture_stride specifies the distance in bytes between consecutive pixels, e.g. 4 for RGBA input
+ * texture_pitch specifies the distance in bytes between consecutive rows, e.g. 4*texture_width for tightly packed RGBA input
+ */
+MESHOPTIMIZER_EXPERIMENTAL void meshopt_opacityMapRasterize(unsigned char* result, int level, int states, const float* uv0, const float* uv1, const float* uv2, const unsigned char* texture_data, size_t texture_stride, size_t texture_pitch, unsigned int texture_width, unsigned int texture_height);
+MESHOPTIMIZER_EXPERIMENTAL size_t meshopt_opacityMapEntrySize(int level, int states);
+
+/**
+ * Experimental: Opacity micromap generator (compact)
+ * Compacts and deduplicates opacity data, merging identical micromap entries and replacing micromap states with special indices (-4..-1) when possible.
+ * Returns the number of OMM entries after compaction; the data array should be trimmed using the last offset/size.
+ *
+ * data should contain opacity data for all input/output entries
+ * levels should contain subdivision levels for all input/output entries
+ * offsets should contain offset into data[] for each entry
+ * levels[i] and offsets[i] will be updated with post-compaction level/offset for entry i, with the total number of entries returned by the function
+ * omm_indices should contain indices into the original OMM data, and will be updated with a new index or a special index (-4..-1) when possible
+ * states should be 2 for 2-state format (opaque/transparent) and 4 for 4-state format (opaque/transparent/unknown)
+ */
+MESHOPTIMIZER_EXPERIMENTAL size_t meshopt_opacityMapCompact(unsigned char* data, size_t data_size, unsigned char* levels, unsigned int* offsets, size_t omm_count, int* omm_indices, size_t triangle_count, int states);
+
+/**
+ * Tangent generation options
+ */
+enum
+{
+	/* Produce tangents compatible with MikkTSpace (same weighting and fallbacks) at the cost of reduced quality. Not recommended unless normal maps are baked. */
+	meshopt_TangentCompatible = 1 << 0,
+	/* Experimental: For vertices only connected to degenerate triangles, output zero tangents instead of an arbitrary fallback.  */
+	meshopt_TangentZeroFallback = 1 << 1,
+};
+
+/**
+ * Experimental: Tangent space generator
+ * Computes per-corner tangent vectors; for each corner, computes normalized tangent vector (xyz) and orientation (w, +/-1).
+ * Bitangent can be reconstructed via cross(normal, tangent.xyz) * tangent.w.
+ * To apply tangents to the mesh, either deindex and reindex it with the tangent stream, or copy tangents to existing vertex data while duplicating
+ * vertices with different tangent vectors (e.g. on UV mirror seams).
+ * Input can be indexed or unindexed (indices=NULL); this does not affect the resulting tangents, but indexed inputs are ~30% faster to process.
+ *
+ * result must contain enough space for the output tangent data (index_count*4 elements)
+ * indices can be NULL if the input is unindexed
+ * vertex_positions should have float3 position in the first 12 bytes of each vertex
+ * vertex_normals should have unit float3 normal in the first 12 bytes of each vertex
+ * vertex_uvs should have float2 texture coordinate in the first 8 bytes of each vertex
+ */
+MESHOPTIMIZER_EXPERIMENTAL void meshopt_generateTangents(float* result, const unsigned int* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, const float* vertex_normals, size_t vertex_normals_stride, const float* vertex_uvs, size_t vertex_uvs_stride, unsigned int options);
+
+/**
+ * Quantize a float into half-precision (as defined by IEEE-754 fp16) floating point value
+ * Generates +-inf for overflow, preserves NaN, flushes denormals to zero, rounds to nearest
+ * Representable magnitude range: [6e-5; 65504]
+ * Maximum relative reconstruction error: 5e-4
+ */
+MESHOPTIMIZER_API unsigned short meshopt_quantizeHalf(float v);
+
+/**
+ * Quantize a float into a floating point value with a limited number of significant mantissa bits, preserving the IEEE-754 fp32 binary representation
+ * Preserves infinities/NaN, flushes denormals to zero, rounds to nearest
+ * Assumes N is in a valid mantissa precision range, which is 1..23
+ */
+MESHOPTIMIZER_API float meshopt_quantizeFloat(float v, int N);
+
+/**
+ * Reverse quantization of a half-precision (as defined by IEEE-754 fp16) floating point value
+ * Preserves Inf/NaN, flushes denormals to zero
+ */
+MESHOPTIMIZER_API float meshopt_dequantizeHalf(unsigned short h);
+
+/**
+ * Experimental: Compute shared exponent suitable for mesh/cluster position quantization
+ * Given mesh or cluster bounds, compute a shared exponent that can be used to quantize any position inside the bounds to a 24-bit integer grid.
+ * The resulting output can be stored as a compact bit-stream to be decoded directly in shaders, or to be used as an input to RT BVH builders,
+ * for example via D3D12_VERTEX_FORMAT_COMPRESSED1 in DXR2 (max_bits=16).
+ *
+ * To quantize positions, compute:
+ *   scale = pow(2, exponent)
+ *   iv = int(round(v / scale))
+ * The resulting integer can be stored as signed 24-bit, or as an unsigned offset from a signed 24-bit anchor value, shared between all positions.
+ *
+ * minv/maxv specify the axis-aligned bounding box of the mesh or cluster; each should refer to a float3 value
+ * min_exp specifies the minimum value for the returned exponent, limiting precision to reduce size; e.g. min_exp = -10 will produce minimum error of 1mm given metric units
+ * max_bits specifies the maximum allowed number of bits for the quantized integer range (offset from anchor is an unsigned integer up to 2^max_bits-1)
+ */
+MESHOPTIMIZER_EXPERIMENTAL int meshopt_computePositionExponent(const float* minv, const float* maxv, int min_exp, int max_bits);
+
+/**
+ * Set allocation callbacks
+ * These callbacks will be used instead of the default operator new/operator delete for all temporary allocations in the library.
+ * Note that all algorithms only allocate memory for temporary use.
+ * allocate/deallocate are always called in a stack-like order - last pointer to be allocated is deallocated first.
+ * This function is not thread safe and must not be called concurrently with any other meshopt_ function.
+ *
+ * In shared library builds, allocations from templated index wrappers in this header will only be redirected if MESHOPTIMIZER_ALLOC_EXPORT is defined.
+ */
+MESHOPTIMIZER_API void meshopt_setAllocator(void* (MESHOPTIMIZER_ALLOC_CALLCONV* allocate)(size_t), void (MESHOPTIMIZER_ALLOC_CALLCONV* deallocate)(void*));
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+/* Quantization into fixed point normalized formats; these are only available as inline C++ functions */
+#ifdef __cplusplus
+/**
+ * Quantize a float in [0..1] range into an N-bit fixed point unorm value
+ * Assumes reconstruction function (q / (2^N-1)), which is the case for fixed-function normalized fixed point conversion
+ * Maximum reconstruction error: 1/2^(N+1)
+ */
+inline int meshopt_quantizeUnorm(float v, int N);
+
+/**
+ * Quantize a float in [-1..1] range into an N-bit fixed point snorm value
+ * Assumes reconstruction function (q / (2^(N-1)-1)), which is the case for fixed-function normalized fixed point conversion (except early OpenGL versions)
+ * Maximum reconstruction error: 1/2^N
+ */
+inline int meshopt_quantizeSnorm(float v, int N);
+#endif
+
+/**
+ * C++ template interface
+ *
+ * These functions mirror the C interface the library provides, providing template-based overloads so that
+ * the caller can use an arbitrary type for the index data, both for input and output.
+ * When the supplied type is the same size as that of unsigned int, the wrappers are zero-cost; when it's not,
+ * the wrappers end up allocating memory and copying index data to convert from one type to another.
+ */
+#if defined(__cplusplus) && !defined(MESHOPTIMIZER_NO_WRAPPERS)
+template <typename T>
+inline size_t meshopt_generateVertexRemap(unsigned int* destination, const T* indices, size_t index_count, const void* vertices, size_t vertex_count, size_t vertex_size);
+template <typename T>
+inline size_t meshopt_generateVertexRemapMulti(unsigned int* destination, const T* indices, size_t index_count, size_t vertex_count, const meshopt_Stream* streams, size_t stream_count);
+template <typename F>
+inline size_t meshopt_generateVertexRemapCustom(unsigned int* destination, const unsigned int* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, F callback);
+template <typename T, typename F>
+inline size_t meshopt_generateVertexRemapCustom(unsigned int* destination, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, F callback);
+template <typename T>
+inline void meshopt_remapIndexBuffer(T* destination, const T* indices, size_t index_count, const unsigned int* remap);
+template <typename T>
+inline size_t meshopt_filterIndexBuffer(T* destination, const T* indices, size_t index_count, const void* vertices, size_t vertex_count, size_t vertex_size, size_t vertex_stride);
+template <typename T>
+inline size_t meshopt_filterIndexBufferMulti(T* destination, const T* indices, size_t index_count, size_t vertex_count, const struct meshopt_Stream* streams, size_t stream_count);
+template <typename T>
+inline void meshopt_generateShadowIndexBuffer(T* destination, const T* indices, size_t index_count, const void* vertices, size_t vertex_count, size_t vertex_size, size_t vertex_stride);
+template <typename T>
+inline void meshopt_generateShadowIndexBufferMulti(T* destination, const T* indices, size_t index_count, size_t vertex_count, const meshopt_Stream* streams, size_t stream_count);
+template <typename T>
+inline void meshopt_generateAdjacencyIndexBuffer(T* destination, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride);
+template <typename T>
+inline void meshopt_generateTessellationIndexBuffer(T* destination, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride);
+template <typename T>
+inline size_t meshopt_generateProvokingIndexBuffer(T* destination, unsigned int* reorder, const T* indices, size_t index_count, size_t vertex_count);
+template <typename T>
+inline void meshopt_optimizeVertexCache(T* destination, const T* indices, size_t index_count, size_t vertex_count);
+template <typename T>
+inline void meshopt_optimizeVertexCacheStrip(T* destination, const T* indices, size_t index_count, size_t vertex_count);
+template <typename T>
+inline void meshopt_optimizeVertexCacheFifo(T* destination, const T* indices, size_t index_count, size_t vertex_count, unsigned int cache_size);
+template <typename T>
+inline void meshopt_optimizeOverdraw(T* destination, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, float threshold);
+template <typename T>
+inline size_t meshopt_optimizeVertexFetchRemap(unsigned int* destination, const T* indices, size_t index_count, size_t vertex_count);
+template <typename T>
+inline size_t meshopt_optimizeVertexFetch(void* destination, T* indices, size_t index_count, const void* vertices, size_t vertex_count, size_t vertex_size);
+template <typename T>
+inline size_t meshopt_encodeIndexBuffer(unsigned char* buffer, size_t buffer_size, const T* indices, size_t index_count);
+template <typename T>
+inline int meshopt_decodeIndexBuffer(T* destination, size_t index_count, const unsigned char* buffer, size_t buffer_size);
+template <typename T>
+inline size_t meshopt_encodeIndexSequence(unsigned char* buffer, size_t buffer_size, const T* indices, size_t index_count);
+template <typename T>
+inline int meshopt_decodeIndexSequence(T* destination, size_t index_count, const unsigned char* buffer, size_t buffer_size);
+template <typename V, typename T>
+inline int meshopt_decodeMeshlet(V* vertices, size_t vertex_count, T* triangles, size_t triangle_count, const unsigned char* buffer, size_t buffer_size);
+inline size_t meshopt_encodeVertexBufferLevel(unsigned char* buffer, size_t buffer_size, const void* vertices, size_t vertex_count, size_t vertex_size, int level);
+template <typename T>
+inline size_t meshopt_simplify(T* destination, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, size_t target_index_count, float target_error, unsigned int options = 0, float* result_error = NULL);
+template <typename T>
+inline size_t meshopt_simplifyWithAttributes(T* destination, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, const float* vertex_attributes, size_t vertex_attributes_stride, const float* attribute_weights, size_t attribute_count, const unsigned char* vertex_lock, size_t target_index_count, float target_error, unsigned int options = 0, float* result_error = NULL);
+template <typename T>
+inline size_t meshopt_simplifyWithUpdate(T* indices, size_t index_count, float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, float* vertex_attributes, size_t vertex_attributes_stride, const float* attribute_weights, size_t attribute_count, const unsigned char* vertex_lock, size_t target_index_count, float target_error, unsigned int options = 0, float* result_error = NULL);
+template <typename T>
+inline size_t meshopt_simplifySloppy(T* destination, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, size_t target_index_count, float target_error, float* result_error = NULL);
+template <typename T>
+inline size_t meshopt_simplifySloppy(T* destination, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, const unsigned char* vertex_lock, size_t target_index_count, float target_error, float* result_error = NULL);
+template <typename T>
+inline size_t meshopt_simplifyPrune(T* destination, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, float target_error);
+template <typename T>
+inline size_t meshopt_stripify(T* destination, const T* indices, size_t index_count, size_t vertex_count, T restart_index);
+template <typename T>
+inline size_t meshopt_unstripify(T* destination, const T* indices, size_t index_count, T restart_index);
+template <typename T>
+inline meshopt_VertexCacheStatistics meshopt_analyzeVertexCache(const T* indices, size_t index_count, size_t vertex_count, unsigned int cache_size, unsigned int warp_size, unsigned int primgroup_size);
+template <typename T>
+inline meshopt_VertexFetchStatistics meshopt_analyzeVertexFetch(const T* indices, size_t index_count, size_t vertex_count, size_t vertex_size);
+template <typename T>
+inline meshopt_OverdrawStatistics meshopt_analyzeOverdraw(const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride);
+template <typename T>
+inline meshopt_CoverageStatistics meshopt_analyzeCoverage(const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride);
+template <typename T>
+inline size_t meshopt_buildMeshlets(meshopt_Meshlet* meshlets, unsigned int* meshlet_vertices, unsigned char* meshlet_triangles, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, size_t max_vertices, size_t max_triangles, float cone_weight);
+template <typename T>
+inline size_t meshopt_buildMeshletsScan(meshopt_Meshlet* meshlets, unsigned int* meshlet_vertices, unsigned char* meshlet_triangles, const T* indices, size_t index_count, size_t vertex_count, size_t max_vertices, size_t max_triangles);
+template <typename T>
+inline size_t meshopt_buildMeshletsFlex(meshopt_Meshlet* meshlets, unsigned int* meshlet_vertices, unsigned char* meshlet_triangles, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, size_t max_vertices, size_t min_triangles, size_t max_triangles, float cone_weight, float split_factor);
+template <typename T>
+inline size_t meshopt_buildMeshletsSpatial(meshopt_Meshlet* meshlets, unsigned int* meshlet_vertices, unsigned char* meshlet_triangles, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, size_t max_vertices, size_t min_triangles, size_t max_triangles, float fill_weight);
+template <typename T>
+inline meshopt_Bounds meshopt_computeClusterBounds(const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride);
+template <typename T>
+inline size_t meshopt_partitionClusters(unsigned int* destination, const T* cluster_indices, size_t total_index_count, const unsigned int* cluster_index_counts, size_t cluster_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, size_t target_partition_size);
+template <typename T>
+inline void meshopt_spatialSortTriangles(T* destination, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride);
+template <typename T>
+inline void meshopt_generateTangents(float* result, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, const float* vertex_normals, size_t vertex_normals_stride, const float* vertex_uvs, size_t vertex_uvs_stride, unsigned int options = 0);
+#endif
+
+/* Inline implementation */
+#ifdef __cplusplus
+inline int meshopt_quantizeUnorm(float v, int N)
+{
+	const float scale = float((1 << N) - 1);
+
+	v = (v >= 0) ? v : 0;
+	v = (v <= 1) ? v : 1;
+
+	return int(v * scale + 0.5f);
+}
+
+inline int meshopt_quantizeSnorm(float v, int N)
+{
+	const float scale = float((1 << (N - 1)) - 1);
+
+	float round = (v >= 0 ? 0.5f : -0.5f);
+
+	v = (v >= -1) ? v : -1;
+	v = (v <= +1) ? v : +1;
+
+	return int(v * scale + round);
+}
+#endif
+
+/* Internal implementation helpers */
+#ifdef __cplusplus
+class meshopt_Allocator
+{
+public:
+	struct Storage
+	{
+		void* (MESHOPTIMIZER_ALLOC_CALLCONV* allocate)(size_t);
+		void (MESHOPTIMIZER_ALLOC_CALLCONV* deallocate)(void*);
+	};
+
+#ifdef MESHOPTIMIZER_ALLOC_EXPORT
+	MESHOPTIMIZER_API static Storage& storage();
+#else
+	static Storage& storage()
+	{
+		static Storage s = {::operator new, ::operator delete };
+		return s;
+	}
+#endif
+
+	meshopt_Allocator()
+	    : blocks()
+	    , count(0)
+	{
+	}
+
+	~meshopt_Allocator()
+	{
+		for (size_t i = count; i > 0; --i)
+			storage().deallocate(blocks[i - 1]);
+	}
+
+	template <typename T>
+	T* allocate(size_t size)
+	{
+		assert(count < sizeof(blocks) / sizeof(blocks[0]));
+		T* result = static_cast<T*>(storage().allocate(size > size_t(-1) / sizeof(T) ? size_t(-1) : size * sizeof(T)));
+		blocks[count++] = result;
+		return result;
+	}
+
+	void deallocate(void* ptr)
+	{
+		assert(count > 0 && blocks[count - 1] == ptr);
+		storage().deallocate(ptr);
+		count--;
+	}
+
+private:
+	void* blocks[24];
+	size_t count;
+};
+#endif
+
+/* Inline implementation for C++ templated wrappers */
+#if defined(__cplusplus) && !defined(MESHOPTIMIZER_NO_WRAPPERS)
+template <typename T, bool ZeroCopy = sizeof(T) == sizeof(unsigned int)>
+struct meshopt_IndexAdapter;
+
+template <typename T>
+struct meshopt_IndexAdapter<T, false>
+{
+	T* result;
+	unsigned int* data;
+	size_t count;
+
+	meshopt_IndexAdapter(T* result_, const T* input, size_t count_)
+	    : result(result_)
+	    , data(NULL)
+	    , count(count_)
+	{
+		size_t size = count > size_t(-1) / sizeof(unsigned int) ? size_t(-1) : count * sizeof(unsigned int);
+
+		data = static_cast<unsigned int*>(meshopt_Allocator::storage().allocate(size));
+
+		if (input)
+		{
+			for (size_t i = 0; i < count; ++i)
+				data[i] = input[i];
+		}
+	}
+
+	~meshopt_IndexAdapter()
+	{
+		if (result)
+		{
+			for (size_t i = 0; i < count; ++i)
+				result[i] = T(data[i]);
+		}
+
+		meshopt_Allocator::storage().deallocate(data);
+	}
+};
+
+template <typename T>
+struct meshopt_IndexAdapter<T, true>
+{
+	unsigned int* data;
+
+	meshopt_IndexAdapter(T* result, const T* input, size_t)
+	    : data(reinterpret_cast<unsigned int*>(result ? result : const_cast<T*>(input)))
+	{
+	}
+};
+
+template <typename T>
+inline size_t meshopt_generateVertexRemap(unsigned int* destination, const T* indices, size_t index_count, const void* vertices, size_t vertex_count, size_t vertex_size)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, indices ? index_count : 0);
+
+	return meshopt_generateVertexRemap(destination, indices ? in.data : NULL, index_count, vertices, vertex_count, vertex_size);
+}
+
+template <typename T>
+inline size_t meshopt_generateVertexRemapMulti(unsigned int* destination, const T* indices, size_t index_count, size_t vertex_count, const meshopt_Stream* streams, size_t stream_count)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, indices ? index_count : 0);
+
+	return meshopt_generateVertexRemapMulti(destination, indices ? in.data : NULL, index_count, vertex_count, streams, stream_count);
+}
+
+template <typename F>
+inline size_t meshopt_generateVertexRemapCustom(unsigned int* destination, const unsigned int* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, F callback)
+{
+	struct Call
+	{
+		static int compare(void* context, unsigned int lhs, unsigned int rhs) { return (*static_cast<F*>(context))(lhs, rhs) ? 1 : 0; }
+	};
+
+	return meshopt_generateVertexRemapCustom(destination, indices, index_count, vertex_positions, vertex_count, vertex_positions_stride, &Call::compare, &callback);
+}
+
+template <typename T, typename F>
+inline size_t meshopt_generateVertexRemapCustom(unsigned int* destination, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, F callback)
+{
+	struct Call
+	{
+		static int compare(void* context, unsigned int lhs, unsigned int rhs) { return (*static_cast<F*>(context))(lhs, rhs) ? 1 : 0; }
+	};
+
+	meshopt_IndexAdapter<T> in(NULL, indices, indices ? index_count : 0);
+
+	return meshopt_generateVertexRemapCustom(destination, indices ? in.data : NULL, index_count, vertex_positions, vertex_count, vertex_positions_stride, &Call::compare, &callback);
+}
+
+template <typename T>
+inline void meshopt_remapIndexBuffer(T* destination, const T* indices, size_t index_count, const unsigned int* remap)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, indices ? index_count : 0);
+	meshopt_IndexAdapter<T> out(destination, NULL, index_count);
+
+	meshopt_remapIndexBuffer(out.data, indices ? in.data : NULL, index_count, remap);
+}
+
+template <typename T>
+inline size_t meshopt_filterIndexBuffer(T* destination, const T* indices, size_t index_count, const void* vertices, size_t vertex_count, size_t vertex_size, size_t vertex_stride)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+	meshopt_IndexAdapter<T> out(destination, NULL, index_count);
+
+	return meshopt_filterIndexBuffer(out.data, in.data, index_count, vertices, vertex_count, vertex_size, vertex_stride);
+}
+
+template <typename T>
+inline size_t meshopt_filterIndexBufferMulti(T* destination, const T* indices, size_t index_count, size_t vertex_count, const struct meshopt_Stream* streams, size_t stream_count)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+	meshopt_IndexAdapter<T> out(destination, NULL, index_count);
+
+	return meshopt_filterIndexBufferMulti(out.data, in.data, index_count, vertex_count, streams, stream_count);
+}
+
+template <typename T>
+inline void meshopt_generateShadowIndexBuffer(T* destination, const T* indices, size_t index_count, const void* vertices, size_t vertex_count, size_t vertex_size, size_t vertex_stride)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+	meshopt_IndexAdapter<T> out(destination, NULL, index_count);
+
+	meshopt_generateShadowIndexBuffer(out.data, in.data, index_count, vertices, vertex_count, vertex_size, vertex_stride);
+}
+
+template <typename T>
+inline void meshopt_generateShadowIndexBufferMulti(T* destination, const T* indices, size_t index_count, size_t vertex_count, const meshopt_Stream* streams, size_t stream_count)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+	meshopt_IndexAdapter<T> out(destination, NULL, index_count);
+
+	meshopt_generateShadowIndexBufferMulti(out.data, in.data, index_count, vertex_count, streams, stream_count);
+}
+
+template <typename T>
+inline void meshopt_generateAdjacencyIndexBuffer(T* destination, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+	meshopt_IndexAdapter<T> out(destination, NULL, index_count * 2);
+
+	meshopt_generateAdjacencyIndexBuffer(out.data, in.data, index_count, vertex_positions, vertex_count, vertex_positions_stride);
+}
+
+template <typename T>
+inline void meshopt_generateTessellationIndexBuffer(T* destination, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+	meshopt_IndexAdapter<T> out(destination, NULL, index_count * 4);
+
+	meshopt_generateTessellationIndexBuffer(out.data, in.data, index_count, vertex_positions, vertex_count, vertex_positions_stride);
+}
+
+template <typename T>
+inline size_t meshopt_generateProvokingIndexBuffer(T* destination, unsigned int* reorder, const T* indices, size_t index_count, size_t vertex_count)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+	meshopt_IndexAdapter<T> out(destination, NULL, index_count);
+
+	size_t bound = vertex_count + (index_count / 3);
+	assert(bound == 0 || size_t(T(bound - 1)) == bound - 1); // bound - 1 must fit in T
+	(void)bound;
+
+	return meshopt_generateProvokingIndexBuffer(out.data, reorder, in.data, index_count, vertex_count);
+}
+
+template <typename T>
+inline void meshopt_optimizeVertexCache(T* destination, const T* indices, size_t index_count, size_t vertex_count)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+	meshopt_IndexAdapter<T> out(destination, NULL, index_count);
+
+	meshopt_optimizeVertexCache(out.data, in.data, index_count, vertex_count);
+}
+
+template <typename T>
+inline void meshopt_optimizeVertexCacheStrip(T* destination, const T* indices, size_t index_count, size_t vertex_count)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+	meshopt_IndexAdapter<T> out(destination, NULL, index_count);
+
+	meshopt_optimizeVertexCacheStrip(out.data, in.data, index_count, vertex_count);
+}
+
+template <typename T>
+inline void meshopt_optimizeVertexCacheFifo(T* destination, const T* indices, size_t index_count, size_t vertex_count, unsigned int cache_size)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+	meshopt_IndexAdapter<T> out(destination, NULL, index_count);
+
+	meshopt_optimizeVertexCacheFifo(out.data, in.data, index_count, vertex_count, cache_size);
+}
+
+template <typename T>
+inline void meshopt_optimizeOverdraw(T* destination, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, float threshold)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+	meshopt_IndexAdapter<T> out(destination, NULL, index_count);
+
+	meshopt_optimizeOverdraw(out.data, in.data, index_count, vertex_positions, vertex_count, vertex_positions_stride, threshold);
+}
+
+template <typename T>
+inline size_t meshopt_optimizeVertexFetchRemap(unsigned int* destination, const T* indices, size_t index_count, size_t vertex_count)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+
+	return meshopt_optimizeVertexFetchRemap(destination, in.data, index_count, vertex_count);
+}
+
+template <typename T>
+inline size_t meshopt_optimizeVertexFetch(void* destination, T* indices, size_t index_count, const void* vertices, size_t vertex_count, size_t vertex_size)
+{
+	meshopt_IndexAdapter<T> inout(indices, indices, index_count);
+
+	return meshopt_optimizeVertexFetch(destination, inout.data, index_count, vertices, vertex_count, vertex_size);
+}
+
+template <typename T>
+inline size_t meshopt_encodeIndexBuffer(unsigned char* buffer, size_t buffer_size, const T* indices, size_t index_count)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+
+	return meshopt_encodeIndexBuffer(buffer, buffer_size, in.data, index_count);
+}
+
+template <typename T>
+inline int meshopt_decodeIndexBuffer(T* destination, size_t index_count, const unsigned char* buffer, size_t buffer_size)
+{
+	char index_size_valid[sizeof(T) == 2 || sizeof(T) == 4 ? 1 : -1];
+	(void)index_size_valid;
+
+	return meshopt_decodeIndexBuffer(destination, index_count, sizeof(T), buffer, buffer_size);
+}
+
+template <typename T>
+inline size_t meshopt_encodeIndexSequence(unsigned char* buffer, size_t buffer_size, const T* indices, size_t index_count)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+
+	return meshopt_encodeIndexSequence(buffer, buffer_size, in.data, index_count);
+}
+
+template <typename T>
+inline int meshopt_decodeIndexSequence(T* destination, size_t index_count, const unsigned char* buffer, size_t buffer_size)
+{
+	char index_size_valid[sizeof(T) == 2 || sizeof(T) == 4 ? 1 : -1];
+	(void)index_size_valid;
+
+	return meshopt_decodeIndexSequence(destination, index_count, sizeof(T), buffer, buffer_size);
+}
+
+template <typename V, typename T>
+inline int meshopt_decodeMeshlet(V* vertices, size_t vertex_count, T* triangles, size_t triangle_count, const unsigned char* buffer, size_t buffer_size)
+{
+	char types_valid[(sizeof(V) == 2 || sizeof(V) == 4) && (sizeof(T) == 1 || sizeof(T) == 4) ? 1 : -1];
+	(void)types_valid;
+
+	return meshopt_decodeMeshlet(vertices, vertex_count, sizeof(V), triangles, triangle_count, sizeof(T) == 1 ? 3 : 4, buffer, buffer_size);
+}
+
+inline size_t meshopt_encodeVertexBufferLevel(unsigned char* buffer, size_t buffer_size, const void* vertices, size_t vertex_count, size_t vertex_size, int level)
+{
+	return meshopt_encodeVertexBufferLevel(buffer, buffer_size, vertices, vertex_count, vertex_size, level, -1);
+}
+
+template <typename T>
+inline size_t meshopt_simplify(T* destination, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, size_t target_index_count, float target_error, unsigned int options, float* result_error)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+	meshopt_IndexAdapter<T> out(destination, NULL, index_count);
+
+	return meshopt_simplify(out.data, in.data, index_count, vertex_positions, vertex_count, vertex_positions_stride, target_index_count, target_error, options, result_error);
+}
+
+template <typename T>
+inline size_t meshopt_simplifyWithAttributes(T* destination, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, const float* vertex_attributes, size_t vertex_attributes_stride, const float* attribute_weights, size_t attribute_count, const unsigned char* vertex_lock, size_t target_index_count, float target_error, unsigned int options, float* result_error)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+	meshopt_IndexAdapter<T> out(destination, NULL, index_count);
+
+	return meshopt_simplifyWithAttributes(out.data, in.data, index_count, vertex_positions, vertex_count, vertex_positions_stride, vertex_attributes, vertex_attributes_stride, attribute_weights, attribute_count, vertex_lock, target_index_count, target_error, options, result_error);
+}
+
+template <typename T>
+inline size_t meshopt_simplifyWithUpdate(T* indices, size_t index_count, float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, float* vertex_attributes, size_t vertex_attributes_stride, const float* attribute_weights, size_t attribute_count, const unsigned char* vertex_lock, size_t target_index_count, float target_error, unsigned int options, float* result_error)
+{
+	meshopt_IndexAdapter<T> inout(indices, indices, index_count);
+
+	return meshopt_simplifyWithUpdate(inout.data, index_count, vertex_positions, vertex_count, vertex_positions_stride, vertex_attributes, vertex_attributes_stride, attribute_weights, attribute_count, vertex_lock, target_index_count, target_error, options, result_error);
+}
+
+template <typename T>
+inline size_t meshopt_simplifySloppy(T* destination, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, size_t target_index_count, float target_error, float* result_error)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+	meshopt_IndexAdapter<T> out(destination, NULL, index_count);
+
+	return meshopt_simplifySloppy(out.data, in.data, index_count, vertex_positions, vertex_count, vertex_positions_stride, NULL, target_index_count, target_error, result_error);
+}
+
+template <typename T>
+inline size_t meshopt_simplifySloppy(T* destination, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, const unsigned char* vertex_lock, size_t target_index_count, float target_error, float* result_error)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+	meshopt_IndexAdapter<T> out(destination, NULL, index_count);
+
+	return meshopt_simplifySloppy(out.data, in.data, index_count, vertex_positions, vertex_count, vertex_positions_stride, vertex_lock, target_index_count, target_error, result_error);
+}
+
+template <typename T>
+inline size_t meshopt_simplifyPrune(T* destination, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, float target_error)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+	meshopt_IndexAdapter<T> out(destination, NULL, index_count);
+
+	return meshopt_simplifyPrune(out.data, in.data, index_count, vertex_positions, vertex_count, vertex_positions_stride, target_error);
+}
+
+template <typename T>
+inline size_t meshopt_stripify(T* destination, const T* indices, size_t index_count, size_t vertex_count, T restart_index)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+	meshopt_IndexAdapter<T> out(destination, NULL, (index_count / 3) * 5);
+
+	return meshopt_stripify(out.data, in.data, index_count, vertex_count, unsigned(restart_index));
+}
+
+template <typename T>
+inline size_t meshopt_unstripify(T* destination, const T* indices, size_t index_count, T restart_index)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+	meshopt_IndexAdapter<T> out(destination, NULL, index_count == 0 ? 0 : (index_count - 2) * 3);
+
+	return meshopt_unstripify(out.data, in.data, index_count, unsigned(restart_index));
+}
+
+template <typename T>
+inline meshopt_VertexCacheStatistics meshopt_analyzeVertexCache(const T* indices, size_t index_count, size_t vertex_count, unsigned int cache_size, unsigned int warp_size, unsigned int primgroup_size)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+
+	return meshopt_analyzeVertexCache(in.data, index_count, vertex_count, cache_size, warp_size, primgroup_size);
+}
+
+template <typename T>
+inline meshopt_VertexFetchStatistics meshopt_analyzeVertexFetch(const T* indices, size_t index_count, size_t vertex_count, size_t vertex_size)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+
+	return meshopt_analyzeVertexFetch(in.data, index_count, vertex_count, vertex_size);
+}
+
+template <typename T>
+inline meshopt_OverdrawStatistics meshopt_analyzeOverdraw(const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+
+	return meshopt_analyzeOverdraw(in.data, index_count, vertex_positions, vertex_count, vertex_positions_stride);
+}
+
+template <typename T>
+inline meshopt_CoverageStatistics meshopt_analyzeCoverage(const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+
+	return meshopt_analyzeCoverage(in.data, index_count, vertex_positions, vertex_count, vertex_positions_stride);
+}
+
+template <typename T>
+inline size_t meshopt_buildMeshlets(meshopt_Meshlet* meshlets, unsigned int* meshlet_vertices, unsigned char* meshlet_triangles, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, size_t max_vertices, size_t max_triangles, float cone_weight)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+
+	return meshopt_buildMeshlets(meshlets, meshlet_vertices, meshlet_triangles, in.data, index_count, vertex_positions, vertex_count, vertex_positions_stride, max_vertices, max_triangles, cone_weight);
+}
+
+template <typename T>
+inline size_t meshopt_buildMeshletsScan(meshopt_Meshlet* meshlets, unsigned int* meshlet_vertices, unsigned char* meshlet_triangles, const T* indices, size_t index_count, size_t vertex_count, size_t max_vertices, size_t max_triangles)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+
+	return meshopt_buildMeshletsScan(meshlets, meshlet_vertices, meshlet_triangles, in.data, index_count, vertex_count, max_vertices, max_triangles);
+}
+
+template <typename T>
+inline size_t meshopt_buildMeshletsFlex(meshopt_Meshlet* meshlets, unsigned int* meshlet_vertices, unsigned char* meshlet_triangles, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, size_t max_vertices, size_t min_triangles, size_t max_triangles, float cone_weight, float split_factor)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+
+	return meshopt_buildMeshletsFlex(meshlets, meshlet_vertices, meshlet_triangles, in.data, index_count, vertex_positions, vertex_count, vertex_positions_stride, max_vertices, min_triangles, max_triangles, cone_weight, split_factor);
+}
+
+template <typename T>
+inline size_t meshopt_buildMeshletsSpatial(meshopt_Meshlet* meshlets, unsigned int* meshlet_vertices, unsigned char* meshlet_triangles, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, size_t max_vertices, size_t min_triangles, size_t max_triangles, float fill_weight)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+
+	return meshopt_buildMeshletsSpatial(meshlets, meshlet_vertices, meshlet_triangles, in.data, index_count, vertex_positions, vertex_count, vertex_positions_stride, max_vertices, min_triangles, max_triangles, fill_weight);
+}
+
+template <typename T>
+inline meshopt_Bounds meshopt_computeClusterBounds(const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+
+	return meshopt_computeClusterBounds(in.data, index_count, vertex_positions, vertex_count, vertex_positions_stride);
+}
+
+template <typename T>
+inline size_t meshopt_partitionClusters(unsigned int* destination, const T* cluster_indices, size_t total_index_count, const unsigned int* cluster_index_counts, size_t cluster_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, size_t target_partition_size)
+{
+	meshopt_IndexAdapter<T> in(NULL, cluster_indices, total_index_count);
+
+	return meshopt_partitionClusters(destination, in.data, total_index_count, cluster_index_counts, cluster_count, vertex_positions, vertex_count, vertex_positions_stride, target_partition_size);
+}
+
+template <typename T>
+inline void meshopt_spatialSortTriangles(T* destination, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, index_count);
+	meshopt_IndexAdapter<T> out(destination, NULL, index_count);
+
+	meshopt_spatialSortTriangles(out.data, in.data, index_count, vertex_positions, vertex_count, vertex_positions_stride);
+}
+
+template <typename T>
+inline void meshopt_generateTangents(float* result, const T* indices, size_t index_count, const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride, const float* vertex_normals, size_t vertex_normals_stride, const float* vertex_uvs, size_t vertex_uvs_stride, unsigned int options)
+{
+	meshopt_IndexAdapter<T> in(NULL, indices, indices ? index_count : 0);
+
+	meshopt_generateTangents(result, indices ? in.data : NULL, index_count, vertex_positions, vertex_count, vertex_positions_stride, vertex_normals, vertex_normals_stride, vertex_uvs, vertex_uvs_stride, options);
+}
+#endif
+
+/**
+ * Copyright (c) 2016-2026 Arseny Kapoulkine
+ *
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation
+ * files (the "Software"), to deal in the Software without
+ * restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following
+ * conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+ * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+ * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+ * OTHER DEALINGS IN THE SOFTWARE.
+ */
diff --git a/third_party/meshoptimizer/simplifier.cpp b/third_party/meshoptimizer/simplifier.cpp
new file mode 100644
index 0000000..5102b21
--- /dev/null
+++ b/third_party/meshoptimizer/simplifier.cpp
@@ -0,0 +1,2948 @@
+// This file is part of meshoptimizer library; see meshoptimizer.h for version/license details
+#include "meshoptimizer.h"
+
+#include <assert.h>
+#include <float.h>
+#include <math.h>
+#include <string.h>
+
+#ifndef TRACE
+#define TRACE 0
+#endif
+
+#if TRACE
+#include <stdio.h>
+#endif
+
+#if TRACE
+#define TRACESTATS(i) stats[i]++;
+#else
+#define TRACESTATS(i) (void)0
+#endif
+
+// This work is based on:
+// Michael Garland and Paul S. Heckbert. Surface simplification using quadric error metrics. 1997
+// Michael Garland. Quadric-based polygonal surface simplification. 1999
+// Peter Lindstrom. Out-of-Core Simplification of Large Polygonal Models. 2000
+// Matthias Teschner, Bruno Heidelberger, Matthias Mueller, Danat Pomeranets, Markus Gross. Optimized Spatial Hashing for Collision Detection of Deformable Objects. 2003
+// Peter Van Sandt, Yannis Chronis, Jignesh M. Patel. Efficiently Searching In-Memory Sorted Arrays: Revenge of the Interpolation Search? 2019
+// Hugues Hoppe. New Quadric Metric for Simplifying Meshes with Appearance Attributes. 1999
+// Hugues Hoppe, Steve Marschner. Efficient Minimization of New Quadric Metric for Simplifying Meshes with Appearance Attributes. 2000
+namespace meshopt
+{
+
+struct EdgeAdjacency
+{
+	struct Edge
+	{
+		unsigned int next;
+		unsigned int prev;
+	};
+
+	unsigned int* offsets;
+	Edge* data;
+};
+
+static void prepareEdgeAdjacency(EdgeAdjacency& adjacency, size_t index_count, size_t vertex_count, meshopt_Allocator& allocator)
+{
+	adjacency.offsets = allocator.allocate<unsigned int>(vertex_count + 1);
+	adjacency.data = allocator.allocate<EdgeAdjacency::Edge>(index_count);
+}
+
+static void updateEdgeAdjacency(EdgeAdjacency& adjacency, const unsigned int* indices, size_t index_count, size_t vertex_count, const unsigned int* remap)
+{
+	size_t face_count = index_count / 3;
+	unsigned int* offsets = adjacency.offsets + 1;
+	EdgeAdjacency::Edge* data = adjacency.data;
+
+	// fill edge counts
+	memset(offsets, 0, vertex_count * sizeof(unsigned int));
+
+	for (size_t i = 0; i < index_count; ++i)
+	{
+		unsigned int v = remap ? remap[indices[i]] : indices[i];
+		assert(v < vertex_count);
+
+		offsets[v]++;
+	}
+
+	// fill offset table
+	unsigned int offset = 0;
+
+	for (size_t i = 0; i < vertex_count; ++i)
+	{
+		unsigned int count = offsets[i];
+		offsets[i] = offset;
+		offset += count;
+	}
+
+	assert(offset == index_count);
+
+	// fill edge data
+	for (size_t i = 0; i < face_count; ++i)
+	{
+		unsigned int a = indices[i * 3 + 0], b = indices[i * 3 + 1], c = indices[i * 3 + 2];
+
+		if (remap)
+		{
+			a = remap[a];
+			b = remap[b];
+			c = remap[c];
+		}
+
+		data[offsets[a]].next = b;
+		data[offsets[a]].prev = c;
+		offsets[a]++;
+
+		data[offsets[b]].next = c;
+		data[offsets[b]].prev = a;
+		offsets[b]++;
+
+		data[offsets[c]].next = a;
+		data[offsets[c]].prev = b;
+		offsets[c]++;
+	}
+
+	// finalize offsets
+	adjacency.offsets[0] = 0;
+	assert(adjacency.offsets[vertex_count] == index_count);
+}
+
+struct PositionHasher
+{
+	const float* vertex_positions;
+	size_t vertex_stride_float;
+	const unsigned int* sparse_remap;
+
+	size_t hash(unsigned int index) const
+	{
+		unsigned int ri = sparse_remap ? sparse_remap[index] : index;
+		const unsigned int* key = reinterpret_cast<const unsigned int*>(vertex_positions + ri * vertex_stride_float);
+
+		unsigned int x = key[0], y = key[1], z = key[2];
+
+		// replace negative zero with zero
+		x = (x == 0x80000000) ? 0 : x;
+		y = (y == 0x80000000) ? 0 : y;
+		z = (z == 0x80000000) ? 0 : z;
+
+		// scramble bits to make sure that integer coordinates have entropy in lower bits
+		x ^= x >> 17;
+		y ^= y >> 17;
+		z ^= z >> 17;
+
+		// Optimized Spatial Hashing for Collision Detection of Deformable Objects
+		return (x * 73856093) ^ (y * 19349663) ^ (z * 83492791);
+	}
+
+	bool equal(unsigned int lhs, unsigned int rhs) const
+	{
+		unsigned int li = sparse_remap ? sparse_remap[lhs] : lhs;
+		unsigned int ri = sparse_remap ? sparse_remap[rhs] : rhs;
+
+		const float* lv = vertex_positions + li * vertex_stride_float;
+		const float* rv = vertex_positions + ri * vertex_stride_float;
+
+		return lv[0] == rv[0] && lv[1] == rv[1] && lv[2] == rv[2];
+	}
+};
+
+struct RemapHasher
+{
+	unsigned int* remap;
+
+	size_t hash(unsigned int id) const
+	{
+		return id * 0x5bd1e995;
+	}
+
+	bool equal(unsigned int lhs, unsigned int rhs) const
+	{
+		return remap[lhs] == rhs;
+	}
+};
+
+static size_t hashBuckets2(size_t count)
+{
+	size_t buckets = 1;
+	while (buckets < count + count / 4)
+		buckets *= 2;
+
+	return buckets;
+}
+
+template <typename T, typename Hash>
+static T* hashLookup2(T* table, size_t buckets, const Hash& hash, const T& key, const T& empty)
+{
+	assert(buckets > 0);
+	assert((buckets & (buckets - 1)) == 0);
+
+	size_t hashmod = buckets - 1;
+	size_t bucket = hash.hash(key) & hashmod;
+
+	for (size_t probe = 0; probe <= hashmod; ++probe)
+	{
+		T& item = table[bucket];
+
+		if (item == empty)
+			return &item;
+
+		if (hash.equal(item, key))
+			return &item;
+
+		// hash collision, quadratic probing
+		bucket = (bucket + probe + 1) & hashmod;
+	}
+
+	assert(false && "Hash table is full"); // unreachable
+	return NULL;
+}
+
+static void buildPositionRemap(unsigned int* remap, unsigned int* wedge, const float* vertex_positions_data, size_t vertex_count, size_t vertex_positions_stride, const unsigned int* sparse_remap, meshopt_Allocator& allocator)
+{
+	PositionHasher hasher = {vertex_positions_data, vertex_positions_stride / sizeof(float), sparse_remap};
+
+	size_t table_size = hashBuckets2(vertex_count);
+	unsigned int* table = allocator.allocate<unsigned int>(table_size);
+	memset(table, -1, table_size * sizeof(unsigned int));
+
+	// build forward remap: for each vertex, which other (canonical) vertex does it map to?
+	// we use position equivalence for this, and remap vertices to other existing vertices
+	for (size_t i = 0; i < vertex_count; ++i)
+	{
+		unsigned int index = unsigned(i);
+		unsigned int* entry = hashLookup2(table, table_size, hasher, index, ~0u);
+
+		if (*entry == ~0u)
+			*entry = index;
+
+		remap[index] = *entry;
+	}
+
+	allocator.deallocate(table);
+
+	if (!wedge)
+		return;
+
+	// build wedge table: for each vertex, which other vertex is the next wedge that also maps to the same vertex?
+	// entries in table form a (cyclic) wedge loop per vertex; for manifold vertices, wedge[i] == remap[i] == i
+	for (size_t i = 0; i < vertex_count; ++i)
+		wedge[i] = unsigned(i);
+
+	for (size_t i = 0; i < vertex_count; ++i)
+		if (remap[i] != i)
+		{
+			unsigned int r = remap[i];
+
+			wedge[i] = wedge[r];
+			wedge[r] = unsigned(i);
+		}
+}
+
+static unsigned int* buildSparseRemap(unsigned int* indices, size_t index_count, size_t vertex_count, size_t* out_vertex_count, meshopt_Allocator& allocator)
+{
+	// use a bit set to compute the precise number of unique vertices
+	unsigned char* filter = allocator.allocate<unsigned char>((vertex_count + 7) / 8);
+
+	for (size_t i = 0; i < index_count; ++i)
+	{
+		unsigned int index = indices[i];
+		assert(index < vertex_count);
+		filter[index / 8] = 0;
+	}
+
+	size_t unique = 0;
+	for (size_t i = 0; i < index_count; ++i)
+	{
+		unsigned int index = indices[i];
+		unique += (filter[index / 8] & (1 << (index % 8))) == 0;
+		filter[index / 8] |= 1 << (index % 8);
+	}
+
+	unsigned int* remap = allocator.allocate<unsigned int>(unique);
+	size_t offset = 0;
+
+	// temporary map dense => sparse; we allocate it last so that we can deallocate it
+	size_t revremap_size = hashBuckets2(unique);
+	unsigned int* revremap = allocator.allocate<unsigned int>(revremap_size);
+	memset(revremap, -1, revremap_size * sizeof(unsigned int));
+
+	// fill remap, using revremap as a helper, and rewrite indices in the same pass
+	RemapHasher hasher = {remap};
+
+	for (size_t i = 0; i < index_count; ++i)
+	{
+		unsigned int index = indices[i];
+		unsigned int* entry = hashLookup2(revremap, revremap_size, hasher, index, ~0u);
+
+		if (*entry == ~0u)
+		{
+			remap[offset] = index;
+			*entry = unsigned(offset);
+			offset++;
+		}
+
+		indices[i] = *entry;
+	}
+
+	allocator.deallocate(revremap);
+
+	assert(offset == unique);
+	*out_vertex_count = unique;
+
+	return remap;
+}
+
+enum VertexKind
+{
+	Kind_Manifold, // not on an attribute seam, not on any boundary
+	Kind_Border,   // not on an attribute seam, has exactly two open edges
+	Kind_Seam,     // on an attribute seam with exactly two attribute seam edges
+	Kind_Complex,  // none of the above; these vertices can move as long as all wedges move to the target vertex
+	Kind_Locked,   // none of the above; these vertices can't move
+
+	Kind_Count
+};
+
+// manifold vertices can collapse onto anything
+// border/seam vertices can collapse onto border/seam respectively, or locked
+// complex vertices can collapse onto complex/locked
+// a rule of thumb is that collapsing kind A into kind B preserves the kind B in the target vertex
+// for example, while we could collapse Complex into Manifold, this would mean the target vertex isn't Manifold anymore
+const unsigned char kCanCollapse[Kind_Count][Kind_Count] = {
+    {1, 1, 1, 1, 1},
+    {0, 1, 0, 0, 1},
+    {0, 0, 1, 0, 1},
+    {0, 0, 0, 1, 1},
+    {0, 0, 0, 0, 0},
+};
+
+// if a vertex is manifold or seam, adjoining edges are guaranteed to have an opposite edge
+// note that for seam edges, the opposite edge isn't present in the attribute-based topology
+// but is present if you consider a position-only mesh variant
+// while many complex collapses have the opposite edge, since complex vertices collapse to the
+// same wedge, keeping opposite edges separate improves the quality by considering both targets
+const unsigned char kHasOpposite[Kind_Count][Kind_Count] = {
+    {1, 1, 1, 1, 1},
+    {1, 0, 1, 0, 0},
+    {1, 1, 1, 0, 1},
+    {1, 0, 0, 0, 0},
+    {1, 0, 1, 0, 0},
+};
+
+static bool hasEdge(const EdgeAdjacency& adjacency, unsigned int a, unsigned int b)
+{
+	unsigned int count = adjacency.offsets[a + 1] - adjacency.offsets[a];
+	const EdgeAdjacency::Edge* edges = adjacency.data + adjacency.offsets[a];
+
+	for (size_t i = 0; i < count; ++i)
+		if (edges[i].next == b)
+			return true;
+
+	return false;
+}
+
+static bool hasEdge(const EdgeAdjacency& adjacency, unsigned int a, unsigned int b, const unsigned int* remap, const unsigned int* wedge)
+{
+	unsigned int v = a;
+
+	do
+	{
+		unsigned int count = adjacency.offsets[v + 1] - adjacency.offsets[v];
+		const EdgeAdjacency::Edge* edges = adjacency.data + adjacency.offsets[v];
+
+		for (size_t i = 0; i < count; ++i)
+			if (remap[edges[i].next] == remap[b])
+				return true;
+
+		v = wedge[v];
+	} while (v != a);
+
+	return false;
+}
+
+static void classifyVertices(unsigned char* result, unsigned int* loop, unsigned int* loopback, size_t vertex_count, const EdgeAdjacency& adjacency, const unsigned int* remap, const unsigned int* wedge, const unsigned char* vertex_lock, const unsigned int* sparse_remap, unsigned int options)
+{
+	memset(loop, -1, vertex_count * sizeof(unsigned int));
+	memset(loopback, -1, vertex_count * sizeof(unsigned int));
+
+	// incoming & outgoing open edges: ~0u if no open edges, i if there are more than 1
+	// note that this is the same data as required in loop[] arrays; loop[] data is only used for border/seam by default
+	// in permissive mode we also use it to guide complex-complex collapses, so we fill it for all vertices
+	unsigned int* openinc = loopback;
+	unsigned int* openout = loop;
+
+	for (size_t i = 0; i < vertex_count; ++i)
+	{
+		unsigned int vertex = unsigned(i);
+
+		unsigned int count = adjacency.offsets[vertex + 1] - adjacency.offsets[vertex];
+		const EdgeAdjacency::Edge* edges = adjacency.data + adjacency.offsets[vertex];
+
+		for (size_t j = 0; j < count; ++j)
+		{
+			unsigned int target = edges[j].next;
+
+			if (target == vertex)
+			{
+				// degenerate triangles have two distinct edges instead of three, and the self edge
+				// is bi-directional by definition; this can break border/seam classification by "closing"
+				// the open edge from another triangle and falsely marking the vertex as manifold
+				// instead we mark the vertex as having >1 open edges which turns it into locked/complex
+				openinc[vertex] = openout[vertex] = vertex;
+			}
+			else if (!hasEdge(adjacency, target, vertex))
+			{
+				openinc[target] = (openinc[target] == ~0u) ? vertex : target;
+				openout[vertex] = (openout[vertex] == ~0u) ? target : vertex;
+			}
+		}
+	}
+
+#if TRACE
+	size_t stats[4] = {};
+#endif
+
+	for (size_t i = 0; i < vertex_count; ++i)
+	{
+		if (remap[i] == i)
+		{
+			if (wedge[i] == i)
+			{
+				// no attribute seam, need to check if it's manifold
+				unsigned int openi = openinc[i], openo = openout[i];
+
+				// note: we classify any vertices with no open edges as manifold
+				// this is technically incorrect - if 4 triangles share an edge, we'll classify vertices as manifold
+				// it's unclear if this is a problem in practice
+				if (openi == ~0u && openo == ~0u)
+				{
+					result[i] = Kind_Manifold;
+				}
+				else if (openi != ~0u && openo != ~0u && remap[openi] == remap[openo] && openi != i)
+				{
+					// classify half-seams as seams (the branch below would mis-classify them as borders)
+					// half-seam is a single vertex that connects to both vertices of a potential seam
+					// treating these as seams allows collapsing the "full" seam vertex onto them
+					result[i] = Kind_Seam;
+				}
+				else if (openi != i && openo != i)
+				{
+					result[i] = Kind_Border;
+				}
+				else
+				{
+					result[i] = Kind_Locked;
+					TRACESTATS(0);
+				}
+			}
+			else if (wedge[wedge[i]] == i)
+			{
+				// attribute seam; need to distinguish between Seam and Locked
+				unsigned int w = wedge[i];
+				unsigned int openiv = openinc[i], openov = openout[i];
+				unsigned int openiw = openinc[w], openow = openout[w];
+
+				// seam should have one open half-edge for each vertex, and the edges need to "connect" - point to the same vertex post-remap
+				if (openiv != ~0u && openiv != i && openov != ~0u && openov != i &&
+				    openiw != ~0u && openiw != w && openow != ~0u && openow != w)
+				{
+					if (remap[openiv] == remap[openow] && remap[openov] == remap[openiw] && remap[openiv] != remap[openov])
+					{
+						result[i] = Kind_Seam;
+					}
+					else
+					{
+						result[i] = Kind_Locked;
+						TRACESTATS(1);
+					}
+				}
+				else
+				{
+					result[i] = Kind_Locked;
+					TRACESTATS(2);
+				}
+			}
+			else
+			{
+				// more than one vertex maps to this one; we don't have classification available
+				result[i] = Kind_Locked;
+				TRACESTATS(3);
+			}
+		}
+		else
+		{
+			assert(remap[i] < i);
+
+			result[i] = result[remap[i]];
+		}
+	}
+
+	if (options & meshopt_SimplifyPermissive)
+		for (size_t i = 0; i < vertex_count; ++i)
+			if (result[i] == Kind_Seam || result[i] == Kind_Locked)
+			{
+				if (remap[i] != i)
+				{
+					// only process primary vertices; wedges will be updated to match the primary vertex
+					result[i] = result[remap[i]];
+					continue;
+				}
+
+				bool protect = false;
+
+				// vertex_lock may protect any wedge, not just the primary vertex, so we switch to complex only if no wedges are protected
+				unsigned int v = unsigned(i);
+				do
+				{
+					unsigned int rv = sparse_remap ? sparse_remap[v] : v;
+					protect |= vertex_lock && (vertex_lock[rv] & meshopt_SimplifyVertex_Protect) != 0;
+					v = wedge[v];
+				} while (v != i);
+
+				// protect if any adjoining edge doesn't have an opposite edge (indicating vertex is on the border)
+				do
+				{
+					const EdgeAdjacency::Edge* edges = &adjacency.data[adjacency.offsets[v]];
+					size_t count = adjacency.offsets[v + 1] - adjacency.offsets[v];
+
+					for (size_t j = 0; j < count; ++j)
+						protect |= !hasEdge(adjacency, edges[j].next, v, remap, wedge);
+					v = wedge[v];
+				} while (v != i);
+
+				result[i] = protect ? result[i] : int(Kind_Complex);
+			}
+
+	if (vertex_lock)
+	{
+		// vertex_lock may lock any wedge, not just the primary vertex, so we need to lock the primary vertex and relock any wedges
+		for (size_t i = 0; i < vertex_count; ++i)
+		{
+			unsigned int ri = sparse_remap ? sparse_remap[i] : unsigned(i);
+
+			if (vertex_lock[ri] & meshopt_SimplifyVertex_Lock)
+				result[remap[i]] = Kind_Locked;
+		}
+
+		for (size_t i = 0; i < vertex_count; ++i)
+			if (result[remap[i]] == Kind_Locked)
+				result[i] = Kind_Locked;
+	}
+
+	if (options & meshopt_SimplifyLockBorder)
+		for (size_t i = 0; i < vertex_count; ++i)
+			if (result[i] == Kind_Border)
+				result[i] = Kind_Locked;
+
+#if TRACE
+	printf("locked: many open edges %d, disconnected seam %d, many seam edges %d, many wedges %d\n",
+	    int(stats[0]), int(stats[1]), int(stats[2]), int(stats[3]));
+#endif
+}
+
+struct Vector3
+{
+	float x, y, z;
+};
+
+static float rescalePositions(Vector3* result, const float* vertex_positions_data, size_t vertex_count, size_t vertex_positions_stride, const unsigned int* sparse_remap = NULL, float* out_offset = NULL)
+{
+	size_t vertex_stride_float = vertex_positions_stride / sizeof(float);
+
+	float minv[3] = {FLT_MAX, FLT_MAX, FLT_MAX};
+	float maxv[3] = {-FLT_MAX, -FLT_MAX, -FLT_MAX};
+
+	for (size_t i = 0; i < vertex_count; ++i)
+	{
+		unsigned int ri = sparse_remap ? sparse_remap[i] : unsigned(i);
+		const float* v = vertex_positions_data + ri * vertex_stride_float;
+
+		if (result)
+		{
+			result[i].x = v[0];
+			result[i].y = v[1];
+			result[i].z = v[2];
+		}
+
+		for (int j = 0; j < 3; ++j)
+		{
+			float vj = v[j];
+
+			minv[j] = minv[j] > vj ? vj : minv[j];
+			maxv[j] = maxv[j] < vj ? vj : maxv[j];
+		}
+	}
+
+	float extent = 0.f;
+
+	extent = (maxv[0] - minv[0]) < extent ? extent : (maxv[0] - minv[0]);
+	extent = (maxv[1] - minv[1]) < extent ? extent : (maxv[1] - minv[1]);
+	extent = (maxv[2] - minv[2]) < extent ? extent : (maxv[2] - minv[2]);
+
+	if (result)
+	{
+		float scale = extent == 0 ? 0.f : 1.f / extent;
+
+		for (size_t i = 0; i < vertex_count; ++i)
+		{
+			result[i].x = (result[i].x - minv[0]) * scale;
+			result[i].y = (result[i].y - minv[1]) * scale;
+			result[i].z = (result[i].z - minv[2]) * scale;
+		}
+	}
+
+	if (out_offset)
+	{
+		out_offset[0] = minv[0];
+		out_offset[1] = minv[1];
+		out_offset[2] = minv[2];
+	}
+
+	return extent;
+}
+
+static void rescaleAttributes(float* result, const float* vertex_attributes_data, size_t vertex_count, size_t vertex_attributes_stride, const float* attribute_weights, size_t attribute_count, const unsigned int* attribute_remap, const unsigned int* sparse_remap)
+{
+	size_t vertex_attributes_stride_float = vertex_attributes_stride / sizeof(float);
+
+	for (size_t i = 0; i < vertex_count; ++i)
+	{
+		unsigned int ri = sparse_remap ? sparse_remap[i] : unsigned(i);
+
+		for (size_t k = 0; k < attribute_count; ++k)
+		{
+			unsigned int rk = attribute_remap[k];
+			float a = vertex_attributes_data[ri * vertex_attributes_stride_float + rk];
+
+			result[i * attribute_count + k] = a * attribute_weights[rk];
+		}
+	}
+}
+
+static void finalizeVertices(float* vertex_positions_data, size_t vertex_positions_stride, float* vertex_attributes_data, size_t vertex_attributes_stride, const float* attribute_weights, size_t attribute_count, size_t vertex_count, const Vector3* vertex_positions, const float* vertex_attributes, const unsigned int* sparse_remap, const unsigned int* attribute_remap, float vertex_scale, const float* vertex_offset, const unsigned char* vertex_kind, const unsigned char* vertex_update, const unsigned char* vertex_lock)
+{
+	size_t vertex_positions_stride_float = vertex_positions_stride / sizeof(float);
+	size_t vertex_attributes_stride_float = vertex_attributes_stride / sizeof(float);
+
+	for (size_t i = 0; i < vertex_count; ++i)
+	{
+		if (!vertex_update[i])
+			continue;
+
+		unsigned int ri = sparse_remap ? sparse_remap[i] : unsigned(i);
+
+		// updating externally locked vertices is not allowed
+		if (vertex_lock && (vertex_lock[ri] & meshopt_SimplifyVertex_Lock) != 0)
+			continue;
+
+		// moving locked vertices may result in floating point drift
+		if (vertex_kind[i] != Kind_Locked)
+		{
+			const Vector3& p = vertex_positions[i];
+			float* v = vertex_positions_data + ri * vertex_positions_stride_float;
+
+			v[0] = p.x * vertex_scale + vertex_offset[0];
+			v[1] = p.y * vertex_scale + vertex_offset[1];
+			v[2] = p.z * vertex_scale + vertex_offset[2];
+		}
+
+		if (attribute_count)
+		{
+			const float* sa = vertex_attributes + i * attribute_count;
+			float* va = vertex_attributes_data + ri * vertex_attributes_stride_float;
+
+			for (size_t k = 0; k < attribute_count; ++k)
+			{
+				unsigned int rk = attribute_remap[k];
+
+				va[rk] = sa[k] / attribute_weights[rk];
+			}
+		}
+	}
+}
+
+static const size_t kMaxAttributes = 32;
+
+struct Quadric
+{
+	// a00*x^2 + a11*y^2 + a22*z^2 + 2*a10*xy + 2*a20*xz + 2*a21*yz + 2*b0*x + 2*b1*y + 2*b2*z + c
+	float a00, a11, a22;
+	float a10, a20, a21;
+	float b0, b1, b2, c;
+	float w;
+};
+
+struct QuadricGrad
+{
+	// gx*x + gy*y + gz*z + gw
+	float gx, gy, gz, gw;
+};
+
+struct Reservoir
+{
+	float x, y, z;
+	float r, g, b;
+	float w;
+};
+
+struct Collapse
+{
+	unsigned int v0;
+	unsigned int v1;
+
+	union
+	{
+		unsigned int bidi;
+		float error;
+		unsigned int errorui;
+	};
+};
+
+static float normalize(Vector3& v)
+{
+	float length = sqrtf(v.x * v.x + v.y * v.y + v.z * v.z);
+
+	if (length > 0)
+	{
+		v.x /= length;
+		v.y /= length;
+		v.z /= length;
+	}
+
+	return length;
+}
+
+static void quadricAdd(Quadric& Q, const Quadric& R)
+{
+	Q.a00 += R.a00;
+	Q.a11 += R.a11;
+	Q.a22 += R.a22;
+	Q.a10 += R.a10;
+	Q.a20 += R.a20;
+	Q.a21 += R.a21;
+	Q.b0 += R.b0;
+	Q.b1 += R.b1;
+	Q.b2 += R.b2;
+	Q.c += R.c;
+	Q.w += R.w;
+}
+
+static void quadricAdd(QuadricGrad& G, const QuadricGrad& R)
+{
+	G.gx += R.gx;
+	G.gy += R.gy;
+	G.gz += R.gz;
+	G.gw += R.gw;
+}
+
+static void quadricAdd(QuadricGrad* G, const QuadricGrad* R, size_t attribute_count)
+{
+	for (size_t k = 0; k < attribute_count; ++k)
+	{
+		G[k].gx += R[k].gx;
+		G[k].gy += R[k].gy;
+		G[k].gz += R[k].gz;
+		G[k].gw += R[k].gw;
+	}
+}
+
+static float quadricEval(const Quadric& Q, const Vector3& v)
+{
+	float rx = Q.b0;
+	float ry = Q.b1;
+	float rz = Q.b2;
+
+	rx += Q.a10 * v.y;
+	ry += Q.a21 * v.z;
+	rz += Q.a20 * v.x;
+
+	rx *= 2;
+	ry *= 2;
+	rz *= 2;
+
+	rx += Q.a00 * v.x;
+	ry += Q.a11 * v.y;
+	rz += Q.a22 * v.z;
+
+	float r = Q.c;
+	r += rx * v.x;
+	r += ry * v.y;
+	r += rz * v.z;
+
+	return r;
+}
+
+static float quadricError(const Quadric& Q, const Vector3& v)
+{
+	float r = quadricEval(Q, v);
+	float s = Q.w == 0.f ? 0.f : 1.f / Q.w;
+
+	return fabsf(r) * s;
+}
+
+static float quadricError(const Quadric& Q, const QuadricGrad* G, size_t attribute_count, const Vector3& v, const float* va)
+{
+	float r = quadricEval(Q, v);
+
+	// see quadricFromAttributes for general derivation; here we need to add the parts of (eval(pos) - attr)^2 that depend on attr
+	for (size_t k = 0; k < attribute_count; ++k)
+	{
+		float a = va[k];
+		float g = v.x * G[k].gx + v.y * G[k].gy + v.z * G[k].gz + G[k].gw;
+
+		r += a * (a * Q.w - 2 * g);
+	}
+
+	// note: unlike position error, we do not normalize by Q.w to retain edge scaling as described in quadricFromAttributes
+	return fabsf(r);
+}
+
+static void quadricFromPlane(Quadric& Q, float a, float b, float c, float d, float w)
+{
+	float aw = a * w;
+	float bw = b * w;
+	float cw = c * w;
+	float dw = d * w;
+
+	Q.a00 = a * aw;
+	Q.a11 = b * bw;
+	Q.a22 = c * cw;
+	Q.a10 = a * bw;
+	Q.a20 = a * cw;
+	Q.a21 = b * cw;
+	Q.b0 = a * dw;
+	Q.b1 = b * dw;
+	Q.b2 = c * dw;
+	Q.c = d * dw;
+	Q.w = w;
+}
+
+static void quadricFromPoint(Quadric& Q, float x, float y, float z, float w)
+{
+	Q.a00 = Q.a11 = Q.a22 = w;
+	Q.a10 = Q.a20 = Q.a21 = 0;
+	Q.b0 = -x * w;
+	Q.b1 = -y * w;
+	Q.b2 = -z * w;
+	Q.c = (x * x + y * y + z * z) * w;
+	Q.w = w;
+}
+
+static void quadricFromTriangle(Quadric& Q, const Vector3& p0, const Vector3& p1, const Vector3& p2, float weight)
+{
+	Vector3 p10 = {p1.x - p0.x, p1.y - p0.y, p1.z - p0.z};
+	Vector3 p20 = {p2.x - p0.x, p2.y - p0.y, p2.z - p0.z};
+
+	// normal = cross(p1 - p0, p2 - p0)
+	Vector3 normal = {p10.y * p20.z - p10.z * p20.y, p10.z * p20.x - p10.x * p20.z, p10.x * p20.y - p10.y * p20.x};
+	float area = normalize(normal);
+
+	float distance = normal.x * p0.x + normal.y * p0.y + normal.z * p0.z;
+
+	// we use sqrtf(area) so that the error is scaled linearly; this tends to improve silhouettes
+	quadricFromPlane(Q, normal.x, normal.y, normal.z, -distance, sqrtf(area) * weight);
+}
+
+static void quadricFromTriangleEdge(Quadric& Q, const Vector3& p0, const Vector3& p1, const Vector3& p2, float weight)
+{
+	Vector3 p10 = {p1.x - p0.x, p1.y - p0.y, p1.z - p0.z};
+
+	// edge length; keep squared length around for projection correction
+	float lengthsq = p10.x * p10.x + p10.y * p10.y + p10.z * p10.z;
+	float length = sqrtf(lengthsq);
+
+	// p20p = length of projection of p2-p0 onto p1-p0; note that p10 is unnormalized so we need to correct it later
+	Vector3 p20 = {p2.x - p0.x, p2.y - p0.y, p2.z - p0.z};
+	float p20p = p20.x * p10.x + p20.y * p10.y + p20.z * p10.z;
+
+	// perp = perpendicular vector from p2 to line segment p1-p0
+	// note: since p10 is unnormalized we need to correct the projection; we scale p20 instead to take advantage of normalize below
+	Vector3 perp = {p20.x * lengthsq - p10.x * p20p, p20.y * lengthsq - p10.y * p20p, p20.z * lengthsq - p10.z * p20p};
+	normalize(perp);
+
+	float distance = perp.x * p0.x + perp.y * p0.y + perp.z * p0.z;
+
+	// note: the weight is scaled linearly with edge length; this has to match the triangle weight
+	quadricFromPlane(Q, perp.x, perp.y, perp.z, -distance, length * weight);
+}
+
+static void quadricFromAttributes(Quadric& Q, QuadricGrad* G, const Vector3& p0, const Vector3& p1, const Vector3& p2, const float* va0, const float* va1, const float* va2, size_t attribute_count)
+{
+	// for each attribute we want to encode the following function into the quadric:
+	// (eval(pos) - attr)^2
+	// where eval(pos) interpolates attribute across the triangle like so:
+	// eval(pos) = pos.x * gx + pos.y * gy + pos.z * gz + gw
+	// where gx/gy/gz/gw are gradients
+	Vector3 p10 = {p1.x - p0.x, p1.y - p0.y, p1.z - p0.z};
+	Vector3 p20 = {p2.x - p0.x, p2.y - p0.y, p2.z - p0.z};
+
+	// normal = cross(p1 - p0, p2 - p0)
+	Vector3 normal = {p10.y * p20.z - p10.z * p20.y, p10.z * p20.x - p10.x * p20.z, p10.x * p20.y - p10.y * p20.x};
+	float area = sqrtf(normal.x * normal.x + normal.y * normal.y + normal.z * normal.z) * 0.5f;
+
+	// quadric is weighted with the square of edge length (= area)
+	// this equalizes the units with the positional error (which, after normalization, is a square of distance)
+	// as a result, a change in weighted attribute of 1 along distance d is approximately equivalent to a change in position of d
+	float w = area;
+
+	// we compute gradients using barycentric coordinates; barycentric coordinates can be computed as follows:
+	// v = (d11 * d20 - d01 * d21) / denom
+	// w = (d00 * d21 - d01 * d20) / denom
+	// u = 1 - v - w
+	// here v0, v1 are triangle edge vectors, v2 is a vector from point to triangle corner, and dij = dot(vi, vj)
+	// note: v2 and d20/d21 can not be evaluated here as v2 is effectively an unknown variable; we need these only as variables for derivation of gradients
+	const Vector3& v0 = p10;
+	const Vector3& v1 = p20;
+	float d00 = v0.x * v0.x + v0.y * v0.y + v0.z * v0.z;
+	float d01 = v0.x * v1.x + v0.y * v1.y + v0.z * v1.z;
+	float d11 = v1.x * v1.x + v1.y * v1.y + v1.z * v1.z;
+	float denom = d00 * d11 - d01 * d01;
+	float denomr = denom == 0 ? 0.f : 1.f / denom;
+
+	// precompute gradient factors
+	// these are derived by directly computing derivative of eval(pos) = a0 * u + a1 * v + a2 * w and factoring out expressions that are shared between attributes
+	float gx1 = (d11 * v0.x - d01 * v1.x) * denomr;
+	float gx2 = (d00 * v1.x - d01 * v0.x) * denomr;
+	float gy1 = (d11 * v0.y - d01 * v1.y) * denomr;
+	float gy2 = (d00 * v1.y - d01 * v0.y) * denomr;
+	float gz1 = (d11 * v0.z - d01 * v1.z) * denomr;
+	float gz2 = (d00 * v1.z - d01 * v0.z) * denomr;
+
+	memset(&Q, 0, sizeof(Quadric));
+
+	Q.w = w;
+
+	for (size_t k = 0; k < attribute_count; ++k)
+	{
+		float a0 = va0[k], a1 = va1[k], a2 = va2[k];
+
+		// compute gradient of eval(pos) for x/y/z/w
+		// the formulas below are obtained by directly computing derivative of eval(pos) = a0 * u + a1 * v + a2 * w
+		float gx = gx1 * (a1 - a0) + gx2 * (a2 - a0);
+		float gy = gy1 * (a1 - a0) + gy2 * (a2 - a0);
+		float gz = gz1 * (a1 - a0) + gz2 * (a2 - a0);
+		float gw = a0 - p0.x * gx - p0.y * gy - p0.z * gz;
+
+		// quadric encodes (eval(pos)-attr)^2; this means that the resulting expansion needs to compute, for example, pos.x * pos.y * K
+		// since quadrics already encode factors for pos.x * pos.y, we can accumulate almost everything in basic quadric fields
+		// note: for simplicity we scale all factors by weight here instead of outside the loop
+		Q.a00 += w * (gx * gx);
+		Q.a11 += w * (gy * gy);
+		Q.a22 += w * (gz * gz);
+
+		Q.a10 += w * (gy * gx);
+		Q.a20 += w * (gz * gx);
+		Q.a21 += w * (gz * gy);
+
+		Q.b0 += w * (gx * gw);
+		Q.b1 += w * (gy * gw);
+		Q.b2 += w * (gz * gw);
+
+		Q.c += w * (gw * gw);
+
+		// the only remaining sum components are ones that depend on attr; these will be added during error evaluation, see quadricError
+		G[k].gx = w * gx;
+		G[k].gy = w * gy;
+		G[k].gz = w * gz;
+		G[k].gw = w * gw;
+	}
+}
+
+static void quadricVolumeGradient(QuadricGrad& G, const Vector3& p0, const Vector3& p1, const Vector3& p2)
+{
+	Vector3 p10 = {p1.x - p0.x, p1.y - p0.y, p1.z - p0.z};
+	Vector3 p20 = {p2.x - p0.x, p2.y - p0.y, p2.z - p0.z};
+
+	// normal = cross(p1 - p0, p2 - p0)
+	Vector3 normal = {p10.y * p20.z - p10.z * p20.y, p10.z * p20.x - p10.x * p20.z, p10.x * p20.y - p10.y * p20.x};
+	float area = normalize(normal) * 0.5f;
+
+	G.gx = normal.x * area;
+	G.gy = normal.y * area;
+	G.gz = normal.z * area;
+	G.gw = (-p0.x * normal.x - p0.y * normal.y - p0.z * normal.z) * area;
+}
+
+static bool quadricSolve(Vector3& p, const Quadric& Q, const QuadricGrad& GV)
+{
+	// solve A*p = -b where A is the quadric matrix and b is the linear term
+	float a00 = Q.a00, a11 = Q.a11, a22 = Q.a22;
+	float a10 = Q.a10, a20 = Q.a20, a21 = Q.a21;
+	float x0 = -Q.b0, x1 = -Q.b1, x2 = -Q.b2;
+
+	float eps = 1e-6f * Q.w;
+
+	// LDL decomposition: A = LDL^T
+	float d0 = a00;
+	float l10 = a10 / d0;
+	float l20 = a20 / d0;
+
+	float d1 = a11 - a10 * l10;
+	float dl21 = a21 - a20 * l10;
+	float l21 = dl21 / d1;
+
+	float d2 = a22 - a20 * l20 - dl21 * l21;
+
+	// solve L*y = x
+	float y0 = x0;
+	float y1 = x1 - l10 * y0;
+	float y2 = x2 - l20 * y0 - l21 * y1;
+
+	// solve D*z = y
+	float z0 = y0 / d0;
+	float z1 = y1 / d1;
+	float z2 = y2 / d2;
+
+	// augment system with linear constraint GV using Lagrange multiplier
+	float a30 = GV.gx, a31 = GV.gy, a32 = GV.gz;
+	float x3 = -GV.gw;
+
+	float l30 = a30 / d0;
+	float dl31 = a31 - a30 * l10;
+	float l31 = dl31 / d1;
+	float dl32 = a32 - a30 * l20 - dl31 * l21;
+	float l32 = dl32 / d2;
+	float d3 = 0.f - a30 * l30 - dl31 * l31 - dl32 * l32;
+
+	float y3 = x3 - l30 * y0 - l31 * y1 - l32 * y2;
+	float z3 = fabsf(d3) > eps ? y3 / d3 : 0.f; // if d3 is zero, we can ignore the constraint
+
+	// substitute L^T*p = z
+	float lambda = z3;
+	float pz = z2 - l32 * lambda;
+	float py = z1 - l21 * pz - l31 * lambda;
+	float px = z0 - l10 * py - l20 * pz - l30 * lambda;
+
+	p.x = px;
+	p.y = py;
+	p.z = pz;
+
+	return fabsf(d0) > eps && fabsf(d1) > eps && fabsf(d2) > eps;
+}
+
+static void quadricReduceAttributes(Quadric& Q, const Quadric& A, const QuadricGrad* G, size_t attribute_count)
+{
+	// update vertex quadric with attribute quadric; multiply by vertex weight to minimize normalized error
+	Q.a00 += A.a00 * Q.w;
+	Q.a11 += A.a11 * Q.w;
+	Q.a22 += A.a22 * Q.w;
+	Q.a10 += A.a10 * Q.w;
+	Q.a20 += A.a20 * Q.w;
+	Q.a21 += A.a21 * Q.w;
+	Q.b0 += A.b0 * Q.w;
+	Q.b1 += A.b1 * Q.w;
+	Q.b2 += A.b2 * Q.w;
+
+	float iaw = A.w == 0 ? 0.f : Q.w / A.w;
+
+	// update linear system based on attribute gradients (BB^T/a)
+	for (size_t k = 0; k < attribute_count; ++k)
+	{
+		const QuadricGrad& g = G[k];
+
+		Q.a00 -= (g.gx * g.gx) * iaw;
+		Q.a11 -= (g.gy * g.gy) * iaw;
+		Q.a22 -= (g.gz * g.gz) * iaw;
+		Q.a10 -= (g.gx * g.gy) * iaw;
+		Q.a20 -= (g.gx * g.gz) * iaw;
+		Q.a21 -= (g.gy * g.gz) * iaw;
+
+		Q.b0 -= (g.gx * g.gw) * iaw;
+		Q.b1 -= (g.gy * g.gw) * iaw;
+		Q.b2 -= (g.gz * g.gw) * iaw;
+	}
+}
+
+static void fillFaceQuadrics(Quadric* vertex_quadrics, QuadricGrad* volume_gradients, const unsigned int* indices, size_t index_count, const Vector3* vertex_positions, const unsigned int* remap)
+{
+	for (size_t i = 0; i < index_count; i += 3)
+	{
+		unsigned int i0 = indices[i + 0];
+		unsigned int i1 = indices[i + 1];
+		unsigned int i2 = indices[i + 2];
+
+		Quadric Q;
+		quadricFromTriangle(Q, vertex_positions[i0], vertex_positions[i1], vertex_positions[i2], 1.f);
+
+		quadricAdd(vertex_quadrics[remap[i0]], Q);
+		quadricAdd(vertex_quadrics[remap[i1]], Q);
+		quadricAdd(vertex_quadrics[remap[i2]], Q);
+
+		if (volume_gradients)
+		{
+			QuadricGrad GV;
+			quadricVolumeGradient(GV, vertex_positions[i0], vertex_positions[i1], vertex_positions[i2]);
+
+			quadricAdd(volume_gradients[remap[i0]], GV);
+			quadricAdd(volume_gradients[remap[i1]], GV);
+			quadricAdd(volume_gradients[remap[i2]], GV);
+		}
+	}
+}
+
+static void fillVertexQuadrics(Quadric* vertex_quadrics, const Vector3* vertex_positions, size_t vertex_count, const unsigned int* remap, const unsigned char* vertex_lock, const unsigned int* sparse_remap, unsigned int options)
+{
+	// by default, we use a very small weight to improve triangulation and numerical stability without affecting the shape or error
+	float factor = (options & meshopt_SimplifyRegularizeLight) ? 1e-2f : ((options & meshopt_SimplifyRegularize) ? 1e-1f : 1e-7f);
+
+	for (size_t i = 0; i < vertex_count; ++i)
+	{
+		if (remap[i] != i)
+			continue;
+
+		// increase regularization weight for vertices marked as priority; for now we only examine the primary vertex
+		unsigned int ri = sparse_remap ? sparse_remap[i] : unsigned(i);
+		bool priority = vertex_lock && (vertex_lock[ri] & meshopt_SimplifyVertex_Priority) != 0;
+
+		const Vector3& p = vertex_positions[i];
+		float w = vertex_quadrics[i].w * (priority ? 1.0f : factor);
+
+		Quadric Q;
+		quadricFromPoint(Q, p.x, p.y, p.z, w);
+
+		quadricAdd(vertex_quadrics[i], Q);
+	}
+}
+
+static void fillEdgeQuadrics(Quadric* vertex_quadrics, const unsigned int* indices, size_t index_count, const Vector3* vertex_positions, const unsigned int* remap, const unsigned char* vertex_kind, const unsigned int* loop, const unsigned int* loopback)
+{
+	for (size_t i = 0; i < index_count; i += 3)
+	{
+		static const int next[4] = {1, 2, 0, 1};
+
+		for (int e = 0; e < 3; ++e)
+		{
+			unsigned int i0 = indices[i + e];
+			unsigned int i1 = indices[i + next[e]];
+
+			unsigned char k0 = vertex_kind[i0];
+			unsigned char k1 = vertex_kind[i1];
+
+			// check that either i0 or i1 are border/seam and are on the same edge loop
+			// note that we need to add the error even for edged that connect e.g. border & locked
+			// if we don't do that, the adjacent border->border edge won't have correct errors for corners
+			if (k0 != Kind_Border && k0 != Kind_Seam && k1 != Kind_Border && k1 != Kind_Seam)
+				continue;
+
+			if ((k0 == Kind_Border || k0 == Kind_Seam) && loop[i0] != i1)
+				continue;
+
+			if ((k1 == Kind_Border || k1 == Kind_Seam) && loopback[i1] != i0)
+				continue;
+
+			unsigned int i2 = indices[i + next[e + 1]];
+
+			// we try hard to maintain border edge geometry; seam edges can move more freely
+			// due to topological restrictions on collapses, seam quadrics slightly improves collapse structure but aren't critical
+			const float kEdgeWeightSeam = 0.5f; // applied twice due to opposite edges
+			const float kEdgeWeightBorder = 10.f;
+
+			float edgeWeight = (k0 == Kind_Border || k1 == Kind_Border) ? kEdgeWeightBorder : kEdgeWeightSeam;
+
+			Quadric Q;
+			quadricFromTriangleEdge(Q, vertex_positions[i0], vertex_positions[i1], vertex_positions[i2], edgeWeight);
+
+			Quadric QT;
+			quadricFromTriangle(QT, vertex_positions[i0], vertex_positions[i1], vertex_positions[i2], edgeWeight);
+
+			// mix edge quadric with triangle quadric to stabilize collapses in both directions; both quadrics inherit edge weight so that their error is added
+			QT.w = 0;
+			quadricAdd(Q, QT);
+
+			quadricAdd(vertex_quadrics[remap[i0]], Q);
+			quadricAdd(vertex_quadrics[remap[i1]], Q);
+		}
+	}
+}
+
+static void fillAttributeQuadrics(Quadric* attribute_quadrics, QuadricGrad* attribute_gradients, const unsigned int* indices, size_t index_count, const Vector3* vertex_positions, const float* vertex_attributes, size_t attribute_count)
+{
+	for (size_t i = 0; i < index_count; i += 3)
+	{
+		unsigned int i0 = indices[i + 0];
+		unsigned int i1 = indices[i + 1];
+		unsigned int i2 = indices[i + 2];
+
+		Quadric QA;
+		QuadricGrad G[kMaxAttributes];
+		quadricFromAttributes(QA, G, vertex_positions[i0], vertex_positions[i1], vertex_positions[i2], &vertex_attributes[i0 * attribute_count], &vertex_attributes[i1 * attribute_count], &vertex_attributes[i2 * attribute_count], attribute_count);
+
+		quadricAdd(attribute_quadrics[i0], QA);
+		quadricAdd(attribute_quadrics[i1], QA);
+		quadricAdd(attribute_quadrics[i2], QA);
+
+		quadricAdd(&attribute_gradients[i0 * attribute_count], G, attribute_count);
+		quadricAdd(&attribute_gradients[i1 * attribute_count], G, attribute_count);
+		quadricAdd(&attribute_gradients[i2 * attribute_count], G, attribute_count);
+	}
+}
+
+// does triangle ABC flip when C is replaced with D?
+static bool hasTriangleFlip(const Vector3& a, const Vector3& b, const Vector3& c, const Vector3& d)
+{
+	Vector3 eb = {b.x - a.x, b.y - a.y, b.z - a.z};
+	Vector3 ec = {c.x - a.x, c.y - a.y, c.z - a.z};
+	Vector3 ed = {d.x - a.x, d.y - a.y, d.z - a.z};
+
+	Vector3 nbc = {eb.y * ec.z - eb.z * ec.y, eb.z * ec.x - eb.x * ec.z, eb.x * ec.y - eb.y * ec.x};
+	Vector3 nbd = {eb.y * ed.z - eb.z * ed.y, eb.z * ed.x - eb.x * ed.z, eb.x * ed.y - eb.y * ed.x};
+
+	float ndp = nbc.x * nbd.x + nbc.y * nbd.y + nbc.z * nbd.z;
+	float abc = nbc.x * nbc.x + nbc.y * nbc.y + nbc.z * nbc.z;
+	float abd = nbd.x * nbd.x + nbd.y * nbd.y + nbd.z * nbd.z;
+
+	// scale is cos(angle); somewhat arbitrarily set to ~75 degrees
+	// note that the "pure" check is ndp <= 0 (90 degree cutoff) but that allows flipping through a series of close-to-90 collapses
+	return ndp <= 0.25f * sqrtf(abc * abd);
+}
+
+static bool hasTriangleFlips(const EdgeAdjacency& adjacency, const Vector3* vertex_positions, const unsigned int* collapse_remap, unsigned int i0, unsigned int i1)
+{
+	assert(collapse_remap[i0] == i0);
+	assert(collapse_remap[i1] == i1);
+
+	const Vector3& v0 = vertex_positions[i0];
+	const Vector3& v1 = vertex_positions[i1];
+
+	const EdgeAdjacency::Edge* edges = &adjacency.data[adjacency.offsets[i0]];
+	size_t count = adjacency.offsets[i0 + 1] - adjacency.offsets[i0];
+
+	for (size_t i = 0; i < count; ++i)
+	{
+		unsigned int a = collapse_remap[edges[i].next];
+		unsigned int b = collapse_remap[edges[i].prev];
+
+		// skip triangles that will get collapsed by i0->i1 collapse or already got collapsed previously
+		if (a == i1 || b == i1 || a == b)
+			continue;
+
+		// early-out when at least one triangle flips due to a collapse
+		if (hasTriangleFlip(vertex_positions[a], vertex_positions[b], v0, v1))
+		{
+#if TRACE >= 2
+			printf("edge block %d -> %d: flip welded %d %d %d\n", i0, i1, a, i0, b);
+#endif
+
+			return true;
+		}
+	}
+
+	return false;
+}
+
+static bool hasTriangleFlips(const EdgeAdjacency& adjacency, const Vector3* vertex_positions, unsigned int i0, const Vector3& v1)
+{
+	const Vector3& v0 = vertex_positions[i0];
+
+	const EdgeAdjacency::Edge* edges = &adjacency.data[adjacency.offsets[i0]];
+	size_t count = adjacency.offsets[i0 + 1] - adjacency.offsets[i0];
+
+	for (size_t i = 0; i < count; ++i)
+	{
+		unsigned int a = edges[i].next, b = edges[i].prev;
+
+		if (hasTriangleFlip(vertex_positions[a], vertex_positions[b], v0, v1))
+			return true;
+	}
+
+	return false;
+}
+
+static float getNeighborhoodRadius(const EdgeAdjacency& adjacency, const Vector3* vertex_positions, unsigned int i0)
+{
+	const Vector3& v0 = vertex_positions[i0];
+
+	const EdgeAdjacency::Edge* edges = &adjacency.data[adjacency.offsets[i0]];
+	size_t count = adjacency.offsets[i0 + 1] - adjacency.offsets[i0];
+
+	float result = 0.f;
+
+	for (size_t i = 0; i < count; ++i)
+	{
+		unsigned int a = edges[i].next, b = edges[i].prev;
+
+		const Vector3& va = vertex_positions[a];
+		const Vector3& vb = vertex_positions[b];
+
+		float da = (va.x - v0.x) * (va.x - v0.x) + (va.y - v0.y) * (va.y - v0.y) + (va.z - v0.z) * (va.z - v0.z);
+		float db = (vb.x - v0.x) * (vb.x - v0.x) + (vb.y - v0.y) * (vb.y - v0.y) + (vb.z - v0.z) * (vb.z - v0.z);
+
+		result = result < da ? da : result;
+		result = result < db ? db : result;
+	}
+
+	return sqrtf(result);
+}
+
+static unsigned int getComplexTarget(unsigned int v, unsigned int target, const unsigned int* remap, const unsigned int* loop, const unsigned int* loopback)
+{
+	unsigned int r = remap[target];
+
+	// use loop metadata to guide complex collapses towards the correct wedge
+	// this works for edges on attribute discontinuities because loop/loopback track the single half-edge without a pair, similar to seams
+	if (loop[v] != ~0u && remap[loop[v]] == r)
+		return loop[v];
+	else if (loopback[v] != ~0u && remap[loopback[v]] == r)
+		return loopback[v];
+	else
+		return target;
+}
+
+static size_t boundEdgeCollapses(const EdgeAdjacency& adjacency, size_t vertex_count, size_t index_count, unsigned char* vertex_kind)
+{
+	size_t dual_count = 0;
+
+	for (size_t i = 0; i < vertex_count; ++i)
+	{
+		unsigned char k = vertex_kind[i];
+		unsigned int e = adjacency.offsets[i + 1] - adjacency.offsets[i];
+
+		dual_count += (k == Kind_Manifold || k == Kind_Seam) ? e : 0;
+	}
+
+	assert(dual_count <= index_count);
+
+	// pad capacity by 3 so that we can check for overflow once per triangle instead of once per edge
+	return (index_count - dual_count / 2) + 3;
+}
+
+static size_t pickEdgeCollapses(Collapse* collapses, size_t collapse_capacity, const unsigned int* indices, size_t index_count, const unsigned int* remap, const unsigned char* vertex_kind, const unsigned int* loop, const unsigned int* loopback)
+{
+	size_t collapse_count = 0;
+
+	for (size_t i = 0; i < index_count; i += 3)
+	{
+		static const int next[3] = {1, 2, 0};
+
+		// this should never happen as boundEdgeCollapses should give an upper bound for the collapse count, but in an unlikely event it does we can just drop extra collapses
+		if (collapse_count + 3 > collapse_capacity)
+			break;
+
+		for (int e = 0; e < 3; ++e)
+		{
+			unsigned int i0 = indices[i + e];
+			unsigned int i1 = indices[i + next[e]];
+
+			// this can happen either when input has a zero-length edge, or when we perform collapses for complex
+			// topology w/seams and collapse a manifold vertex that connects to both wedges onto one of them
+			// we leave edges like this alone since they may be important for preserving mesh integrity
+			if (remap[i0] == remap[i1])
+				continue;
+
+			unsigned char k0 = vertex_kind[i0];
+			unsigned char k1 = vertex_kind[i1];
+
+			// the edge has to be collapsible in at least one direction
+			if (!(kCanCollapse[k0][k1] | kCanCollapse[k1][k0]))
+				continue;
+
+			// manifold and seam edges should occur twice (i0->i1 and i1->i0) - skip redundant edges
+			if (kHasOpposite[k0][k1] && remap[i1] > remap[i0])
+				continue;
+
+			// two vertices are on a border or a seam, but there's no direct edge between them
+			// this indicates that they belong to two different edge loops and we should not collapse this edge
+			// loop[] and loopback[] track half edges so we only need to check one of them
+			if ((k0 == Kind_Border || k0 == Kind_Seam) && k1 != Kind_Manifold && loop[i0] != i1)
+				continue;
+			if ((k1 == Kind_Border || k1 == Kind_Seam) && k0 != Kind_Manifold && loopback[i1] != i0)
+				continue;
+
+			// edge can be collapsed in either direction - we will pick the one with minimum error
+			// note: we evaluate error later during collapse ranking, here we just tag the edge as bidirectional
+			if (kCanCollapse[k0][k1] & kCanCollapse[k1][k0])
+			{
+				Collapse c = {i0, i1, {/* bidi= */ 1}};
+				collapses[collapse_count++] = c;
+			}
+			else
+			{
+				// edge can only be collapsed in one direction
+				unsigned int e0 = kCanCollapse[k0][k1] ? i0 : i1;
+				unsigned int e1 = kCanCollapse[k0][k1] ? i1 : i0;
+
+				Collapse c = {e0, e1, {/* bidi= */ 0}};
+				collapses[collapse_count++] = c;
+			}
+		}
+	}
+
+	return collapse_count;
+}
+
+static void rankEdgeCollapses(Collapse* collapses, size_t collapse_count, const Vector3* vertex_positions, const float* vertex_attributes, const Quadric* vertex_quadrics, const Quadric* attribute_quadrics, const QuadricGrad* attribute_gradients, size_t attribute_count, const unsigned int* remap, const unsigned int* wedge, const unsigned char* vertex_kind, const unsigned int* loop, const unsigned int* loopback)
+{
+	for (size_t i = 0; i < collapse_count; ++i)
+	{
+		Collapse& c = collapses[i];
+
+		unsigned int i0 = c.v0;
+		unsigned int i1 = c.v1;
+		bool bidi = c.bidi;
+
+		float ei = quadricError(vertex_quadrics[remap[i0]], vertex_positions[i1]);
+		float ej = bidi ? quadricError(vertex_quadrics[remap[i1]], vertex_positions[i0]) : FLT_MAX;
+
+#if TRACE >= 3
+		float di = ei, dj = ej;
+#endif
+
+		if (attribute_count)
+		{
+			ei += quadricError(attribute_quadrics[i0], &attribute_gradients[i0 * attribute_count], attribute_count, vertex_positions[i1], &vertex_attributes[i1 * attribute_count]);
+			ej += bidi ? quadricError(attribute_quadrics[i1], &attribute_gradients[i1 * attribute_count], attribute_count, vertex_positions[i0], &vertex_attributes[i0 * attribute_count]) : 0;
+
+			// seam edges need to aggregate attribute errors between primary and secondary edges, as attribute quadrics are separate
+			if (vertex_kind[i0] == Kind_Seam)
+			{
+				// for seam collapses we need to find the seam pair; this is a bit tricky since we need to rely on edge loops as target vertex may be locked (and thus have more than two wedges)
+				unsigned int s0 = wedge[i0];
+				unsigned int s1 = loop[i0] == i1 ? loopback[s0] : loop[s0];
+
+				assert(wedge[s0] == i0); // s0 may be equal to i0 for half-seams
+				assert(s1 != ~0u && remap[s1] == remap[i1]);
+
+				// note: this should never happen due to the assertion above, but when disabled if we ever hit this case we'll get a memory safety issue; for now play it safe
+				s1 = (s1 != ~0u) ? s1 : wedge[i1];
+
+				ei += quadricError(attribute_quadrics[s0], &attribute_gradients[s0 * attribute_count], attribute_count, vertex_positions[s1], &vertex_attributes[s1 * attribute_count]);
+				ej += bidi ? quadricError(attribute_quadrics[s1], &attribute_gradients[s1 * attribute_count], attribute_count, vertex_positions[s0], &vertex_attributes[s0 * attribute_count]) : 0;
+			}
+			else
+			{
+				// complex edges can have multiple wedges, so we need to aggregate errors for all wedges based on the selected target
+				if (vertex_kind[i0] == Kind_Complex)
+					for (unsigned int v = wedge[i0]; v != i0; v = wedge[v])
+					{
+						unsigned int t = getComplexTarget(v, i1, remap, loop, loopback);
+
+						ei += quadricError(attribute_quadrics[v], &attribute_gradients[v * attribute_count], attribute_count, vertex_positions[t], &vertex_attributes[t * attribute_count]);
+					}
+
+				if (vertex_kind[i1] == Kind_Complex && bidi)
+					for (unsigned int v = wedge[i1]; v != i1; v = wedge[v])
+					{
+						unsigned int t = getComplexTarget(v, i0, remap, loop, loopback);
+
+						ej += quadricError(attribute_quadrics[v], &attribute_gradients[v * attribute_count], attribute_count, vertex_positions[t], &vertex_attributes[t * attribute_count]);
+					}
+			}
+		}
+
+		// pick edge direction with minimal error (branchless)
+		bool rev = bidi & (ej < ei);
+
+		c.v0 = rev ? i1 : i0;
+		c.v1 = rev ? i0 : i1;
+		c.error = ej < ei ? ej : ei;
+
+#if TRACE >= 3
+		if (bidi)
+			printf("edge eval %d -> %d: error %f (pos %f, attr %f); reverse %f (pos %f, attr %f)\n",
+			    rev ? i1 : i0, rev ? i0 : i1,
+			    sqrtf(rev ? ej : ei), sqrtf(rev ? dj : di), sqrtf(rev ? ej - dj : ei - di),
+			    sqrtf(rev ? ei : ej), sqrtf(rev ? di : dj), sqrtf(rev ? ei - di : ej - dj));
+		else
+			printf("edge eval %d -> %d: error %f (pos %f, attr %f)\n", i0, i1, sqrtf(c.error), sqrtf(di), sqrtf(ei - di));
+#endif
+	}
+}
+
+static void sortEdgeCollapses(unsigned int* sort_order, const Collapse* collapses, size_t collapse_count)
+{
+	// we use counting sort to order collapses by error; since the exact sort order is not as critical,
+	// only top 12 bits of exponent+mantissa (8 bits of exponent and 4 bits of mantissa) are used.
+	// to avoid excessive stack usage, we clamp the exponent range as collapses with errors much higher than 1 are not useful.
+	const unsigned int sort_bits = 12;
+	const unsigned int sort_bins = 2048 + 512; // exponent range [-127, 32)
+
+	// fill histogram for counting sort
+	unsigned int histogram[sort_bins];
+	memset(histogram, 0, sizeof(histogram));
+
+	for (size_t i = 0; i < collapse_count; ++i)
+	{
+		// skip sign bit since error is non-negative
+		unsigned int error = collapses[i].errorui;
+		unsigned int key = (error << 1) >> (32 - sort_bits);
+		key = key < sort_bins ? key : sort_bins - 1;
+
+		histogram[key]++;
+	}
+
+	// compute offsets based on histogram data
+	size_t histogram_sum = 0;
+
+	for (size_t i = 0; i < sort_bins; ++i)
+	{
+		size_t count = histogram[i];
+		histogram[i] = unsigned(histogram_sum);
+		histogram_sum += count;
+	}
+
+	assert(histogram_sum == collapse_count);
+
+	// compute sort order based on offsets
+	for (size_t i = 0; i < collapse_count; ++i)
+	{
+		// skip sign bit since error is non-negative
+		unsigned int error = collapses[i].errorui;
+		unsigned int key = (error << 1) >> (32 - sort_bits);
+		key = key < sort_bins ? key : sort_bins - 1;
+
+		sort_order[histogram[key]++] = unsigned(i);
+	}
+}
+
+static size_t performEdgeCollapses(unsigned int* collapse_remap, unsigned char* collapse_locked, const Collapse* collapses, size_t collapse_count, const unsigned int* collapse_order, const unsigned int* remap, const unsigned int* wedge, const unsigned char* vertex_kind, const unsigned int* loop, const unsigned int* loopback, const Vector3* vertex_positions, const EdgeAdjacency& adjacency, size_t triangle_collapse_goal, float error_limit, float& result_error)
+{
+	size_t edge_collapses = 0;
+	size_t triangle_collapses = 0;
+
+	// most collapses remove 2 triangles; use this to establish a bound on the pass in terms of error limit
+	// note that edge_collapse_goal is an estimate; triangle_collapse_goal will be used to actually limit collapses
+	size_t edge_collapse_goal = triangle_collapse_goal / 2;
+
+#if TRACE
+	size_t stats[7] = {};
+#endif
+
+	for (size_t i = 0; i < collapse_count; ++i)
+	{
+		const Collapse& c = collapses[collapse_order[i]];
+
+		TRACESTATS(0);
+
+		if (c.error > error_limit)
+		{
+			TRACESTATS(4);
+			break;
+		}
+
+		if (triangle_collapses >= triangle_collapse_goal)
+		{
+			TRACESTATS(5);
+			break;
+		}
+
+		// we limit the error in each pass based on the error of optimal last collapse; since many collapses will be locked
+		// as they will share vertices with other successfull collapses, we need to increase the acceptable error by some factor
+		float error_goal = edge_collapse_goal < collapse_count ? 1.5f * collapses[collapse_order[edge_collapse_goal]].error : FLT_MAX;
+
+		// on average, each collapse is expected to lock 6 other collapses; to avoid degenerate passes on meshes with odd
+		// topology, we only abort if we got over 1/6 collapses accordingly.
+		if (c.error > error_goal && c.error > result_error && triangle_collapses > triangle_collapse_goal / 6)
+		{
+			TRACESTATS(6);
+			break;
+		}
+
+		unsigned int i0 = c.v0;
+		unsigned int i1 = c.v1;
+
+		unsigned int r0 = remap[i0];
+		unsigned int r1 = remap[i1];
+
+		unsigned char kind = vertex_kind[i0];
+
+		// we don't collapse vertices that had source or target vertex involved in a collapse
+		// it's important to not move the vertices twice since it complicates the tracking/remapping logic
+		// it's important to not move other vertices towards a moved vertex to preserve error since we don't re-rank collapses mid-pass
+		if (collapse_locked[r0] | collapse_locked[r1])
+		{
+			TRACESTATS(1);
+			continue;
+		}
+
+		if (hasTriangleFlips(adjacency, vertex_positions, collapse_remap, r0, r1))
+		{
+			// adjust collapse goal since this collapse is invalid and shouldn't factor into error goal
+			edge_collapse_goal++;
+
+			TRACESTATS(2);
+			continue;
+		}
+
+#if TRACE >= 2
+		printf("edge commit %d -> %d: kind %d->%d, error %f\n", i0, i1, vertex_kind[i0], vertex_kind[i1], sqrtf(c.error));
+#endif
+
+		assert(collapse_remap[r0] == r0);
+		assert(collapse_remap[r1] == r1);
+
+		if (kind == Kind_Complex)
+		{
+			// remap all vertices in the complex to the target vertex
+			unsigned int v = i0;
+
+			do
+			{
+				unsigned int t = getComplexTarget(v, i1, remap, loop, loopback);
+
+				collapse_remap[v] = t;
+				v = wedge[v];
+			} while (v != i0);
+		}
+		else if (kind == Kind_Seam)
+		{
+			// for seam collapses we need to move the seam pair together; this is a bit tricky since we need to rely on edge loops as target vertex may be locked (and thus have more than two wedges)
+			unsigned int s0 = wedge[i0];
+			unsigned int s1 = loop[i0] == i1 ? loopback[s0] : loop[s0];
+			assert(wedge[s0] == i0); // s0 may be equal to i0 for half-seams
+			assert(s1 != ~0u && remap[s1] == r1);
+
+			// additional asserts to verify that the seam pair is consistent
+			assert(kind != vertex_kind[i1] || s1 == wedge[i1]);
+			assert(loop[i0] == i1 || loopback[i0] == i1);
+			assert(loop[s0] == s1 || loopback[s0] == s1);
+
+			// note: this should never happen due to the assertion above, but when disabled if we ever hit this case we'll get a memory safety issue; for now play it safe
+			s1 = (s1 != ~0u) ? s1 : wedge[i1];
+
+			collapse_remap[i0] = i1;
+			collapse_remap[s0] = s1;
+		}
+		else
+		{
+			assert(wedge[i0] == i0);
+
+			collapse_remap[i0] = i1;
+		}
+
+		// note: we technically don't need to lock r1 if it's a locked vertex, as it can't move and its quadric won't be used
+		// however, this results in slightly worse error on some meshes because the locked collapses get an unfair advantage wrt scheduling
+		collapse_locked[r0] = 1;
+		collapse_locked[r1] = 1;
+
+		// border edges collapse 1 triangle, other edges collapse 2 or more
+		triangle_collapses += (kind == Kind_Border) ? 1 : 2;
+		edge_collapses++;
+
+		result_error = result_error < c.error ? c.error : result_error;
+	}
+
+#if TRACE
+	float error_goal_last = edge_collapse_goal < collapse_count ? 1.5f * collapses[collapse_order[edge_collapse_goal]].error : FLT_MAX;
+	float error_goal_limit = error_goal_last < error_limit ? error_goal_last : error_limit;
+
+	printf("removed %d triangles, error %e (goal %e); evaluated %d/%d collapses (done %d, skipped %d, invalid %d); %s\n",
+	    int(triangle_collapses), sqrtf(result_error), sqrtf(error_goal_limit),
+	    int(stats[0]), int(collapse_count), int(edge_collapses), int(stats[1]), int(stats[2]),
+	    stats[4] ? "error limit" : (stats[5] ? "count limit" : (stats[6] ? "error goal" : "out of collapses")));
+#endif
+
+	return edge_collapses;
+}
+
+static void updateQuadrics(const unsigned int* collapse_remap, size_t vertex_count, Quadric* vertex_quadrics, QuadricGrad* volume_gradients, Quadric* attribute_quadrics, QuadricGrad* attribute_gradients, size_t attribute_count, const Vector3* vertex_positions, const unsigned int* remap, float& vertex_error)
+{
+	for (size_t i = 0; i < vertex_count; ++i)
+	{
+		if (collapse_remap[i] == i)
+			continue;
+
+		unsigned int i0 = unsigned(i);
+		unsigned int i1 = collapse_remap[i];
+
+		unsigned int r0 = remap[i0];
+		unsigned int r1 = remap[i1];
+
+		// ensure we only update vertex_quadrics once: primary vertex must be moved if any wedge is moved
+		if (i0 == r0)
+		{
+			quadricAdd(vertex_quadrics[r1], vertex_quadrics[r0]);
+
+			if (volume_gradients)
+				quadricAdd(volume_gradients[r1], volume_gradients[r0]);
+		}
+
+		if (attribute_count)
+		{
+			quadricAdd(attribute_quadrics[i1], attribute_quadrics[i0]);
+			quadricAdd(&attribute_gradients[i1 * attribute_count], &attribute_gradients[i0 * attribute_count], attribute_count);
+
+			if (i0 == r0)
+			{
+				// when attributes are used, distance error needs to be recomputed as collapses don't track it; it is safe to do this after the quadric adjustment
+				float derr = quadricError(vertex_quadrics[r0], vertex_positions[r1]);
+				vertex_error = vertex_error < derr ? derr : vertex_error;
+			}
+		}
+	}
+}
+
+static void solvePositions(Vector3* vertex_positions, size_t vertex_count, const Quadric* vertex_quadrics, const QuadricGrad* volume_gradients, const Quadric* attribute_quadrics, const QuadricGrad* attribute_gradients, size_t attribute_count, const unsigned int* remap, const unsigned int* wedge, const EdgeAdjacency& adjacency, const unsigned char* vertex_kind, const unsigned char* vertex_update)
+{
+#if TRACE
+	size_t stats[6] = {};
+#endif
+
+	for (size_t i = 0; i < vertex_count; ++i)
+	{
+		if (!vertex_update[i])
+			continue;
+
+		// moving vertices on an attribute discontinuity may result in extrapolating UV outside of the chart bounds
+		// moving vertices on a border requires a stronger edge quadric to preserve the border geometry
+		if (vertex_kind[i] == Kind_Locked || vertex_kind[i] == Kind_Seam || vertex_kind[i] == Kind_Border)
+			continue;
+
+		if (remap[i] != i)
+		{
+			vertex_positions[i] = vertex_positions[remap[i]];
+			continue;
+		}
+
+		TRACESTATS(0);
+
+		const Vector3& vp = vertex_positions[i];
+
+		Quadric Q = vertex_quadrics[i];
+		QuadricGrad GV = {};
+
+		// add a point quadric for regularization to stabilize the solution
+		Quadric R;
+		quadricFromPoint(R, vp.x, vp.y, vp.z, Q.w * 1e-4f);
+		quadricAdd(Q, R);
+
+		if (attribute_count)
+		{
+			// optimal point simultaneously minimizes attribute quadrics for all wedges
+			unsigned int v = unsigned(i);
+			do
+			{
+				quadricReduceAttributes(Q, attribute_quadrics[v], &attribute_gradients[v * attribute_count], attribute_count);
+				v = wedge[v];
+			} while (v != i);
+
+			// minimizing attribute quadrics results in volume loss so we incorporate volume gradient as a constraint
+			if (volume_gradients)
+				GV = volume_gradients[i];
+		}
+
+		Vector3 p;
+		if (!quadricSolve(p, Q, GV))
+		{
+			TRACESTATS(2);
+			continue;
+		}
+
+		// reject updates that move the vertex too far from its neighborhood
+		// this detects and fixes most cases when the quadric is not well-defined
+		float nr = getNeighborhoodRadius(adjacency, vertex_positions, unsigned(i));
+		float dp = (p.x - vp.x) * (p.x - vp.x) + (p.y - vp.y) * (p.y - vp.y) + (p.z - vp.z) * (p.z - vp.z);
+
+		if (dp > nr * nr)
+		{
+			TRACESTATS(3);
+			continue;
+		}
+
+		// reject updates that would flip a neighboring triangle, as we do for edge collapse
+		if (hasTriangleFlips(adjacency, vertex_positions, unsigned(i), p))
+		{
+			TRACESTATS(4);
+			continue;
+		}
+
+		// reject updates that increase positional error too much; allow some tolerance to improve attribute quality
+		if (quadricError(vertex_quadrics[i], p) > quadricError(vertex_quadrics[i], vp) * 1.5f + 1e-6f)
+		{
+			TRACESTATS(5);
+			continue;
+		}
+
+		TRACESTATS(1);
+		vertex_positions[i] = p;
+	}
+
+#if TRACE
+	printf("updated %d/%d positions; failed solve %d bounds %d flip %d error %d\n", int(stats[1]), int(stats[0]), int(stats[2]), int(stats[3]), int(stats[4]), int(stats[5]));
+#endif
+}
+
+static void solveAttributes(Vector3* vertex_positions, float* vertex_attributes, size_t vertex_count, const Quadric* attribute_quadrics, const QuadricGrad* attribute_gradients, size_t attribute_count, const unsigned int* remap, const unsigned int* wedge, const unsigned char* vertex_kind, const unsigned char* vertex_update)
+{
+	for (size_t i = 0; i < vertex_count; ++i)
+	{
+		if (!vertex_update[i])
+			continue;
+
+		if (remap[i] != i)
+			continue;
+
+		for (size_t k = 0; k < attribute_count; ++k)
+		{
+			unsigned int shared = ~0u;
+
+			// for complex vertices, preserve attribute continuity and use highest weight wedge if values were shared
+			if (vertex_kind[i] == Kind_Complex)
+			{
+				shared = unsigned(i);
+
+				for (unsigned int v = wedge[i]; v != i; v = wedge[v])
+					if (vertex_attributes[v * attribute_count + k] != vertex_attributes[i * attribute_count + k])
+						shared = ~0u;
+					else if (shared != ~0u && attribute_quadrics[v].w > attribute_quadrics[shared].w)
+						shared = v;
+			}
+
+			// update attributes for all wedges
+			unsigned int v = unsigned(i);
+			do
+			{
+				unsigned int r = (shared == ~0u) ? v : shared;
+
+				const Vector3& p = vertex_positions[i]; // same for all wedges
+				const Quadric& A = attribute_quadrics[r];
+				const QuadricGrad& G = attribute_gradients[r * attribute_count + k];
+
+				float iw = A.w == 0 ? 0.f : 1.f / A.w;
+				float av = (G.gx * p.x + G.gy * p.y + G.gz * p.z + G.gw) * iw;
+
+				vertex_attributes[v * attribute_count + k] = av;
+				v = wedge[v];
+			} while (v != i);
+		}
+	}
+}
+
+static size_t remapIndexBuffer(unsigned int* indices, size_t index_count, const unsigned int* collapse_remap, const unsigned int* remap)
+{
+	size_t write = 0;
+
+	for (size_t i = 0; i < index_count; i += 3)
+	{
+		unsigned int v0 = collapse_remap[indices[i + 0]];
+		unsigned int v1 = collapse_remap[indices[i + 1]];
+		unsigned int v2 = collapse_remap[indices[i + 2]];
+
+		// we never move the vertex twice during a single pass
+		assert(collapse_remap[v0] == v0);
+		assert(collapse_remap[v1] == v1);
+		assert(collapse_remap[v2] == v2);
+
+		// collapse zero area triangles even if they are not topologically degenerate
+		// this is required to cleanup manifold->seam collapses when a vertex is collapsed onto a seam pair
+		// as well as complex collapses and some other cases where cross wedge collapses are performed
+		unsigned int r0 = remap[v0];
+		unsigned int r1 = remap[v1];
+		unsigned int r2 = remap[v2];
+
+		if (r0 != r1 && r0 != r2 && r1 != r2)
+		{
+			indices[write + 0] = v0;
+			indices[write + 1] = v1;
+			indices[write + 2] = v2;
+			write += 3;
+		}
+	}
+
+	return write;
+}
+
+static void remapEdgeLoops(unsigned int* loop, size_t vertex_count, const unsigned int* collapse_remap)
+{
+	for (size_t i = 0; i < vertex_count; ++i)
+	{
+		// note: this is a no-op for vertices that were remapped
+		// ideally we would clear the loop entries for those for consistency, even though they aren't going to be used
+		// however, the remapping process needs loop information for remapped vertices, so this would require a separate pass
+		if (loop[i] != ~0u)
+		{
+			unsigned int l = loop[i];
+			unsigned int r = collapse_remap[l];
+
+			// i == r is a special case when the seam edge is collapsed in a direction opposite to where loop goes
+			if (i == r)
+				loop[i] = (loop[l] != ~0u) ? collapse_remap[loop[l]] : ~0u;
+			else
+				loop[i] = r;
+		}
+	}
+}
+
+static unsigned int follow(unsigned int* parents, unsigned int index)
+{
+	while (index != parents[index])
+	{
+		unsigned int parent = parents[index];
+		parents[index] = parents[parent];
+		index = parent;
+	}
+
+	return index;
+}
+
+static size_t buildComponents(unsigned int* components, size_t vertex_count, const unsigned int* indices, size_t index_count, const unsigned int* remap)
+{
+	for (size_t i = 0; i < vertex_count; ++i)
+		components[i] = unsigned(i);
+
+	// compute a unique (but not sequential!) index for each component via union-find
+	for (size_t i = 0; i < index_count; i += 3)
+	{
+		static const int next[4] = {1, 2, 0, 1};
+
+		for (int e = 0; e < 3; ++e)
+		{
+			unsigned int i0 = indices[i + e];
+			unsigned int i1 = indices[i + next[e]];
+
+			unsigned int r0 = remap[i0];
+			unsigned int r1 = remap[i1];
+
+			r0 = follow(components, r0);
+			r1 = follow(components, r1);
+
+			// merge components with larger indices into components with smaller indices
+			// this guarantees that the root of the component is always the one with the smallest index
+			if (r0 != r1)
+				components[r0 < r1 ? r1 : r0] = r0 < r1 ? r0 : r1;
+		}
+	}
+
+	// make sure each element points to the component root *before* we renumber the components
+	for (size_t i = 0; i < vertex_count; ++i)
+		if (remap[i] == i)
+			components[i] = follow(components, unsigned(i));
+
+	unsigned int next_component = 0;
+
+	// renumber components using sequential indices
+	// a sequential pass is sufficient because component root always has the smallest index
+	// note: it is unsafe to use follow() in this pass because we're replacing component links with sequential indices inplace
+	for (size_t i = 0; i < vertex_count; ++i)
+	{
+		if (remap[i] == i)
+		{
+			unsigned int root = components[i];
+			assert(root <= i); // make sure we already computed the component for non-roots
+			components[i] = (root == i) ? next_component++ : components[root];
+		}
+		else
+		{
+			assert(remap[i] < i); // make sure we already computed the component
+			components[i] = components[remap[i]];
+		}
+	}
+
+	return next_component;
+}
+
+static void measureComponents(float* component_errors, size_t component_count, const unsigned int* components, const Vector3* vertex_positions, size_t vertex_count)
+{
+	memset(component_errors, 0, component_count * 4 * sizeof(float));
+
+	// compute approximate sphere center for each component as an average
+	for (size_t i = 0; i < vertex_count; ++i)
+	{
+		unsigned int c = components[i];
+		assert(components[i] < component_count);
+
+		Vector3 v = vertex_positions[i]; // copy avoids aliasing issues
+
+		component_errors[c * 4 + 0] += v.x;
+		component_errors[c * 4 + 1] += v.y;
+		component_errors[c * 4 + 2] += v.z;
+		component_errors[c * 4 + 3] += 1; // weight
+	}
+
+	// complete the center computation, and reinitialize [3] as a radius
+	for (size_t i = 0; i < component_count; ++i)
+	{
+		float w = component_errors[i * 4 + 3];
+		float iw = w == 0.f ? 0.f : 1.f / w;
+
+		component_errors[i * 4 + 0] *= iw;
+		component_errors[i * 4 + 1] *= iw;
+		component_errors[i * 4 + 2] *= iw;
+		component_errors[i * 4 + 3] = 0; // radius
+	}
+
+	// compute squared radius for each component
+	for (size_t i = 0; i < vertex_count; ++i)
+	{
+		unsigned int c = components[i];
+
+		float dx = vertex_positions[i].x - component_errors[c * 4 + 0];
+		float dy = vertex_positions[i].y - component_errors[c * 4 + 1];
+		float dz = vertex_positions[i].z - component_errors[c * 4 + 2];
+		float r = dx * dx + dy * dy + dz * dz;
+
+		component_errors[c * 4 + 3] = component_errors[c * 4 + 3] < r ? r : component_errors[c * 4 + 3];
+	}
+
+	// we've used the output buffer as scratch space, so we need to move the results to proper indices
+	for (size_t i = 0; i < component_count; ++i)
+	{
+#if TRACE >= 2
+		printf("component %d: center %f %f %f, error %e\n", int(i),
+		    component_errors[i * 4 + 0], component_errors[i * 4 + 1], component_errors[i * 4 + 2], sqrtf(component_errors[i * 4 + 3]));
+#endif
+		// note: we keep the squared error to make it match quadric error metric
+		component_errors[i] = component_errors[i * 4 + 3];
+	}
+}
+
+static size_t pruneComponents(unsigned int* indices, size_t index_count, const unsigned int* components, const float* component_errors, size_t component_count, float error_cutoff, float& nexterror)
+{
+	(void)component_count;
+
+	size_t write = 0;
+	float min_error = FLT_MAX;
+
+	for (size_t i = 0; i < index_count; i += 3)
+	{
+		unsigned int v0 = indices[i + 0], v1 = indices[i + 1], v2 = indices[i + 2];
+		unsigned int c = components[v0];
+		assert(c == components[v1] && c == components[v2]);
+
+		if (component_errors[c] > error_cutoff)
+		{
+			min_error = min_error > component_errors[c] ? component_errors[c] : min_error;
+
+			indices[write + 0] = v0;
+			indices[write + 1] = v1;
+			indices[write + 2] = v2;
+			write += 3;
+		}
+	}
+
+#if TRACE
+	size_t pruned_components = 0;
+	for (size_t i = 0; i < component_count; ++i)
+		pruned_components += (component_errors[i] >= nexterror && component_errors[i] <= error_cutoff);
+
+	printf("pruned %d triangles in %d components (goal %e); next %e\n", int((index_count - write) / 3), int(pruned_components), sqrtf(error_cutoff), min_error < FLT_MAX ? sqrtf(min_error) : min_error * 2);
+#endif
+
+	// update next error with the smallest error of the remaining components
+	nexterror = min_error;
+	return write;
+}
+
+struct CellHasher
+{
+	const unsigned int* vertex_ids;
+
+	size_t hash(unsigned int i) const
+	{
+		unsigned int h = vertex_ids[i];
+
+		// MurmurHash2 finalizer
+		h ^= h >> 13;
+		h *= 0x5bd1e995;
+		h ^= h >> 15;
+		return h;
+	}
+
+	bool equal(unsigned int lhs, unsigned int rhs) const
+	{
+		return vertex_ids[lhs] == vertex_ids[rhs];
+	}
+};
+
+struct IdHasher
+{
+	size_t hash(unsigned int id) const
+	{
+		unsigned int h = id;
+
+		// MurmurHash2 finalizer
+		h ^= h >> 13;
+		h *= 0x5bd1e995;
+		h ^= h >> 15;
+		return h;
+	}
+
+	bool equal(unsigned int lhs, unsigned int rhs) const
+	{
+		return lhs == rhs;
+	}
+};
+
+struct TriangleHasher
+{
+	const unsigned int* indices;
+
+	size_t hash(unsigned int i) const
+	{
+		const unsigned int* tri = indices + i * 3;
+
+		// Optimized Spatial Hashing for Collision Detection of Deformable Objects
+		return (tri[0] * 73856093) ^ (tri[1] * 19349663) ^ (tri[2] * 83492791);
+	}
+
+	bool equal(unsigned int lhs, unsigned int rhs) const
+	{
+		const unsigned int* lt = indices + lhs * 3;
+		const unsigned int* rt = indices + rhs * 3;
+
+		return lt[0] == rt[0] && lt[1] == rt[1] && lt[2] == rt[2];
+	}
+};
+
+static void computeVertexIds(unsigned int* vertex_ids, const Vector3* vertex_positions, const unsigned char* vertex_lock, size_t vertex_count, int grid_size)
+{
+	assert(grid_size >= 1 && grid_size <= 1024);
+	float cell_scale = float(grid_size - 1);
+
+	for (size_t i = 0; i < vertex_count; ++i)
+	{
+		const Vector3& v = vertex_positions[i];
+
+		int xi = int(v.x * cell_scale + 0.5f);
+		int yi = int(v.y * cell_scale + 0.5f);
+		int zi = int(v.z * cell_scale + 0.5f);
+
+		if (vertex_lock && (vertex_lock[i] & meshopt_SimplifyVertex_Lock))
+			vertex_ids[i] = (1 << 30) | unsigned(i);
+		else
+			vertex_ids[i] = (xi << 20) | (yi << 10) | zi;
+	}
+}
+
+static size_t countTriangles(const unsigned int* vertex_ids, const unsigned int* indices, size_t index_count)
+{
+	size_t result = 0;
+
+	for (size_t i = 0; i < index_count; i += 3)
+	{
+		unsigned int id0 = vertex_ids[indices[i + 0]];
+		unsigned int id1 = vertex_ids[indices[i + 1]];
+		unsigned int id2 = vertex_ids[indices[i + 2]];
+
+		result += (id0 != id1) & (id0 != id2) & (id1 != id2);
+	}
+
+	return result;
+}
+
+static size_t fillVertexCells(unsigned int* table, size_t table_size, unsigned int* vertex_cells, const unsigned int* vertex_ids, size_t vertex_count)
+{
+	CellHasher hasher = {vertex_ids};
+
+	memset(table, -1, table_size * sizeof(unsigned int));
+
+	size_t result = 0;
+
+	for (size_t i = 0; i < vertex_count; ++i)
+	{
+		unsigned int* entry = hashLookup2(table, table_size, hasher, unsigned(i), ~0u);
+
+		if (*entry == ~0u)
+		{
+			*entry = unsigned(i);
+			vertex_cells[i] = unsigned(result++);
+		}
+		else
+		{
+			vertex_cells[i] = vertex_cells[*entry];
+		}
+	}
+
+	return result;
+}
+
+static size_t countVertexCells(unsigned int* table, size_t table_size, const unsigned int* vertex_ids, size_t vertex_count)
+{
+	IdHasher hasher;
+
+	memset(table, -1, table_size * sizeof(unsigned int));
+
+	size_t result = 0;
+
+	for (size_t i = 0; i < vertex_count; ++i)
+	{
+		unsigned int id = vertex_ids[i];
+		unsigned int* entry = hashLookup2(table, table_size, hasher, id, ~0u);
+
+		result += (*entry == ~0u);
+		*entry = id;
+	}
+
+	return result;
+}
+
+static void fillCellQuadrics(Quadric* cell_quadrics, const unsigned int* indices, size_t index_count, const Vector3* vertex_positions, const unsigned int* vertex_cells)
+{
+	for (size_t i = 0; i < index_count; i += 3)
+	{
+		unsigned int i0 = indices[i + 0];
+		unsigned int i1 = indices[i + 1];
+		unsigned int i2 = indices[i + 2];
+
+		unsigned int c0 = vertex_cells[i0];
+		unsigned int c1 = vertex_cells[i1];
+		unsigned int c2 = vertex_cells[i2];
+
+		int single_cell = (c0 == c1) & (c0 == c2);
+
+		Quadric Q;
+		quadricFromTriangle(Q, vertex_positions[i0], vertex_positions[i1], vertex_positions[i2], single_cell ? 3.f : 1.f);
+
+		if (single_cell)
+		{
+			quadricAdd(cell_quadrics[c0], Q);
+		}
+		else
+		{
+			quadricAdd(cell_quadrics[c0], Q);
+			quadricAdd(cell_quadrics[c1], Q);
+			quadricAdd(cell_quadrics[c2], Q);
+		}
+	}
+}
+
+static void fillCellReservoirs(Reservoir* cell_reservoirs, size_t cell_count, const Vector3* vertex_positions, const float* vertex_colors, size_t vertex_colors_stride, size_t vertex_count, const unsigned int* vertex_cells)
+{
+	static const float dummy_color[] = {0.f, 0.f, 0.f};
+
+	size_t vertex_colors_stride_float = vertex_colors_stride / sizeof(float);
+
+	for (size_t i = 0; i < vertex_count; ++i)
+	{
+		unsigned int cell = vertex_cells[i];
+		const Vector3& v = vertex_positions[i];
+		Reservoir& r = cell_reservoirs[cell];
+
+		const float* color = vertex_colors ? &vertex_colors[i * vertex_colors_stride_float] : dummy_color;
+
+		r.x += v.x;
+		r.y += v.y;
+		r.z += v.z;
+		r.r += color[0];
+		r.g += color[1];
+		r.b += color[2];
+		r.w += 1.f;
+	}
+
+	for (size_t i = 0; i < cell_count; ++i)
+	{
+		Reservoir& r = cell_reservoirs[i];
+
+		float iw = r.w == 0.f ? 0.f : 1.f / r.w;
+
+		r.x *= iw;
+		r.y *= iw;
+		r.z *= iw;
+		r.r *= iw;
+		r.g *= iw;
+		r.b *= iw;
+	}
+}
+
+static void fillCellRemap(unsigned int* cell_remap, float* cell_errors, size_t cell_count, const unsigned int* vertex_cells, const Quadric* cell_quadrics, const Vector3* vertex_positions, size_t vertex_count)
+{
+	memset(cell_remap, -1, cell_count * sizeof(unsigned int));
+
+	for (size_t i = 0; i < vertex_count; ++i)
+	{
+		unsigned int cell = vertex_cells[i];
+		float error = quadricError(cell_quadrics[cell], vertex_positions[i]);
+
+		if (cell_remap[cell] == ~0u || cell_errors[cell] > error)
+		{
+			cell_remap[cell] = unsigned(i);
+			cell_errors[cell] = error;
+		}
+	}
+}
+
+static void fillCellRemap(unsigned int* cell_remap, float* cell_errors, size_t cell_count, const unsigned int* vertex_cells, const Reservoir* cell_reservoirs, const Vector3* vertex_positions, const float* vertex_colors, size_t vertex_colors_stride, float color_weight, size_t vertex_count)
+{
+	static const float dummy_color[] = {0.f, 0.f, 0.f};
+
+	size_t vertex_colors_stride_float = vertex_colors_stride / sizeof(float);
+
+	memset(cell_remap, -1, cell_count * sizeof(unsigned int));
+
+	for (size_t i = 0; i < vertex_count; ++i)
+	{
+		unsigned int cell = vertex_cells[i];
+		const Vector3& v = vertex_positions[i];
+		const Reservoir& r = cell_reservoirs[cell];
+
+		const float* color = vertex_colors ? &vertex_colors[i * vertex_colors_stride_float] : dummy_color;
+
+		float pos_error = (v.x - r.x) * (v.x - r.x) + (v.y - r.y) * (v.y - r.y) + (v.z - r.z) * (v.z - r.z);
+		float col_error = (color[0] - r.r) * (color[0] - r.r) + (color[1] - r.g) * (color[1] - r.g) + (color[2] - r.b) * (color[2] - r.b);
+		float error = pos_error + color_weight * col_error;
+
+		if (cell_remap[cell] == ~0u || cell_errors[cell] > error)
+		{
+			cell_remap[cell] = unsigned(i);
+			cell_errors[cell] = error;
+		}
+	}
+}
+
+static size_t filterTriangles(unsigned int* destination, unsigned int* tritable, size_t tritable_size, const unsigned int* indices, size_t index_count, const unsigned int* vertex_cells, const unsigned int* cell_remap)
+{
+	TriangleHasher hasher = {destination};
+
+	memset(tritable, -1, tritable_size * sizeof(unsigned int));
+
+	size_t result = 0;
+
+	for (size_t i = 0; i < index_count; i += 3)
+	{
+		unsigned int c0 = vertex_cells[indices[i + 0]];
+		unsigned int c1 = vertex_cells[indices[i + 1]];
+		unsigned int c2 = vertex_cells[indices[i + 2]];
+
+		if (c0 != c1 && c0 != c2 && c1 != c2)
+		{
+			unsigned int a = cell_remap[c0];
+			unsigned int b = cell_remap[c1];
+			unsigned int c = cell_remap[c2];
+
+			if (b < a && b < c)
+			{
+				unsigned int t = a;
+				a = b, b = c, c = t;
+			}
+			else if (c < a && c < b)
+			{
+				unsigned int t = c;
+				c = b, b = a, a = t;
+			}
+
+			destination[result * 3 + 0] = a;
+			destination[result * 3 + 1] = b;
+			destination[result * 3 + 2] = c;
+
+			unsigned int* entry = hashLookup2(tritable, tritable_size, hasher, unsigned(result), ~0u);
+
+			if (*entry == ~0u)
+				*entry = unsigned(result++);
+		}
+	}
+
+	return result * 3;
+}
+
+static float interpolate(float y, float x0, float y0, float x1, float y1, float x2, float y2)
+{
+	// three point interpolation from "revenge of interpolation search" paper
+	float num = (y1 - y) * (x1 - x2) * (x1 - x0) * (y2 - y0);
+	float den = (y2 - y) * (x1 - x2) * (y0 - y1) + (y0 - y) * (x1 - x0) * (y1 - y2);
+	return x1 + (den == 0.f ? 0.f : num / den);
+}
+
+} // namespace meshopt
+
+// Note: this is only exposed for development purposes; do *not* use
+enum
+{
+	meshopt_SimplifyInternalSolve = 1 << 29,
+	meshopt_SimplifyInternalDebug = 1 << 30
+};
+
+size_t meshopt_simplifyEdge(unsigned int* destination, const unsigned int* indices, size_t index_count, const float* vertex_positions_data, size_t vertex_count, size_t vertex_positions_stride, const float* vertex_attributes_data, size_t vertex_attributes_stride, const float* attribute_weights, size_t attribute_count, const unsigned char* vertex_lock, size_t target_index_count, float target_error, unsigned int options, float* out_result_error)
+{
+	using namespace meshopt;
+
+	assert(index_count % 3 == 0);
+	assert(vertex_positions_stride >= 12 && vertex_positions_stride <= 256);
+	assert(vertex_positions_stride % sizeof(float) == 0);
+	assert(target_index_count <= index_count);
+	assert(target_error >= 0);
+	assert(vertex_attributes_stride >= attribute_count * sizeof(float) && vertex_attributes_stride <= 256);
+	assert(vertex_attributes_stride % sizeof(float) == 0);
+	assert(attribute_count <= kMaxAttributes);
+	for (size_t i = 0; i < attribute_count; ++i)
+		assert(attribute_weights[i] >= 0);
+
+	meshopt_Allocator allocator;
+
+	unsigned int* result = destination;
+	if (result != indices)
+		memcpy(result, indices, index_count * sizeof(unsigned int));
+
+	// build an index remap and update indices/vertex_count to minimize the subsequent work
+	// note: as a consequence, errors will be computed relative to the subset extent
+	unsigned int* sparse_remap = NULL;
+	if (options & meshopt_SimplifySparse)
+		sparse_remap = buildSparseRemap(result, index_count, vertex_count, &vertex_count, allocator);
+
+	// build adjacency information
+	EdgeAdjacency adjacency = {};
+	prepareEdgeAdjacency(adjacency, index_count, vertex_count, allocator);
+	updateEdgeAdjacency(adjacency, result, index_count, vertex_count, NULL);
+
+	// build position remap that maps each vertex to the one with identical position
+	// wedge table stores next vertex with identical position for each vertex
+	unsigned int* remap = allocator.allocate<unsigned int>(vertex_count);
+	unsigned int* wedge = allocator.allocate<unsigned int>(vertex_count);
+	buildPositionRemap(remap, wedge, vertex_positions_data, vertex_count, vertex_positions_stride, sparse_remap, allocator);
+
+	// classify vertices; vertex kind determines collapse rules, see kCanCollapse
+	unsigned char* vertex_kind = allocator.allocate<unsigned char>(vertex_count);
+	unsigned int* loop = allocator.allocate<unsigned int>(vertex_count);
+	unsigned int* loopback = allocator.allocate<unsigned int>(vertex_count);
+	classifyVertices(vertex_kind, loop, loopback, vertex_count, adjacency, remap, wedge, vertex_lock, sparse_remap, options);
+
+#if TRACE
+	size_t unique_positions = 0;
+	for (size_t i = 0; i < vertex_count; ++i)
+		unique_positions += remap[i] == i;
+
+	printf("position remap: %d vertices => %d positions\n", int(vertex_count), int(unique_positions));
+
+	size_t kinds[Kind_Count] = {};
+	for (size_t i = 0; i < vertex_count; ++i)
+		kinds[vertex_kind[i]] += remap[i] == i;
+
+	printf("kinds: manifold %d, border %d, seam %d, complex %d, locked %d\n",
+	    int(kinds[Kind_Manifold]), int(kinds[Kind_Border]), int(kinds[Kind_Seam]), int(kinds[Kind_Complex]), int(kinds[Kind_Locked]));
+#endif
+
+	Vector3* vertex_positions = allocator.allocate<Vector3>(vertex_count);
+	float vertex_offset[3] = {};
+	float vertex_scale = rescalePositions(vertex_positions, vertex_positions_data, vertex_count, vertex_positions_stride, sparse_remap, vertex_offset);
+
+	float* vertex_attributes = NULL;
+	unsigned int attribute_remap[kMaxAttributes];
+
+	if (attribute_count)
+	{
+		// remap attributes to only include ones with weight > 0 to minimize memory/compute overhead for quadrics
+		size_t attributes_used = 0;
+		for (size_t i = 0; i < attribute_count; ++i)
+			if (attribute_weights[i] > 0)
+				attribute_remap[attributes_used++] = unsigned(i);
+
+		attribute_count = attributes_used;
+		vertex_attributes = allocator.allocate<float>(vertex_count * attribute_count);
+		rescaleAttributes(vertex_attributes, vertex_attributes_data, vertex_count, vertex_attributes_stride, attribute_weights, attribute_count, attribute_remap, sparse_remap);
+	}
+
+	Quadric* vertex_quadrics = allocator.allocate<Quadric>(vertex_count);
+	memset(vertex_quadrics, 0, vertex_count * sizeof(Quadric));
+
+	Quadric* attribute_quadrics = NULL;
+	QuadricGrad* attribute_gradients = NULL;
+	QuadricGrad* volume_gradients = NULL;
+
+	if (attribute_count)
+	{
+		attribute_quadrics = allocator.allocate<Quadric>(vertex_count);
+		memset(attribute_quadrics, 0, vertex_count * sizeof(Quadric));
+
+		attribute_gradients = allocator.allocate<QuadricGrad>(vertex_count * attribute_count);
+		memset(attribute_gradients, 0, vertex_count * attribute_count * sizeof(QuadricGrad));
+
+		if (options & meshopt_SimplifyInternalSolve)
+		{
+			volume_gradients = allocator.allocate<QuadricGrad>(vertex_count);
+			memset(volume_gradients, 0, vertex_count * sizeof(QuadricGrad));
+		}
+	}
+
+	fillFaceQuadrics(vertex_quadrics, volume_gradients, result, index_count, vertex_positions, remap);
+	fillVertexQuadrics(vertex_quadrics, vertex_positions, vertex_count, remap, vertex_lock, sparse_remap, options);
+	fillEdgeQuadrics(vertex_quadrics, result, index_count, vertex_positions, remap, vertex_kind, loop, loopback);
+
+	if (attribute_count)
+		fillAttributeQuadrics(attribute_quadrics, attribute_gradients, result, index_count, vertex_positions, vertex_attributes, attribute_count);
+
+	unsigned int* components = NULL;
+	float* component_errors = NULL;
+	size_t component_count = 0;
+	float component_nexterror = 0;
+
+	if (options & meshopt_SimplifyPrune)
+	{
+		components = allocator.allocate<unsigned int>(vertex_count);
+		component_count = buildComponents(components, vertex_count, result, index_count, remap);
+
+		component_errors = allocator.allocate<float>(component_count * 4); // overallocate for temporary use inside measureComponents
+		measureComponents(component_errors, component_count, components, vertex_positions, vertex_count);
+
+		component_nexterror = FLT_MAX;
+		for (size_t i = 0; i < component_count; ++i)
+			component_nexterror = component_nexterror > component_errors[i] ? component_errors[i] : component_nexterror;
+
+#if TRACE
+		printf("components: %d (min error %e)\n", int(component_count), sqrtf(component_nexterror));
+#endif
+	}
+
+#if TRACE
+	size_t pass_count = 0;
+#endif
+
+	size_t collapse_capacity = boundEdgeCollapses(adjacency, vertex_count, index_count, vertex_kind);
+
+	Collapse* edge_collapses = allocator.allocate<Collapse>(collapse_capacity);
+	unsigned int* collapse_order = allocator.allocate<unsigned int>(collapse_capacity);
+	unsigned int* collapse_remap = allocator.allocate<unsigned int>(vertex_count);
+	unsigned char* collapse_locked = allocator.allocate<unsigned char>(vertex_count);
+
+	size_t result_count = index_count;
+	float result_error = 0;
+	float vertex_error = 0;
+
+	// target_error input is linear; we need to adjust it to match quadricError units
+	float error_scale = (options & meshopt_SimplifyErrorAbsolute) ? vertex_scale : 1.f;
+	float error_limit = (target_error * target_error) / (error_scale * error_scale);
+
+	while (result_count > target_index_count)
+	{
+		// note: throughout the simplification process adjacency structure reflects welded topology for result-in-progress
+		updateEdgeAdjacency(adjacency, result, result_count, vertex_count, remap);
+
+		size_t edge_collapse_count = pickEdgeCollapses(edge_collapses, collapse_capacity, result, result_count, remap, vertex_kind, loop, loopback);
+		assert(edge_collapse_count <= collapse_capacity);
+
+		// no edges can be collapsed any more due to topology restrictions
+		if (edge_collapse_count == 0)
+			break;
+
+#if TRACE
+		printf("pass %d:%c", int(pass_count++), TRACE >= 2 ? '\n' : ' ');
+#endif
+
+		rankEdgeCollapses(edge_collapses, edge_collapse_count, vertex_positions, vertex_attributes, vertex_quadrics, attribute_quadrics, attribute_gradients, attribute_count, remap, wedge, vertex_kind, loop, loopback);
+
+		sortEdgeCollapses(collapse_order, edge_collapses, edge_collapse_count);
+
+		size_t triangle_collapse_goal = (result_count - target_index_count) / 3;
+
+		for (size_t i = 0; i < vertex_count; ++i)
+			collapse_remap[i] = unsigned(i);
+
+		memset(collapse_locked, 0, vertex_count);
+
+		size_t collapses = performEdgeCollapses(collapse_remap, collapse_locked, edge_collapses, edge_collapse_count, collapse_order, remap, wedge, vertex_kind, loop, loopback, vertex_positions, adjacency, triangle_collapse_goal, error_limit, result_error);
+
+		// no edges can be collapsed any more due to hitting the error limit or triangle collapse limit
+		if (collapses == 0)
+			break;
+
+		updateQuadrics(collapse_remap, vertex_count, vertex_quadrics, volume_gradients, attribute_quadrics, attribute_gradients, attribute_count, vertex_positions, remap, vertex_error);
+
+		// updateQuadrics will update vertex error if we use attributes, but if we don't then result_error and vertex_error are equivalent
+		vertex_error = attribute_count == 0 ? result_error : vertex_error;
+
+		// note: we update loops following edge collapses, but after this we might still have stale loop data
+		// this can happen when a triangle with a loop edge gets collapsed along a non-loop edge
+		// that works since a loop that points to a vertex that is no longer connected is not affecting collapse logic
+		remapEdgeLoops(loop, vertex_count, collapse_remap);
+		remapEdgeLoops(loopback, vertex_count, collapse_remap);
+
+		result_count = remapIndexBuffer(result, result_count, collapse_remap, remap);
+
+		if ((options & meshopt_SimplifyPrune) && result_count > target_index_count && component_nexterror <= vertex_error)
+			result_count = pruneComponents(result, result_count, components, component_errors, component_count, vertex_error, component_nexterror);
+	}
+
+	// at this point, component_nexterror might be stale: component it references may have been removed through a series of edge collapses
+	bool component_nextstale = true;
+
+	// we're done with the regular simplification but we're still short of the target; try pruning more aggressively towards error_limit
+	while ((options & meshopt_SimplifyPrune) && result_count > target_index_count && component_nexterror <= error_limit)
+	{
+#if TRACE
+		printf("pass %d: cleanup; ", int(pass_count++));
+#endif
+
+		float component_cutoff = component_nexterror * 1.5f < error_limit ? component_nexterror * 1.5f : error_limit;
+
+		// track maximum error in eligible components as we are increasing resulting error
+		float component_maxerror = 0;
+		for (size_t i = 0; i < component_count; ++i)
+			if (component_errors[i] > component_maxerror && component_errors[i] <= component_cutoff)
+				component_maxerror = component_errors[i];
+
+		size_t new_count = pruneComponents(result, result_count, components, component_errors, component_count, component_cutoff, component_nexterror);
+		if (new_count == result_count && !component_nextstale)
+			break;
+
+		component_nextstale = false; // pruneComponents guarantees next error is up to date
+		result_count = new_count;
+		result_error = result_error < component_maxerror ? component_maxerror : result_error;
+		vertex_error = vertex_error < component_maxerror ? component_maxerror : vertex_error;
+	}
+
+#if TRACE
+	printf("result: %d triangles, error: %e (pos %.3e); total %d passes\n", int(result_count / 3), sqrtf(result_error), sqrtf(vertex_error), int(pass_count));
+#endif
+
+	// if solve is requested, update input buffers destructively from internal data
+	if (options & meshopt_SimplifyInternalSolve)
+	{
+		unsigned char* vertex_update = collapse_locked; // reuse as scratch space
+		memset(vertex_update, 0, vertex_count);
+
+		// limit quadric solve to vertices that are still used in the result
+		for (size_t i = 0; i < result_count; ++i)
+		{
+			unsigned int v = result[i];
+
+			// mark the vertex for finalizeVertices and root vertex for solve*
+			vertex_update[remap[v]] = vertex_update[v] = 1;
+		}
+
+		// edge adjacency may be stale as we haven't updated it after last series of edge collapses
+		updateEdgeAdjacency(adjacency, result, result_count, vertex_count, remap);
+
+		solvePositions(vertex_positions, vertex_count, vertex_quadrics, volume_gradients, attribute_quadrics, attribute_gradients, attribute_count, remap, wedge, adjacency, vertex_kind, vertex_update);
+
+		if (attribute_count)
+			solveAttributes(vertex_positions, vertex_attributes, vertex_count, attribute_quadrics, attribute_gradients, attribute_count, remap, wedge, vertex_kind, vertex_update);
+
+		finalizeVertices(const_cast<float*>(vertex_positions_data), vertex_positions_stride, const_cast<float*>(vertex_attributes_data), vertex_attributes_stride, attribute_weights, attribute_count, vertex_count, vertex_positions, vertex_attributes, sparse_remap, attribute_remap, vertex_scale, vertex_offset, vertex_kind, vertex_update, vertex_lock);
+	}
+
+	// if debug visualization data is requested, fill it instead of index data; for simplicity, this doesn't work with sparsity
+	if ((options & meshopt_SimplifyInternalDebug) && !sparse_remap)
+	{
+		assert(Kind_Count <= 8 && vertex_count < (1 << 28)); // 3 bit kind, 1 bit loop
+
+		for (size_t i = 0; i < result_count; i += 3)
+		{
+			unsigned int a = result[i + 0], b = result[i + 1], c = result[i + 2];
+
+			result[i + 0] |= (vertex_kind[a] << 28) | (unsigned(loop[a] == b || loopback[b] == a) << 31);
+			result[i + 1] |= (vertex_kind[b] << 28) | (unsigned(loop[b] == c || loopback[c] == b) << 31);
+			result[i + 2] |= (vertex_kind[c] << 28) | (unsigned(loop[c] == a || loopback[a] == c) << 31);
+		}
+	}
+
+	// convert resulting indices back into the dense space of the larger mesh
+	if (sparse_remap)
+		for (size_t i = 0; i < result_count; ++i)
+			result[i] = sparse_remap[result[i]];
+
+	// result_error is quadratic; we need to remap it back to linear
+	if (out_result_error)
+		*out_result_error = sqrtf(result_error) * error_scale;
+
+	return result_count;
+}
+
+size_t meshopt_simplify(unsigned int* destination, const unsigned int* indices, size_t index_count, const float* vertex_positions_data, size_t vertex_count, size_t vertex_positions_stride, size_t target_index_count, float target_error, unsigned int options, float* out_result_error)
+{
+	assert((options & meshopt_SimplifyInternalSolve) == 0); // use meshopt_simplifyWithUpdate instead
+
+	return meshopt_simplifyEdge(destination, indices, index_count, vertex_positions_data, vertex_count, vertex_positions_stride, NULL, 0, NULL, 0, NULL, target_index_count, target_error, options, out_result_error);
+}
+
+size_t meshopt_simplifyWithAttributes(unsigned int* destination, const unsigned int* indices, size_t index_count, const float* vertex_positions_data, size_t vertex_count, size_t vertex_positions_stride, const float* vertex_attributes_data, size_t vertex_attributes_stride, const float* attribute_weights, size_t attribute_count, const unsigned char* vertex_lock, size_t target_index_count, float target_error, unsigned int options, float* out_result_error)
+{
+	assert((options & meshopt_SimplifyInternalSolve) == 0); // use meshopt_simplifyWithUpdate instead
+
+	return meshopt_simplifyEdge(destination, indices, index_count, vertex_positions_data, vertex_count, vertex_positions_stride, vertex_attributes_data, vertex_attributes_stride, attribute_weights, attribute_count, vertex_lock, target_index_count, target_error, options, out_result_error);
+}
+
+size_t meshopt_simplifyWithUpdate(unsigned int* indices, size_t index_count, float* vertex_positions_data, size_t vertex_count, size_t vertex_positions_stride, float* vertex_attributes_data, size_t vertex_attributes_stride, const float* attribute_weights, size_t attribute_count, const unsigned char* vertex_lock, size_t target_index_count, float target_error, unsigned int options, float* out_result_error)
+{
+	return meshopt_simplifyEdge(indices, indices, index_count, vertex_positions_data, vertex_count, vertex_positions_stride, vertex_attributes_data, vertex_attributes_stride, attribute_weights, attribute_count, vertex_lock, target_index_count, target_error, options | meshopt_SimplifyInternalSolve, out_result_error);
+}
+
+size_t meshopt_simplifySloppy(unsigned int* destination, const unsigned int* indices, size_t index_count, const float* vertex_positions_data, size_t vertex_count, size_t vertex_positions_stride, const unsigned char* vertex_lock, size_t target_index_count, float target_error, float* out_result_error)
+{
+	using namespace meshopt;
+
+	assert(index_count % 3 == 0);
+	assert(vertex_positions_stride >= 12 && vertex_positions_stride <= 256);
+	assert(vertex_positions_stride % sizeof(float) == 0);
+	assert(target_index_count <= index_count);
+	assert(target_error >= 0);
+
+	// we expect to get ~2 triangles/vertex in the output
+	size_t target_cell_count = target_index_count / 6;
+
+	meshopt_Allocator allocator;
+
+	Vector3* vertex_positions = allocator.allocate<Vector3>(vertex_count);
+	rescalePositions(vertex_positions, vertex_positions_data, vertex_count, vertex_positions_stride);
+
+	// find the optimal grid size using guided binary search
+#if TRACE
+	printf("source: %d vertices, %d triangles\n", int(vertex_count), int(index_count / 3));
+	printf("target: %d cells, %d triangles\n", int(target_cell_count), int(target_index_count / 3));
+#endif
+
+	unsigned int* vertex_ids = allocator.allocate<unsigned int>(vertex_count);
+
+	const int kInterpolationPasses = 5;
+
+	// invariant: # of triangles in min_grid <= target_count
+	int min_grid = int(1.f / (target_error < 1e-3f ? 1e-3f : (target_error < 1.f ? target_error : 1.f)));
+	int max_grid = 1025;
+	size_t min_triangles = 0;
+	size_t max_triangles = index_count / 3;
+
+	// when we're error-limited, we compute the triangle count for the min. size; this accelerates convergence and provides the correct answer when we can't use a larger grid
+	if (min_grid > 1 || vertex_lock)
+	{
+		computeVertexIds(vertex_ids, vertex_positions, vertex_lock, vertex_count, min_grid);
+		min_triangles = countTriangles(vertex_ids, indices, index_count);
+	}
+
+	// instead of starting in the middle, let's guess as to what the answer might be! triangle count usually grows as a square of grid size...
+	int next_grid_size = int(sqrtf(float(target_cell_count)) + 0.5f);
+
+	for (int pass = 0; pass < 10 + kInterpolationPasses; ++pass)
+	{
+		if (min_triangles >= target_index_count / 3 || max_grid - min_grid <= 1)
+			break;
+
+		// we clamp the prediction of the grid size to make sure that the search converges
+		int grid_size = next_grid_size;
+		grid_size = (grid_size <= min_grid) ? min_grid + 1 : (grid_size >= max_grid ? max_grid - 1 : grid_size);
+
+		computeVertexIds(vertex_ids, vertex_positions, vertex_lock, vertex_count, grid_size);
+		size_t triangles = countTriangles(vertex_ids, indices, index_count);
+
+#if TRACE
+		printf("pass %d (%s): grid size %d, triangles %d, %s\n",
+		    pass, (pass == 0) ? "guess" : (pass <= kInterpolationPasses ? "lerp" : "binary"),
+		    grid_size, int(triangles),
+		    (triangles <= target_index_count / 3) ? "under" : "over");
+#endif
+
+		float tip = interpolate(float(size_t(target_index_count / 3)), float(min_grid), float(min_triangles), float(grid_size), float(triangles), float(max_grid), float(max_triangles));
+
+		if (triangles <= target_index_count / 3)
+		{
+			min_grid = grid_size;
+			min_triangles = triangles;
+		}
+		else
+		{
+			max_grid = grid_size;
+			max_triangles = triangles;
+		}
+
+		// we start by using interpolation search - it usually converges faster
+		// however, interpolation search has a worst case of O(N) so we switch to binary search after a few iterations which converges in O(logN)
+		next_grid_size = (pass < kInterpolationPasses) ? int(tip + 0.5f) : (min_grid + max_grid) / 2;
+	}
+
+	if (min_triangles == 0)
+	{
+		if (out_result_error)
+			*out_result_error = 1.f;
+
+		return 0;
+	}
+
+	// build vertex->cell association by mapping all vertices with the same quantized position to the same cell
+	size_t table_size = hashBuckets2(vertex_count);
+	unsigned int* table = allocator.allocate<unsigned int>(table_size);
+
+	unsigned int* vertex_cells = allocator.allocate<unsigned int>(vertex_count);
+
+	computeVertexIds(vertex_ids, vertex_positions, vertex_lock, vertex_count, min_grid);
+	size_t cell_count = fillVertexCells(table, table_size, vertex_cells, vertex_ids, vertex_count);
+
+	// build a quadric for each target cell
+	Quadric* cell_quadrics = allocator.allocate<Quadric>(cell_count);
+	memset(cell_quadrics, 0, cell_count * sizeof(Quadric));
+
+	fillCellQuadrics(cell_quadrics, indices, index_count, vertex_positions, vertex_cells);
+
+	// for each target cell, find the vertex with the minimal error
+	unsigned int* cell_remap = allocator.allocate<unsigned int>(cell_count);
+	float* cell_errors = allocator.allocate<float>(cell_count);
+
+	fillCellRemap(cell_remap, cell_errors, cell_count, vertex_cells, cell_quadrics, vertex_positions, vertex_count);
+
+	// compute error
+	float result_error = 0.f;
+
+	for (size_t i = 0; i < cell_count; ++i)
+		result_error = result_error < cell_errors[i] ? cell_errors[i] : result_error;
+
+	// vertex collapses often result in duplicate triangles; we need a table to filter them out
+	size_t tritable_size = hashBuckets2(min_triangles);
+	unsigned int* tritable = allocator.allocate<unsigned int>(tritable_size);
+
+	// note: this is the first and last write to destination, which allows aliasing destination with indices
+	size_t write = filterTriangles(destination, tritable, tritable_size, indices, index_count, vertex_cells, cell_remap);
+
+#if TRACE
+	printf("result: grid size %d, %d cells, %d triangles (%d unfiltered), error %e\n", min_grid, int(cell_count), int(write / 3), int(min_triangles), sqrtf(result_error));
+#endif
+
+	if (out_result_error)
+		*out_result_error = sqrtf(result_error);
+
+	return write;
+}
+
+size_t meshopt_simplifyPrune(unsigned int* destination, const unsigned int* indices, size_t index_count, const float* vertex_positions_data, size_t vertex_count, size_t vertex_positions_stride, float target_error)
+{
+	using namespace meshopt;
+
+	assert(index_count % 3 == 0);
+	assert(vertex_positions_stride >= 12 && vertex_positions_stride <= 256);
+	assert(vertex_positions_stride % sizeof(float) == 0);
+	assert(target_error >= 0);
+
+	meshopt_Allocator allocator;
+
+	unsigned int* result = destination;
+	if (result != indices)
+		memcpy(result, indices, index_count * sizeof(unsigned int));
+
+	// build position remap that maps each vertex to the one with identical position
+	unsigned int* remap = allocator.allocate<unsigned int>(vertex_count);
+	buildPositionRemap(remap, NULL, vertex_positions_data, vertex_count, vertex_positions_stride, NULL, allocator);
+
+	Vector3* vertex_positions = allocator.allocate<Vector3>(vertex_count);
+	rescalePositions(vertex_positions, vertex_positions_data, vertex_count, vertex_positions_stride, NULL);
+
+	unsigned int* components = allocator.allocate<unsigned int>(vertex_count);
+	size_t component_count = buildComponents(components, vertex_count, indices, index_count, remap);
+
+	float* component_errors = allocator.allocate<float>(component_count * 4); // overallocate for temporary use inside measureComponents
+	measureComponents(component_errors, component_count, components, vertex_positions, vertex_count);
+
+	float component_nexterror = 0;
+	size_t result_count = pruneComponents(result, index_count, components, component_errors, component_count, target_error * target_error, component_nexterror);
+
+	return result_count;
+}
+
+size_t meshopt_simplifyPoints(unsigned int* destination, const float* vertex_positions_data, size_t vertex_count, size_t vertex_positions_stride, const float* vertex_colors, size_t vertex_colors_stride, float color_weight, size_t target_vertex_count)
+{
+	using namespace meshopt;
+
+	assert(vertex_positions_stride >= 12 && vertex_positions_stride <= 256);
+	assert(vertex_positions_stride % sizeof(float) == 0);
+	assert(vertex_colors_stride == 0 || (vertex_colors_stride >= 12 && vertex_colors_stride <= 256));
+	assert(vertex_colors_stride % sizeof(float) == 0);
+	assert(vertex_colors == NULL || vertex_colors_stride != 0);
+	assert(target_vertex_count <= vertex_count);
+
+	size_t target_cell_count = target_vertex_count;
+
+	if (target_cell_count == 0)
+		return 0;
+
+	meshopt_Allocator allocator;
+
+	Vector3* vertex_positions = allocator.allocate<Vector3>(vertex_count);
+	rescalePositions(vertex_positions, vertex_positions_data, vertex_count, vertex_positions_stride);
+
+	// find the optimal grid size using guided binary search
+#if TRACE
+	printf("source: %d vertices\n", int(vertex_count));
+	printf("target: %d cells\n", int(target_cell_count));
+#endif
+
+	unsigned int* vertex_ids = allocator.allocate<unsigned int>(vertex_count);
+
+	size_t table_size = hashBuckets2(vertex_count);
+	unsigned int* table = allocator.allocate<unsigned int>(table_size);
+
+	const int kInterpolationPasses = 5;
+
+	// invariant: # of vertices in min_grid <= target_count
+	int min_grid = 0;
+	int max_grid = 1025;
+	size_t min_vertices = 0;
+	size_t max_vertices = vertex_count;
+
+	// instead of starting in the middle, let's guess as to what the answer might be! surface point count usually grows as a square of grid size...
+	int next_grid_size = int(sqrtf(float(target_cell_count)) + 0.5f);
+
+	for (int pass = 0; pass < 10 + kInterpolationPasses; ++pass)
+	{
+		assert(min_vertices < target_vertex_count);
+		assert(max_grid - min_grid > 1);
+
+		// we clamp the prediction of the grid size to make sure that the search converges
+		int grid_size = next_grid_size;
+		grid_size = (grid_size <= min_grid) ? min_grid + 1 : (grid_size >= max_grid ? max_grid - 1 : grid_size);
+
+		computeVertexIds(vertex_ids, vertex_positions, NULL, vertex_count, grid_size);
+		size_t vertices = countVertexCells(table, table_size, vertex_ids, vertex_count);
+
+#if TRACE
+		printf("pass %d (%s): grid size %d, vertices %d, %s\n",
+		    pass, (pass == 0) ? "guess" : (pass <= kInterpolationPasses ? "lerp" : "binary"),
+		    grid_size, int(vertices),
+		    (vertices <= target_vertex_count) ? "under" : "over");
+#endif
+
+		float tip = interpolate(float(target_vertex_count), float(min_grid), float(min_vertices), float(grid_size), float(vertices), float(max_grid), float(max_vertices));
+
+		if (vertices <= target_vertex_count)
+		{
+			min_grid = grid_size;
+			min_vertices = vertices;
+		}
+		else
+		{
+			max_grid = grid_size;
+			max_vertices = vertices;
+		}
+
+		if (vertices == target_vertex_count || max_grid - min_grid <= 1)
+			break;
+
+		// we start by using interpolation search - it usually converges faster
+		// however, interpolation search has a worst case of O(N) so we switch to binary search after a few iterations which converges in O(logN)
+		next_grid_size = (pass < kInterpolationPasses) ? int(tip + 0.5f) : (min_grid + max_grid) / 2;
+	}
+
+	if (min_vertices == 0)
+		return 0;
+
+	// build vertex->cell association by mapping all vertices with the same quantized position to the same cell
+	unsigned int* vertex_cells = allocator.allocate<unsigned int>(vertex_count);
+
+	computeVertexIds(vertex_ids, vertex_positions, NULL, vertex_count, min_grid);
+	size_t cell_count = fillVertexCells(table, table_size, vertex_cells, vertex_ids, vertex_count);
+
+	// accumulate points into a reservoir for each target cell
+	Reservoir* cell_reservoirs = allocator.allocate<Reservoir>(cell_count);
+	memset(cell_reservoirs, 0, cell_count * sizeof(Reservoir));
+
+	fillCellReservoirs(cell_reservoirs, cell_count, vertex_positions, vertex_colors, vertex_colors_stride, vertex_count, vertex_cells);
+
+	// for each target cell, find the vertex with the minimal error
+	unsigned int* cell_remap = allocator.allocate<unsigned int>(cell_count);
+	float* cell_errors = allocator.allocate<float>(cell_count);
+
+	// we scale the color weight to bring it to the same scale as position so that error addition makes sense
+	float color_weight_scaled = color_weight * (min_grid == 1 ? 1.f : 1.f / (min_grid - 1));
+
+	fillCellRemap(cell_remap, cell_errors, cell_count, vertex_cells, cell_reservoirs, vertex_positions, vertex_colors, vertex_colors_stride, color_weight_scaled * color_weight_scaled, vertex_count);
+
+	// copy results to the output
+	assert(cell_count <= target_vertex_count);
+	memcpy(destination, cell_remap, sizeof(unsigned int) * cell_count);
+
+#if TRACE
+	// compute error
+	float result_error = 0.f;
+
+	for (size_t i = 0; i < cell_count; ++i)
+		result_error = result_error < cell_errors[i] ? cell_errors[i] : result_error;
+
+	printf("result: %d cells, %e error\n", int(cell_count), sqrtf(result_error));
+#endif
+
+	return cell_count;
+}
+
+float meshopt_simplifyScale(const float* vertex_positions, size_t vertex_count, size_t vertex_positions_stride)
+{
+	using namespace meshopt;
+
+	assert(vertex_positions_stride >= 12 && vertex_positions_stride <= 256);
+	assert(vertex_positions_stride % sizeof(float) == 0);
+
+	float extent = rescalePositions(NULL, vertex_positions, vertex_count, vertex_positions_stride);
+
+	return extent;
+}
diff --git a/third_party/meshoptimizer/vfetchoptimizer.cpp b/third_party/meshoptimizer/vfetchoptimizer.cpp
new file mode 100644
index 0000000..4847465
--- /dev/null
+++ b/third_party/meshoptimizer/vfetchoptimizer.cpp
@@ -0,0 +1,71 @@
+// This file is part of meshoptimizer library; see meshoptimizer.h for version/license details
+#include "meshoptimizer.h"
+
+#include <assert.h>
+#include <string.h>
+
+size_t meshopt_optimizeVertexFetchRemap(unsigned int* destination, const unsigned int* indices, size_t index_count, size_t vertex_count)
+{
+	memset(destination, -1, vertex_count * sizeof(unsigned int));
+
+	unsigned int next_vertex = 0;
+
+	for (size_t i = 0; i < index_count; ++i)
+	{
+		unsigned int index = indices[i];
+		assert(index < vertex_count);
+
+		if (destination[index] == ~0u)
+		{
+			destination[index] = next_vertex++;
+		}
+	}
+
+	assert(next_vertex <= vertex_count);
+
+	return next_vertex;
+}
+
+size_t meshopt_optimizeVertexFetch(void* destination, unsigned int* indices, size_t index_count, const void* vertices, size_t vertex_count, size_t vertex_size)
+{
+	assert(vertex_size > 0 && vertex_size <= 256);
+
+	meshopt_Allocator allocator;
+
+	// support in-place optimization
+	if (destination == vertices)
+	{
+		unsigned char* vertices_copy = allocator.allocate<unsigned char>(vertex_count * vertex_size);
+		memcpy(vertices_copy, vertices, vertex_count * vertex_size);
+		vertices = vertices_copy;
+	}
+
+	// build vertex remap table
+	unsigned int* vertex_remap = allocator.allocate<unsigned int>(vertex_count);
+	memset(vertex_remap, -1, vertex_count * sizeof(unsigned int));
+
+	unsigned int next_vertex = 0;
+
+	for (size_t i = 0; i < index_count; ++i)
+	{
+		unsigned int index = indices[i];
+		assert(index < vertex_count);
+
+		unsigned int& remap = vertex_remap[index];
+
+		if (remap == ~0u) // vertex was not added to destination VB
+		{
+			// add vertex
+			memcpy(static_cast<unsigned char*>(destination) + next_vertex * vertex_size, static_cast<const unsigned char*>(vertices) + index * vertex_size, vertex_size);
+
+			remap = next_vertex++;
+		}
+
+		// modify indices in place
+		indices[i] = remap;
+	}
+
+	assert(next_vertex <= vertex_count);
+
+	return next_vertex;
+}
diff --git a/third_party/xatlas/xatlas.cpp b/third_party/xatlas/xatlas.cpp
new file mode 100644
index 0000000..5c5c57e
--- /dev/null
+++ b/third_party/xatlas/xatlas.cpp
@@ -0,0 +1,10044 @@
+/*
+MIT License
+
+Copyright (c) 2018-2020 Jonathan Young
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+*/
+/*
+thekla_atlas
+https://github.com/Thekla/thekla_atlas
+MIT License
+Copyright (c) 2013 Thekla, Inc
+Copyright NVIDIA Corporation 2006 -- Ignacio Castano <icastano@nvidia.com>
+
+Fast-BVH
+https://github.com/brandonpelfrey/Fast-BVH
+MIT License
+Copyright (c) 2012 Brandon Pelfrey
+*/
+#include "xatlas.h"
+#ifndef XATLAS_C_API
+#define XATLAS_C_API 0
+#endif
+#if XATLAS_C_API
+#include "xatlas_c.h"
+#endif
+#include <atomic>
+#include <condition_variable>
+#include <mutex>
+#include <thread>
+#include <assert.h>
+#include <float.h> // FLT_MAX
+#include <limits.h>
+#include <math.h>
+#define __STDC_LIMIT_MACROS
+#include <stdint.h>
+#include <stdio.h>
+#include <string.h>
+
+#ifndef XA_DEBUG
+#ifdef NDEBUG
+#define XA_DEBUG 0
+#else
+#define XA_DEBUG 1
+#endif
+#endif
+
+#ifndef XA_PROFILE
+#define XA_PROFILE 0
+#endif
+#if XA_PROFILE
+#include <chrono>
+#endif
+
+#ifndef XA_MULTITHREADED
+#define XA_MULTITHREADED 1
+#endif
+
+#define XA_STR(x) #x
+#define XA_XSTR(x) XA_STR(x)
+
+#ifndef XA_ASSERT
+#define XA_ASSERT(exp) if (!(exp)) { XA_PRINT_WARNING("\rASSERT: %s %s %d\n", XA_XSTR(exp), __FILE__, __LINE__); }
+#endif
+
+#ifndef XA_DEBUG_ASSERT
+#define XA_DEBUG_ASSERT(exp) assert(exp)
+#endif
+
+#ifndef XA_PRINT
+#define XA_PRINT(...) \
+	if (xatlas::internal::s_print && xatlas::internal::s_printVerbose) \
+		xatlas::internal::s_print(__VA_ARGS__);
+#endif
+
+#ifndef XA_PRINT_WARNING
+#define XA_PRINT_WARNING(...) \
+	if (xatlas::internal::s_print) \
+		xatlas::internal::s_print(__VA_ARGS__);
+#endif
+
+#define XA_ALLOC(tag, type) (type *)internal::Realloc(nullptr, sizeof(type), tag, __FILE__, __LINE__)
+#define XA_ALLOC_ARRAY(tag, type, num) (type *)internal::Realloc(nullptr, sizeof(type) * (num), tag, __FILE__, __LINE__)
+#define XA_REALLOC(tag, ptr, type, num) (type *)internal::Realloc(ptr, sizeof(type) * (num), tag, __FILE__, __LINE__)
+#define XA_REALLOC_SIZE(tag, ptr, size) (uint8_t *)internal::Realloc(ptr, size, tag, __FILE__, __LINE__)
+#define XA_FREE(ptr) internal::Realloc(ptr, 0, internal::MemTag::Default, __FILE__, __LINE__)
+#define XA_NEW(tag, type) new (XA_ALLOC(tag, type)) type()
+#define XA_NEW_ARGS(tag, type, ...) new (XA_ALLOC(tag, type)) type(__VA_ARGS__)
+
+#ifdef _MSC_VER
+#define XA_INLINE __forceinline
+#else
+#define XA_INLINE inline
+#endif
+
+#if defined(__clang__) || defined(__GNUC__)
+#define XA_NODISCARD [[nodiscard]]
+#elif defined(_MSC_VER)
+#define XA_NODISCARD _Check_return_
+#else
+#define XA_NODISCARD
+#endif
+
+#define XA_UNUSED(a) ((void)(a))
+
+#define XA_MERGE_CHARTS 1
+#define XA_MERGE_CHARTS_MIN_NORMAL_DEVIATION 0.5f
+#define XA_RECOMPUTE_CHARTS 1
+#define XA_CHECK_PARAM_WINDING 0
+#define XA_CHECK_PIECEWISE_CHART_QUALITY 0
+#define XA_CHECK_T_JUNCTIONS 0
+
+#define XA_DEBUG_HEAP 0
+#define XA_DEBUG_SINGLE_CHART 0
+#define XA_DEBUG_ALL_CHARTS_INVALID 0
+#define XA_DEBUG_EXPORT_ATLAS_IMAGES 0
+#define XA_DEBUG_EXPORT_ATLAS_IMAGES_PER_CHART 0 // Export an atlas image after each chart is added.
+#define XA_DEBUG_EXPORT_BOUNDARY_GRID 0
+#define XA_DEBUG_EXPORT_TGA (XA_DEBUG_EXPORT_ATLAS_IMAGES || XA_DEBUG_EXPORT_BOUNDARY_GRID)
+#define XA_DEBUG_EXPORT_OBJ_FACE_GROUPS 0
+#define XA_DEBUG_EXPORT_OBJ_CHART_GROUPS 0
+#define XA_DEBUG_EXPORT_OBJ_PLANAR_REGIONS 0
+#define XA_DEBUG_EXPORT_OBJ_CHARTS 0
+#define XA_DEBUG_EXPORT_OBJ_TJUNCTION 0 // XA_CHECK_T_JUNCTIONS must also be set
+#define XA_DEBUG_EXPORT_OBJ_CHARTS_AFTER_PARAMETERIZATION 0
+#define XA_DEBUG_EXPORT_OBJ_INVALID_PARAMETERIZATION 0
+#define XA_DEBUG_EXPORT_OBJ_RECOMPUTED_CHARTS 0
+
+#define XA_DEBUG_EXPORT_OBJ (0 \
+	|| XA_DEBUG_EXPORT_OBJ_FACE_GROUPS \
+	|| XA_DEBUG_EXPORT_OBJ_CHART_GROUPS \
+	|| XA_DEBUG_EXPORT_OBJ_PLANAR_REGIONS \
+	|| XA_DEBUG_EXPORT_OBJ_CHARTS \
+	|| XA_DEBUG_EXPORT_OBJ_TJUNCTION \
+	|| XA_DEBUG_EXPORT_OBJ_CHARTS_AFTER_PARAMETERIZATION \
+	|| XA_DEBUG_EXPORT_OBJ_INVALID_PARAMETERIZATION \
+	|| XA_DEBUG_EXPORT_OBJ_RECOMPUTED_CHARTS)
+
+#ifdef _MSC_VER
+#define XA_FOPEN(_file, _filename, _mode) { if (fopen_s(&_file, _filename, _mode) != 0) _file = NULL; }
+#define XA_SPRINTF(_buffer, _size, _format, ...) sprintf_s(_buffer, _size, _format, __VA_ARGS__)
+#else
+#define XA_FOPEN(_file, _filename, _mode) _file = fopen(_filename, _mode)
+#define XA_SPRINTF(_buffer, _size, _format, ...) sprintf(_buffer, _format, __VA_ARGS__)
+#endif
+
+namespace xatlas {
+namespace internal {
+
+static ReallocFunc s_realloc = realloc;
+static FreeFunc s_free = free;
+static PrintFunc s_print = printf;
+static bool s_printVerbose = false;
+
+#if XA_PROFILE
+typedef uint64_t Duration;
+
+#define XA_PROFILE_START(var) const std::chrono::time_point<std::chrono::high_resolution_clock> var##Start = std::chrono::high_resolution_clock::now();
+#define XA_PROFILE_END(var) internal::s_profile.var += uint64_t(std::chrono::duration_cast<std::chrono::microseconds>(std::chrono::high_resolution_clock::now() - var##Start).count());
+#define XA_PROFILE_PRINT_AND_RESET(label, var) XA_PRINT("%s%.2f seconds (%g ms)\n", label, internal::durationToSeconds(internal::s_profile.var), internal::durationToMs(internal::s_profile.var)); internal::s_profile.var = 0u;
+#define XA_PROFILE_ALLOC 0
+
+struct ProfileData
+{
+#if XA_PROFILE_ALLOC
+	std::atomic<Duration> alloc;
+#endif
+	std::chrono::time_point<std::chrono::high_resolution_clock> addMeshRealStart;
+	Duration addMeshReal;
+	Duration addMeshCopyData;
+	std::atomic<Duration> addMeshThread;
+	std::atomic<Duration> addMeshCreateColocals;
+	Duration computeChartsReal;
+	std::atomic<Duration> computeChartsThread;
+	std::atomic<Duration> createFaceGroups;
+	std::atomic<Duration> extractInvalidMeshGeometry;
+	std::atomic<Duration> chartGroupComputeChartsReal;
+	std::atomic<Duration> chartGroupComputeChartsThread;
+	std::atomic<Duration> createChartGroupMesh;
+	std::atomic<Duration> createChartGroupMeshColocals;
+	std::atomic<Duration> createChartGroupMeshBoundaries;
+	std::atomic<Duration> buildAtlas;
+	std::atomic<Duration> buildAtlasInit;
+	std::atomic<Duration> planarCharts;
+	std::atomic<Duration> originalUvCharts;
+	std::atomic<Duration> clusteredCharts;
+	std::atomic<Duration> clusteredChartsPlaceSeeds;
+	std::atomic<Duration> clusteredChartsPlaceSeedsBoundaryIntersection;
+	std::atomic<Duration> clusteredChartsRelocateSeeds;
+	std::atomic<Duration> clusteredChartsReset;
+	std::atomic<Duration> clusteredChartsGrow;
+	std::atomic<Duration> clusteredChartsGrowBoundaryIntersection;
+	std::atomic<Duration> clusteredChartsMerge;
+	std::atomic<Duration> clusteredChartsFillHoles;
+	std::atomic<Duration> copyChartFaces;
+	std::atomic<Duration> createChartMeshAndParameterizeReal;
+	std::atomic<Duration> createChartMeshAndParameterizeThread;
+	std::atomic<Duration> createChartMesh;
+	std::atomic<Duration> parameterizeCharts;
+	std::atomic<Duration> parameterizeChartsOrthogonal;
+	std::atomic<Duration> parameterizeChartsLSCM;
+	std::atomic<Duration> parameterizeChartsRecompute;
+	std::atomic<Duration> parameterizeChartsPiecewise;
+	std::atomic<Duration> parameterizeChartsPiecewiseBoundaryIntersection;
+	std::atomic<Duration> parameterizeChartsEvaluateQuality;
+	Duration packCharts;
+	Duration packChartsAddCharts;
+	std::atomic<Duration> packChartsAddChartsThread;
+	std::atomic<Duration> packChartsAddChartsRestoreTexcoords;
+	Duration packChartsRasterize;
+	Duration packChartsDilate;
+	Duration packChartsFindLocation;
+	Duration packChartsBlit;
+	Duration buildOutputMeshes;
+};
+
+static ProfileData s_profile;
+
+static double durationToMs(Duration c)
+{
+	return (double)c * 0.001;
+}
+
+static double durationToSeconds(Duration c)
+{
+	return (double)c * 0.000001;
+}
+#else
+#define XA_PROFILE_START(var)
+#define XA_PROFILE_END(var)
+#define XA_PROFILE_PRINT_AND_RESET(label, var)
+#define XA_PROFILE_ALLOC 0
+#endif
+
+struct MemTag
+{
+	enum
+	{
+		Default,
+		BitImage,
+		BVH,
+		Matrix,
+		Mesh,
+		MeshBoundaries,
+		MeshColocals,
+		MeshEdgeMap,
+		MeshIndices,
+		MeshNormals,
+		MeshPositions,
+		MeshTexcoords,
+		OpenNL,
+		SegmentAtlasChartCandidates,
+		SegmentAtlasChartFaces,
+		SegmentAtlasMeshData,
+		SegmentAtlasPlanarRegions,
+		Count
+	};
+};
+
+#if XA_DEBUG_HEAP
+struct AllocHeader
+{
+	size_t size;
+	const char *file;
+	int line;
+	int tag;
+	uint32_t id;
+	AllocHeader *prev, *next;
+	bool free;
+};
+
+static std::mutex s_allocMutex;
+static AllocHeader *s_allocRoot = nullptr;
+static size_t s_allocTotalCount = 0, s_allocTotalSize = 0, s_allocPeakSize = 0, s_allocCount[MemTag::Count] = { 0 }, s_allocTotalTagSize[MemTag::Count] = { 0 }, s_allocPeakTagSize[MemTag::Count] = { 0 };
+static uint32_t s_allocId =0 ;
+static constexpr uint32_t kAllocRedzone = 0x12345678;
+
+static void *Realloc(void *ptr, size_t size, int tag, const char *file, int line)
+{
+	std::unique_lock<std::mutex> lock(s_allocMutex);
+	if (!size && !ptr)
+		return nullptr;
+	uint8_t *realPtr = nullptr;
+	AllocHeader *header = nullptr;
+	if (ptr) {
+		realPtr = ((uint8_t *)ptr) - sizeof(AllocHeader);
+		header = (AllocHeader *)realPtr;
+	}
+	if (realPtr && size) {
+		s_allocTotalSize -= header->size;
+		s_allocTotalTagSize[header->tag] -= header->size;
+		// realloc, remove.
+		if (header->prev)
+			header->prev->next = header->next;
+		else
+			s_allocRoot = header->next;
+		if (header->next)
+			header->next->prev = header->prev;
+	}
+	if (!size) {
+		s_allocTotalSize -= header->size;
+		s_allocTotalTagSize[header->tag] -= header->size;
+		XA_ASSERT(!header->free); // double free
+		header->free = true;
+		return nullptr;
+	}
+	size += sizeof(AllocHeader) + sizeof(kAllocRedzone);
+	uint8_t *newPtr = (uint8_t *)s_realloc(realPtr, size);
+	if (!newPtr)
+		return nullptr;
+	header = (AllocHeader *)newPtr;
+	header->size = size;
+	header->file = file;
+	header->line = line;
+	header->tag = tag;
+	header->id = s_allocId++;
+	header->free = false;
+	if (!s_allocRoot) {
+		s_allocRoot = header;
+		header->prev = header->next = 0;
+	} else {
+		header->prev = nullptr;
+		header->next = s_allocRoot;
+		s_allocRoot = header;
+		header->next->prev = header;
+	}
+	s_allocTotalCount++;
+	s_allocTotalSize += size;
+	if (s_allocTotalSize > s_allocPeakSize)
+		s_allocPeakSize = s_allocTotalSize;
+	s_allocCount[tag]++;
+	s_allocTotalTagSize[tag] += size;
+	if (s_allocTotalTagSize[tag] > s_allocPeakTagSize[tag])
+		s_allocPeakTagSize[tag] = s_allocTotalTagSize[tag];
+	auto redzone = (uint32_t *)(newPtr + size - sizeof(kAllocRedzone));
+	*redzone = kAllocRedzone;
+	return newPtr + sizeof(AllocHeader);
+}
+
+static void ReportLeaks()
+{
+	printf("Checking for memory leaks...\n");
+	bool anyLeaks = false;
+	AllocHeader *header = s_allocRoot;
+	while (header) {
+		if (!header->free) {
+			printf("   Leak: ID %u, %zu bytes, %s %d\n", header->id, header->size, header->file, header->line);
+			anyLeaks = true;
+		}
+		auto redzone = (const uint32_t *)((const uint8_t *)header + header->size - sizeof(kAllocRedzone));
+		if (*redzone != kAllocRedzone)
+			printf("   Redzone corrupted: %zu bytes %s %d\n", header->size, header->file, header->line);
+		header = header->next;
+	}
+	if (!anyLeaks)
+		printf("   No memory leaks\n");
+	header = s_allocRoot;
+	while (header) {
+		AllocHeader *destroy = header;
+		header = header->next;
+		s_realloc(destroy, 0);
+	}
+	s_allocRoot = nullptr;
+	s_allocTotalSize = s_allocPeakSize = 0;
+	for (int i = 0; i < MemTag::Count; i++)
+		s_allocTotalTagSize[i] = s_allocPeakTagSize[i] = 0;
+}
+
+static void PrintMemoryUsage()
+{
+	XA_PRINT("Total allocations: %zu\n", s_allocTotalCount);
+	XA_PRINT("Memory usage: %0.2fMB current, %0.2fMB peak\n", internal::s_allocTotalSize / 1024.0f / 1024.0f, internal::s_allocPeakSize / 1024.0f / 1024.0f);
+	static const char *labels[] = { // Sync with MemTag
+		"Default",
+		"BitImage",
+		"BVH",
+		"Matrix",
+		"Mesh",
+		"MeshBoundaries",
+		"MeshColocals",
+		"MeshEdgeMap",
+		"MeshIndices",
+		"MeshNormals",
+		"MeshPositions",
+		"MeshTexcoords",
+		"OpenNL",
+		"SegmentAtlasChartCandidates",
+		"SegmentAtlasChartFaces",
+		"SegmentAtlasMeshData",
+		"SegmentAtlasPlanarRegions"
+	};
+	for (int i = 0; i < MemTag::Count; i++) {
+		XA_PRINT("   %s: %zu allocations, %0.2fMB current, %0.2fMB peak\n", labels[i], internal::s_allocCount[i], internal::s_allocTotalTagSize[i] / 1024.0f / 1024.0f, internal::s_allocPeakTagSize[i] / 1024.0f / 1024.0f);
+	}
+}
+
+#define XA_PRINT_MEM_USAGE internal::PrintMemoryUsage();
+#else
+static void *Realloc(void *ptr, size_t size, int /*tag*/, const char * /*file*/, int /*line*/)
+{
+	if (size == 0 && !ptr)
+		return nullptr;
+	if (size == 0 && s_free) {
+		s_free(ptr);
+		return nullptr;
+	}
+#if XA_PROFILE_ALLOC
+	XA_PROFILE_START(alloc)
+#endif
+	void *mem = s_realloc(ptr, size);
+#if XA_PROFILE_ALLOC
+	XA_PROFILE_END(alloc)
+#endif
+	XA_DEBUG_ASSERT(size <= 0 || (size > 0 && mem));
+	return mem;
+}
+#define XA_PRINT_MEM_USAGE
+#endif
+
+static constexpr float kPi = 3.14159265358979323846f;
+static constexpr float kPi2 = 6.28318530717958647692f;
+static constexpr float kEpsilon = 0.0001f;
+static constexpr float kAreaEpsilon = FLT_EPSILON;
+static constexpr float kNormalEpsilon = 0.001f;
+
+static int align(int x, int a)
+{
+	return (x + a - 1) & ~(a - 1);
+}
+
+template <typename T>
+static T max(const T &a, const T &b)
+{
+	return a > b ? a : b;
+}
+
+template <typename T>
+static T min(const T &a, const T &b)
+{
+	return a < b ? a : b;
+}
+
+template <typename T>
+static T max3(const T &a, const T &b, const T &c)
+{
+	return max(a, max(b, c));
+}
+
+/// Return the maximum of the three arguments.
+template <typename T>
+static T min3(const T &a, const T &b, const T &c)
+{
+	return min(a, min(b, c));
+}
+
+/// Clamp between two values.
+template <typename T>
+static T clamp(const T &x, const T &a, const T &b)
+{
+	return min(max(x, a), b);
+}
+
+template <typename T>
+static void swap(T &a, T &b)
+{
+	T temp = a;
+	a = b;
+	b = temp;
+}
+
+union FloatUint32
+{
+	float f;
+	uint32_t u;
+};
+
+static bool isFinite(float f)
+{
+	FloatUint32 fu;
+	fu.f = f;
+	return fu.u != 0x7F800000u && fu.u != 0x7F800001u;
+}
+
+static bool isNan(float f)
+{
+	return f != f;
+}
+
+// Robust floating point comparisons:
+// http://realtimecollisiondetection.net/blog/?p=89
+static bool equal(const float f0, const float f1, const float epsilon)
+{
+	//return fabs(f0-f1) <= epsilon;
+	return fabs(f0 - f1) <= epsilon * max3(1.0f, fabsf(f0), fabsf(f1));
+}
+
+static int ftoi_ceil(float val)
+{
+	return (int)ceilf(val);
+}
+
+static bool isZero(const float f, const float epsilon)
+{
+	return fabs(f) <= epsilon;
+}
+
+static float square(float f)
+{
+	return f * f;
+}
+
+/** Return the next power of two.
+* @see http://graphics.stanford.edu/~seander/bithacks.html
+* @warning Behaviour for 0 is undefined.
+* @note isPowerOfTwo(x) == true -> nextPowerOfTwo(x) == x
+* @note nextPowerOfTwo(x) = 2 << log2(x-1)
+*/
+static uint32_t nextPowerOfTwo(uint32_t x)
+{
+	XA_DEBUG_ASSERT( x != 0 );
+	// On modern CPUs this is supposed to be as fast as using the bsr instruction.
+	x--;
+	x |= x >> 1;
+	x |= x >> 2;
+	x |= x >> 4;
+	x |= x >> 8;
+	x |= x >> 16;
+	return x + 1;
+}
+
+class Vector2
+{
+public:
+	Vector2() {}
+	explicit Vector2(float f) : x(f), y(f) {}
+	Vector2(float _x, float _y): x(_x), y(_y) {}
+
+	Vector2 operator-() const
+	{
+		return Vector2(-x, -y);
+	}
+
+	void operator+=(const Vector2 &v)
+	{
+		x += v.x;
+		y += v.y;
+	}
+
+	void operator-=(const Vector2 &v)
+	{
+		x -= v.x;
+		y -= v.y;
+	}
+
+	void operator*=(float s)
+	{
+		x *= s;
+		y *= s;
+	}
+
+	void operator*=(const Vector2 &v)
+	{
+		x *= v.x;
+		y *= v.y;
+	}
+
+	float x, y;
+};
+
+static bool operator==(const Vector2 &a, const Vector2 &b)
+{
+	return a.x == b.x && a.y == b.y;
+}
+
+static bool operator!=(const Vector2 &a, const Vector2 &b)
+{
+	return a.x != b.x || a.y != b.y;
+}
+
+/*static Vector2 operator+(const Vector2 &a, const Vector2 &b)
+{
+	return Vector2(a.x + b.x, a.y + b.y);
+}*/
+
+static Vector2 operator-(const Vector2 &a, const Vector2 &b)
+{
+	return Vector2(a.x - b.x, a.y - b.y);
+}
+
+static Vector2 operator*(const Vector2 &v, float s)
+{
+	return Vector2(v.x * s, v.y * s);
+}
+
+static float dot(const Vector2 &a, const Vector2 &b)
+{
+	return a.x * b.x + a.y * b.y;
+}
+
+static float lengthSquared(const Vector2 &v)
+{
+	return v.x * v.x + v.y * v.y;
+}
+
+static float length(const Vector2 &v)
+{
+	return sqrtf(lengthSquared(v));
+}
+
+#if XA_DEBUG
+static bool isNormalized(const Vector2 &v, float epsilon = kNormalEpsilon)
+{
+	return equal(length(v), 1, epsilon);
+}
+#endif
+
+static Vector2 normalize(const Vector2 &v)
+{
+	const float l = length(v);
+	XA_DEBUG_ASSERT(l > 0.0f); // Never negative.
+	const Vector2 n = v * (1.0f / l);
+	XA_DEBUG_ASSERT(isNormalized(n));
+	return n;
+}
+
+static Vector2 normalizeSafe(const Vector2 &v, const Vector2 &fallback)
+{
+	const float l = length(v);
+	if (l > 0.0f) // Never negative.
+		return v * (1.0f / l);
+	return fallback;
+}
+
+static bool equal(const Vector2 &v1, const Vector2 &v2, float epsilon)
+{
+	return equal(v1.x, v2.x, epsilon) && equal(v1.y, v2.y, epsilon);
+}
+
+static Vector2 min(const Vector2 &a, const Vector2 &b)
+{
+	return Vector2(min(a.x, b.x), min(a.y, b.y));
+}
+
+static Vector2 max(const Vector2 &a, const Vector2 &b)
+{
+	return Vector2(max(a.x, b.x), max(a.y, b.y));
+}
+
+static bool isFinite(const Vector2 &v)
+{
+	return isFinite(v.x) && isFinite(v.y);
+}
+
+static float triangleArea(const Vector2 &a, const Vector2 &b, const Vector2 &c)
+{
+	// IC: While it may be appealing to use the following expression:
+	//return (c.x * a.y + a.x * b.y + b.x * c.y - b.x * a.y - c.x * b.y - a.x * c.y) * 0.5f;
+	// That's actually a terrible idea. Small triangles far from the origin can end up producing fairly large floating point
+	// numbers and the results becomes very unstable and dependent on the order of the factors.
+	// Instead, it's preferable to subtract the vertices first, and multiply the resulting small values together. The result
+	// in this case is always much more accurate (as long as the triangle is small) and less dependent of the location of
+	// the triangle.
+	//return ((a.x - c.x) * (b.y - c.y) - (a.y - c.y) * (b.x - c.x)) * 0.5f;
+	const Vector2 v0 = a - c;
+	const Vector2 v1 = b - c;
+	return (v0.x * v1.y - v0.y * v1.x) * 0.5f;
+}
+
+static bool linesIntersect(const Vector2 &a1, const Vector2 &a2, const Vector2 &b1, const Vector2 &b2, float epsilon)
+{
+	const Vector2 v0 = a2 - a1;
+	const Vector2 v1 = b2 - b1;
+	const float denom = -v1.x * v0.y + v0.x * v1.y;
+	if (equal(denom, 0.0f, epsilon))
+		return false;
+	const float s = (-v0.y * (a1.x - b1.x) + v0.x * (a1.y - b1.y)) / denom;
+	if (s > epsilon && s < 1.0f - epsilon) {
+		const float t = ( v1.x * (a1.y - b1.y) - v1.y * (a1.x - b1.x)) / denom;
+		return t > epsilon && t < 1.0f - epsilon;
+	}
+	return false;
+}
+
+struct Vector2i
+{
+	Vector2i() {}
+	Vector2i(int32_t _x, int32_t _y) : x(_x), y(_y) {}
+
+	int32_t x, y;
+};
+
+class Vector3
+{
+public:
+	Vector3() {}
+	explicit Vector3(float f) : x(f), y(f), z(f) {}
+	Vector3(float _x, float _y, float _z) : x(_x), y(_y), z(_z) {}
+	Vector3(const Vector2 &v, float _z) : x(v.x), y(v.y), z(_z) {}
+
+	Vector2 xy() const
+	{
+		return Vector2(x, y);
+	}
+
+	Vector3 operator-() const
+	{
+		return Vector3(-x, -y, -z);
+	}
+
+	void operator+=(const Vector3 &v)
+	{
+		x += v.x;
+		y += v.y;
+		z += v.z;
+	}
+
+	void operator-=(const Vector3 &v)
+	{
+		x -= v.x;
+		y -= v.y;
+		z -= v.z;
+	}
+
+	void operator*=(float s)
+	{
+		x *= s;
+		y *= s;
+		z *= s;
+	}
+
+	void operator/=(float s)
+	{
+		float is = 1.0f / s;
+		x *= is;
+		y *= is;
+		z *= is;
+	}
+
+	void operator*=(const Vector3 &v)
+	{
+		x *= v.x;
+		y *= v.y;
+		z *= v.z;
+	}
+
+	void operator/=(const Vector3 &v)
+	{
+		x /= v.x;
+		y /= v.y;
+		z /= v.z;
+	}
+
+	float x, y, z;
+};
+
+static Vector3 operator+(const Vector3 &a, const Vector3 &b)
+{
+	return Vector3(a.x + b.x, a.y + b.y, a.z + b.z);
+}
+
+static Vector3 operator-(const Vector3 &a, const Vector3 &b)
+{
+	return Vector3(a.x - b.x, a.y - b.y, a.z - b.z);
+}
+
+static bool operator==(const Vector3 &a, const Vector3 &b)
+{
+	return a.x == b.x && a.y == b.y && a.z == b.z;
+}
+
+static Vector3 cross(const Vector3 &a, const Vector3 &b)
+{
+	return Vector3(a.y * b.z - a.z * b.y, a.z * b.x - a.x * b.z, a.x * b.y - a.y * b.x);
+}
+
+static Vector3 operator*(const Vector3 &v, float s)
+{
+	return Vector3(v.x * s, v.y * s, v.z * s);
+}
+
+static Vector3 operator/(const Vector3 &v, float s)
+{
+	return v * (1.0f / s);
+}
+
+static float dot(const Vector3 &a, const Vector3 &b)
+{
+	return a.x * b.x + a.y * b.y + a.z * b.z;
+}
+
+static float lengthSquared(const Vector3 &v)
+{
+	return v.x * v.x + v.y * v.y + v.z * v.z;
+}
+
+static float length(const Vector3 &v)
+{
+	return sqrtf(lengthSquared(v));
+}
+
+static bool isNormalized(const Vector3 &v, float epsilon = kNormalEpsilon)
+{
+	return equal(length(v), 1.0f, epsilon);
+}
+
+static Vector3 normalize(const Vector3 &v)
+{
+	const float l = length(v);
+	XA_DEBUG_ASSERT(l > 0.0f); // Never negative.
+	const Vector3 n = v * (1.0f / l);
+	XA_DEBUG_ASSERT(isNormalized(n));
+	return n;
+}
+
+static Vector3 normalizeSafe(const Vector3 &v, const Vector3 &fallback)
+{
+	const float l = length(v);
+	if (l > 0.0f) // Never negative.
+		return v * (1.0f / l);
+	return fallback;
+}
+
+static bool equal(const Vector3 &v0, const Vector3 &v1, float epsilon)
+{
+	return fabs(v0.x - v1.x) <= epsilon && fabs(v0.y - v1.y) <= epsilon && fabs(v0.z - v1.z) <= epsilon;
+}
+
+static Vector3 min(const Vector3 &a, const Vector3 &b)
+{
+	return Vector3(min(a.x, b.x), min(a.y, b.y), min(a.z, b.z));
+}
+
+static Vector3 max(const Vector3 &a, const Vector3 &b)
+{
+	return Vector3(max(a.x, b.x), max(a.y, b.y), max(a.z, b.z));
+}
+
+#if XA_DEBUG
+bool isFinite(const Vector3 &v)
+{
+	return isFinite(v.x) && isFinite(v.y) && isFinite(v.z);
+}
+#endif
+
+struct Extents2
+{
+	Vector2 min, max;
+
+	Extents2() {}
+
+	Extents2(Vector2 p1, Vector2 p2)
+	{
+		min = xatlas::internal::min(p1, p2);
+		max = xatlas::internal::max(p1, p2);
+	}
+
+	void reset()
+	{
+		min.x = min.y = FLT_MAX;
+		max.x = max.y = -FLT_MAX;
+	}
+
+	void add(Vector2 p)
+	{
+		min = xatlas::internal::min(min, p);
+		max = xatlas::internal::max(max, p);
+	}
+
+	Vector2 midpoint() const
+	{
+		return Vector2(min.x + (max.x - min.x) * 0.5f, min.y + (max.y - min.y) * 0.5f);
+	}
+
+	static bool intersect(const Extents2 &e1, const Extents2 &e2)
+	{
+		return e1.min.x <= e2.max.x && e1.max.x >= e2.min.x && e1.min.y <= e2.max.y && e1.max.y >= e2.min.y;
+	}
+};
+
+// From Fast-BVH
+struct AABB
+{
+	AABB() : min(FLT_MAX, FLT_MAX, FLT_MAX), max(-FLT_MAX, -FLT_MAX, -FLT_MAX) {}
+	AABB(const Vector3 &_min, const Vector3 &_max) : min(_min), max(_max) { }
+	AABB(const Vector3 &p, float radius = 0.0f) : min(p), max(p) { if (radius > 0.0f) expand(radius); }
+
+	bool intersect(const AABB &other) const
+	{
+		return min.x <= other.max.x && max.x >= other.min.x && min.y <= other.max.y && max.y >= other.min.y && min.z <= other.max.z && max.z >= other.min.z;
+	}
+
+	void expandToInclude(const Vector3 &p)
+	{
+		min = internal::min(min, p);
+		max = internal::max(max, p);
+	}
+
+	void expandToInclude(const AABB &aabb)
+	{
+		min = internal::min(min, aabb.min);
+		max = internal::max(max, aabb.max);
+	}
+
+	void expand(float amount)
+	{
+		min -= Vector3(amount);
+		max += Vector3(amount);
+	}
+
+	Vector3 centroid() const
+	{
+		return min + (max - min) * 0.5f;
+	}
+
+	uint32_t maxDimension() const
+	{
+		const Vector3 extent = max - min;
+		uint32_t result = 0;
+		if (extent.y > extent.x) {
+			result = 1;
+			if (extent.z > extent.y)
+				result = 2;
+		}
+		else if(extent.z > extent.x)
+			result = 2;
+		return result;
+	}
+
+	Vector3 min, max;
+};
+
+struct ArrayBase
+{
+	ArrayBase(uint32_t _elementSize, int memTag = MemTag::Default) : buffer(nullptr), elementSize(_elementSize), size(0), capacity(0)
+	{
+#if XA_DEBUG_HEAP
+		this->memTag = memTag;
+#else
+		XA_UNUSED(memTag);
+#endif
+	}
+
+	~ArrayBase()
+	{
+		XA_FREE(buffer);
+	}
+
+	XA_INLINE void clear()
+	{
+		size = 0;
+	}
+
+	void copyFrom(const uint8_t *data, uint32_t length)
+	{
+		XA_DEBUG_ASSERT(data);
+		XA_DEBUG_ASSERT(length > 0);
+		resize(length, true);
+		if (buffer && data && length > 0)
+			memcpy(buffer, data, length * elementSize);
+	}
+
+	void copyTo(ArrayBase &other) const
+	{
+		XA_DEBUG_ASSERT(elementSize == other.elementSize);
+		XA_DEBUG_ASSERT(size > 0);
+		other.resize(size, true);
+		if (other.buffer && buffer && size > 0)
+			memcpy(other.buffer, buffer, size * elementSize);
+	}
+
+	void destroy()
+	{
+		size = 0;
+		XA_FREE(buffer);
+		buffer = nullptr;
+		capacity = 0;
+		size = 0;
+	}
+
+	// Insert the given element at the given index shifting all the elements up.
+	void insertAt(uint32_t index, const uint8_t *value)
+	{
+		XA_DEBUG_ASSERT(index >= 0 && index <= size);
+		XA_DEBUG_ASSERT(value);
+		resize(size + 1, false);
+		XA_DEBUG_ASSERT(buffer);
+		if (buffer && index < size - 1)
+			memmove(buffer + elementSize * (index + 1), buffer + elementSize * index, elementSize * (size - 1 - index));
+		if (buffer && value)
+			memcpy(&buffer[index * elementSize], value, elementSize);
+	}
+
+	void moveTo(ArrayBase &other)
+	{
+		XA_DEBUG_ASSERT(elementSize == other.elementSize);
+		other.destroy();
+		other.buffer = buffer;
+		other.elementSize = elementSize;
+		other.size = size;
+		other.capacity = capacity;
+#if XA_DEBUG_HEAP
+		other.memTag = memTag;
+#endif
+		buffer = nullptr;
+		elementSize = size = capacity = 0;
+	}
+
+	void pop_back()
+	{
+		XA_DEBUG_ASSERT(size > 0);
+		resize(size - 1, false);
+	}
+
+	void push_back(const uint8_t *value)
+	{
+		XA_DEBUG_ASSERT(value < buffer || value >= buffer + size);
+		XA_DEBUG_ASSERT(value);
+		resize(size + 1, false);
+		XA_DEBUG_ASSERT(buffer);
+		if (buffer && value)
+			memcpy(&buffer[(size - 1) * elementSize], value, elementSize);
+	}
+
+	void push_back(const ArrayBase &other)
+	{
+		XA_DEBUG_ASSERT(elementSize == other.elementSize);
+		if (other.size > 0) {
+			const uint32_t oldSize = size;
+			resize(size + other.size, false);
+			XA_DEBUG_ASSERT(buffer);
+			if (buffer)
+				memcpy(buffer + oldSize * elementSize, other.buffer, other.size * other.elementSize);
+		}
+	}
+
+	// Remove the element at the given index. This is an expensive operation!
+	void removeAt(uint32_t index)
+	{
+		XA_DEBUG_ASSERT(index >= 0 && index < size);
+		XA_DEBUG_ASSERT(buffer);
+		if (buffer) {
+			if (size > 1)
+				memmove(buffer + elementSize * index, buffer + elementSize * (index + 1), elementSize * (size - 1 - index));
+			if (size > 0)
+				size--;
+		}
+	}
+
+	// Element at index is swapped with the last element, then the array length is decremented.
+	void removeAtFast(uint32_t index)
+	{
+		XA_DEBUG_ASSERT(index >= 0 && index < size);
+		XA_DEBUG_ASSERT(buffer);
+		if (buffer) {
+			if (size > 1 && index != size - 1)
+				memcpy(buffer + elementSize * index, buffer + elementSize * (size - 1), elementSize);
+			if (size > 0)
+				size--;
+		}
+	}
+
+	void reserve(uint32_t desiredSize)
+	{
+		if (desiredSize > capacity)
+			setArrayCapacity(desiredSize);
+	}
+
+	void resize(uint32_t newSize, bool exact)
+	{
+		size = newSize;
+		if (size > capacity) {
+			// First allocation is always exact. Otherwise, following allocations grow array to 150% of desired size.
+			uint32_t newBufferSize;
+			if (capacity == 0 || exact)
+				newBufferSize = size;
+			else
+				newBufferSize = size + (size >> 2);
+			setArrayCapacity(newBufferSize);
+		}
+	}
+
+	void setArrayCapacity(uint32_t newCapacity)
+	{
+		XA_DEBUG_ASSERT(newCapacity >= size);
+		if (newCapacity == 0) {
+			// free the buffer.
+			if (buffer != nullptr) {
+				XA_FREE(buffer);
+				buffer = nullptr;
+			}
+		} else {
+			// realloc the buffer
+#if XA_DEBUG_HEAP
+			buffer = XA_REALLOC_SIZE(memTag, buffer, newCapacity * elementSize);
+#else
+			buffer = XA_REALLOC_SIZE(MemTag::Default, buffer, newCapacity * elementSize);
+#endif
+		}
+		capacity = newCapacity;
+	}
+
+#if XA_DEBUG_HEAP
+	void setMemTag(int _memTag)
+	{
+		this->memTag = _memTag;
+	}
+#endif
+
+	uint8_t *buffer;
+	uint32_t elementSize;
+	uint32_t size;
+	uint32_t capacity;
+#if XA_DEBUG_HEAP
+	int memTag;
+#endif
+};
+
+template<typename T>
+class Array
+{
+public:
+	Array(int memTag = MemTag::Default) : m_base(sizeof(T), memTag) {}
+	Array(const Array&) = delete;
+	Array &operator=(const Array &) = delete;
+
+	XA_INLINE const T &operator[](uint32_t index) const
+	{
+		XA_DEBUG_ASSERT(index < m_base.size);
+		XA_DEBUG_ASSERT(m_base.buffer);
+		return ((const T *)m_base.buffer)[index];
+	}
+
+	XA_INLINE T &operator[](uint32_t index)
+	{
+		XA_DEBUG_ASSERT(index < m_base.size);
+		XA_DEBUG_ASSERT(m_base.buffer);
+		return ((T *)m_base.buffer)[index];
+	}
+
+	XA_INLINE const T &back() const
+	{
+		XA_DEBUG_ASSERT(!isEmpty());
+		return ((const T *)m_base.buffer)[m_base.size - 1];
+	}
+
+	XA_INLINE T *begin() { return (T *)m_base.buffer; }
+	XA_INLINE void clear() { m_base.clear(); }
+
+	bool contains(const T &value) const
+	{
+		for (uint32_t i = 0; i < m_base.size; i++) {
+			if (((const T *)m_base.buffer)[i] == value)
+				return true;
+		}
+		return false;
+	}
+
+	void copyFrom(const T *data, uint32_t length) { m_base.copyFrom((const uint8_t *)data, length); }
+	void copyTo(Array &other) const { m_base.copyTo(other.m_base); }
+	XA_INLINE const T *data() const { return (const T *)m_base.buffer; }
+	XA_INLINE T *data() { return (T *)m_base.buffer; }
+	void destroy() { m_base.destroy(); }
+	XA_INLINE T *end() { return (T *)m_base.buffer + m_base.size; }
+	XA_INLINE bool isEmpty() const { return m_base.size == 0; }
+	void insertAt(uint32_t index, const T &value) { m_base.insertAt(index, (const uint8_t *)&value); }
+	void moveTo(Array &other) { m_base.moveTo(other.m_base); }
+	void push_back(const T &value) { m_base.push_back((const uint8_t *)&value); }
+	void push_back(const Array &other) { m_base.push_back(other.m_base); }
+	void pop_back() { m_base.pop_back(); }
+	void removeAt(uint32_t index) { m_base.removeAt(index); }
+	void removeAtFast(uint32_t index) { m_base.removeAtFast(index); }
+	void reserve(uint32_t desiredSize) { m_base.reserve(desiredSize); }
+	void resize(uint32_t newSize) { m_base.resize(newSize, true); }
+
+	void runCtors()
+	{
+		for (uint32_t i = 0; i < m_base.size; i++)
+			new (&((T *)m_base.buffer)[i]) T;
+	}
+
+	void runDtors()
+	{
+		for (uint32_t i = 0; i < m_base.size; i++)
+			((T *)m_base.buffer)[i].~T();
+	}
+
+	void fill(const T &value)
+	{
+		auto buffer = (T *)m_base.buffer;
+		for (uint32_t i = 0; i < m_base.size; i++)
+			buffer[i] = value;
+	}
+
+	void fillBytes(uint8_t value)
+	{
+		if (m_base.buffer && m_base.size > 0)
+			memset(m_base.buffer, (int)value, m_base.size * m_base.elementSize);
+	}
+
+#if XA_DEBUG_HEAP
+	void setMemTag(int memTag) { m_base.setMemTag(memTag); }
+#endif
+
+	XA_INLINE uint32_t size() const { return m_base.size; }
+
+	XA_INLINE void zeroOutMemory()
+	{
+		if (m_base.buffer && m_base.size > 0)
+			memset(m_base.buffer, 0, m_base.elementSize * m_base.size);
+	}
+
+private:
+	ArrayBase m_base;
+};
+
+template<typename T>
+struct ArrayView
+{
+	ArrayView() : data(nullptr), length(0) {}
+	ArrayView(Array<T> &a) : data(a.data()), length(a.size()) {}
+	ArrayView(T *_data, uint32_t _length) : data(_data), length(_length) {}
+	ArrayView &operator=(Array<T> &a) { data = a.data(); length = a.size(); return *this; }
+	XA_INLINE const T &operator[](uint32_t index) const { XA_DEBUG_ASSERT(index < length); return data[index]; }
+	XA_INLINE T &operator[](uint32_t index) { XA_DEBUG_ASSERT(index < length); return data[index]; }
+	T *data;
+	uint32_t length;
+};
+
+template<typename T>
+struct ConstArrayView
+{
+	ConstArrayView() : data(nullptr), length(0) {}
+	ConstArrayView(const Array<T> &a) : data(a.data()), length(a.size()) {}
+	ConstArrayView(ArrayView<T> av) : data(av.data), length(av.length) {}
+	ConstArrayView(const T *_data, uint32_t _length) : data(_data), length(_length) {}
+	ConstArrayView &operator=(const Array<T> &a) { data = a.data(); length = a.size(); return *this; }
+	XA_INLINE const T &operator[](uint32_t index) const { XA_DEBUG_ASSERT(index < length); return data[index]; }
+	const T *data;
+	uint32_t length;
+};
+
+/// Basis class to compute tangent space basis, ortogonalizations and to transform vectors from one space to another.
+struct Basis
+{
+	XA_NODISCARD static Vector3 computeTangent(const Vector3 &normal)
+	{
+		XA_ASSERT(isNormalized(normal));
+		// Choose minimum axis.
+		Vector3 tangent;
+		if (fabsf(normal.x) < fabsf(normal.y) && fabsf(normal.x) < fabsf(normal.z))
+			tangent = Vector3(1, 0, 0);
+		else if (fabsf(normal.y) < fabsf(normal.z))
+			tangent = Vector3(0, 1, 0);
+		else
+			tangent = Vector3(0, 0, 1);
+		// Ortogonalize
+		tangent -= normal * dot(normal, tangent);
+		tangent = normalize(tangent);
+		return tangent;
+	}
+
+	XA_NODISCARD static Vector3 computeBitangent(const Vector3 &normal, const Vector3 &tangent)
+	{
+		return cross(normal, tangent);
+	}
+
+	Vector3 tangent = Vector3(0.0f);
+	Vector3 bitangent = Vector3(0.0f);
+	Vector3 normal = Vector3(0.0f);
+};
+
+// Simple bit array.
+class BitArray
+{
+public:
+	BitArray() : m_size(0) {}
+
+	BitArray(uint32_t sz)
+	{
+		resize(sz);
+	}
+
+	void resize(uint32_t new_size)
+	{
+		m_size = new_size;
+		m_wordArray.resize((m_size + 31) >> 5);
+	}
+
+	bool get(uint32_t index) const
+	{
+		XA_DEBUG_ASSERT(index < m_size);
+		return (m_wordArray[index >> 5] & (1 << (index & 31))) != 0;
+	}
+
+	void set(uint32_t index)
+	{
+		XA_DEBUG_ASSERT(index < m_size);
+		m_wordArray[index >> 5] |= (1 << (index & 31));
+	}
+
+	void unset(uint32_t index)
+	{
+		XA_DEBUG_ASSERT(index < m_size);
+		m_wordArray[index >> 5] &= ~(1 << (index & 31));
+	}
+
+	void zeroOutMemory()
+	{
+		m_wordArray.zeroOutMemory();
+	}
+
+private:
+	uint32_t m_size; // Number of bits stored.
+	Array<uint32_t> m_wordArray;
+};
+
+class BitImage
+{
+public:
+	BitImage() : m_width(0), m_height(0), m_rowStride(0), m_data(MemTag::BitImage) {}
+
+	BitImage(uint32_t w, uint32_t h) : m_width(w), m_height(h), m_data(MemTag::BitImage)
+	{
+		m_rowStride = (m_width + 63) >> 6;
+		m_data.resize(m_rowStride * m_height);
+		m_data.zeroOutMemory();
+	}
+
+	BitImage(const BitImage &other) = delete;
+	BitImage &operator=(const BitImage &other) = delete;
+	uint32_t width() const { return m_width; }
+	uint32_t height() const { return m_height; }
+
+	void copyTo(BitImage &other)
+	{
+		other.m_width = m_width;
+		other.m_height = m_height;
+		other.m_rowStride = m_rowStride;
+		m_data.copyTo(other.m_data);
+	}
+
+	void resize(uint32_t w, uint32_t h, bool discard)
+	{
+		const uint32_t rowStride = (w + 63) >> 6;
+		if (discard) {
+			m_data.resize(rowStride * h);
+			m_data.zeroOutMemory();
+		} else {
+			Array<uint64_t> tmp;
+			tmp.resize(rowStride * h);
+			memset(tmp.data(), 0, tmp.size() * sizeof(uint64_t));
+			// If only height has changed, can copy all rows at once.
+			if (rowStride == m_rowStride) {
+				memcpy(tmp.data(), m_data.data(), m_rowStride * min(m_height, h) * sizeof(uint64_t));
+			} else if (m_width > 0 && m_height > 0) {
+				const uint32_t height = min(m_height, h);
+				for (uint32_t i = 0; i < height; i++)
+					memcpy(&tmp[i * rowStride], &m_data[i * m_rowStride], min(rowStride, m_rowStride) * sizeof(uint64_t));
+			}
+			tmp.moveTo(m_data);
+		}
+		m_width = w;
+		m_height = h;
+		m_rowStride = rowStride;
+	}
+
+	bool get(uint32_t x, uint32_t y) const
+	{
+		XA_DEBUG_ASSERT(x < m_width && y < m_height);
+		const uint32_t index = (x >> 6) + y * m_rowStride;
+		return (m_data[index] & (UINT64_C(1) << (uint64_t(x) & UINT64_C(63)))) != 0;
+	}
+
+	void set(uint32_t x, uint32_t y)
+	{
+		XA_DEBUG_ASSERT(x < m_width && y < m_height);
+		const uint32_t index = (x >> 6) + y * m_rowStride;
+		m_data[index] |= UINT64_C(1) << (uint64_t(x) & UINT64_C(63));
+		XA_DEBUG_ASSERT(get(x, y));
+	}
+
+	void zeroOutMemory()
+	{
+		m_data.zeroOutMemory();
+	}
+
+	bool canBlit(const BitImage &image, uint32_t offsetX, uint32_t offsetY) const
+	{
+		for (uint32_t y = 0; y < image.m_height; y++) {
+			const uint32_t thisY = y + offsetY;
+			if (thisY >= m_height)
+				continue;
+			uint32_t x = 0;
+			for (;;) {
+				const uint32_t thisX = x + offsetX;
+				if (thisX >= m_width)
+					break;
+				const uint32_t thisBlockShift = thisX % 64;
+				const uint64_t thisBlock = m_data[(thisX >> 6) + thisY * m_rowStride] >> thisBlockShift;
+				const uint32_t blockShift = x % 64;
+				const uint64_t block = image.m_data[(x >> 6) + y * image.m_rowStride] >> blockShift;
+				if ((thisBlock & block) != 0)
+					return false;
+				x += 64 - max(thisBlockShift, blockShift);
+				if (x >= image.m_width)
+					break;
+			}
+		}
+		return true;
+	}
+
+	void dilate(uint32_t padding)
+	{
+		BitImage tmp(m_width, m_height);
+		for (uint32_t p = 0; p < padding; p++) {
+			tmp.zeroOutMemory();
+			for (uint32_t y = 0; y < m_height; y++) {
+				for (uint32_t x = 0; x < m_width; x++) {
+					bool b = get(x, y);
+					if (!b) {
+						if (x > 0) {
+							b |= get(x - 1, y);
+							if (y > 0) b |= get(x - 1, y - 1);
+							if (y < m_height - 1) b |= get(x - 1, y + 1);
+						}
+						if (y > 0) b |= get(x, y - 1);
+						if (y < m_height - 1) b |= get(x, y + 1);
+						if (x < m_width - 1) {
+							b |= get(x + 1, y);
+							if (y > 0) b |= get(x + 1, y - 1);
+							if (y < m_height - 1) b |= get(x + 1, y + 1);
+						}
+					}
+					if (b)
+						tmp.set(x, y);
+				}
+			}
+			tmp.m_data.copyTo(m_data);
+		}
+	}
+
+private:
+	uint32_t m_width;
+	uint32_t m_height;
+	uint32_t m_rowStride; // In uint64_t's
+	Array<uint64_t> m_data;
+};
+
+// From Fast-BVH
+class BVH
+{
+public:
+	BVH(const Array<AABB> &objectAabbs, uint32_t leafSize = 4) : m_objectIds(MemTag::BVH), m_nodes(MemTag::BVH)
+	{
+		m_objectAabbs = &objectAabbs;
+		if (m_objectAabbs->isEmpty())
+			return;
+		m_objectIds.resize(objectAabbs.size());
+		for (uint32_t i = 0; i < m_objectIds.size(); i++)
+			m_objectIds[i] = i;
+		BuildEntry todo[128];
+		uint32_t stackptr = 0;
+		const uint32_t kRoot = 0xfffffffc;
+		const uint32_t kUntouched = 0xffffffff;
+		const uint32_t kTouchedTwice = 0xfffffffd;
+		// Push the root
+		todo[stackptr].start = 0;
+		todo[stackptr].end = objectAabbs.size();
+		todo[stackptr].parent = kRoot;
+		stackptr++;
+		Node node;
+		m_nodes.reserve(objectAabbs.size() * 2);
+		uint32_t nNodes = 0;
+		while(stackptr > 0) {
+			// Pop the next item off of the stack
+			const BuildEntry &bnode = todo[--stackptr];
+			const uint32_t start = bnode.start;
+			const uint32_t end = bnode.end;
+			const uint32_t nPrims = end - start;
+			nNodes++;
+			node.start = start;
+			node.nPrims = nPrims;
+			node.rightOffset = kUntouched;
+			// Calculate the bounding box for this node
+			AABB bb(objectAabbs[m_objectIds[start]]);
+			AABB bc(objectAabbs[m_objectIds[start]].centroid());
+			for(uint32_t p = start + 1; p < end; ++p) {
+				bb.expandToInclude(objectAabbs[m_objectIds[p]]);
+				bc.expandToInclude(objectAabbs[m_objectIds[p]].centroid());
+			}
+			node.aabb = bb;
+			// If the number of primitives at this point is less than the leaf
+			// size, then this will become a leaf. (Signified by rightOffset == 0)
+			if (nPrims <= leafSize)
+				node.rightOffset = 0;
+			m_nodes.push_back(node);
+			// Child touches parent...
+			// Special case: Don't do this for the root.
+			if (bnode.parent != kRoot) {
+				m_nodes[bnode.parent].rightOffset--;
+				// When this is the second touch, this is the right child.
+				// The right child sets up the offset for the flat tree.
+				if (m_nodes[bnode.parent].rightOffset == kTouchedTwice )
+					m_nodes[bnode.parent].rightOffset = nNodes - 1 - bnode.parent;
+			}
+			// If this is a leaf, no need to subdivide.
+			if (node.rightOffset == 0)
+				continue;
+			// Set the split dimensions
+			const uint32_t split_dim = bc.maxDimension();
+			// Split on the center of the longest axis
+			const float split_coord = 0.5f * ((&bc.min.x)[split_dim] + (&bc.max.x)[split_dim]);
+			// Partition the list of objects on this split
+			uint32_t mid = start;
+			for (uint32_t i = start; i < end; ++i) {
+				const Vector3 centroid(objectAabbs[m_objectIds[i]].centroid());
+				if ((&centroid.x)[split_dim] < split_coord) {
+					swap(m_objectIds[i], m_objectIds[mid]);
+					++mid;
+				}
+			}
+			// If we get a bad split, just choose the center...
+			if (mid == start || mid == end)
+				mid = start + (end - start) / 2;
+			// Push right child
+			todo[stackptr].start = mid;
+			todo[stackptr].end = end;
+			todo[stackptr].parent = nNodes - 1;
+			stackptr++;
+			// Push left child
+			todo[stackptr].start = start;
+			todo[stackptr].end = mid;
+			todo[stackptr].parent = nNodes - 1;
+			stackptr++;
+		}
+	}
+
+	void query(const AABB &queryAabb, Array<uint32_t> &result) const
+	{
+		result.clear();
+		// Working set
+		uint32_t todo[64];
+		int32_t stackptr = 0;
+		// "Push" on the root node to the working set
+		todo[stackptr] = 0;
+		while(stackptr >= 0) {
+			// Pop off the next node to work on.
+			const int ni = todo[stackptr--];
+			const Node &node = m_nodes[ni];
+			// Is leaf -> Intersect
+			if (node.rightOffset == 0) {
+				for(uint32_t o = 0; o < node.nPrims; ++o) {
+					const uint32_t obj = node.start + o;
+					if (queryAabb.intersect((*m_objectAabbs)[m_objectIds[obj]]))
+						result.push_back(m_objectIds[obj]);
+				}
+			} else { // Not a leaf
+				const uint32_t left = ni + 1;
+				const uint32_t right = ni + node.rightOffset;
+				if (queryAabb.intersect(m_nodes[left].aabb))
+					todo[++stackptr] = left;
+				if (queryAabb.intersect(m_nodes[right].aabb))
+					todo[++stackptr] = right;
+			}
+		}
+	}
+
+private:
+	struct BuildEntry
+	{
+		uint32_t parent; // If non-zero then this is the index of the parent. (used in offsets)
+		uint32_t start, end; // The range of objects in the object list covered by this node.
+	};
+
+	struct Node
+	{
+		AABB aabb;
+		uint32_t start, nPrims, rightOffset;
+	};
+
+	const Array<AABB> *m_objectAabbs;
+	Array<uint32_t> m_objectIds;
+	Array<Node> m_nodes;
+};
+
+struct Fit
+{
+	static bool computeBasis(ConstArrayView<Vector3> points, Basis *basis)
+	{
+		if (computeLeastSquaresNormal(points, &basis->normal)) {
+			basis->tangent = Basis::computeTangent(basis->normal);
+			basis->bitangent = Basis::computeBitangent(basis->normal, basis->tangent);
+			return true;
+		}
+		return computeEigen(points, basis);
+	}
+
+private:
+	// Fit a plane to a collection of points.
+	// Fast, and accurate to within a few degrees.
+	// Returns None if the points do not span a plane.
+	// https://www.ilikebigbits.com/2015_03_04_plane_from_points.html
+	static bool computeLeastSquaresNormal(ConstArrayView<Vector3> points, Vector3 *normal)
+	{
+		XA_DEBUG_ASSERT(points.length >= 3);
+		if (points.length == 3) {
+			*normal = normalize(cross(points[2] - points[0], points[1] - points[0]));
+			return true;
+		}
+		const float invN = 1.0f / float(points.length);
+		Vector3 centroid(0.0f);
+		for (uint32_t i = 0; i < points.length; i++)
+			centroid += points[i];
+		centroid *= invN;
+		// Calculate full 3x3 covariance matrix, excluding symmetries:
+		float xx = 0.0f, xy = 0.0f, xz = 0.0f, yy = 0.0f, yz = 0.0f, zz = 0.0f;
+		for (uint32_t i = 0; i < points.length; i++) {
+			Vector3 r = points[i] - centroid;
+			xx += r.x * r.x;
+			xy += r.x * r.y;
+			xz += r.x * r.z;
+			yy += r.y * r.y;
+			yz += r.y * r.z;
+			zz += r.z * r.z;
+		}
+#if 0
+		xx *= invN;
+		xy *= invN;
+		xz *= invN;
+		yy *= invN;
+		yz *= invN;
+		zz *= invN;
+		Vector3 weighted_dir(0.0f);
+		{
+			float det_x = yy * zz - yz * yz;
+			const Vector3 axis_dir(det_x, xz * yz - xy * zz, xy * yz - xz * yy);
+			float weight = det_x * det_x;
+			if (dot(weighted_dir, axis_dir) < 0.0f)
+				weight = -weight;
+			weighted_dir += axis_dir * weight;
+		}
+		{
+			float det_y = xx * zz - xz * xz;
+			const Vector3 axis_dir(xz * yz - xy * zz, det_y, xy * xz - yz * xx);
+			float weight = det_y * det_y;
+			if (dot(weighted_dir, axis_dir) < 0.0f)
+				weight = -weight;
+			weighted_dir += axis_dir * weight;
+		}
+		{
+			float det_z = xx * yy - xy * xy;
+			const Vector3 axis_dir(xy * yz - xz * yy, xy * xz - yz * xx, det_z);
+			float weight = det_z * det_z;
+			if (dot(weighted_dir, axis_dir) < 0.0f)
+				weight = -weight;
+			weighted_dir += axis_dir * weight;
+		}
+		*normal = normalize(weighted_dir, kEpsilon);
+#else
+		const float det_x = yy * zz - yz * yz;
+		const float det_y = xx * zz - xz * xz;
+		const float det_z = xx * yy - xy * xy;
+		const float det_max = max(det_x, max(det_y, det_z));
+		if (det_max <= 0.0f)
+			return false; // The points don't span a plane
+		// Pick path with best conditioning:
+		Vector3 dir(0.0f);
+		if (det_max == det_x)
+			dir = Vector3(det_x,xz * yz - xy * zz,xy * yz - xz * yy);
+		else if (det_max == det_y)
+			dir = Vector3(xz * yz - xy * zz, det_y, xy * xz - yz * xx);
+		else if (det_max == det_z)
+			dir = Vector3(xy * yz - xz * yy, xy * xz - yz * xx, det_z);
+		const float len = length(dir);
+		if (isZero(len, kEpsilon))
+			return false;
+		*normal = dir * (1.0f / len);
+#endif
+		return isNormalized(*normal);
+	}
+
+	static bool computeEigen(ConstArrayView<Vector3> points, Basis *basis)
+	{
+		float matrix[6];
+		computeCovariance(points, matrix);
+		if (matrix[0] == 0 && matrix[3] == 0 && matrix[5] == 0)
+			return false;
+		float eigenValues[3];
+		Vector3 eigenVectors[3];
+		if (!eigenSolveSymmetric3(matrix, eigenValues, eigenVectors))
+			return false;
+		basis->normal = normalize(eigenVectors[2]);
+		basis->tangent = normalize(eigenVectors[0]);
+		basis->bitangent = normalize(eigenVectors[1]);
+		return true;
+	}
+
+	static Vector3 computeCentroid(ConstArrayView<Vector3> points)
+	{
+		Vector3 centroid(0.0f);
+		for (uint32_t i = 0; i < points.length; i++)
+			centroid += points[i];
+		centroid /= float(points.length);
+		return centroid;
+	}
+
+	static Vector3 computeCovariance(ConstArrayView<Vector3> points, float * covariance)
+	{
+		// compute the centroid
+		Vector3 centroid = computeCentroid(points);
+		// compute covariance matrix
+		for (int i = 0; i < 6; i++) {
+			covariance[i] = 0.0f;
+		}
+		for (uint32_t i = 0; i < points.length; i++) {
+			Vector3 v = points[i] - centroid;
+			covariance[0] += v.x * v.x;
+			covariance[1] += v.x * v.y;
+			covariance[2] += v.x * v.z;
+			covariance[3] += v.y * v.y;
+			covariance[4] += v.y * v.z;
+			covariance[5] += v.z * v.z;
+		}
+		return centroid;
+	}
+
+	// Tridiagonal solver from Charles Bloom.
+	// Householder transforms followed by QL decomposition.
+	// Seems to be based on the code from Numerical Recipes in C.
+	static bool eigenSolveSymmetric3(const float matrix[6], float eigenValues[3], Vector3 eigenVectors[3])
+	{
+		XA_DEBUG_ASSERT(matrix != nullptr && eigenValues != nullptr && eigenVectors != nullptr);
+		float subd[3];
+		float diag[3];
+		float work[3][3];
+		work[0][0] = matrix[0];
+		work[0][1] = work[1][0] = matrix[1];
+		work[0][2] = work[2][0] = matrix[2];
+		work[1][1] = matrix[3];
+		work[1][2] = work[2][1] = matrix[4];
+		work[2][2] = matrix[5];
+		EigenSolver3_Tridiagonal(work, diag, subd);
+		if (!EigenSolver3_QLAlgorithm(work, diag, subd)) {
+			for (int i = 0; i < 3; i++) {
+				eigenValues[i] = 0;
+				eigenVectors[i] = Vector3(0);
+			}
+			return false;
+		}
+		for (int i = 0; i < 3; i++) {
+			eigenValues[i] = (float)diag[i];
+		}
+		// eigenvectors are the columns; make them the rows :
+		for (int i = 0; i < 3; i++) {
+			for (int j = 0; j < 3; j++) {
+				(&eigenVectors[j].x)[i] = (float) work[i][j];
+			}
+		}
+		// shuffle to sort by singular value :
+		if (eigenValues[2] > eigenValues[0] && eigenValues[2] > eigenValues[1]) {
+			swap(eigenValues[0], eigenValues[2]);
+			swap(eigenVectors[0], eigenVectors[2]);
+		}
+		if (eigenValues[1] > eigenValues[0]) {
+			swap(eigenValues[0], eigenValues[1]);
+			swap(eigenVectors[0], eigenVectors[1]);
+		}
+		if (eigenValues[2] > eigenValues[1]) {
+			swap(eigenValues[1], eigenValues[2]);
+			swap(eigenVectors[1], eigenVectors[2]);
+		}
+		XA_DEBUG_ASSERT(eigenValues[0] >= eigenValues[1] && eigenValues[0] >= eigenValues[2]);
+		XA_DEBUG_ASSERT(eigenValues[1] >= eigenValues[2]);
+		return true;
+	}
+
+private:
+	static void EigenSolver3_Tridiagonal(float mat[3][3], float *diag, float *subd)
+	{
+		// Householder reduction T = Q^t M Q
+		//   Input:
+		//     mat, symmetric 3x3 matrix M
+		//   Output:
+		//     mat, orthogonal matrix Q
+		//     diag, diagonal entries of T
+		//     subd, subdiagonal entries of T (T is symmetric)
+		const float epsilon = 1e-08f;
+		float a = mat[0][0];
+		float b = mat[0][1];
+		float c = mat[0][2];
+		float d = mat[1][1];
+		float e = mat[1][2];
+		float f = mat[2][2];
+		diag[0] = a;
+		subd[2] = 0.f;
+		if (fabsf(c) >= epsilon) {
+			const float ell = sqrtf(b * b + c * c);
+			b /= ell;
+			c /= ell;
+			const float q = 2 * b * e + c * (f - d);
+			diag[1] = d + c * q;
+			diag[2] = f - c * q;
+			subd[0] = ell;
+			subd[1] = e - b * q;
+			mat[0][0] = 1;
+			mat[0][1] = 0;
+			mat[0][2] = 0;
+			mat[1][0] = 0;
+			mat[1][1] = b;
+			mat[1][2] = c;
+			mat[2][0] = 0;
+			mat[2][1] = c;
+			mat[2][2] = -b;
+		} else {
+			diag[1] = d;
+			diag[2] = f;
+			subd[0] = b;
+			subd[1] = e;
+			mat[0][0] = 1;
+			mat[0][1] = 0;
+			mat[0][2] = 0;
+			mat[1][0] = 0;
+			mat[1][1] = 1;
+			mat[1][2] = 0;
+			mat[2][0] = 0;
+			mat[2][1] = 0;
+			mat[2][2] = 1;
+		}
+	}
+
+	static bool EigenSolver3_QLAlgorithm(float mat[3][3], float *diag, float *subd)
+	{
+		// QL iteration with implicit shifting to reduce matrix from tridiagonal
+		// to diagonal
+		const int maxiter = 32;
+		for (int ell = 0; ell < 3; ell++) {
+			int iter;
+			for (iter = 0; iter < maxiter; iter++) {
+				int m;
+				for (m = ell; m <= 1; m++) {
+					float dd = fabsf(diag[m]) + fabsf(diag[m + 1]);
+					if ( fabsf(subd[m]) + dd == dd )
+						break;
+				}
+				if ( m == ell )
+					break;
+				float g = (diag[ell + 1] - diag[ell]) / (2 * subd[ell]);
+				float r = sqrtf(g * g + 1);
+				if ( g < 0 )
+					g = diag[m] - diag[ell] + subd[ell] / (g - r);
+				else
+					g = diag[m] - diag[ell] + subd[ell] / (g + r);
+				float s = 1, c = 1, p = 0;
+				for (int i = m - 1; i >= ell; i--) {
+					float f = s * subd[i], b = c * subd[i];
+					if ( fabsf(f) >= fabsf(g) ) {
+						c = g / f;
+						r = sqrtf(c * c + 1);
+						subd[i + 1] = f * r;
+						c *= (s = 1 / r);
+					} else {
+						s = f / g;
+						r = sqrtf(s * s + 1);
+						subd[i + 1] = g * r;
+						s *= (c = 1 / r);
+					}
+					g = diag[i + 1] - p;
+					r = (diag[i] - g) * s + 2 * b * c;
+					p = s * r;
+					diag[i + 1] = g + p;
+					g = c * r - b;
+					for (int k = 0; k < 3; k++) {
+						f = mat[k][i + 1];
+						mat[k][i + 1] = s * mat[k][i] + c * f;
+						mat[k][i] = c * mat[k][i] - s * f;
+					}
+				}
+				diag[ell] -= p;
+				subd[ell] = g;
+				subd[m] = 0;
+			}
+			if ( iter == maxiter )
+				// should not get here under normal circumstances
+				return false;
+		}
+		return true;
+	}
+};
+
+static uint32_t sdbmHash(const void *data_in, uint32_t size, uint32_t h = 5381)
+{
+	const uint8_t *data = (const uint8_t *) data_in;
+	uint32_t i = 0;
+	while (i < size) {
+		h = (h << 16) + (h << 6) - h + (uint32_t ) data[i++];
+	}
+	return h;
+}
+
+template <typename T>
+static uint32_t hash(const T &t, uint32_t h = 5381)
+{
+	return sdbmHash(&t, sizeof(T), h);
+}
+
+template <typename Key>
+struct Hash
+{
+	uint32_t operator()(const Key &k) const { return hash(k); }
+};
+
+template <typename Key>
+struct PassthroughHash
+{
+	uint32_t operator()(const Key &k) const { return (uint32_t)k; }
+};
+
+template <typename Key>
+struct Equal
+{
+	bool operator()(const Key &k0, const Key &k1) const { return k0 == k1; }
+};
+
+template<typename Key, typename H = Hash<Key>, typename E = Equal<Key> >
+class HashMap
+{
+public:
+	HashMap(int memTag, uint32_t size) : m_memTag(memTag), m_size(size), m_numSlots(0), m_slots(nullptr), m_keys(memTag), m_next(memTag)
+	{
+	}
+
+	~HashMap()
+	{
+		if (m_slots)
+			XA_FREE(m_slots);
+	}
+
+	void destroy()
+	{
+		if (m_slots) {
+			XA_FREE(m_slots);
+			m_slots = nullptr;
+		}
+		m_keys.destroy();
+		m_next.destroy();
+	}
+
+	uint32_t add(const Key &key)
+	{
+		if (!m_slots)
+			alloc();
+		const uint32_t hash = computeHash(key);
+		m_keys.push_back(key);
+		m_next.push_back(m_slots[hash]);
+		m_slots[hash] = m_next.size() - 1;
+		return m_keys.size() - 1;
+	}
+
+	uint32_t get(const Key &key) const
+	{
+		if (!m_slots)
+			return UINT32_MAX;
+		return find(key, m_slots[computeHash(key)]);
+	}
+
+	uint32_t getNext(const Key &key, uint32_t current) const
+	{
+		return find(key, m_next[current]);
+	}
+
+private:
+	void alloc()
+	{
+		XA_DEBUG_ASSERT(m_size > 0);
+		m_numSlots = nextPowerOfTwo(m_size);
+		auto minNumSlots = uint32_t(m_size * 1.3);
+		if (m_numSlots < minNumSlots)
+			m_numSlots = nextPowerOfTwo(minNumSlots);
+		m_slots = XA_ALLOC_ARRAY(m_memTag, uint32_t, m_numSlots);
+		for (uint32_t i = 0; i < m_numSlots; i++)
+			m_slots[i] = UINT32_MAX;
+		m_keys.reserve(m_size);
+		m_next.reserve(m_size);
+	}
+
+	uint32_t computeHash(const Key &key) const
+	{
+		H hash;
+		return hash(key) & (m_numSlots - 1);
+	}
+
+	uint32_t find(const Key &key, uint32_t current) const
+	{
+		E equal;
+		while (current != UINT32_MAX) {
+			if (equal(m_keys[current], key))
+				return current;
+			current = m_next[current];
+		}
+		return current;
+	}
+
+	int m_memTag;
+	uint32_t m_size;
+	uint32_t m_numSlots;
+	uint32_t *m_slots;
+	Array<Key> m_keys;
+	Array<uint32_t> m_next;
+};
+
+template<typename T>
+static void insertionSort(T *data, uint32_t length)
+{
+	for (int32_t i = 1; i < (int32_t)length; i++) {
+		T x = data[i];
+		int32_t j = i - 1;
+		while (j >= 0 && x < data[j]) {
+			data[j + 1] = data[j];
+			j--;
+		}
+		data[j + 1] = x;
+	}
+}
+
+class KISSRng
+{
+public:
+	KISSRng() { reset(); }
+
+	void reset()
+	{
+		x = 123456789;
+		y = 362436000;
+		z = 521288629;
+		c = 7654321;
+	}
+
+	uint32_t getRange(uint32_t range)
+	{
+		if (range == 0)
+			return 0;
+		x = 69069 * x + 12345;
+		y ^= (y << 13);
+		y ^= (y >> 17);
+		y ^= (y << 5);
+		uint64_t t = 698769069ULL * z + c;
+		c = (t >> 32);
+		return (x + y + (z = (uint32_t)t)) % (range + 1);
+	}
+
+private:
+	uint32_t x, y, z, c;
+};
+
+// Based on Pierre Terdiman's and Michael Herf's source code.
+// http://www.codercorner.com/RadixSortRevisited.htm
+// http://www.stereopsis.com/radix.html
+class RadixSort
+{
+public:
+	void sort(ConstArrayView<float> input)
+	{
+		if (input.length == 0) {
+			m_buffer1.clear();
+			m_buffer2.clear();
+			m_ranks = m_buffer1.data();
+			m_ranks2 = m_buffer2.data();
+			return;
+		}
+		// Resize lists if needed
+		m_buffer1.resize(input.length);
+		m_buffer2.resize(input.length);
+		m_ranks = m_buffer1.data();
+		m_ranks2 = m_buffer2.data();
+		m_validRanks = false;
+		if (input.length < 32)
+			insertionSort(input);
+		else {
+			// @@ Avoid touching the input multiple times.
+			for (uint32_t i = 0; i < input.length; i++) {
+				floatFlip((uint32_t &)input[i]);
+			}
+			radixSort(ConstArrayView<uint32_t>((const uint32_t *)input.data, input.length));
+			for (uint32_t i = 0; i < input.length; i++) {
+				ifloatFlip((uint32_t &)input[i]);
+			}
+		}
+	}
+
+	// Access to results. m_ranks is a list of indices in sorted order, i.e. in the order you may further process your data
+	const uint32_t *ranks() const
+	{
+		XA_DEBUG_ASSERT(m_validRanks);
+		return m_ranks;
+	}
+
+private:
+	uint32_t *m_ranks, *m_ranks2;
+	Array<uint32_t> m_buffer1, m_buffer2;
+	bool m_validRanks = false;
+
+	void floatFlip(uint32_t &f)
+	{
+		int32_t mask = (int32_t(f) >> 31) | 0x80000000; // Warren Hunt, Manchor Ko.
+		f ^= mask;
+	}
+
+	void ifloatFlip(uint32_t &f)
+	{
+		uint32_t mask = ((f >> 31) - 1) | 0x80000000; // Michael Herf.
+		f ^= mask;
+	}
+
+	void createHistograms(ConstArrayView<uint32_t> input, uint32_t *histogram)
+	{
+		const uint32_t bucketCount = sizeof(uint32_t);
+		// Init bucket pointers.
+		uint32_t *h[bucketCount];
+		for (uint32_t i = 0; i < bucketCount; i++) {
+			h[i] = histogram + 256 * i;
+		}
+		// Clear histograms.
+		memset(histogram, 0, 256 * bucketCount * sizeof(uint32_t));
+		// @@ Add support for signed integers.
+		// Build histograms.
+		const uint8_t *p = (const uint8_t *)input.data;  // @@ Does this break aliasing rules?
+		const uint8_t *pe = p + input.length * sizeof(uint32_t);
+		while (p != pe) {
+			h[0][*p++]++, h[1][*p++]++, h[2][*p++]++, h[3][*p++]++;
+		}
+	}
+
+	void insertionSort(ConstArrayView<float> input)
+	{
+		if (!m_validRanks) {
+			m_ranks[0] = 0;
+			for (uint32_t i = 1; i != input.length; ++i) {
+				int rank = m_ranks[i] = i;
+				uint32_t j = i;
+				while (j != 0 && input[rank] < input[m_ranks[j - 1]]) {
+					m_ranks[j] = m_ranks[j - 1];
+					--j;
+				}
+				if (i != j) {
+					m_ranks[j] = rank;
+				}
+			}
+			m_validRanks = true;
+		} else {
+			for (uint32_t i = 1; i != input.length; ++i) {
+				int rank = m_ranks[i];
+				uint32_t j = i;
+				while (j != 0 && input[rank] < input[m_ranks[j - 1]]) {
+					m_ranks[j] = m_ranks[j - 1];
+					--j;
+				}
+				if (i != j) {
+					m_ranks[j] = rank;
+				}
+			}
+		}
+	}
+
+	void radixSort(ConstArrayView<uint32_t> input)
+	{
+		const uint32_t P = sizeof(uint32_t); // pass count
+		// Allocate histograms & offsets on the stack
+		uint32_t histogram[256 * P];
+		uint32_t *link[256];
+		createHistograms(input, histogram);
+		// Radix sort, j is the pass number (0=LSB, P=MSB)
+		for (uint32_t j = 0; j < P; j++) {
+			// Pointer to this bucket.
+			const uint32_t *h = &histogram[j * 256];
+			auto inputBytes = (const uint8_t *)input.data; // @@ Is this aliasing legal?
+			inputBytes += j;
+			if (h[inputBytes[0]] == input.length) {
+				// Skip this pass, all values are the same.
+				continue;
+			}
+			// Create offsets
+			link[0] = m_ranks2;
+			for (uint32_t i = 1; i < 256; i++) link[i] = link[i - 1] + h[i - 1];
+			// Perform Radix Sort
+			if (!m_validRanks) {
+				for (uint32_t i = 0; i < input.length; i++) {
+					*link[inputBytes[i * P]]++ = i;
+				}
+				m_validRanks = true;
+			} else {
+				for (uint32_t i = 0; i < input.length; i++) {
+					const uint32_t idx = m_ranks[i];
+					*link[inputBytes[idx * P]]++ = idx;
+				}
+			}
+			// Swap pointers for next pass. Valid indices - the most recent ones - are in m_ranks after the swap.
+			swap(m_ranks, m_ranks2);
+		}
+		// All values were equal, generate linear ranks.
+		if (!m_validRanks) {
+			for (uint32_t i = 0; i < input.length; i++)
+				m_ranks[i] = i;
+			m_validRanks = true;
+		}
+	}
+};
+
+// Wrapping this in a class allows temporary arrays to be re-used.
+class BoundingBox2D
+{
+public:
+	Vector2 majorAxis, minorAxis, minCorner, maxCorner;
+
+	void clear()
+	{
+		m_boundaryVertices.clear();
+	}
+
+	void appendBoundaryVertex(Vector2 v)
+	{
+		m_boundaryVertices.push_back(v);
+	}
+
+	// This should compute convex hull and use rotating calipers to find the best box. Currently it uses a brute force method.
+	// If vertices are empty, the boundary vertices are used.
+	void compute(ConstArrayView<Vector2> vertices = ConstArrayView<Vector2>())
+	{
+		XA_DEBUG_ASSERT(!m_boundaryVertices.isEmpty());
+		if (vertices.length == 0)
+			vertices = m_boundaryVertices;
+		convexHull(m_boundaryVertices, m_hull, 0.00001f);
+		// @@ Ideally I should use rotating calipers to find the best box. Using brute force for now.
+		float best_area = FLT_MAX;
+		Vector2 best_min(0);
+		Vector2 best_max(0);
+		Vector2 best_axis(0);
+		const uint32_t hullCount = m_hull.size();
+		for (uint32_t i = 0, j = hullCount - 1; i < hullCount; j = i, i++) {
+			if (equal(m_hull[i], m_hull[j], kEpsilon))
+				continue;
+			Vector2 axis = normalize(m_hull[i] - m_hull[j]);
+			XA_DEBUG_ASSERT(isFinite(axis));
+			// Compute bounding box.
+			Vector2 box_min(FLT_MAX, FLT_MAX);
+			Vector2 box_max(-FLT_MAX, -FLT_MAX);
+			// Consider all points, not only boundary points, in case the input chart is malformed.
+			for (uint32_t v = 0; v < vertices.length; v++) {
+				const Vector2 &point = vertices[v];
+				const float x = dot(axis, point);
+				const float y = dot(Vector2(-axis.y, axis.x), point);
+				box_min.x = min(box_min.x, x);
+				box_max.x = max(box_max.x, x);
+				box_min.y = min(box_min.y, y);
+				box_max.y = max(box_max.y, y);
+			}
+			// Compute box area.
+			const float area = (box_max.x - box_min.x) * (box_max.y - box_min.y);
+			if (area < best_area) {
+				best_area = area;
+				best_min = box_min;
+				best_max = box_max;
+				best_axis = axis;
+			}
+		}
+		majorAxis = best_axis;
+		minorAxis = Vector2(-best_axis.y, best_axis.x);
+		minCorner = best_min;
+		maxCorner = best_max;
+		XA_ASSERT(isFinite(majorAxis) && isFinite(minorAxis) && isFinite(minCorner));
+	}
+
+private:
+	// Compute the convex hull using Graham Scan.
+	void convexHull(ConstArrayView<Vector2> input, Array<Vector2> &output, float epsilon)
+	{
+		m_coords.resize(input.length);
+		for (uint32_t i = 0; i < input.length; i++)
+			m_coords[i] = input[i].x;
+		m_radix.sort(m_coords);
+		const uint32_t *ranks = m_radix.ranks();
+		m_top.clear();
+		m_bottom.clear();
+		m_top.reserve(input.length);
+		m_bottom.reserve(input.length);
+		Vector2 P = input[ranks[0]];
+		Vector2 Q = input[ranks[input.length - 1]];
+		float topy = max(P.y, Q.y);
+		float boty = min(P.y, Q.y);
+		for (uint32_t i = 0; i < input.length; i++) {
+			Vector2 p = input[ranks[i]];
+			if (p.y >= boty)
+				m_top.push_back(p);
+		}
+		for (uint32_t i = 0; i < input.length; i++) {
+			Vector2 p = input[ranks[input.length - 1 - i]];
+			if (p.y <= topy)
+				m_bottom.push_back(p);
+		}
+		// Filter top list.
+		output.clear();
+		XA_DEBUG_ASSERT(m_top.size() >= 2);
+		output.push_back(m_top[0]);
+		output.push_back(m_top[1]);
+		for (uint32_t i = 2; i < m_top.size(); ) {
+			Vector2 a = output[output.size() - 2];
+			Vector2 b = output[output.size() - 1];
+			Vector2 c = m_top[i];
+			float area = triangleArea(a, b, c);
+			if (area >= -epsilon)
+				output.pop_back();
+			if (area < -epsilon || output.size() == 1) {
+				output.push_back(c);
+				i++;
+			}
+		}
+		uint32_t top_count = output.size();
+		XA_DEBUG_ASSERT(m_bottom.size() >= 2);
+		output.push_back(m_bottom[1]);
+		// Filter bottom list.
+		for (uint32_t i = 2; i < m_bottom.size(); ) {
+			Vector2 a = output[output.size() - 2];
+			Vector2 b = output[output.size() - 1];
+			Vector2 c = m_bottom[i];
+			float area = triangleArea(a, b, c);
+			if (area >= -epsilon)
+				output.pop_back();
+			if (area < -epsilon || output.size() == top_count) {
+				output.push_back(c);
+				i++;
+			}
+		}
+		// Remove duplicate element.
+		XA_DEBUG_ASSERT(output.size() > 0);
+		output.pop_back();
+	}
+
+	Array<Vector2> m_boundaryVertices;
+	Array<float> m_coords;
+	Array<Vector2> m_top, m_bottom, m_hull;
+	RadixSort m_radix;
+};
+
+struct EdgeKey
+{
+	EdgeKey(const EdgeKey &k) : v0(k.v0), v1(k.v1) {}
+	EdgeKey(uint32_t _v0, uint32_t _v1) : v0(_v0), v1(_v1) {}
+	bool operator==(const EdgeKey &k) const { return v0 == k.v0 && v1 == k.v1; }
+
+	uint32_t v0;
+	uint32_t v1;
+};
+
+struct EdgeHash
+{
+	uint32_t operator()(const EdgeKey &k) const { return k.v0 * 32768u + k.v1; }
+};
+
+static uint32_t meshEdgeFace(uint32_t edge) { return edge / 3; }
+static uint32_t meshEdgeIndex0(uint32_t edge) { return edge; }
+
+static uint32_t meshEdgeIndex1(uint32_t edge)
+{
+	const uint32_t faceFirstEdge = edge / 3 * 3;
+	return faceFirstEdge + (edge - faceFirstEdge + 1) % 3;
+}
+
+struct MeshFlags
+{
+	enum
+	{
+		HasIgnoredFaces = 1<<0,
+		HasNormals = 1<<1,
+		HasMaterials = 1<<2
+	};
+};
+
+class Mesh
+{
+public:
+	Mesh(float epsilon, uint32_t approxVertexCount, uint32_t approxFaceCount, uint32_t flags = 0, uint32_t id = UINT32_MAX) : m_epsilon(epsilon), m_flags(flags), m_id(id), m_faceIgnore(MemTag::Mesh), m_faceMaterials(MemTag::Mesh), m_indices(MemTag::MeshIndices), m_positions(MemTag::MeshPositions), m_normals(MemTag::MeshNormals), m_texcoords(MemTag::MeshTexcoords), m_nextColocalVertex(MemTag::MeshColocals), m_firstColocalVertex(MemTag::MeshColocals), m_boundaryEdges(MemTag::MeshBoundaries), m_oppositeEdges(MemTag::MeshBoundaries), m_edgeMap(MemTag::MeshEdgeMap, approxFaceCount * 3)
+	{
+		m_indices.reserve(approxFaceCount * 3);
+		m_positions.reserve(approxVertexCount);
+		m_texcoords.reserve(approxVertexCount);
+		if (m_flags & MeshFlags::HasIgnoredFaces)
+			m_faceIgnore.reserve(approxFaceCount);
+		if (m_flags & MeshFlags::HasNormals)
+			m_normals.reserve(approxVertexCount);
+		if (m_flags & MeshFlags::HasMaterials)
+			m_faceMaterials.reserve(approxFaceCount);
+	}
+
+	uint32_t flags() const { return m_flags; }
+	uint32_t id() const { return m_id; }
+
+	void addVertex(const Vector3 &pos, const Vector3 &normal = Vector3(0.0f), const Vector2 &texcoord = Vector2(0.0f))
+	{
+		XA_DEBUG_ASSERT(isFinite(pos));
+		m_positions.push_back(pos);
+		if (m_flags & MeshFlags::HasNormals)
+			m_normals.push_back(normal);
+		m_texcoords.push_back(texcoord);
+	}
+
+	void addFace(const uint32_t *indices, bool ignore = false, uint32_t material = UINT32_MAX)
+	{
+		if (m_flags & MeshFlags::HasIgnoredFaces)
+			m_faceIgnore.push_back(ignore);
+		if (m_flags & MeshFlags::HasMaterials)
+			m_faceMaterials.push_back(material);
+		const uint32_t firstIndex = m_indices.size();
+		for (uint32_t i = 0; i < 3; i++)
+			m_indices.push_back(indices[i]);
+		for (uint32_t i = 0; i < 3; i++) {
+			const uint32_t vertex0 = m_indices[firstIndex + i];
+			const uint32_t vertex1 = m_indices[firstIndex + (i + 1) % 3];
+			m_edgeMap.add(EdgeKey(vertex0, vertex1));
+		}
+	}
+
+	void createColocalsBVH()
+	{
+		const uint32_t vertexCount = m_positions.size();
+		Array<AABB> aabbs(MemTag::BVH);
+		aabbs.resize(vertexCount);
+		for (uint32_t i = 0; i < m_positions.size(); i++)
+			aabbs[i] = AABB(m_positions[i], m_epsilon);
+		BVH bvh(aabbs);
+		Array<uint32_t> colocals(MemTag::MeshColocals);
+		Array<uint32_t> potential(MemTag::MeshColocals);
+		m_nextColocalVertex.resize(vertexCount);
+		m_nextColocalVertex.fillBytes(0xff);
+		m_firstColocalVertex.resize(vertexCount);
+		m_firstColocalVertex.fillBytes(0xff);
+		for (uint32_t i = 0; i < vertexCount; i++) {
+			if (m_nextColocalVertex[i] != UINT32_MAX)
+				continue; // Already linked.
+			// Find other vertices colocal to this one.
+			colocals.clear();
+			colocals.push_back(i); // Always add this vertex.
+			bvh.query(AABB(m_positions[i], m_epsilon), potential);
+			for (uint32_t j = 0; j < potential.size(); j++) {
+				const uint32_t otherVertex = potential[j];
+				if (otherVertex != i && equal(m_positions[i], m_positions[otherVertex], m_epsilon) && m_nextColocalVertex[otherVertex] == UINT32_MAX)
+					colocals.push_back(otherVertex);
+			}
+			if (colocals.size() == 1) {
+				// No colocals for this vertex.
+				m_nextColocalVertex[i] = i;
+				m_firstColocalVertex[i] = i;
+				continue;
+			}
+			// Link in ascending order.
+			insertionSort(colocals.data(), colocals.size());
+			for (uint32_t j = 0; j < colocals.size(); j++) {
+				m_nextColocalVertex[colocals[j]] = colocals[(j + 1) % colocals.size()];
+				m_firstColocalVertex[colocals[j]] = colocals[0];
+			}
+			XA_DEBUG_ASSERT(m_nextColocalVertex[i] != UINT32_MAX);
+		}
+	}
+
+	void createColocalsHash()
+	{
+		const uint32_t vertexCount = m_positions.size();
+		HashMap<Vector3> positionToVertexMap(MemTag::Default, vertexCount);
+		for (uint32_t i = 0; i < vertexCount; i++)
+			positionToVertexMap.add(m_positions[i]);
+		Array<uint32_t> colocals(MemTag::MeshColocals);
+		m_nextColocalVertex.resize(vertexCount);
+		m_nextColocalVertex.fillBytes(0xff);
+		m_firstColocalVertex.resize(vertexCount);
+		m_firstColocalVertex.fillBytes(0xff);
+		for (uint32_t i = 0; i < vertexCount; i++) {
+			if (m_nextColocalVertex[i] != UINT32_MAX)
+				continue; // Already linked.
+			// Find other vertices colocal to this one.
+			colocals.clear();
+			colocals.push_back(i); // Always add this vertex.
+			uint32_t otherVertex = positionToVertexMap.get(m_positions[i]);
+			while (otherVertex != UINT32_MAX) {
+				if (otherVertex != i && equal(m_positions[i], m_positions[otherVertex], m_epsilon) && m_nextColocalVertex[otherVertex] == UINT32_MAX)
+					colocals.push_back(otherVertex);
+				otherVertex = positionToVertexMap.getNext(m_positions[i], otherVertex);
+			}
+			if (colocals.size() == 1) {
+				// No colocals for this vertex.
+				m_nextColocalVertex[i] = i;
+				m_firstColocalVertex[i] = i;
+				continue;
+			}
+			// Link in ascending order.
+			insertionSort(colocals.data(), colocals.size());
+			for (uint32_t j = 0; j < colocals.size(); j++) {
+				m_nextColocalVertex[colocals[j]] = colocals[(j + 1) % colocals.size()];
+				m_firstColocalVertex[colocals[j]] = colocals[0];
+			}
+			XA_DEBUG_ASSERT(m_nextColocalVertex[i] != UINT32_MAX);
+		}
+	}
+
+	void createColocals()
+	{
+		if (m_epsilon <= FLT_EPSILON)
+			createColocalsHash();
+		else
+			createColocalsBVH();
+	}
+
+	void createBoundaries()
+	{
+		const uint32_t edgeCount = m_indices.size();
+		const uint32_t vertexCount = m_positions.size();
+		m_oppositeEdges.resize(edgeCount);
+		m_boundaryEdges.reserve(uint32_t(edgeCount * 0.1f));
+		m_isBoundaryVertex.resize(vertexCount);
+		m_isBoundaryVertex.zeroOutMemory();
+		for (uint32_t i = 0; i < edgeCount; i++)
+			m_oppositeEdges[i] = UINT32_MAX;
+		const uint32_t faceCount = m_indices.size() / 3;
+		for (uint32_t i = 0; i < faceCount; i++) {
+			if (isFaceIgnored(i))
+				continue;
+			for (uint32_t j = 0; j < 3; j++) {
+				const uint32_t edge = i * 3 + j;
+				const uint32_t vertex0 = m_indices[edge];
+				const uint32_t vertex1 = m_indices[i * 3 + (j + 1) % 3];
+				// If there is an edge with opposite winding to this one, the edge isn't on a boundary.
+				const uint32_t oppositeEdge = findEdge(vertex1, vertex0);
+				if (oppositeEdge != UINT32_MAX) {
+					m_oppositeEdges[edge] = oppositeEdge;
+				} else {
+					m_boundaryEdges.push_back(edge);
+					m_isBoundaryVertex.set(vertex0);
+					m_isBoundaryVertex.set(vertex1);
+				}
+			}
+		}
+	}
+
+	/// Find edge, test all colocals.
+	uint32_t findEdge(uint32_t vertex0, uint32_t vertex1) const
+	{
+		// Try to find exact vertex match first.
+		{
+			EdgeKey key(vertex0, vertex1);
+			uint32_t edge = m_edgeMap.get(key);
+			while (edge != UINT32_MAX) {
+				// Don't find edges of ignored faces.
+				if (!isFaceIgnored(meshEdgeFace(edge)))
+					return edge;
+				edge = m_edgeMap.getNext(key, edge);
+			}
+		}
+		// If colocals were created, try every permutation.
+		if (!m_nextColocalVertex.isEmpty()) {
+			uint32_t colocalVertex0 = vertex0;
+			for (;;) {
+				uint32_t colocalVertex1 = vertex1;
+				for (;;) {
+					EdgeKey key(colocalVertex0, colocalVertex1);
+					uint32_t edge = m_edgeMap.get(key);
+					while (edge != UINT32_MAX) {
+						// Don't find edges of ignored faces.
+						if (!isFaceIgnored(meshEdgeFace(edge)))
+							return edge;
+						edge = m_edgeMap.getNext(key, edge);
+					}
+					colocalVertex1 = m_nextColocalVertex[colocalVertex1];
+					if (colocalVertex1 == vertex1)
+						break; // Back to start.
+				}
+				colocalVertex0 = m_nextColocalVertex[colocalVertex0];
+				if (colocalVertex0 == vertex0)
+					break; // Back to start.
+			}
+		}
+		return UINT32_MAX;
+	}
+
+	// Edge map can be destroyed when no longer used to reduce memory usage. It's used by:
+	//   * Mesh::createBoundaries()
+	//   * Mesh::edgeMap() (used by MeshFaceGroups)
+	void destroyEdgeMap()
+	{
+		m_edgeMap.destroy();
+	}
+
+#if XA_DEBUG_EXPORT_OBJ
+	void writeObjVertices(FILE *file) const
+	{
+		for (uint32_t i = 0; i < m_positions.size(); i++)
+			fprintf(file, "v %g %g %g\n", m_positions[i].x, m_positions[i].y, m_positions[i].z);
+		if (m_flags & MeshFlags::HasNormals) {
+			for (uint32_t i = 0; i < m_normals.size(); i++)
+				fprintf(file, "vn %g %g %g\n", m_normals[i].x, m_normals[i].y, m_normals[i].z);
+		}
+		for (uint32_t i = 0; i < m_texcoords.size(); i++)
+			fprintf(file, "vt %g %g\n", m_texcoords[i].x, m_texcoords[i].y);
+	}
+
+	void writeObjFace(FILE *file, uint32_t face, uint32_t offset = 0) const
+	{
+		fprintf(file, "f ");
+		for (uint32_t j = 0; j < 3; j++) {
+			const uint32_t index = m_indices[face * 3 + j] + 1 + offset; // 1-indexed
+			fprintf(file, "%d/%d/%d%c", index, index, index, j == 2 ? '\n' : ' ');
+		}
+	}
+
+	void writeObjBoundaryEges(FILE *file) const
+	{
+		if (m_oppositeEdges.isEmpty())
+			return; // Boundaries haven't been created.
+		fprintf(file, "o boundary_edges\n");
+		for (uint32_t i = 0; i < edgeCount(); i++) {
+			if (m_oppositeEdges[i] != UINT32_MAX)
+				continue;
+			fprintf(file, "l %d %d\n", m_indices[meshEdgeIndex0(i)] + 1, m_indices[meshEdgeIndex1(i)] + 1); // 1-indexed
+		}
+	}
+
+	void writeObjFile(const char *filename) const
+	{
+		FILE *file;
+		XA_FOPEN(file, filename, "w");
+		if (!file)
+			return;
+		writeObjVertices(file);
+		fprintf(file, "s off\n");
+		fprintf(file, "o object\n");
+		for (uint32_t i = 0; i < faceCount(); i++)
+			writeObjFace(file, i);
+		writeObjBoundaryEges(file);
+		fclose(file);
+	}
+#endif
+
+	float computeSurfaceArea() const
+	{
+		float area = 0;
+		for (uint32_t f = 0; f < faceCount(); f++)
+			area += computeFaceArea(f);
+		XA_DEBUG_ASSERT(area >= 0);
+		return area;
+	}
+
+	// Returned value is always positive, even if some triangles are flipped.
+	float computeParametricArea() const
+	{
+		float area = 0;
+		for (uint32_t f = 0; f < faceCount(); f++)
+			area += fabsf(computeFaceParametricArea(f)); // May be negative, depends on texcoord winding.
+		return area;
+	}
+
+	float computeFaceArea(uint32_t face) const
+	{
+		const Vector3 &p0 = m_positions[m_indices[face * 3 + 0]];
+		const Vector3 &p1 = m_positions[m_indices[face * 3 + 1]];
+		const Vector3 &p2 = m_positions[m_indices[face * 3 + 2]];
+		return length(cross(p1 - p0, p2 - p0)) * 0.5f;
+	}
+
+	Vector3 computeFaceCentroid(uint32_t face) const
+	{
+		Vector3 sum(0.0f);
+		for (uint32_t i = 0; i < 3; i++)
+			sum += m_positions[m_indices[face * 3 + i]];
+		return sum / 3.0f;
+	}
+
+	// Average of the edge midpoints weighted by the edge length.
+	// I want a point inside the triangle, but closer to the cirumcenter.
+	Vector3 computeFaceCenter(uint32_t face) const
+	{
+		const Vector3 &p0 = m_positions[m_indices[face * 3 + 0]];
+		const Vector3 &p1 = m_positions[m_indices[face * 3 + 1]];
+		const Vector3 &p2 = m_positions[m_indices[face * 3 + 2]];
+		const float l0 = length(p1 - p0);
+		const float l1 = length(p2 - p1);
+		const float l2 = length(p0 - p2);
+		const Vector3 m0 = (p0 + p1) * l0 / (l0 + l1 + l2);
+		const Vector3 m1 = (p1 + p2) * l1 / (l0 + l1 + l2);
+		const Vector3 m2 = (p2 + p0) * l2 / (l0 + l1 + l2);
+		return m0 + m1 + m2;
+	}
+
+	Vector3 computeFaceNormal(uint32_t face) const
+	{
+		const Vector3 &p0 = m_positions[m_indices[face * 3 + 0]];
+		const Vector3 &p1 = m_positions[m_indices[face * 3 + 1]];
+		const Vector3 &p2 = m_positions[m_indices[face * 3 + 2]];
+		const Vector3 e0 = p2 - p0;
+		const Vector3 e1 = p1 - p0;
+		const Vector3 normalAreaScaled = cross(e0, e1);
+		return normalizeSafe(normalAreaScaled, Vector3(0, 0, 1));
+	}
+
+	float computeFaceParametricArea(uint32_t face) const
+	{
+		const Vector2 &t0 = m_texcoords[m_indices[face * 3 + 0]];
+		const Vector2 &t1 = m_texcoords[m_indices[face * 3 + 1]];
+		const Vector2 &t2 = m_texcoords[m_indices[face * 3 + 2]];
+		return triangleArea(t0, t1, t2);
+	}
+
+	// @@ This is not exactly accurate, we should compare the texture coordinates...
+	bool isSeam(uint32_t edge) const
+	{
+		const uint32_t oppositeEdge = m_oppositeEdges[edge];
+		if (oppositeEdge == UINT32_MAX)
+			return false; // boundary edge
+		const uint32_t e0 = meshEdgeIndex0(edge);
+		const uint32_t e1 = meshEdgeIndex1(edge);
+		const uint32_t oe0 = meshEdgeIndex0(oppositeEdge);
+		const uint32_t oe1 = meshEdgeIndex1(oppositeEdge);
+		return m_indices[e0] != m_indices[oe1] || m_indices[e1] != m_indices[oe0];
+	}
+
+	bool isTextureSeam(uint32_t edge) const
+	{
+		const uint32_t oppositeEdge = m_oppositeEdges[edge];
+		if (oppositeEdge == UINT32_MAX)
+			return false; // boundary edge
+		const uint32_t e0 = meshEdgeIndex0(edge);
+		const uint32_t e1 = meshEdgeIndex1(edge);
+		const uint32_t oe0 = meshEdgeIndex0(oppositeEdge);
+		const uint32_t oe1 = meshEdgeIndex1(oppositeEdge);
+		return m_texcoords[m_indices[e0]] != m_texcoords[m_indices[oe1]] || m_texcoords[m_indices[e1]] != m_texcoords[m_indices[oe0]];
+	}
+
+	uint32_t firstColocalVertex(uint32_t vertex) const
+	{
+		XA_DEBUG_ASSERT(m_firstColocalVertex.size() == m_positions.size());
+		return m_firstColocalVertex[vertex];
+	}
+
+	XA_INLINE float epsilon() const { return m_epsilon; }
+	XA_INLINE uint32_t edgeCount() const { return m_indices.size(); }
+	XA_INLINE uint32_t oppositeEdge(uint32_t edge) const { return m_oppositeEdges[edge]; }
+	XA_INLINE bool isBoundaryEdge(uint32_t edge) const { return m_oppositeEdges[edge] == UINT32_MAX; }
+	XA_INLINE const Array<uint32_t> &boundaryEdges() const { return m_boundaryEdges; }
+	XA_INLINE bool isBoundaryVertex(uint32_t vertex) const { return m_isBoundaryVertex.get(vertex); }
+	XA_INLINE uint32_t vertexCount() const { return m_positions.size(); }
+	XA_INLINE uint32_t vertexAt(uint32_t i) const { return m_indices[i]; }
+	XA_INLINE const Vector3 &position(uint32_t vertex) const { return m_positions[vertex]; }
+	XA_INLINE ConstArrayView<Vector3> positions() const { return m_positions; }
+	XA_INLINE const Vector3 &normal(uint32_t vertex) const { XA_DEBUG_ASSERT(m_flags & MeshFlags::HasNormals); return m_normals[vertex]; }
+	XA_INLINE const Vector2 &texcoord(uint32_t vertex) const { return m_texcoords[vertex]; }
+	XA_INLINE Vector2 &texcoord(uint32_t vertex) { return m_texcoords[vertex]; }
+	XA_INLINE const ConstArrayView<Vector2> texcoords() const { return m_texcoords; }
+	XA_INLINE ArrayView<Vector2> texcoords() { return m_texcoords; }
+	XA_INLINE uint32_t faceCount() const { return m_indices.size() / 3; }
+	XA_INLINE ConstArrayView<uint32_t> indices() const { return m_indices; }
+	XA_INLINE uint32_t indexCount() const { return m_indices.size(); }
+	XA_INLINE bool isFaceIgnored(uint32_t face) const { return (m_flags & MeshFlags::HasIgnoredFaces) && m_faceIgnore[face]; }
+	XA_INLINE uint32_t faceMaterial(uint32_t face) const { return (m_flags & MeshFlags::HasMaterials) ? m_faceMaterials[face] : UINT32_MAX; }
+	XA_INLINE const HashMap<EdgeKey, EdgeHash> &edgeMap() const { return m_edgeMap; }
+
+private:
+
+	float m_epsilon;
+	uint32_t m_flags;
+	uint32_t m_id;
+	Array<bool> m_faceIgnore;
+	Array<uint32_t> m_faceMaterials;
+	Array<uint32_t> m_indices;
+	Array<Vector3> m_positions;
+	Array<Vector3> m_normals;
+	Array<Vector2> m_texcoords;
+
+	// Populated by createColocals
+	Array<uint32_t> m_nextColocalVertex; // In: vertex index. Out: the vertex index of the next colocal position.
+	Array<uint32_t> m_firstColocalVertex;
+
+	// Populated by createBoundaries
+	BitArray m_isBoundaryVertex;
+	Array<uint32_t> m_boundaryEdges;
+	Array<uint32_t> m_oppositeEdges; // In: edge index. Out: the index of the opposite edge (i.e. wound the opposite direction). UINT32_MAX if the input edge is a boundary edge.
+
+	HashMap<EdgeKey, EdgeHash> m_edgeMap;
+
+public:
+	class FaceEdgeIterator
+	{
+	public:
+		FaceEdgeIterator (const Mesh *mesh, uint32_t face) : m_mesh(mesh), m_face(face), m_relativeEdge(0)
+		{
+			m_edge = m_face * 3;
+		}
+
+		void advance()
+		{
+			if (m_relativeEdge < 3) {
+				m_edge++;
+				m_relativeEdge++;
+			}
+		}
+
+		bool isDone() const
+		{
+			return m_relativeEdge == 3;
+		}
+
+		bool isBoundary() const { return m_mesh->m_oppositeEdges[m_edge] == UINT32_MAX; }
+		bool isSeam() const { return m_mesh->isSeam(m_edge); }
+		bool isTextureSeam() const { return m_mesh->isTextureSeam(m_edge); }
+		uint32_t edge() const { return m_edge; }
+		uint32_t relativeEdge() const { return m_relativeEdge; }
+		uint32_t face() const { return m_face; }
+		uint32_t oppositeEdge() const { return m_mesh->m_oppositeEdges[m_edge]; }
+
+		uint32_t oppositeFace() const
+		{
+			const uint32_t oedge = m_mesh->m_oppositeEdges[m_edge];
+			if (oedge == UINT32_MAX)
+				return UINT32_MAX;
+			return meshEdgeFace(oedge);
+		}
+
+		uint32_t vertex0() const { return m_mesh->m_indices[m_face * 3 + m_relativeEdge]; }
+		uint32_t vertex1() const { return m_mesh->m_indices[m_face * 3 + (m_relativeEdge + 1) % 3]; }
+		const Vector3 &position0() const { return m_mesh->m_positions[vertex0()]; }
+		const Vector3 &position1() const { return m_mesh->m_positions[vertex1()]; }
+		const Vector3 &normal0() const { return m_mesh->m_normals[vertex0()]; }
+		const Vector3 &normal1() const { return m_mesh->m_normals[vertex1()]; }
+		const Vector2 &texcoord0() const { return m_mesh->m_texcoords[vertex0()]; }
+		const Vector2 &texcoord1() const { return m_mesh->m_texcoords[vertex1()]; }
+
+	private:
+		const Mesh *m_mesh;
+		uint32_t m_face;
+		uint32_t m_edge;
+		uint32_t m_relativeEdge;
+	};
+};
+
+struct MeshFaceGroups
+{
+	typedef uint32_t Handle;
+	static constexpr Handle kInvalid = UINT32_MAX;
+
+	MeshFaceGroups(const Mesh *mesh) : m_mesh(mesh), m_groups(MemTag::Mesh), m_firstFace(MemTag::Mesh), m_nextFace(MemTag::Mesh), m_faceCount(MemTag::Mesh) {}
+	XA_INLINE Handle groupAt(uint32_t face) const { return m_groups[face]; }
+	XA_INLINE uint32_t groupCount() const { return m_faceCount.size(); }
+	XA_INLINE uint32_t nextFace(uint32_t face) const { return m_nextFace[face]; }
+	XA_INLINE uint32_t faceCount(uint32_t group) const { return m_faceCount[group]; }
+
+	void compute()
+	{
+		m_groups.resize(m_mesh->faceCount());
+		m_groups.fillBytes(0xff); // Set all faces to kInvalid
+		uint32_t firstUnassignedFace = 0;
+		Handle group = 0;
+		Array<uint32_t> growFaces;
+		const uint32_t n = m_mesh->faceCount();
+		m_nextFace.resize(n);
+		for (;;) {
+			// Find an unassigned face.
+			uint32_t face = UINT32_MAX;
+			for (uint32_t f = firstUnassignedFace; f < n; f++) {
+				if (m_groups[f] == kInvalid && !m_mesh->isFaceIgnored(f)) {
+					face = f;
+					firstUnassignedFace = f + 1;
+					break;
+				}
+			}
+			if (face == UINT32_MAX)
+				break; // All faces assigned to a group (except ignored faces).
+			m_groups[face] = group;
+			m_nextFace[face] = UINT32_MAX;
+			m_firstFace.push_back(face);
+			growFaces.clear();
+			growFaces.push_back(face);
+			uint32_t prevFace = face, groupFaceCount = 1;
+			// Find faces connected to the face and assign them to the same group as the face, unless they are already assigned to another group.
+			for (;;) {
+				if (growFaces.isEmpty())
+					break;
+				const uint32_t f = growFaces.back();
+				growFaces.pop_back();
+				const uint32_t material = m_mesh->faceMaterial(f);
+				for (Mesh::FaceEdgeIterator edgeIt(m_mesh, f); !edgeIt.isDone(); edgeIt.advance()) {
+					const uint32_t oppositeEdge = m_mesh->findEdge(edgeIt.vertex1(), edgeIt.vertex0());
+					if (oppositeEdge == UINT32_MAX)
+						continue; // Boundary edge.
+					const uint32_t oppositeFace = meshEdgeFace(oppositeEdge);
+					if (m_mesh->isFaceIgnored(oppositeFace))
+						continue; // Don't add ignored faces to group.
+					if (m_mesh->faceMaterial(oppositeFace) != material)
+						continue; // Different material.
+					if (m_groups[oppositeFace] != kInvalid)
+						continue; // Connected face is already assigned to another group.
+					m_groups[oppositeFace] = group;
+					m_nextFace[oppositeFace] = UINT32_MAX;
+					if (prevFace != UINT32_MAX)
+						m_nextFace[prevFace] = oppositeFace;
+					prevFace = oppositeFace;
+					groupFaceCount++;
+					growFaces.push_back(oppositeFace);
+				}
+			}
+			m_faceCount.push_back(groupFaceCount);
+			group++;
+			XA_ASSERT(group < kInvalid);
+		}
+	}
+
+	class Iterator
+	{
+	public:
+		Iterator(const MeshFaceGroups *meshFaceGroups, Handle group) : m_meshFaceGroups(meshFaceGroups)
+		{
+			XA_DEBUG_ASSERT(group != kInvalid);
+			m_current = m_meshFaceGroups->m_firstFace[group];
+		}
+
+		void advance()
+		{
+			m_current = m_meshFaceGroups->m_nextFace[m_current];
+		}
+
+		bool isDone() const
+		{
+			return m_current == UINT32_MAX;
+		}
+
+		uint32_t face() const
+		{
+			return m_current;
+		}
+
+	private:
+		const MeshFaceGroups *m_meshFaceGroups;
+		uint32_t m_current;
+	};
+
+private:
+	const Mesh *m_mesh;
+	Array<Handle> m_groups;
+	Array<uint32_t> m_firstFace;
+	Array<uint32_t> m_nextFace; // In: face. Out: the next face in the same group.
+	Array<uint32_t> m_faceCount; // In: face group. Out: number of faces in the group.
+};
+
+constexpr MeshFaceGroups::Handle MeshFaceGroups::kInvalid;
+
+#if XA_CHECK_T_JUNCTIONS
+static bool lineIntersectsPoint(const Vector3 &point, const Vector3 &lineStart, const Vector3 &lineEnd, float *t, float epsilon)
+{
+	float tt;
+	if (!t)
+		t = &tt;
+	*t = 0.0f;
+	if (equal(lineStart, point, epsilon) || equal(lineEnd, point, epsilon))
+		return false; // Vertex lies on either line vertices.
+	const Vector3 v01 = point - lineStart;
+	const Vector3 v21 = lineEnd - lineStart;
+	const float l = length(v21);
+	const float d = length(cross(v01, v21)) / l;
+	if (!isZero(d, epsilon))
+		return false;
+	*t = dot(v01, v21) / (l * l);
+	return *t > kEpsilon && *t < 1.0f - kEpsilon;
+}
+
+// Returns the number of T-junctions found.
+static int meshCheckTJunctions(const Mesh &inputMesh)
+{
+	int count = 0;
+	const uint32_t vertexCount = inputMesh.vertexCount();
+	const uint32_t edgeCount = inputMesh.edgeCount();
+	for (uint32_t v = 0; v < vertexCount; v++) {
+		if (!inputMesh.isBoundaryVertex(v))
+			continue;
+		// Find edges that this vertex overlaps with.
+		const Vector3 &pos = inputMesh.position(v);
+		for (uint32_t e = 0; e < edgeCount; e++) {
+			if (!inputMesh.isBoundaryEdge(e))
+				continue;
+			const Vector3 &edgePos1 = inputMesh.position(inputMesh.vertexAt(meshEdgeIndex0(e)));
+			const Vector3 &edgePos2 = inputMesh.position(inputMesh.vertexAt(meshEdgeIndex1(e)));
+			float t;
+			if (lineIntersectsPoint(pos, edgePos1, edgePos2, &t, inputMesh.epsilon()))
+				count++;
+		}
+	}
+	return count;
+}
+#endif
+
+// References invalid faces and vertices in a mesh.
+struct InvalidMeshGeometry
+{
+	// If meshFaceGroups is not null, invalid faces have the face group MeshFaceGroups::kInvalid.
+	// If meshFaceGroups is null, invalid faces are Mesh::isFaceIgnored.
+	void extract(const Mesh *mesh, const MeshFaceGroups *meshFaceGroups)
+	{
+		// Copy invalid faces.
+		m_faces.clear();
+		const uint32_t meshFaceCount = mesh->faceCount();
+		for (uint32_t f = 0; f < meshFaceCount; f++) {
+			if ((meshFaceGroups && meshFaceGroups->groupAt(f) == MeshFaceGroups::kInvalid) || (!meshFaceGroups && mesh->isFaceIgnored(f)))
+				m_faces.push_back(f);
+		}
+		// Create *unique* list of vertices of invalid faces.
+		const uint32_t faceCount = m_faces.size();
+		m_indices.resize(faceCount * 3);
+		const uint32_t approxVertexCount = min(faceCount * 3, mesh->vertexCount());
+		m_vertexToSourceVertexMap.clear();
+		m_vertexToSourceVertexMap.reserve(approxVertexCount);
+		HashMap<uint32_t, PassthroughHash<uint32_t>> sourceVertexToVertexMap(MemTag::Mesh, approxVertexCount);
+		for (uint32_t f = 0; f < faceCount; f++) {
+			const uint32_t face = m_faces[f];
+			for (uint32_t i = 0; i < 3; i++) {
+				const uint32_t vertex = mesh->vertexAt(face * 3 + i);
+				uint32_t newVertex = sourceVertexToVertexMap.get(vertex);
+				if (newVertex == UINT32_MAX) {
+					newVertex = sourceVertexToVertexMap.add(vertex);
+					m_vertexToSourceVertexMap.push_back(vertex);
+				}
+				m_indices[f * 3 + i] = newVertex;
+			}
+		}
+	}
+
+	ConstArrayView<uint32_t> faces() const { return m_faces; }
+	ConstArrayView<uint32_t> indices() const { return m_indices; }
+	ConstArrayView<uint32_t> vertices() const { return m_vertexToSourceVertexMap; }
+
+private:
+	Array<uint32_t> m_faces, m_indices;
+	Array<uint32_t> m_vertexToSourceVertexMap; // Map face vertices to vertices of the source mesh.
+};
+
+struct Progress
+{
+	Progress(ProgressCategory category, ProgressFunc func, void *userData, uint32_t maxValue) : cancel(false), m_category(category), m_func(func), m_userData(userData), m_value(0), m_maxValue(maxValue), m_percent(0)
+	{
+		if (m_func) {
+			if (!m_func(category, 0, userData))
+				cancel = true;
+		}
+	}
+
+	~Progress()
+	{
+		if (m_func) {
+			if (!m_func(m_category, 100, m_userData))
+				cancel = true;
+		}
+	}
+
+	void increment(uint32_t value)
+	{
+		m_value += value;
+		update();
+	}
+
+	void setMaxValue(uint32_t maxValue)
+	{
+		m_maxValue = maxValue;
+		update();
+	}
+
+	std::atomic<bool> cancel;
+
+private:
+	void update()
+	{
+		if (!m_func)
+			return;
+		const uint32_t newPercent = uint32_t(ceilf(m_value.load() / (float)m_maxValue.load() * 100.0f));
+		if (newPercent != m_percent) {
+			// Atomic max.
+			uint32_t oldPercent = m_percent;
+			while (oldPercent < newPercent && !m_percent.compare_exchange_weak(oldPercent, newPercent)) {}
+			if (!m_func(m_category, m_percent, m_userData))
+				cancel = true;
+		}
+	}
+
+	ProgressCategory m_category;
+	ProgressFunc m_func;
+	void *m_userData;
+	std::atomic<uint32_t> m_value, m_maxValue, m_percent;
+};
+
+struct Spinlock
+{
+	void lock() { while(m_lock.test_and_set(std::memory_order_acquire)) {} }
+	void unlock() { m_lock.clear(std::memory_order_release); }
+
+private:
+	std::atomic_flag m_lock = ATOMIC_FLAG_INIT;
+};
+
+struct TaskGroupHandle
+{
+	uint32_t value = UINT32_MAX;
+};
+
+struct Task
+{
+	void (*func)(void *groupUserData, void *taskUserData);
+	void *userData; // Passed to func as taskUserData.
+};
+
+#if XA_MULTITHREADED
+class TaskScheduler
+{
+public:
+	TaskScheduler() : m_shutdown(false)
+	{
+		m_threadIndex = 0;
+		// Max with current task scheduler usage is 1 per thread + 1 deep nesting, but allow for some slop.
+		m_maxGroups = std::thread::hardware_concurrency() * 4;
+		m_groups = XA_ALLOC_ARRAY(MemTag::Default, TaskGroup, m_maxGroups);
+		for (uint32_t i = 0; i < m_maxGroups; i++) {
+			new (&m_groups[i]) TaskGroup();
+			m_groups[i].free = true;
+			m_groups[i].ref = 0;
+			m_groups[i].userData = nullptr;
+		}
+		m_workers.resize(std::thread::hardware_concurrency() <= 1 ? 1 : std::thread::hardware_concurrency() - 1);
+		for (uint32_t i = 0; i < m_workers.size(); i++) {
+			new (&m_workers[i]) Worker();
+			m_workers[i].wakeup = false;
+			m_workers[i].thread = XA_NEW_ARGS(MemTag::Default, std::thread, workerThread, this, &m_workers[i], i + 1);
+		}
+	}
+
+	~TaskScheduler()
+	{
+		m_shutdown = true;
+		for (uint32_t i = 0; i < m_workers.size(); i++) {
+			Worker &worker = m_workers[i];
+			XA_DEBUG_ASSERT(worker.thread);
+			worker.wakeup = true;
+			worker.cv.notify_one();
+			if (worker.thread->joinable())
+				worker.thread->join();
+			worker.thread->~thread();
+			XA_FREE(worker.thread);
+			worker.~Worker();
+		}
+		for (uint32_t i = 0; i < m_maxGroups; i++)
+			m_groups[i].~TaskGroup();
+		XA_FREE(m_groups);
+	}
+
+	uint32_t threadCount() const
+	{
+		return max(1u, std::thread::hardware_concurrency()); // Including the main thread.
+	}
+
+	// userData is passed to Task::func as groupUserData.
+	TaskGroupHandle createTaskGroup(void *userData = nullptr, uint32_t reserveSize = 0)
+	{
+		// Claim the first free group.
+		for (uint32_t i = 0; i < m_maxGroups; i++) {
+			TaskGroup &group = m_groups[i];
+			bool expected = true;
+			if (!group.free.compare_exchange_strong(expected, false))
+				continue;
+			group.queueLock.lock();
+			group.queueHead = 0;
+			group.queue.clear();
+			group.queue.reserve(reserveSize);
+			group.queueLock.unlock();
+			group.userData = userData;
+			group.ref = 0;
+			TaskGroupHandle handle;
+			handle.value = i;
+			return handle;
+		}
+		XA_DEBUG_ASSERT(false);
+		TaskGroupHandle handle;
+		handle.value = UINT32_MAX;
+		return handle;
+	}
+
+	void run(TaskGroupHandle handle, const Task &task)
+	{
+		XA_DEBUG_ASSERT(handle.value != UINT32_MAX);
+		TaskGroup &group = m_groups[handle.value];
+		group.queueLock.lock();
+		group.queue.push_back(task);
+		group.queueLock.unlock();
+		group.ref++;
+		// Wake up a worker to run this task.
+		for (uint32_t i = 0; i < m_workers.size(); i++) {
+			m_workers[i].wakeup = true;
+			m_workers[i].cv.notify_one();
+		}
+	}
+
+	void wait(TaskGroupHandle *handle)
+	{
+		if (handle->value == UINT32_MAX) {
+			XA_DEBUG_ASSERT(false);
+			return;
+		}
+		// Run tasks from the group queue until empty.
+		TaskGroup &group = m_groups[handle->value];
+		for (;;) {
+			Task *task = nullptr;
+			group.queueLock.lock();
+			if (group.queueHead < group.queue.size())
+				task = &group.queue[group.queueHead++];
+			group.queueLock.unlock();
+			if (!task)
+				break;
+			task->func(group.userData, task->userData);
+			group.ref--;
+		}
+		// Even though the task queue is empty, workers can still be running tasks.
+		while (group.ref > 0)
+			std::this_thread::yield();
+		group.free = true;
+		handle->value = UINT32_MAX;
+	}
+
+	static uint32_t currentThreadIndex() { return m_threadIndex; }
+
+private:
+	struct TaskGroup
+	{
+		std::atomic<bool> free;
+		Array<Task> queue; // Items are never removed. queueHead is incremented to pop items.
+		uint32_t queueHead = 0;
+		Spinlock queueLock;
+		std::atomic<uint32_t> ref; // Increment when a task is enqueued, decrement when a task finishes.
+		void *userData;
+	};
+
+	struct Worker
+	{
+		std::thread *thread = nullptr;
+		std::mutex mutex;
+		std::condition_variable cv;
+		std::atomic<bool> wakeup;
+	};
+
+	TaskGroup *m_groups;
+	Array<Worker> m_workers;
+	std::atomic<bool> m_shutdown;
+	uint32_t m_maxGroups;
+	static thread_local uint32_t m_threadIndex;
+
+	static void workerThread(TaskScheduler *scheduler, Worker *worker, uint32_t threadIndex)
+	{
+		m_threadIndex = threadIndex;
+		std::unique_lock<std::mutex> lock(worker->mutex);
+		for (;;) {
+			worker->cv.wait(lock, [=]{ return worker->wakeup.load(); });
+			worker->wakeup = false;
+			for (;;) {
+				if (scheduler->m_shutdown)
+					return;
+				// Look for a task in any of the groups and run it.
+				TaskGroup *group = nullptr;
+				Task *task = nullptr;
+				for (uint32_t i = 0; i < scheduler->m_maxGroups; i++) {
+					group = &scheduler->m_groups[i];
+					if (group->free || group->ref == 0)
+						continue;
+					group->queueLock.lock();
+					if (group->queueHead < group->queue.size()) {
+						task = &group->queue[group->queueHead++];
+						group->queueLock.unlock();
+						break;
+					}
+					group->queueLock.unlock();
+				}
+				if (!task)
+					break;
+				task->func(group->userData, task->userData);
+				group->ref--;
+			}
+		}
+	}
+};
+
+thread_local uint32_t TaskScheduler::m_threadIndex;
+#else
+class TaskScheduler
+{
+public:
+	~TaskScheduler()
+	{
+		for (uint32_t i = 0; i < m_groups.size(); i++)
+			destroyGroup({ i });
+	}
+
+	uint32_t threadCount() const
+	{
+		return 1;
+	}
+
+	TaskGroupHandle createTaskGroup(void *userData = nullptr, uint32_t reserveSize = 0)
+	{
+		TaskGroup *group = XA_NEW(MemTag::Default, TaskGroup);
+		group->queue.reserve(reserveSize);
+		group->userData = userData;
+		m_groups.push_back(group);
+		TaskGroupHandle handle;
+		handle.value = m_groups.size() - 1;
+		return handle;
+	}
+
+	void run(TaskGroupHandle handle, Task task)
+	{
+		m_groups[handle.value]->queue.push_back(task);
+	}
+
+	void wait(TaskGroupHandle *handle)
+	{
+		if (handle->value == UINT32_MAX) {
+			XA_DEBUG_ASSERT(false);
+			return;
+		}
+		TaskGroup *group = m_groups[handle->value];
+		for (uint32_t i = 0; i < group->queue.size(); i++)
+			group->queue[i].func(group->userData, group->queue[i].userData);
+		group->queue.clear();
+		destroyGroup(*handle);
+		handle->value = UINT32_MAX;
+	}
+
+	static uint32_t currentThreadIndex() { return 0; }
+
+private:
+	void destroyGroup(TaskGroupHandle handle)
+	{
+		TaskGroup *group = m_groups[handle.value];
+		if (group) {
+			group->~TaskGroup();
+			XA_FREE(group);
+			m_groups[handle.value] = nullptr;
+		}
+	}
+
+	struct TaskGroup
+	{
+		Array<Task> queue;
+		void *userData;
+	};
+
+	Array<TaskGroup *> m_groups;
+};
+#endif
+
+#if XA_DEBUG_EXPORT_TGA
+const uint8_t TGA_TYPE_RGB = 2;
+const uint8_t TGA_ORIGIN_UPPER = 0x20;
+
+#pragma pack(push, 1)
+struct TgaHeader
+{
+	uint8_t id_length;
+	uint8_t colormap_type;
+	uint8_t image_type;
+	uint16_t colormap_index;
+	uint16_t colormap_length;
+	uint8_t colormap_size;
+	uint16_t x_origin;
+	uint16_t y_origin;
+	uint16_t width;
+	uint16_t height;
+	uint8_t pixel_size;
+	uint8_t flags;
+	enum { Size = 18 };
+};
+#pragma pack(pop)
+
+static void WriteTga(const char *filename, const uint8_t *data, uint32_t width, uint32_t height)
+{
+	XA_DEBUG_ASSERT(sizeof(TgaHeader) == TgaHeader::Size);
+	FILE *f;
+	XA_FOPEN(f, filename, "wb");
+	if (!f)
+		return;
+	TgaHeader tga;
+	tga.id_length = 0;
+	tga.colormap_type = 0;
+	tga.image_type = TGA_TYPE_RGB;
+	tga.colormap_index = 0;
+	tga.colormap_length = 0;
+	tga.colormap_size = 0;
+	tga.x_origin = 0;
+	tga.y_origin = 0;
+	tga.width = (uint16_t)width;
+	tga.height = (uint16_t)height;
+	tga.pixel_size = 24;
+	tga.flags = TGA_ORIGIN_UPPER;
+	fwrite(&tga, sizeof(TgaHeader), 1, f);
+	fwrite(data, sizeof(uint8_t), width * height * 3, f);
+	fclose(f);
+}
+#endif
+
+template<typename T>
+class ThreadLocal
+{
+public:
+	ThreadLocal()
+	{
+#if XA_MULTITHREADED
+		const uint32_t n = std::thread::hardware_concurrency();
+#else
+		const uint32_t n = 1;
+#endif
+		m_array = XA_ALLOC_ARRAY(MemTag::Default, T, n);
+		for (uint32_t i = 0; i < n; i++)
+			new (&m_array[i]) T;
+	}
+
+	~ThreadLocal()
+	{
+#if XA_MULTITHREADED
+		const uint32_t n = std::thread::hardware_concurrency();
+#else
+		const uint32_t n = 1;
+#endif
+		for (uint32_t i = 0; i < n; i++)
+			m_array[i].~T();
+		XA_FREE(m_array);
+	}
+
+	T &get() const
+	{
+		return m_array[TaskScheduler::currentThreadIndex()];
+	}
+
+private:
+	T *m_array;
+};
+
+// Implemented as a struct so the temporary arrays can be reused.
+struct Triangulator
+{
+	// This is doing a simple ear-clipping algorithm that skips invalid triangles. Ideally, we should
+	// also sort the ears by angle, start with the ones that have the smallest angle and proceed in order.
+	void triangulatePolygon(ConstArrayView<Vector3> vertices, ConstArrayView<uint32_t> inputIndices, Array<uint32_t> &outputIndices)
+	{
+		m_polygonVertices.clear();
+		m_polygonVertices.reserve(inputIndices.length);
+		outputIndices.clear();
+		if (inputIndices.length == 3) {
+			// Simple case for triangles.
+			outputIndices.push_back(inputIndices[0]);
+			outputIndices.push_back(inputIndices[1]);
+			outputIndices.push_back(inputIndices[2]);
+		}
+		else {
+			// Build 2D polygon projecting vertices onto normal plane.
+			// Faces are not necesarily planar, this is for example the case, when the face comes from filling a hole. In such cases
+			// it's much better to use the best fit plane.
+			Basis basis;
+			basis.normal = normalize(cross(vertices[inputIndices[1]] - vertices[inputIndices[0]], vertices[inputIndices[2]] - vertices[inputIndices[1]]));
+			basis.tangent = basis.computeTangent(basis.normal);
+			basis.bitangent = basis.computeBitangent(basis.normal, basis.tangent);
+			const uint32_t edgeCount = inputIndices.length;
+			m_polygonPoints.clear();
+			m_polygonPoints.reserve(edgeCount);
+			m_polygonAngles.clear();
+			m_polygonAngles.reserve(edgeCount);
+			for (uint32_t i = 0; i < inputIndices.length; i++) {
+				m_polygonVertices.push_back(inputIndices[i]);
+				const Vector3 &pos = vertices[inputIndices[i]];
+				m_polygonPoints.push_back(Vector2(dot(basis.tangent, pos), dot(basis.bitangent, pos)));
+			}
+			m_polygonAngles.resize(edgeCount);
+			while (m_polygonVertices.size() > 2) {
+				const uint32_t size = m_polygonVertices.size();
+				// Update polygon angles. @@ Update only those that have changed.
+				float minAngle = kPi2;
+				uint32_t bestEar = 0; // Use first one if none of them is valid.
+				bool bestIsValid = false;
+				for (uint32_t i = 0; i < size; i++) {
+					uint32_t i0 = i;
+					uint32_t i1 = (i + 1) % size; // Use Sean's polygon interation trick.
+					uint32_t i2 = (i + 2) % size;
+					Vector2 p0 = m_polygonPoints[i0];
+					Vector2 p1 = m_polygonPoints[i1];
+					Vector2 p2 = m_polygonPoints[i2];
+					float d = clamp(dot(p0 - p1, p2 - p1) / (length(p0 - p1) * length(p2 - p1)), -1.0f, 1.0f);
+					float angle = acosf(d);
+					float area = triangleArea(p0, p1, p2);
+					if (area < 0.0f)
+						angle = kPi2 - angle;
+					m_polygonAngles[i1] = angle;
+					if (angle < minAngle || !bestIsValid) {
+						// Make sure this is a valid ear, if not, skip this point.
+						bool valid = true;
+						for (uint32_t j = 0; j < size; j++) {
+							if (j == i0 || j == i1 || j == i2)
+								continue;
+							Vector2 p = m_polygonPoints[j];
+							if (pointInTriangle(p, p0, p1, p2)) {
+								valid = false;
+								break;
+							}
+						}
+						if (valid || !bestIsValid) {
+							minAngle = angle;
+							bestEar = i1;
+							bestIsValid = valid;
+						}
+					}
+				}
+				// Clip best ear:
+				const uint32_t i0 = (bestEar + size - 1) % size;
+				const uint32_t i1 = (bestEar + 0) % size;
+				const uint32_t i2 = (bestEar + 1) % size;
+				outputIndices.push_back(m_polygonVertices[i0]);
+				outputIndices.push_back(m_polygonVertices[i1]);
+				outputIndices.push_back(m_polygonVertices[i2]);
+				m_polygonVertices.removeAt(i1);
+				m_polygonPoints.removeAt(i1);
+				m_polygonAngles.removeAt(i1);
+			}
+		}
+	}
+
+private:
+	static bool pointInTriangle(const Vector2 &p, const Vector2 &a, const Vector2 &b, const Vector2 &c)
+	{
+		return triangleArea(a, b, p) >= kAreaEpsilon && triangleArea(b, c, p) >= kAreaEpsilon && triangleArea(c, a, p) >= kAreaEpsilon;
+	}
+
+	Array<int> m_polygonVertices;
+	Array<float> m_polygonAngles;
+	Array<Vector2> m_polygonPoints;
+};
+
+class UniformGrid2
+{
+public:
+	// indices are optional.
+	void reset(ConstArrayView<Vector2> positions, ConstArrayView<uint32_t> indices = ConstArrayView<uint32_t>(), uint32_t reserveEdgeCount = 0)
+	{
+		m_edges.clear();
+		if (reserveEdgeCount > 0)
+			m_edges.reserve(reserveEdgeCount);
+		m_positions = positions;
+		m_indices = indices;
+		m_cellDataOffsets.clear();
+	}
+
+	void append(uint32_t edge)
+	{
+		XA_DEBUG_ASSERT(m_cellDataOffsets.isEmpty());
+		m_edges.push_back(edge);
+	}
+
+	bool intersect(Vector2 v1, Vector2 v2, float epsilon)
+	{
+		const uint32_t edgeCount = m_edges.size();
+		bool bruteForce = edgeCount <= 20;
+		if (!bruteForce && m_cellDataOffsets.isEmpty())
+			bruteForce = !createGrid();
+		if (bruteForce) {
+			for (uint32_t j = 0; j < edgeCount; j++) {
+				const uint32_t edge = m_edges[j];
+				if (linesIntersect(v1, v2, edgePosition0(edge), edgePosition1(edge), epsilon))
+					return true;
+			}
+		} else {
+			computePotentialEdges(v1, v2);
+			uint32_t prevEdge = UINT32_MAX;
+			for (uint32_t j = 0; j < m_potentialEdges.size(); j++) {
+				const uint32_t edge = m_potentialEdges[j];
+				if (edge == prevEdge)
+					continue;
+				if (linesIntersect(v1, v2, edgePosition0(edge), edgePosition1(edge), epsilon))
+					return true;
+				prevEdge = edge;
+			}
+		}
+		return false;
+	}
+
+	// If edges is empty, checks for intersection with all edges in the grid.
+	bool intersect(float epsilon, ConstArrayView<uint32_t> edges = ConstArrayView<uint32_t>(), ConstArrayView<uint32_t> ignoreEdges = ConstArrayView<uint32_t>())
+	{
+		bool bruteForce = m_edges.size() <= 20;
+		if (!bruteForce && m_cellDataOffsets.isEmpty())
+			bruteForce = !createGrid();
+		const uint32_t *edges1, *edges2 = nullptr;
+		uint32_t edges1Count, edges2Count = 0;
+		if (edges.length == 0) {
+			edges1 = m_edges.data();
+			edges1Count = m_edges.size();
+		} else {
+			edges1 = edges.data;
+			edges1Count = edges.length;
+		}
+		if (bruteForce) {
+			edges2 = m_edges.data();
+			edges2Count = m_edges.size();
+		}
+		for (uint32_t i = 0; i < edges1Count; i++) {
+			const uint32_t edge1 = edges1[i];
+			const uint32_t edge1Vertex[2] = { vertexAt(meshEdgeIndex0(edge1)), vertexAt(meshEdgeIndex1(edge1)) };
+			const Vector2 &edge1Position1 = m_positions[edge1Vertex[0]];
+			const Vector2 &edge1Position2 = m_positions[edge1Vertex[1]];
+			const Extents2 edge1Extents(edge1Position1, edge1Position2);
+			uint32_t j = 0;
+			if (bruteForce) {
+				// If checking against self, test each edge pair only once.
+				if (edges.length == 0) {
+					j = i + 1;
+					if (j == edges1Count)
+						break;
+				}
+			} else {
+				computePotentialEdges(edgePosition0(edge1), edgePosition1(edge1));
+				edges2 = m_potentialEdges.data();
+				edges2Count = m_potentialEdges.size();
+			}
+			uint32_t prevEdge = UINT32_MAX; // Handle potential edges duplicates.
+			for (; j < edges2Count; j++) {
+				const uint32_t edge2 = edges2[j];
+				if (edge1 == edge2)
+					continue;
+				if (edge2 == prevEdge)
+					continue;
+				prevEdge = edge2;
+				// Check if edge2 is ignored.
+				bool ignore = false;
+				for (uint32_t k = 0; k < ignoreEdges.length; k++) {
+					if (edge2 == ignoreEdges[k]) {
+						ignore = true;
+						break;
+					}
+				}
+				if (ignore)
+					continue;
+				const uint32_t edge2Vertex[2] = { vertexAt(meshEdgeIndex0(edge2)), vertexAt(meshEdgeIndex1(edge2)) };
+				// Ignore connected edges, since they can't intersect (only overlap), and may be detected as false positives.
+				if (edge1Vertex[0] == edge2Vertex[0] || edge1Vertex[0] == edge2Vertex[1] || edge1Vertex[1] == edge2Vertex[0] || edge1Vertex[1] == edge2Vertex[1])
+					continue;
+				const Vector2 &edge2Position1 = m_positions[edge2Vertex[0]];
+				const Vector2 &edge2Position2 = m_positions[edge2Vertex[1]];
+				if (!Extents2::intersect(edge1Extents, Extents2(edge2Position1, edge2Position2)))
+					continue;
+				if (linesIntersect(edge1Position1, edge1Position2, edge2Position1, edge2Position2, epsilon))
+					return true;
+			}
+		}
+		return false;
+	}
+
+#if XA_DEBUG_EXPORT_BOUNDARY_GRID
+	void debugExport(const char *filename)
+	{
+		Array<uint8_t> image;
+		image.resize(m_gridWidth * m_gridHeight * 3);
+		for (uint32_t y = 0; y < m_gridHeight; y++) {
+			for (uint32_t x = 0; x < m_gridWidth; x++) {
+				uint8_t *bgr = &image[(x + y * m_gridWidth) * 3];
+				bgr[0] = bgr[1] = bgr[2] = 32;
+				uint32_t offset = m_cellDataOffsets[x + y * m_gridWidth];
+				while (offset != UINT32_MAX) {
+					const uint32_t edge2 = m_cellData[offset];
+					srand(edge2);
+					for (uint32_t i = 0; i < 3; i++)
+						bgr[i] = uint8_t(bgr[i] * 0.5f + (rand() % 255) * 0.5f);
+					offset = m_cellData[offset + 1];
+				}
+			}
+		}
+		WriteTga(filename, image.data(), m_gridWidth, m_gridHeight);
+	}
+#endif
+
+private:
+	bool createGrid()
+	{
+		// Compute edge extents. Min will be the grid origin.
+		const uint32_t edgeCount = m_edges.size();
+		Extents2 edgeExtents;
+		edgeExtents.reset();
+		for (uint32_t i = 0; i < edgeCount; i++) {
+			const uint32_t edge = m_edges[i];
+			edgeExtents.add(edgePosition0(edge));
+			edgeExtents.add(edgePosition1(edge));
+		}
+		m_gridOrigin = edgeExtents.min;
+		// Size grid to approximately one edge per cell in the largest dimension.
+		const Vector2 extentsSize(edgeExtents.max - edgeExtents.min);
+		m_cellSize = max(extentsSize.x, extentsSize.y) / (float)clamp(edgeCount, 32u, 512u);
+		if (m_cellSize <= 0.0f)
+			return false;
+		m_gridWidth = uint32_t(ceilf(extentsSize.x / m_cellSize));
+		m_gridHeight = uint32_t(ceilf(extentsSize.y / m_cellSize));
+		if (m_gridWidth <= 1 || m_gridHeight <= 1)
+			return false;
+		// Insert edges into cells.
+		m_cellDataOffsets.resize(m_gridWidth * m_gridHeight);
+		for (uint32_t i = 0; i < m_cellDataOffsets.size(); i++)
+			m_cellDataOffsets[i] = UINT32_MAX;
+		m_cellData.clear();
+		m_cellData.reserve(edgeCount * 2);
+		for (uint32_t i = 0; i < edgeCount; i++) {
+			const uint32_t edge = m_edges[i];
+			traverse(edgePosition0(edge), edgePosition1(edge));
+			XA_DEBUG_ASSERT(!m_traversedCellOffsets.isEmpty());
+			for (uint32_t j = 0; j < m_traversedCellOffsets.size(); j++) {
+				const uint32_t cell = m_traversedCellOffsets[j];
+				uint32_t offset = m_cellDataOffsets[cell];
+				if (offset == UINT32_MAX)
+					m_cellDataOffsets[cell] = m_cellData.size();
+				else {
+					for (;;) {
+						uint32_t &nextOffset = m_cellData[offset + 1];
+						if (nextOffset == UINT32_MAX) {
+							nextOffset = m_cellData.size();
+							break;
+						}
+						offset = nextOffset;
+					}
+				}
+				m_cellData.push_back(edge);
+				m_cellData.push_back(UINT32_MAX);
+			}
+		}
+		return true;
+	}
+
+	void computePotentialEdges(Vector2 p1, Vector2 p2)
+	{
+		m_potentialEdges.clear();
+		traverse(p1, p2);
+		for (uint32_t j = 0; j < m_traversedCellOffsets.size(); j++) {
+			const uint32_t cell = m_traversedCellOffsets[j];
+			uint32_t offset = m_cellDataOffsets[cell];
+			while (offset != UINT32_MAX) {
+				const uint32_t edge2 = m_cellData[offset];
+				m_potentialEdges.push_back(edge2);
+				offset = m_cellData[offset + 1];
+			}
+		}
+		if (m_potentialEdges.isEmpty())
+			return;
+		insertionSort(m_potentialEdges.data(), m_potentialEdges.size());
+	}
+
+	// "A Fast Voxel Traversal Algorithm for Ray Tracing"
+	void traverse(Vector2 p1, Vector2 p2)
+	{
+		const Vector2 dir = p2 - p1;
+		const Vector2 normal = normalizeSafe(dir, Vector2(0.0f));
+		const int stepX = dir.x >= 0 ? 1 : -1;
+		const int stepY = dir.y >= 0 ? 1 : -1;
+		const uint32_t firstCell[2] = { cellX(p1.x), cellY(p1.y) };
+		const uint32_t lastCell[2] = { cellX(p2.x), cellY(p2.y) };
+		float distToNextCellX;
+		if (stepX == 1)
+			distToNextCellX = (firstCell[0] + 1) * m_cellSize - (p1.x - m_gridOrigin.x);
+		else
+			distToNextCellX = (p1.x - m_gridOrigin.x) - firstCell[0] * m_cellSize;
+		float distToNextCellY;
+		if (stepY == 1)
+			distToNextCellY = (firstCell[1] + 1) * m_cellSize - (p1.y - m_gridOrigin.y);
+		else
+			distToNextCellY = (p1.y - m_gridOrigin.y) - firstCell[1] * m_cellSize;
+		float tMaxX, tMaxY, tDeltaX, tDeltaY;
+		if (normal.x > kEpsilon || normal.x < -kEpsilon) {
+			tMaxX = (distToNextCellX * stepX) / normal.x;
+			tDeltaX = (m_cellSize * stepX) / normal.x;
+		}
+		else
+			tMaxX = tDeltaX = FLT_MAX;
+		if (normal.y > kEpsilon || normal.y < -kEpsilon) {
+			tMaxY = (distToNextCellY * stepY) / normal.y;
+			tDeltaY = (m_cellSize * stepY) / normal.y;
+		}
+		else
+			tMaxY = tDeltaY = FLT_MAX;
+		m_traversedCellOffsets.clear();
+		m_traversedCellOffsets.push_back(firstCell[0] + firstCell[1] * m_gridWidth);
+		uint32_t currentCell[2] = { firstCell[0], firstCell[1] };
+		while (!(currentCell[0] == lastCell[0] && currentCell[1] == lastCell[1])) {
+			if (tMaxX < tMaxY) {
+				tMaxX += tDeltaX;
+				currentCell[0] += stepX;
+			} else {
+				tMaxY += tDeltaY;
+				currentCell[1] += stepY;
+			}
+			if (currentCell[0] >= m_gridWidth || currentCell[1] >= m_gridHeight)
+				break;
+			if (stepX == -1 && currentCell[0] < lastCell[0])
+				break;
+			if (stepX == 1 && currentCell[0] > lastCell[0])
+				break;
+			if (stepY == -1 && currentCell[1] < lastCell[1])
+				break;
+			if (stepY == 1 && currentCell[1] > lastCell[1])
+				break;
+			m_traversedCellOffsets.push_back(currentCell[0] + currentCell[1] * m_gridWidth);
+		}
+	}
+
+	uint32_t cellX(float x) const
+	{
+		return min((uint32_t)max(0.0f, (x - m_gridOrigin.x) / m_cellSize), m_gridWidth - 1u);
+	}
+
+	uint32_t cellY(float y) const
+	{
+		return min((uint32_t)max(0.0f, (y - m_gridOrigin.y) / m_cellSize), m_gridHeight - 1u);
+	}
+
+	Vector2 edgePosition0(uint32_t edge) const
+	{
+		return m_positions[vertexAt(meshEdgeIndex0(edge))];
+	}
+
+	Vector2 edgePosition1(uint32_t edge) const
+	{
+		return m_positions[vertexAt(meshEdgeIndex1(edge))];
+	}
+
+	uint32_t vertexAt(uint32_t index) const
+	{
+		return m_indices.length > 0 ? m_indices[index] : index;
+	}
+
+	Array<uint32_t> m_edges;
+	ConstArrayView<Vector2> m_positions;
+	ConstArrayView<uint32_t> m_indices; // Optional. Empty if unused.
+	float m_cellSize;
+	Vector2 m_gridOrigin;
+	uint32_t m_gridWidth, m_gridHeight; // in cells
+	Array<uint32_t> m_cellDataOffsets;
+	Array<uint32_t> m_cellData;
+	Array<uint32_t> m_potentialEdges;
+	Array<uint32_t> m_traversedCellOffsets;
+};
+
+struct UvMeshChart
+{
+	Array<uint32_t> faces;
+	Array<uint32_t> indices;
+	uint32_t material;
+};
+
+struct UvMesh
+{
+	UvMeshDecl decl;
+	BitArray faceIgnore;
+	Array<uint32_t> faceMaterials;
+	Array<uint32_t> indices;
+	Array<Vector2> texcoords; // Copied from input and never modified, UvMeshInstance::texcoords are. Used to restore UvMeshInstance::texcoords so packing can be run multiple times.
+	Array<UvMeshChart *> charts;
+	Array<uint32_t> vertexToChartMap;
+};
+
+struct UvMeshInstance
+{
+	UvMesh *mesh;
+	Array<Vector2> texcoords;
+};
+
+/*
+ *  Copyright (c) 2004-2010, Bruno Levy
+ *  All rights reserved.
+ *
+ *  Redistribution and use in source and binary forms, with or without
+ *  modification, are permitted provided that the following conditions are met:
+ *
+ *  * Redistributions of source code must retain the above copyright notice,
+ *  this list of conditions and the following disclaimer.
+ *  * Redistributions in binary form must reproduce the above copyright notice,
+ *  this list of conditions and the following disclaimer in the documentation
+ *  and/or other materials provided with the distribution.
+ *  * Neither the name of the ALICE Project-Team nor the names of its
+ *  contributors may be used to endorse or promote products derived from this
+ *  software without specific prior written permission.
+ *
+ *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ *  POSSIBILITY OF SUCH DAMAGE.
+ *
+ *  If you modify this software, you should include a notice giving the
+ *  name of the person performing the modification, the date of modification,
+ *  and the reason for such modification.
+ *
+ *  Contact: Bruno Levy
+ *
+ *     levy@loria.fr
+ *
+ *     ALICE Project
+ *     LORIA, INRIA Lorraine,
+ *     Campus Scientifique, BP 239
+ *     54506 VANDOEUVRE LES NANCY CEDEX
+ *     FRANCE
+ */
+namespace opennl {
+#define NL_NEW(T)              XA_ALLOC(MemTag::OpenNL, T)
+#define NL_NEW_ARRAY(T,NB)     XA_ALLOC_ARRAY(MemTag::OpenNL, T, NB)
+#define NL_RENEW_ARRAY(T,x,NB) XA_REALLOC(MemTag::OpenNL, x, T, NB)
+#define NL_DELETE(x)           XA_FREE(x); x = nullptr
+#define NL_DELETE_ARRAY(x)     XA_FREE(x); x = nullptr
+#define NL_CLEAR(x, T)         memset(x, 0, sizeof(T));
+#define NL_CLEAR_ARRAY(T,x,NB) memset(x, 0, (size_t)(NB)*sizeof(T))
+#define NL_NEW_VECTOR(dim)     XA_ALLOC_ARRAY(MemTag::OpenNL, double, dim)
+#define NL_DELETE_VECTOR(ptr)  XA_FREE(ptr)
+
+struct NLMatrixStruct;
+typedef NLMatrixStruct * NLMatrix;
+typedef void (*NLDestroyMatrixFunc)(NLMatrix M);
+typedef void (*NLMultMatrixVectorFunc)(NLMatrix M, const double* x, double* y);
+
+#define NL_MATRIX_SPARSE_DYNAMIC 0x1001
+#define NL_MATRIX_CRS            0x1002
+#define NL_MATRIX_OTHER          0x1006
+
+struct NLMatrixStruct
+{
+	uint32_t m;
+	uint32_t n;
+	uint32_t type;
+	NLDestroyMatrixFunc destroy_func;
+	NLMultMatrixVectorFunc mult_func;
+};
+
+/* Dynamic arrays for sparse row/columns */
+
+struct NLCoeff
+{
+	uint32_t index;
+	double value;
+};
+
+struct NLRowColumn
+{
+	uint32_t size;
+	uint32_t capacity;
+	NLCoeff* coeff;
+};
+
+/* Compressed Row Storage */
+
+struct NLCRSMatrix
+{
+	uint32_t m;
+	uint32_t n;
+	uint32_t type;
+	NLDestroyMatrixFunc destroy_func;
+	NLMultMatrixVectorFunc mult_func;
+	double* val;
+	uint32_t* rowptr;
+	uint32_t* colind;
+	uint32_t nslices;
+	uint32_t* sliceptr;
+};
+
+/* SparseMatrix data structure */
+
+struct NLSparseMatrix
+{
+	uint32_t m;
+	uint32_t n;
+	uint32_t type;
+	NLDestroyMatrixFunc destroy_func;
+	NLMultMatrixVectorFunc mult_func;
+	uint32_t diag_size;
+	uint32_t diag_capacity;
+	NLRowColumn* row;
+	NLRowColumn* column;
+	double*    diag;
+	uint32_t row_capacity;
+	uint32_t column_capacity;
+};
+
+/* NLContext data structure */
+
+struct NLBufferBinding
+{
+	void* base_address;
+	uint32_t stride;
+};
+
+#define NL_BUFFER_ITEM(B,i) *(double*)((void*)((char*)((B).base_address)+((i)*(B).stride)))
+
+struct NLContext
+{
+	NLBufferBinding *variable_buffer;
+	double *variable_value;
+	bool *variable_is_locked;
+	uint32_t *variable_index;
+	uint32_t n;
+	NLMatrix M;
+	NLMatrix P;
+	NLMatrix B;
+	NLRowColumn af;
+	NLRowColumn al;
+	double *x;
+	double *b;
+	uint32_t nb_variables;
+	uint32_t nb_systems;
+	uint32_t current_row;
+	uint32_t max_iterations;
+	bool max_iterations_defined;
+	double threshold;
+	double omega;
+	uint32_t used_iterations;
+	double error;
+};
+
+static void nlDeleteMatrix(NLMatrix M)
+{
+	if (!M)
+		return;
+	M->destroy_func(M);
+	NL_DELETE(M);
+}
+
+static void nlMultMatrixVector(NLMatrix M, const double* x, double* y)
+{
+	M->mult_func(M, x, y);
+}
+
+static void nlRowColumnConstruct(NLRowColumn* c)
+{
+	c->size = 0;
+	c->capacity = 0;
+	c->coeff = nullptr;
+}
+
+static void nlRowColumnDestroy(NLRowColumn* c)
+{
+	NL_DELETE_ARRAY(c->coeff);
+	c->size = 0;
+	c->capacity = 0;
+}
+
+static void nlRowColumnGrow(NLRowColumn* c)
+{
+	if (c->capacity != 0) {
+		c->capacity = 2 * c->capacity;
+		c->coeff = NL_RENEW_ARRAY(NLCoeff, c->coeff, c->capacity);
+	} else {
+		c->capacity = 4;
+		c->coeff = NL_NEW_ARRAY(NLCoeff, c->capacity);
+		NL_CLEAR_ARRAY(NLCoeff, c->coeff, c->capacity);
+	}
+}
+
+static void nlRowColumnAdd(NLRowColumn* c, uint32_t index, double value)
+{
+	for (uint32_t i = 0; i < c->size; i++) {
+		if (c->coeff[i].index == index) {
+			c->coeff[i].value += value;
+			return;
+		}
+	}
+	if (c->size == c->capacity)
+		nlRowColumnGrow(c);
+	c->coeff[c->size].index = index;
+	c->coeff[c->size].value = value;
+	c->size++;
+}
+
+/* Does not check whether the index already exists */
+static void nlRowColumnAppend(NLRowColumn* c, uint32_t index, double value)
+{
+	if (c->size == c->capacity)
+		nlRowColumnGrow(c);
+	c->coeff[c->size].index = index;
+	c->coeff[c->size].value = value;
+	c->size++;
+}
+
+static void nlRowColumnZero(NLRowColumn* c)
+{
+	c->size = 0;
+}
+
+static void nlRowColumnClear(NLRowColumn* c)
+{
+	c->size = 0;
+	c->capacity = 0;
+	NL_DELETE_ARRAY(c->coeff);
+}
+
+static int nlCoeffCompare(const void* p1, const void* p2)
+{
+	return (((NLCoeff*)(p2))->index < ((NLCoeff*)(p1))->index);
+}
+
+static void nlRowColumnSort(NLRowColumn* c)
+{
+	qsort(c->coeff, c->size, sizeof(NLCoeff), nlCoeffCompare);
+}
+
+/* CRSMatrix data structure */
+
+static void nlCRSMatrixDestroy(NLCRSMatrix* M)
+{
+	NL_DELETE_ARRAY(M->val);
+	NL_DELETE_ARRAY(M->rowptr);
+	NL_DELETE_ARRAY(M->colind);
+	NL_DELETE_ARRAY(M->sliceptr);
+	M->m = 0;
+	M->n = 0;
+	M->nslices = 0;
+}
+
+static void nlCRSMatrixMultSlice(NLCRSMatrix* M, const double* x, double* y, uint32_t Ibegin, uint32_t Iend)
+{
+	for (uint32_t i = Ibegin; i < Iend; ++i) {
+		double sum = 0.0;
+		for (uint32_t j = M->rowptr[i]; j < M->rowptr[i + 1]; ++j)
+			sum += M->val[j] * x[M->colind[j]];
+		y[i] = sum;
+	}
+}
+
+static void nlCRSMatrixMult(NLCRSMatrix* M, const double* x, double* y)
+{
+	int nslices = (int)(M->nslices);
+	for (int slice = 0; slice < nslices; ++slice)
+		nlCRSMatrixMultSlice(M, x, y, M->sliceptr[slice], M->sliceptr[slice + 1]);
+}
+
+static void nlCRSMatrixConstruct(NLCRSMatrix* M, uint32_t m, uint32_t n, uint32_t nnz, uint32_t nslices)
+{
+	M->m = m;
+	M->n = n;
+	M->type = NL_MATRIX_CRS;
+	M->destroy_func = (NLDestroyMatrixFunc)nlCRSMatrixDestroy;
+	M->mult_func = (NLMultMatrixVectorFunc)nlCRSMatrixMult;
+	M->nslices = nslices;
+	M->val = NL_NEW_ARRAY(double, nnz);
+	NL_CLEAR_ARRAY(double, M->val, nnz);
+	M->rowptr = NL_NEW_ARRAY(uint32_t, m + 1);
+	NL_CLEAR_ARRAY(uint32_t, M->rowptr, m + 1);
+	M->colind = NL_NEW_ARRAY(uint32_t, nnz);
+	NL_CLEAR_ARRAY(uint32_t, M->colind, nnz);
+	M->sliceptr = NL_NEW_ARRAY(uint32_t, nslices + 1);
+	NL_CLEAR_ARRAY(uint32_t, M->sliceptr, nslices + 1);
+}
+
+/* SparseMatrix data structure */
+
+static void nlSparseMatrixDestroyRowColumns(NLSparseMatrix* M)
+{
+	for (uint32_t i = 0; i < M->m; i++)
+		nlRowColumnDestroy(&(M->row[i]));
+	NL_DELETE_ARRAY(M->row);
+}
+
+static void nlSparseMatrixDestroy(NLSparseMatrix* M)
+{
+	XA_DEBUG_ASSERT(M->type == NL_MATRIX_SPARSE_DYNAMIC);
+	nlSparseMatrixDestroyRowColumns(M);
+	NL_DELETE_ARRAY(M->diag);
+}
+
+static void nlSparseMatrixAdd(NLSparseMatrix* M, uint32_t i, uint32_t j, double value)
+{
+	XA_DEBUG_ASSERT(i >= 0 && i <= M->m - 1);
+	XA_DEBUG_ASSERT(j >= 0 && j <= M->n - 1);
+	if (i == j)
+		M->diag[i] += value;
+	nlRowColumnAdd(&(M->row[i]), j, value);
+}
+
+/* Returns the number of non-zero coefficients */
+static uint32_t nlSparseMatrixNNZ(NLSparseMatrix* M)
+{
+	uint32_t nnz = 0;
+	for (uint32_t i = 0; i < M->m; i++)
+		nnz += M->row[i].size;
+	return nnz;
+}
+
+static void nlSparseMatrixSort(NLSparseMatrix* M)
+{
+	for (uint32_t i = 0; i < M->m; i++)
+		nlRowColumnSort(&(M->row[i]));
+}
+
+/* SparseMatrix x Vector routines, internal helper routines */
+
+static void nlSparseMatrix_mult_rows(NLSparseMatrix* A,	const double* x, double* y)
+{
+	/*
+	 * Note: OpenMP does not like unsigned ints
+	 * (causes some floating point exceptions),
+	 * therefore I use here signed ints for all
+	 * indices.
+	 */
+	int m = (int)(A->m);
+	NLCoeff* c = nullptr;
+	NLRowColumn* Ri = nullptr;
+	for (int i = 0; i < m; i++) {
+		Ri = &(A->row[i]);
+		y[i] = 0;
+		for (int ij = 0; ij < (int)(Ri->size); ij++) {
+			c = &(Ri->coeff[ij]);
+			y[i] += c->value * x[c->index];
+		}
+	}
+}
+
+static void nlSparseMatrixMult(NLSparseMatrix* A, const double* x, double* y)
+{
+	XA_DEBUG_ASSERT(A->type == NL_MATRIX_SPARSE_DYNAMIC);
+	nlSparseMatrix_mult_rows(A, x, y);
+}
+
+static void nlSparseMatrixConstruct(NLSparseMatrix* M, uint32_t m, uint32_t n)
+{
+	M->m = m;
+	M->n = n;
+	M->type = NL_MATRIX_SPARSE_DYNAMIC;
+	M->destroy_func = (NLDestroyMatrixFunc)nlSparseMatrixDestroy;
+	M->mult_func = (NLMultMatrixVectorFunc)nlSparseMatrixMult;
+	M->row = NL_NEW_ARRAY(NLRowColumn, m);
+	NL_CLEAR_ARRAY(NLRowColumn, M->row, m);
+	M->row_capacity = m;
+	for (uint32_t i = 0; i < n; i++)
+		nlRowColumnConstruct(&(M->row[i]));
+	M->row_capacity = 0;
+	M->column = nullptr;
+	M->column_capacity = 0;
+	M->diag_size = min(m, n);
+	M->diag_capacity = M->diag_size;
+	M->diag = NL_NEW_ARRAY(double, M->diag_size);
+	NL_CLEAR_ARRAY(double, M->diag, M->diag_size);
+}
+
+static NLMatrix nlCRSMatrixNewFromSparseMatrix(NLSparseMatrix* M)
+{
+	uint32_t nnz = nlSparseMatrixNNZ(M);
+	uint32_t nslices = 8; /* TODO: get number of cores */
+	uint32_t slice, cur_bound, cur_NNZ, cur_row;
+	uint32_t k;
+	uint32_t slice_size = nnz / nslices;
+	NLCRSMatrix* CRS = NL_NEW(NLCRSMatrix);
+	NL_CLEAR(CRS, NLCRSMatrix);
+	nlCRSMatrixConstruct(CRS, M->m, M->n, nnz, nslices);
+	nlSparseMatrixSort(M);
+	/* Convert matrix to CRS format */
+	k = 0;
+	for (uint32_t i = 0; i < M->m; ++i) {
+		NLRowColumn* Ri = &(M->row[i]);
+		CRS->rowptr[i] = k;
+		for (uint32_t ij = 0; ij < Ri->size; ij++) {
+			NLCoeff* c = &(Ri->coeff[ij]);
+			CRS->val[k] = c->value;
+			CRS->colind[k] = c->index;
+			++k;
+		}
+	}
+	CRS->rowptr[M->m] = k;
+	/* Create "slices" to be used by parallel sparse matrix vector product */
+	if (CRS->sliceptr) {
+		cur_bound = slice_size;
+		cur_NNZ = 0;
+		cur_row = 0;
+		CRS->sliceptr[0] = 0;
+		for (slice = 1; slice < nslices; ++slice) {
+			while (cur_NNZ < cur_bound && cur_row < M->m) {
+				cur_NNZ += CRS->rowptr[cur_row + 1] - CRS->rowptr[cur_row];
+				++cur_row;
+			}
+			CRS->sliceptr[slice] = cur_row;
+			cur_bound += slice_size;
+		}
+		CRS->sliceptr[nslices] = M->m;
+	}
+	return (NLMatrix)CRS;
+}
+
+static void nlMatrixCompress(NLMatrix* M)
+{
+	NLMatrix CRS = nullptr;
+	if ((*M)->type != NL_MATRIX_SPARSE_DYNAMIC)
+		return;
+	CRS = nlCRSMatrixNewFromSparseMatrix((NLSparseMatrix*)*M);
+	nlDeleteMatrix(*M);
+	*M = CRS;
+}
+
+static NLContext *nlNewContext()
+{
+	NLContext* result = NL_NEW(NLContext);
+	NL_CLEAR(result, NLContext);
+	result->max_iterations = 100;
+	result->threshold = 1e-6;
+	result->omega = 1.5;
+	result->nb_systems = 1;
+	return result;
+}
+
+static void nlDeleteContext(NLContext *context)
+{
+	nlDeleteMatrix(context->M);
+	context->M = nullptr;
+	nlDeleteMatrix(context->P);
+	context->P = nullptr;
+	nlDeleteMatrix(context->B);
+	context->B = nullptr;
+	nlRowColumnDestroy(&context->af);
+	nlRowColumnDestroy(&context->al);
+	NL_DELETE_ARRAY(context->variable_value);
+	NL_DELETE_ARRAY(context->variable_buffer);
+	NL_DELETE_ARRAY(context->variable_is_locked);
+	NL_DELETE_ARRAY(context->variable_index);
+	NL_DELETE_ARRAY(context->x);
+	NL_DELETE_ARRAY(context->b);
+	NL_DELETE(context);
+}
+
+static double ddot(int n, const double *x, const double *y)
+{
+	double sum = 0.0;
+	for (int i = 0; i < n; i++)
+		sum += x[i] * y[i];
+	return sum;
+}
+
+static void daxpy(int n, double a, const double *x, double *y)
+{
+	for (int i = 0; i < n; i++)
+		y[i] = a * x[i] + y[i];
+}
+
+static void dscal(int n, double a, double *x)
+{
+	for (int i = 0; i < n; i++)
+		x[i] *= a;
+}
+
+/*
+ * The implementation of the solvers is inspired by
+ * the lsolver library, by Christian Badura, available from:
+ * http://www.mathematik.uni-freiburg.de
+ * /IAM/Research/projectskr/lin_solver/
+ *
+ * About the Conjugate Gradient, details can be found in:
+ *  Ashby, Manteuffel, Saylor
+ *     A taxononmy for conjugate gradient methods
+ *     SIAM J Numer Anal 27, 1542-1568 (1990)
+ *
+ *  This version is completely abstract, the same code can be used for
+ * CPU/GPU, dense matrix / sparse matrix etc...
+ *  Abstraction is realized through:
+  *   - Abstract matrix interface (NLMatrix), that can implement different
+ *     versions of matrix x vector product (CPU/GPU, sparse/dense ...)
+ */
+
+static uint32_t nlSolveSystem_PRE_CG(NLMatrix M, NLMatrix P, double* b, double* x, double eps, uint32_t max_iter, double *sq_bnorm, double *sq_rnorm)
+{
+	int     N = (int)M->n;
+	double* r = NL_NEW_VECTOR(N);
+	double* d = NL_NEW_VECTOR(N);
+	double* h = NL_NEW_VECTOR(N);
+	double *Ad = h;
+	uint32_t its = 0;
+	double rh, alpha, beta;
+	double b_square = ddot(N, b, b);
+	double err = eps * eps*b_square;
+	double curr_err;
+	nlMultMatrixVector(M, x, r);
+	daxpy(N, -1., b, r);
+	nlMultMatrixVector(P, r, d);
+	memcpy(h, d, N * sizeof(double));
+	rh = ddot(N, r, h);
+	curr_err = ddot(N, r, r);
+	while (curr_err > err && its < max_iter) {
+		nlMultMatrixVector(M, d, Ad);
+		alpha = rh / ddot(N, d, Ad);
+		daxpy(N, -alpha, d, x);
+		daxpy(N, -alpha, Ad, r);
+		nlMultMatrixVector(P, r, h);
+		beta = 1. / rh;
+		rh = ddot(N, r, h);
+		beta *= rh;
+		dscal(N, beta, d);
+		daxpy(N, 1., h, d);
+		++its;
+		curr_err = ddot(N, r, r);
+	}
+	NL_DELETE_VECTOR(r);
+	NL_DELETE_VECTOR(d);
+	NL_DELETE_VECTOR(h);
+	*sq_bnorm = b_square;
+	*sq_rnorm = curr_err;
+	return its;
+}
+
+static uint32_t nlSolveSystemIterative(NLContext *context, NLMatrix M, NLMatrix P, double* b_in, double* x_in, double eps, uint32_t max_iter)
+{
+	uint32_t result = 0;
+	double rnorm = 0.0;
+	double bnorm = 0.0;
+	double* b = b_in;
+	double* x = x_in;
+	XA_DEBUG_ASSERT(M->m == M->n);
+	double sq_bnorm, sq_rnorm;
+	result = nlSolveSystem_PRE_CG(M, P, b, x, eps, max_iter, &sq_bnorm, &sq_rnorm);
+	/* Get residual norm and rhs norm */
+	bnorm = sqrt(sq_bnorm);
+	rnorm = sqrt(sq_rnorm);
+	if (bnorm == 0.0)
+		context->error = rnorm;
+	else
+		context->error = rnorm / bnorm;
+	context->used_iterations = result;
+	return result;
+}
+
+static bool nlSolveIterative(NLContext *context)
+{
+	double* b = context->b;
+	double* x = context->x;
+	uint32_t n = context->n;
+	NLMatrix M = context->M;
+	NLMatrix P = context->P;
+	for (uint32_t k = 0; k < context->nb_systems; ++k) {
+		nlSolveSystemIterative(context, M, P, b, x, context->threshold, context->max_iterations);
+		b += n;
+		x += n;
+	}
+	return true;
+}
+
+struct NLJacobiPreconditioner
+{
+	uint32_t m;
+	uint32_t n;
+	uint32_t type;
+	NLDestroyMatrixFunc destroy_func;
+	NLMultMatrixVectorFunc mult_func;
+	double* diag_inv;
+};
+
+static void nlJacobiPreconditionerDestroy(NLJacobiPreconditioner* M)
+{
+	NL_DELETE_ARRAY(M->diag_inv);
+}
+
+static void nlJacobiPreconditionerMult(NLJacobiPreconditioner* M, const double* x, double* y)
+{
+	for (uint32_t i = 0; i < M->n; ++i)
+		y[i] = x[i] * M->diag_inv[i];
+}
+
+static NLMatrix nlNewJacobiPreconditioner(NLMatrix M_in)
+{
+	NLSparseMatrix* M = nullptr;
+	NLJacobiPreconditioner* result = nullptr;
+	XA_DEBUG_ASSERT(M_in->type == NL_MATRIX_SPARSE_DYNAMIC);
+	XA_DEBUG_ASSERT(M_in->m == M_in->n);
+	M = (NLSparseMatrix*)M_in;
+	result = NL_NEW(NLJacobiPreconditioner);
+	NL_CLEAR(result, NLJacobiPreconditioner);
+	result->m = M->m;
+	result->n = M->n;
+	result->type = NL_MATRIX_OTHER;
+	result->destroy_func = (NLDestroyMatrixFunc)nlJacobiPreconditionerDestroy;
+	result->mult_func = (NLMultMatrixVectorFunc)nlJacobiPreconditionerMult;
+	result->diag_inv = NL_NEW_ARRAY(double, M->n);
+	NL_CLEAR_ARRAY(double, result->diag_inv, M->n);
+	for (uint32_t i = 0; i < M->n; ++i)
+		result->diag_inv[i] = (M->diag[i] == 0.0) ? 1.0 : 1.0 / M->diag[i];
+	return (NLMatrix)result;
+}
+
+#define NL_NB_VARIABLES 0x101
+#define NL_MAX_ITERATIONS 0x103
+
+static void nlSolverParameteri(NLContext *context, uint32_t pname, int param)
+{
+	if (pname == NL_NB_VARIABLES) {
+		XA_DEBUG_ASSERT(param > 0);
+		context->nb_variables = (uint32_t)param;
+	} else if (pname == NL_MAX_ITERATIONS) {
+		XA_DEBUG_ASSERT(param > 0);
+		context->max_iterations = (uint32_t)param;
+		context->max_iterations_defined = true;
+	}
+}
+
+static void nlSetVariable(NLContext *context, uint32_t index, double value)
+{
+	XA_DEBUG_ASSERT(index >= 0 && index <= context->nb_variables - 1);
+	NL_BUFFER_ITEM(context->variable_buffer[0], index) = value;
+}
+
+static double nlGetVariable(NLContext *context, uint32_t index)
+{
+	XA_DEBUG_ASSERT(index >= 0 && index <= context->nb_variables - 1);
+	return NL_BUFFER_ITEM(context->variable_buffer[0], index);
+}
+
+static void nlLockVariable(NLContext *context, uint32_t index)
+{
+	XA_DEBUG_ASSERT(index >= 0 && index <= context->nb_variables - 1);
+	context->variable_is_locked[index] = true;
+}
+
+static void nlVariablesToVector(NLContext *context)
+{
+	uint32_t n = context->n;
+	XA_DEBUG_ASSERT(context->x);
+	for (uint32_t k = 0; k < context->nb_systems; ++k) {
+		for (uint32_t i = 0; i < context->nb_variables; ++i) {
+			if (!context->variable_is_locked[i]) {
+				uint32_t index = context->variable_index[i];
+				XA_DEBUG_ASSERT(index < context->n);
+				double value = NL_BUFFER_ITEM(context->variable_buffer[k], i);
+				context->x[index + k * n] = value;
+			}
+		}
+	}
+}
+
+static void nlVectorToVariables(NLContext *context)
+{
+	uint32_t n = context->n;
+	XA_DEBUG_ASSERT(context->x);
+	for (uint32_t k = 0; k < context->nb_systems; ++k) {
+		for (uint32_t i = 0; i < context->nb_variables; ++i) {
+			if (!context->variable_is_locked[i]) {
+				uint32_t index = context->variable_index[i];
+				XA_DEBUG_ASSERT(index < context->n);
+				double value = context->x[index + k * n];
+				NL_BUFFER_ITEM(context->variable_buffer[k], i) = value;
+			}
+		}
+	}
+}
+
+static void nlCoefficient(NLContext *context, uint32_t index, double value)
+{
+	XA_DEBUG_ASSERT(index >= 0 && index <= context->nb_variables - 1);
+	if (context->variable_is_locked[index]) {
+		/*
+		 * Note: in al, indices are NLvariable indices,
+		 * within [0..nb_variables-1]
+		 */
+		nlRowColumnAppend(&(context->al), index, value);
+	} else {
+		/*
+		 * Note: in af, indices are system indices,
+		 * within [0..n-1]
+		 */
+		nlRowColumnAppend(&(context->af), context->variable_index[index], value);
+	}
+}
+
+#define NL_SYSTEM  0x0
+#define NL_MATRIX  0x1
+#define NL_ROW     0x2
+
+static void nlBegin(NLContext *context, uint32_t prim)
+{
+	if (prim == NL_SYSTEM) {
+		XA_DEBUG_ASSERT(context->nb_variables > 0);
+		context->variable_buffer = NL_NEW_ARRAY(NLBufferBinding, context->nb_systems);
+		NL_CLEAR_ARRAY(NLBufferBinding, context->variable_buffer, context->nb_systems);
+		context->variable_value = NL_NEW_ARRAY(double, context->nb_variables * context->nb_systems);
+		NL_CLEAR_ARRAY(double, context->variable_value, context->nb_variables * context->nb_systems);
+		for (uint32_t k = 0; k < context->nb_systems; ++k) {
+			context->variable_buffer[k].base_address =
+				context->variable_value +
+				k * context->nb_variables;
+			context->variable_buffer[k].stride = sizeof(double);
+		}
+		context->variable_is_locked = NL_NEW_ARRAY(bool, context->nb_variables);
+		NL_CLEAR_ARRAY(bool, context->variable_is_locked, context->nb_variables);
+		context->variable_index = NL_NEW_ARRAY(uint32_t, context->nb_variables);
+		NL_CLEAR_ARRAY(uint32_t, context->variable_index, context->nb_variables);
+	} else if (prim == NL_MATRIX) {
+		if (context->M)
+			return;
+		uint32_t n = 0;
+		for (uint32_t i = 0; i < context->nb_variables; i++) {
+			if (!context->variable_is_locked[i]) {
+				context->variable_index[i] = n;
+				n++;
+			} else
+				context->variable_index[i] = (uint32_t)~0;
+		}
+		context->n = n;
+		if (!context->max_iterations_defined)
+			context->max_iterations = n * 5;
+		context->M = (NLMatrix)(NL_NEW(NLSparseMatrix));
+		NL_CLEAR(context->M, NLSparseMatrix);
+		nlSparseMatrixConstruct((NLSparseMatrix*)(context->M), n, n);
+		context->x = NL_NEW_ARRAY(double, n*context->nb_systems);
+		NL_CLEAR_ARRAY(double, context->x, n*context->nb_systems);
+		context->b = NL_NEW_ARRAY(double, n*context->nb_systems);
+		NL_CLEAR_ARRAY(double, context->b, n*context->nb_systems);
+		nlVariablesToVector(context);
+		nlRowColumnConstruct(&context->af);
+		nlRowColumnConstruct(&context->al);
+		context->current_row = 0;
+	} else if (prim == NL_ROW) {
+		nlRowColumnZero(&context->af);
+		nlRowColumnZero(&context->al);
+	}
+}
+
+static void nlEnd(NLContext *context, uint32_t prim)
+{
+	if (prim == NL_MATRIX) {
+		nlRowColumnClear(&context->af);
+		nlRowColumnClear(&context->al);
+	} else if (prim == NL_ROW) {
+		NLRowColumn*    af = &context->af;
+		NLRowColumn*    al = &context->al;
+		NLSparseMatrix* M = (NLSparseMatrix*)context->M;
+		double* b = context->b;
+		uint32_t nf = af->size;
+		uint32_t nl = al->size;
+		uint32_t n = context->n;
+		double S;
+		/*
+		 * least_squares : we want to solve
+		 * A'A x = A'b
+		 */
+		for (uint32_t i = 0; i < nf; i++) {
+			for (uint32_t j = 0; j < nf; j++) {
+				nlSparseMatrixAdd(M, af->coeff[i].index, af->coeff[j].index, af->coeff[i].value * af->coeff[j].value);
+			}
+		}
+		for (uint32_t k = 0; k < context->nb_systems; ++k) {
+			S = 0.0;
+			for (uint32_t jj = 0; jj < nl; ++jj) {
+				uint32_t j = al->coeff[jj].index;
+				S += al->coeff[jj].value * NL_BUFFER_ITEM(context->variable_buffer[k], j);
+			}
+			for (uint32_t jj = 0; jj < nf; jj++)
+				b[k*n + af->coeff[jj].index] -= af->coeff[jj].value * S;
+		}
+		context->current_row++;
+	}
+}
+
+static bool nlSolve(NLContext *context)
+{
+	nlDeleteMatrix(context->P);
+	context->P = nlNewJacobiPreconditioner(context->M);
+	nlMatrixCompress(&context->M);
+	bool result = nlSolveIterative(context);
+	nlVectorToVariables(context);
+	return result;
+}
+} // namespace opennl
+
+namespace raster {
+class ClippedTriangle
+{
+public:
+	ClippedTriangle(const Vector2 &a, const Vector2 &b, const Vector2 &c)
+	{
+		m_numVertices = 3;
+		m_activeVertexBuffer = 0;
+		m_verticesA[0] = a;
+		m_verticesA[1] = b;
+		m_verticesA[2] = c;
+		m_vertexBuffers[0] = m_verticesA;
+		m_vertexBuffers[1] = m_verticesB;
+		m_area = 0;
+	}
+
+	void clipHorizontalPlane(float offset, float clipdirection)
+	{
+		Vector2 *v  = m_vertexBuffers[m_activeVertexBuffer];
+		m_activeVertexBuffer ^= 1;
+		Vector2 *v2 = m_vertexBuffers[m_activeVertexBuffer];
+		v[m_numVertices] = v[0];
+		float dy2,   dy1 = offset - v[0].y;
+		int   dy2in, dy1in = clipdirection * dy1 >= 0;
+		uint32_t  p = 0;
+		for (uint32_t k = 0; k < m_numVertices; k++) {
+			dy2   = offset - v[k + 1].y;
+			dy2in = clipdirection * dy2 >= 0;
+			if (dy1in) v2[p++] = v[k];
+			if ( dy1in + dy2in == 1 ) { // not both in/out
+				float dx = v[k + 1].x - v[k].x;
+				float dy = v[k + 1].y - v[k].y;
+				v2[p++] = Vector2(v[k].x + dy1 * (dx / dy), offset);
+			}
+			dy1 = dy2;
+			dy1in = dy2in;
+		}
+		m_numVertices = p;
+	}
+
+	void clipVerticalPlane(float offset, float clipdirection)
+	{
+		Vector2 *v  = m_vertexBuffers[m_activeVertexBuffer];
+		m_activeVertexBuffer ^= 1;
+		Vector2 *v2 = m_vertexBuffers[m_activeVertexBuffer];
+		v[m_numVertices] = v[0];
+		float dx2,   dx1   = offset - v[0].x;
+		int   dx2in, dx1in = clipdirection * dx1 >= 0;
+		uint32_t  p = 0;
+		for (uint32_t k = 0; k < m_numVertices; k++) {
+			dx2 = offset - v[k + 1].x;
+			dx2in = clipdirection * dx2 >= 0;
+			if (dx1in) v2[p++] = v[k];
+			if ( dx1in + dx2in == 1 ) { // not both in/out
+				float dx = v[k + 1].x - v[k].x;
+				float dy = v[k + 1].y - v[k].y;
+				v2[p++] = Vector2(offset, v[k].y + dx1 * (dy / dx));
+			}
+			dx1 = dx2;
+			dx1in = dx2in;
+		}
+		m_numVertices = p;
+	}
+
+	void computeArea()
+	{
+		Vector2 *v  = m_vertexBuffers[m_activeVertexBuffer];
+		v[m_numVertices] = v[0];
+		m_area = 0;
+		for (uint32_t k = 0; k < m_numVertices; k++) {
+			// http://local.wasp.uwa.edu.au/~pbourke/geometry/polyarea/
+			float f = v[k].x * v[k + 1].y - v[k + 1].x * v[k].y;
+			m_area += f;
+		}
+		m_area = 0.5f * fabsf(m_area);
+	}
+
+	void clipAABox(float x0, float y0, float x1, float y1)
+	{
+		clipVerticalPlane(x0, -1);
+		clipHorizontalPlane(y0, -1);
+		clipVerticalPlane(x1, 1);
+		clipHorizontalPlane(y1, 1);
+		computeArea();
+	}
+
+	float area() const
+	{
+		return m_area;
+	}
+
+private:
+	Vector2 m_verticesA[7 + 1];
+	Vector2 m_verticesB[7 + 1];
+	Vector2 *m_vertexBuffers[2];
+	uint32_t m_numVertices;
+	uint32_t m_activeVertexBuffer;
+	float m_area;
+};
+
+/// A callback to sample the environment. Return false to terminate rasterization.
+typedef bool (*SamplingCallback)(void *param, int x, int y);
+
+/// A triangle for rasterization.
+struct Triangle
+{
+	Triangle(const Vector2 &_v0, const Vector2 &_v1, const Vector2 &_v2) : v1(_v0), v2(_v2), v3(_v1), n1(0.0f), n2(0.0f), n3(0.0f)
+	{
+		// make sure every triangle is front facing.
+		flipBackface();
+		// Compute deltas.
+		if (isValid())
+			computeUnitInwardNormals();
+	}
+
+	bool isValid()
+	{
+		const Vector2 e0 = v3 - v1;
+		const Vector2 e1 = v2 - v1;
+		const float area = e0.y * e1.x - e1.y * e0.x;
+		return area != 0.0f;
+	}
+
+	// extents has to be multiple of BK_SIZE!!
+	bool drawAA(const Vector2 &extents, SamplingCallback cb, void *param)
+	{
+		const float PX_INSIDE = 1.0f/sqrtf(2.0f);
+		const float PX_OUTSIDE = -1.0f/sqrtf(2.0f);
+		const float BK_SIZE = 8;
+		const float BK_INSIDE = sqrtf(BK_SIZE*BK_SIZE/2.0f);
+		const float BK_OUTSIDE = -sqrtf(BK_SIZE*BK_SIZE/2.0f);
+		// Bounding rectangle
+		float minx = floorf(max(min3(v1.x, v2.x, v3.x), 0.0f));
+		float miny = floorf(max(min3(v1.y, v2.y, v3.y), 0.0f));
+		float maxx = ceilf( min(max3(v1.x, v2.x, v3.x), extents.x - 1.0f));
+		float maxy = ceilf( min(max3(v1.y, v2.y, v3.y), extents.y - 1.0f));
+		// There's no reason to align the blocks to the viewport, instead we align them to the origin of the triangle bounds.
+		minx = floorf(minx);
+		miny = floorf(miny);
+		//minx = (float)(((int)minx) & (~((int)BK_SIZE - 1))); // align to blocksize (we don't need to worry about blocks partially out of viewport)
+		//miny = (float)(((int)miny) & (~((int)BK_SIZE - 1)));
+		minx += 0.5;
+		miny += 0.5; // sampling at texel centers!
+		maxx += 0.5;
+		maxy += 0.5;
+		// Half-edge constants
+		float C1 = n1.x * (-v1.x) + n1.y * (-v1.y);
+		float C2 = n2.x * (-v2.x) + n2.y * (-v2.y);
+		float C3 = n3.x * (-v3.x) + n3.y * (-v3.y);
+		// Loop through blocks
+		for (float y0 = miny; y0 <= maxy; y0 += BK_SIZE) {
+			for (float x0 = minx; x0 <= maxx; x0 += BK_SIZE) {
+				// Corners of block
+				float xc = (x0 + (BK_SIZE - 1) / 2.0f);
+				float yc = (y0 + (BK_SIZE - 1) / 2.0f);
+				// Evaluate half-space functions
+				float aC = C1 + n1.x * xc + n1.y * yc;
+				float bC = C2 + n2.x * xc + n2.y * yc;
+				float cC = C3 + n3.x * xc + n3.y * yc;
+				// Skip block when outside an edge
+				if ( (aC <= BK_OUTSIDE) || (bC <= BK_OUTSIDE) || (cC <= BK_OUTSIDE) ) continue;
+				// Accept whole block when totally covered
+				if ( (aC >= BK_INSIDE) && (bC >= BK_INSIDE) && (cC >= BK_INSIDE) ) {
+					for (float y = y0; y < y0 + BK_SIZE; y++) {
+						for (float x = x0; x < x0 + BK_SIZE; x++) {
+							if (!cb(param, (int)x, (int)y))
+								return false;
+						}
+					}
+				} else { // Partially covered block
+					float CY1 = C1 + n1.x * x0 + n1.y * y0;
+					float CY2 = C2 + n2.x * x0 + n2.y * y0;
+					float CY3 = C3 + n3.x * x0 + n3.y * y0;
+					for (float y = y0; y < y0 + BK_SIZE; y++) { // @@ This is not clipping to scissor rectangle correctly.
+						float CX1 = CY1;
+						float CX2 = CY2;
+						float CX3 = CY3;
+						for (float x = x0; x < x0 + BK_SIZE; x++) { // @@ This is not clipping to scissor rectangle correctly.
+							if (CX1 >= PX_INSIDE && CX2 >= PX_INSIDE && CX3 >= PX_INSIDE) {
+								if (!cb(param, (int)x, (int)y))
+									return false;
+							} else if ((CX1 >= PX_OUTSIDE) && (CX2 >= PX_OUTSIDE) && (CX3 >= PX_OUTSIDE)) {
+								// triangle partially covers pixel. do clipping.
+								ClippedTriangle ct(v1 - Vector2(x, y), v2 - Vector2(x, y), v3 - Vector2(x, y));
+								ct.clipAABox(-0.5, -0.5, 0.5, 0.5);
+								if (ct.area() > 0.0f) {
+									if (!cb(param, (int)x, (int)y))
+										return false;
+								}
+							}
+							CX1 += n1.x;
+							CX2 += n2.x;
+							CX3 += n3.x;
+						}
+						CY1 += n1.y;
+						CY2 += n2.y;
+						CY3 += n3.y;
+					}
+				}
+			}
+		}
+		return true;
+	}
+
+private:
+	void flipBackface()
+	{
+		// check if triangle is backfacing, if so, swap two vertices
+		if ( ((v3.x - v1.x) * (v2.y - v1.y) - (v3.y - v1.y) * (v2.x - v1.x)) < 0 ) {
+			Vector2 hv = v1;
+			v1 = v2;
+			v2 = hv; // swap pos
+		}
+	}
+
+	// compute unit inward normals for each edge.
+	void computeUnitInwardNormals()
+	{
+		n1 = v1 - v2;
+		n1 = Vector2(-n1.y, n1.x);
+		n1 = n1 * (1.0f / sqrtf(dot(n1, n1)));
+		n2 = v2 - v3;
+		n2 = Vector2(-n2.y, n2.x);
+		n2 = n2 * (1.0f / sqrtf(dot(n2, n2)));
+		n3 = v3 - v1;
+		n3 = Vector2(-n3.y, n3.x);
+		n3 = n3 * (1.0f / sqrtf(dot(n3, n3)));
+	}
+
+	// Vertices.
+	Vector2 v1, v2, v3;
+	Vector2 n1, n2, n3; // unit inward normals
+};
+
+// Process the given triangle. Returns false if rasterization was interrupted by the callback.
+static bool drawTriangle(const Vector2 &extents, const Vector2 v[3], SamplingCallback cb, void *param)
+{
+	Triangle tri(v[0], v[1], v[2]);
+	// @@ It would be nice to have a conservative drawing mode that enlarges the triangle extents by one texel and is able to handle degenerate triangles.
+	// @@ Maybe the simplest thing to do would be raster triangle edges.
+	if (tri.isValid())
+		return tri.drawAA(extents, cb, param);
+	return true;
+}
+
+} // namespace raster
+
+namespace segment {
+
+// - Insertion is o(n)
+// - Smallest element goes at the end, so that popping it is o(1).
+struct CostQueue
+{
+	CostQueue(uint32_t size = UINT32_MAX) : m_maxSize(size), m_pairs(MemTag::SegmentAtlasChartCandidates) {}
+
+	float peekCost() const
+	{
+		return m_pairs.back().cost;
+	}
+
+	uint32_t peekFace() const
+	{
+		return m_pairs.back().face;
+	}
+
+	void push(float cost, uint32_t face)
+	{
+		const Pair p = { cost, face };
+		if (m_pairs.isEmpty() || cost < peekCost())
+			m_pairs.push_back(p);
+		else {
+			uint32_t i = 0;
+			const uint32_t count = m_pairs.size();
+			for (; i < count; i++) {
+				if (m_pairs[i].cost < cost)
+					break;
+			}
+			m_pairs.insertAt(i, p);
+			if (m_pairs.size() > m_maxSize)
+				m_pairs.removeAt(0);
+		}
+	}
+
+	uint32_t pop()
+	{
+		XA_DEBUG_ASSERT(!m_pairs.isEmpty());
+		uint32_t f = m_pairs.back().face;
+		m_pairs.pop_back();
+		return f;
+	}
+
+	XA_INLINE void clear()
+	{
+		m_pairs.clear();
+	}
+
+	XA_INLINE uint32_t count() const
+	{
+		return m_pairs.size();
+	}
+
+private:
+	const uint32_t m_maxSize;
+
+	struct Pair
+	{
+		float cost;
+		uint32_t face;
+	};
+
+	Array<Pair> m_pairs;
+};
+
+struct AtlasData
+{
+	ChartOptions options;
+	const Mesh *mesh = nullptr;
+	Array<float> edgeDihedralAngles;
+	Array<float> edgeLengths;
+	Array<float> faceAreas;
+	Array<float> faceUvAreas; // Can be negative.
+	Array<Vector3> faceNormals;
+	BitArray isFaceInChart;
+
+	AtlasData() : edgeDihedralAngles(MemTag::SegmentAtlasMeshData), edgeLengths(MemTag::SegmentAtlasMeshData), faceAreas(MemTag::SegmentAtlasMeshData), faceNormals(MemTag::SegmentAtlasMeshData) {}
+
+	void compute()
+	{
+		const uint32_t faceCount = mesh->faceCount();
+		const uint32_t edgeCount = mesh->edgeCount();
+		edgeDihedralAngles.resize(edgeCount);
+		edgeLengths.resize(edgeCount);
+		faceAreas.resize(faceCount);
+		if (options.useInputMeshUvs)
+			faceUvAreas.resize(faceCount);
+		faceNormals.resize(faceCount);
+		isFaceInChart.resize(faceCount);
+		isFaceInChart.zeroOutMemory();
+		for (uint32_t f = 0; f < faceCount; f++) {
+			for (uint32_t i = 0; i < 3; i++) {
+				const uint32_t edge = f * 3 + i;
+				const Vector3 &p0 = mesh->position(mesh->vertexAt(meshEdgeIndex0(edge)));
+				const Vector3 &p1 = mesh->position(mesh->vertexAt(meshEdgeIndex1(edge)));
+				edgeLengths[edge] = length(p1 - p0);
+				XA_DEBUG_ASSERT(edgeLengths[edge] > 0.0f);
+			}
+			faceAreas[f] = mesh->computeFaceArea(f);
+			XA_DEBUG_ASSERT(faceAreas[f] > 0.0f);
+			if (options.useInputMeshUvs)
+				faceUvAreas[f] = mesh->computeFaceParametricArea(f);
+			faceNormals[f] = mesh->computeFaceNormal(f);
+		}
+		for (uint32_t face = 0; face < faceCount; face++) {
+			for (uint32_t i = 0; i < 3; i++) {
+				const uint32_t edge = face * 3 + i;
+				const uint32_t oedge = mesh->oppositeEdge(edge);
+				if (oedge == UINT32_MAX)
+					edgeDihedralAngles[edge] = FLT_MAX;
+				else {
+					const uint32_t oface = meshEdgeFace(oedge);
+					edgeDihedralAngles[edge] = edgeDihedralAngles[oedge] = dot(faceNormals[face], faceNormals[oface]);
+				}
+			}
+		}
+	}
+};
+
+// If MeshDecl::vertexUvData is set on input meshes, find charts by floodfilling faces in world/model space without crossing UV seams.
+struct OriginalUvCharts
+{
+	OriginalUvCharts(AtlasData &data) : m_data(data) {}
+	uint32_t chartCount() const { return m_charts.size(); }
+	const Basis &chartBasis(uint32_t chartIndex) const { return m_chartBasis[chartIndex]; }
+
+	ConstArrayView<uint32_t> chartFaces(uint32_t chartIndex) const
+	{
+		const Chart &chart = m_charts[chartIndex];
+		return ConstArrayView<uint32_t>(&m_chartFaces[chart.firstFace], chart.faceCount);
+	}
+
+	void compute()
+	{
+		m_charts.clear();
+		m_chartFaces.clear();
+		const Mesh *mesh = m_data.mesh;
+		const uint32_t faceCount = mesh->faceCount();
+		for (uint32_t f = 0; f < faceCount; f++) {
+			if (m_data.isFaceInChart.get(f))
+				continue;
+			if (isZero(m_data.faceUvAreas[f], kAreaEpsilon))
+				continue; // Face must have valid UVs.
+			// Found an unassigned face, create a new chart.
+			Chart chart;
+			chart.firstFace = m_chartFaces.size();
+			chart.faceCount = 1;
+			m_chartFaces.push_back(f);
+			m_data.isFaceInChart.set(f);
+			floodfillFaces(chart);
+			m_charts.push_back(chart);
+		}
+		// Compute basis for each chart.
+		m_chartBasis.resize(m_charts.size());
+		for (uint32_t c = 0; c < m_charts.size(); c++)
+		{
+			const Chart &chart = m_charts[c];
+			m_tempPoints.resize(chart.faceCount * 3);
+			for (uint32_t f = 0; f < chart.faceCount; f++) {
+				const uint32_t face = m_chartFaces[chart.firstFace + f];
+				for (uint32_t i = 0; i < 3; i++)
+					m_tempPoints[f * 3 + i] = m_data.mesh->position(m_data.mesh->vertexAt(face * 3 + i));
+			}
+			Fit::computeBasis(m_tempPoints, &m_chartBasis[c]);
+		}
+	}
+
+private:
+	struct Chart
+	{
+		uint32_t firstFace, faceCount;
+	};
+
+	void floodfillFaces(Chart &chart)
+	{
+		const bool isFaceAreaNegative = m_data.faceUvAreas[m_chartFaces[chart.firstFace]] < 0.0f;
+		for (;;) {
+			bool newFaceAdded = false;
+			const uint32_t faceCount = chart.faceCount;
+			for (uint32_t f = 0; f < faceCount; f++) {
+				const uint32_t sourceFace = m_chartFaces[chart.firstFace + f];
+				for (Mesh::FaceEdgeIterator edgeIt(m_data.mesh, sourceFace); !edgeIt.isDone(); edgeIt.advance()) {
+					const uint32_t face = edgeIt.oppositeFace();
+					if (face == UINT32_MAX)
+						continue; // Boundary edge.
+					if (m_data.isFaceInChart.get(face))
+						continue; // Already assigned to a chart.
+					if (isZero(m_data.faceUvAreas[face], kAreaEpsilon))
+						continue; // Face must have valid UVs.
+					if ((m_data.faceUvAreas[face] < 0.0f) != isFaceAreaNegative)
+						continue; // Face winding is opposite of the first chart face.
+					const Vector2 &uv0 = m_data.mesh->texcoord(edgeIt.vertex0());
+					const Vector2 &uv1 = m_data.mesh->texcoord(edgeIt.vertex1());
+					const Vector2 &ouv0 = m_data.mesh->texcoord(m_data.mesh->vertexAt(meshEdgeIndex0(edgeIt.oppositeEdge())));
+					const Vector2 &ouv1 = m_data.mesh->texcoord(m_data.mesh->vertexAt(meshEdgeIndex1(edgeIt.oppositeEdge())));
+					if (!equal(uv0, ouv1, m_data.mesh->epsilon()) || !equal(uv1, ouv0, m_data.mesh->epsilon()))
+						continue; // UVs must match exactly.
+					m_chartFaces.push_back(face);
+					chart.faceCount++;
+					m_data.isFaceInChart.set(face);
+					newFaceAdded = true;
+				}
+			}
+			if (!newFaceAdded)
+				break;
+		}
+	}
+
+	AtlasData &m_data;
+	Array<Chart> m_charts;
+	Array<Basis> m_chartBasis;
+	Array<uint32_t> m_chartFaces;
+	Array<Vector3> m_tempPoints;
+};
+
+#if XA_DEBUG_EXPORT_OBJ_PLANAR_REGIONS
+static uint32_t s_planarRegionsCurrentRegion;
+static uint32_t s_planarRegionsCurrentVertex;
+#endif
+
+struct PlanarCharts
+{
+	PlanarCharts(AtlasData &data) : m_data(data), m_nextRegionFace(MemTag::SegmentAtlasPlanarRegions), m_faceToRegionId(MemTag::SegmentAtlasPlanarRegions) {}
+	const Basis &chartBasis(uint32_t chartIndex) const { return m_chartBasis[chartIndex]; }
+	uint32_t chartCount() const { return m_charts.size(); }
+
+	ConstArrayView<uint32_t> chartFaces(uint32_t chartIndex) const
+	{
+		const Chart &chart = m_charts[chartIndex];
+		return ConstArrayView<uint32_t>(&m_chartFaces[chart.firstFace], chart.faceCount);
+	}
+
+	uint32_t regionIdFromFace(uint32_t face) const { return m_faceToRegionId[face]; }
+	uint32_t nextRegionFace(uint32_t face) const { return m_nextRegionFace[face]; }
+	float regionArea(uint32_t region) const { return m_regionAreas[region]; }
+
+	void compute()
+	{
+		const uint32_t faceCount = m_data.mesh->faceCount();
+		// Precompute regions of coplanar incident faces.
+		m_regionFirstFace.clear();
+		m_nextRegionFace.resize(faceCount);
+		m_faceToRegionId.resize(faceCount);
+		for (uint32_t f = 0; f < faceCount; f++) {
+			m_nextRegionFace[f] = f;
+			m_faceToRegionId[f] = UINT32_MAX;
+		}
+		Array<uint32_t> faceStack;
+		faceStack.reserve(min(faceCount, 16u));
+		uint32_t regionCount = 0;
+		for (uint32_t f = 0; f < faceCount; f++) {
+			if (m_nextRegionFace[f] != f)
+				continue; // Already assigned.
+			if (m_data.isFaceInChart.get(f))
+				continue; // Already in a chart.
+			faceStack.clear();
+			faceStack.push_back(f);
+			for (;;) {
+				if (faceStack.isEmpty())
+					break;
+				const uint32_t face = faceStack.back();
+				m_faceToRegionId[face] = regionCount;
+				faceStack.pop_back();
+				for (Mesh::FaceEdgeIterator it(m_data.mesh, face); !it.isDone(); it.advance()) {
+					const uint32_t oface = it.oppositeFace();
+					if (it.isBoundary())
+						continue;
+					if (m_nextRegionFace[oface] != oface)
+						continue; // Already assigned.
+					if (m_data.isFaceInChart.get(oface))
+						continue; // Already in a chart.
+					if (!equal(dot(m_data.faceNormals[face], m_data.faceNormals[oface]), 1.0f, kEpsilon))
+						continue; // Not coplanar.
+					const uint32_t next = m_nextRegionFace[face];
+					m_nextRegionFace[face] = oface;
+					m_nextRegionFace[oface] = next;
+					m_faceToRegionId[oface] = regionCount;
+					faceStack.push_back(oface);
+				}
+			}
+			m_regionFirstFace.push_back(f);
+			regionCount++;
+		}
+#if XA_DEBUG_EXPORT_OBJ_PLANAR_REGIONS
+		static std::mutex s_mutex;
+		{
+			std::lock_guard<std::mutex> lock(s_mutex);
+			FILE *file;
+			XA_FOPEN(file, "debug_mesh_planar_regions.obj", s_planarRegionsCurrentRegion == 0 ? "w" : "a");
+			if (file) {
+				m_data.mesh->writeObjVertices(file);
+				fprintf(file, "s off\n");
+				for (uint32_t i = 0; i < regionCount; i++) {
+					fprintf(file, "o region%u\n", s_planarRegionsCurrentRegion);
+					for (uint32_t j = 0; j < faceCount; j++) {
+						if (m_faceToRegionId[j] == i)
+							m_data.mesh->writeObjFace(file, j, s_planarRegionsCurrentVertex);
+					}
+					s_planarRegionsCurrentRegion++;
+				}
+				s_planarRegionsCurrentVertex += m_data.mesh->vertexCount();
+				fclose(file);
+			}
+		}
+#endif
+		// Precompute planar region areas.
+		m_regionAreas.resize(regionCount);
+		m_regionAreas.zeroOutMemory();
+		for (uint32_t f = 0; f < faceCount; f++) {
+			if (m_faceToRegionId[f] == UINT32_MAX)
+				continue;
+			m_regionAreas[m_faceToRegionId[f]] += m_data.faceAreas[f];
+		}
+		// Create charts from suitable planar regions.
+		// The dihedral angle of all boundary edges must be >= 90 degrees.
+		m_charts.clear();
+		m_chartFaces.clear();
+		for (uint32_t region = 0; region < regionCount; region++) {
+			const uint32_t firstRegionFace = m_regionFirstFace[region];
+			uint32_t face = firstRegionFace;
+			bool createChart = true;
+			do {
+				for (Mesh::FaceEdgeIterator it(m_data.mesh, face); !it.isDone(); it.advance()) {
+					if (it.isBoundary())
+						continue; // Ignore mesh boundary edges.
+					const uint32_t oface = it.oppositeFace();
+					if (m_faceToRegionId[oface] == region)
+						continue; // Ignore internal edges.
+					const float angle = m_data.edgeDihedralAngles[it.edge()];
+					if (angle > 0.0f && angle < FLT_MAX) { // FLT_MAX on boundaries.
+						createChart = false;
+						break;
+					}
+				}
+				if (!createChart)
+					break;
+				face = m_nextRegionFace[face];
+			}
+			while (face != firstRegionFace);
+			// Create a chart.
+			if (createChart) {
+				Chart chart;
+				chart.firstFace = m_chartFaces.size();
+				chart.faceCount = 0;
+				face = firstRegionFace;
+				do {
+					m_data.isFaceInChart.set(face);
+					m_chartFaces.push_back(face);
+					chart.faceCount++;
+					face = m_nextRegionFace[face];
+				}
+				while (face != firstRegionFace);
+				m_charts.push_back(chart);
+			}
+		}
+		// Compute basis for each chart using the first face normal (all faces have the same normal).
+		m_chartBasis.resize(m_charts.size());
+		for (uint32_t c = 0; c < m_charts.size(); c++)
+		{
+			const uint32_t face = m_chartFaces[m_charts[c].firstFace];
+			Basis &basis = m_chartBasis[c];
+			basis.normal = m_data.faceNormals[face];
+			basis.tangent = Basis::computeTangent(basis.normal);
+			basis.bitangent = Basis::computeBitangent(basis.normal, basis.tangent);
+		}
+	}
+
+private:
+	struct Chart
+	{
+		uint32_t firstFace, faceCount;
+	};
+
+	AtlasData &m_data;
+	Array<uint32_t> m_regionFirstFace;
+	Array<uint32_t> m_nextRegionFace;
+	Array<uint32_t> m_faceToRegionId;
+	Array<float> m_regionAreas;
+	Array<Chart> m_charts;
+	Array<uint32_t> m_chartFaces;
+	Array<Basis> m_chartBasis;
+};
+
+struct ClusteredCharts
+{
+	ClusteredCharts(AtlasData &data, const PlanarCharts &planarCharts) : m_data(data), m_planarCharts(planarCharts), m_texcoords(MemTag::SegmentAtlasMeshData), m_bestTriangles(10), m_placingSeeds(false) {}
+
+	~ClusteredCharts()
+	{
+		const uint32_t chartCount = m_charts.size();
+		for (uint32_t i = 0; i < chartCount; i++) {
+			m_charts[i]->~Chart();
+			XA_FREE(m_charts[i]);
+		}
+	}
+
+	uint32_t chartCount() const { return m_charts.size(); }
+	ConstArrayView<uint32_t> chartFaces(uint32_t chartIndex) const { return m_charts[chartIndex]->faces; }
+	const Basis &chartBasis(uint32_t chartIndex) const { return m_charts[chartIndex]->basis; }
+
+	void compute()
+	{
+		const uint32_t faceCount = m_data.mesh->faceCount();
+		m_facesLeft = 0;
+		for (uint32_t i = 0; i < faceCount; i++) {
+			if (!m_data.isFaceInChart.get(i))
+				m_facesLeft++;
+		}
+		const uint32_t chartCount = m_charts.size();
+		for (uint32_t i = 0; i < chartCount; i++) {
+			m_charts[i]->~Chart();
+			XA_FREE(m_charts[i]);
+		}
+		m_charts.clear();
+		m_faceCharts.resize(faceCount);
+		m_faceCharts.fill(-1);
+		m_texcoords.resize(faceCount * 3);
+		if (m_facesLeft == 0)
+			return;
+		// Create initial charts greedely.
+		placeSeeds(m_data.options.maxCost * 0.5f);
+		if (m_data.options.maxIterations == 0) {
+			XA_DEBUG_ASSERT(m_facesLeft == 0);
+			return;
+		}
+		relocateSeeds();
+		resetCharts();
+		// Restart process growing charts in parallel.
+		uint32_t iteration = 0;
+		for (;;) {
+			growCharts(m_data.options.maxCost);
+			// When charts cannot grow more: fill holes, merge charts, relocate seeds and start new iteration.
+			fillHoles(m_data.options.maxCost * 0.5f);
+#if XA_MERGE_CHARTS
+			mergeCharts();
+#endif
+			if (++iteration == m_data.options.maxIterations)
+				break;
+			if (!relocateSeeds())
+				break;
+			resetCharts();
+		}
+		// Make sure no holes are left!
+		XA_DEBUG_ASSERT(m_facesLeft == 0);
+	}
+
+private:
+	struct Chart
+	{
+		Chart() : faces(MemTag::SegmentAtlasChartFaces) {}
+
+		int id = -1;
+		Basis basis; // Best fit normal.
+		float area = 0.0f;
+		float boundaryLength = 0.0f;
+		Vector3 centroidSum = Vector3(0.0f); // Sum of chart face centroids.
+		Vector3 centroid = Vector3(0.0f); // Average centroid of chart faces.
+		Array<uint32_t> faces;
+		Array<uint32_t> failedPlanarRegions;
+		CostQueue candidates;
+		uint32_t seed;
+	};
+
+	void placeSeeds(float threshold)
+	{
+		XA_PROFILE_START(clusteredChartsPlaceSeeds)
+		m_placingSeeds = true;
+		// Instead of using a predefiened number of seeds:
+		// - Add seeds one by one, growing chart until a certain treshold.
+		// - Undo charts and restart growing process.
+		// @@ How can we give preference to faces far from sharp features as in the LSCM paper?
+		//   - those points can be found using a simple flood filling algorithm.
+		//   - how do we weight the probabilities?
+		while (m_facesLeft > 0)
+			createChart(threshold);
+		m_placingSeeds = false;
+		XA_PROFILE_END(clusteredChartsPlaceSeeds)
+	}
+
+	// Returns true if any of the charts can grow more.
+	void growCharts(float threshold)
+	{
+		XA_PROFILE_START(clusteredChartsGrow)
+		for (;;) {
+			if (m_facesLeft == 0)
+				break;
+			// Get the single best candidate out of the chart best candidates.
+			uint32_t bestFace = UINT32_MAX, bestChart = UINT32_MAX;
+			float lowestCost = FLT_MAX;
+			for (uint32_t i = 0; i < m_charts.size(); i++) {
+				Chart *chart = m_charts[i];
+				// Get the best candidate from the chart.
+				// Cleanup any best candidates that have been claimed by another chart.
+				uint32_t face = UINT32_MAX;
+				float cost = FLT_MAX;
+				for (;;) {
+					if (chart->candidates.count() == 0)
+						break;
+					cost = chart->candidates.peekCost();
+					face = chart->candidates.peekFace();
+					if (!m_data.isFaceInChart.get(face))
+						break;
+					else {
+						// Face belongs to another chart. Pop from queue so the next best candidate can be retrieved.
+						chart->candidates.pop();
+						face = UINT32_MAX;
+					}
+				}
+				if (face == UINT32_MAX)
+					continue; // No candidates for this chart.
+				// See if best candidate overall.
+				if (cost < lowestCost) {
+					lowestCost = cost;
+					bestFace = face;
+					bestChart = i;
+				}
+			}
+			if (bestFace == UINT32_MAX || lowestCost > threshold)
+				break;
+			Chart *chart = m_charts[bestChart];
+			chart->candidates.pop(); // Pop the selected candidate from the queue.
+			if (!addFaceToChart(chart, bestFace))
+				chart->failedPlanarRegions.push_back(m_planarCharts.regionIdFromFace(bestFace));
+		}
+		XA_PROFILE_END(clusteredChartsGrow)
+	}
+
+	void resetCharts()
+	{
+		XA_PROFILE_START(clusteredChartsReset)
+		const uint32_t faceCount = m_data.mesh->faceCount();
+		for (uint32_t i = 0; i < faceCount; i++) {
+			if (m_faceCharts[i] != -1)
+				m_data.isFaceInChart.unset(i);
+			m_faceCharts[i] = -1;
+		}
+		m_facesLeft = 0;
+		for (uint32_t i = 0; i < faceCount; i++) {
+			if (!m_data.isFaceInChart.get(i))
+				m_facesLeft++;
+		}
+		const uint32_t chartCount = m_charts.size();
+		for (uint32_t i = 0; i < chartCount; i++) {
+			Chart *chart = m_charts[i];
+			chart->area = 0.0f;
+			chart->boundaryLength = 0.0f;
+			chart->basis.normal = Vector3(0.0f);
+			chart->basis.tangent = Vector3(0.0f);
+			chart->basis.bitangent = Vector3(0.0f);
+			chart->centroidSum = Vector3(0.0f);
+			chart->centroid = Vector3(0.0f);
+			chart->faces.clear();
+			chart->candidates.clear();
+			chart->failedPlanarRegions.clear();
+			addFaceToChart(chart, chart->seed);
+		}
+		XA_PROFILE_END(clusteredChartsReset)
+	}
+
+	bool relocateSeeds()
+	{
+		XA_PROFILE_START(clusteredChartsRelocateSeeds)
+		bool anySeedChanged = false;
+		const uint32_t chartCount = m_charts.size();
+		for (uint32_t i = 0; i < chartCount; i++) {
+			if (relocateSeed(m_charts[i])) {
+				anySeedChanged = true;
+			}
+		}
+		XA_PROFILE_END(clusteredChartsRelocateSeeds)
+		return anySeedChanged;
+	}
+
+	void fillHoles(float threshold)
+	{
+		XA_PROFILE_START(clusteredChartsFillHoles)
+		while (m_facesLeft > 0)
+			createChart(threshold);
+		XA_PROFILE_END(clusteredChartsFillHoles)
+	}
+
+#if XA_MERGE_CHARTS
+	void mergeCharts()
+	{
+		XA_PROFILE_START(clusteredChartsMerge)
+		const uint32_t chartCount = m_charts.size();
+		// Merge charts progressively until there's none left to merge.
+		for (;;) {
+			bool merged = false;
+			for (int c = chartCount - 1; c >= 0; c--) {
+				Chart *chart = m_charts[c];
+				if (chart == nullptr)
+					continue;
+				float externalBoundaryLength = 0.0f;
+				m_sharedBoundaryLengths.resize(chartCount);
+				m_sharedBoundaryLengths.zeroOutMemory();
+				m_sharedBoundaryLengthsNoSeams.resize(chartCount);
+				m_sharedBoundaryLengthsNoSeams.zeroOutMemory();
+				m_sharedBoundaryEdgeCountNoSeams.resize(chartCount);
+				m_sharedBoundaryEdgeCountNoSeams.zeroOutMemory();
+				const uint32_t faceCount = chart->faces.size();
+				for (uint32_t i = 0; i < faceCount; i++) {
+					const uint32_t f = chart->faces[i];
+					for (Mesh::FaceEdgeIterator it(m_data.mesh, f); !it.isDone(); it.advance()) {
+						const float l = m_data.edgeLengths[it.edge()];
+						if (it.isBoundary()) {
+							externalBoundaryLength += l;
+						} else {
+							const int neighborChart = m_faceCharts[it.oppositeFace()];
+							if (neighborChart == -1)
+								externalBoundaryLength += l;
+							else if (m_charts[neighborChart] != chart) {
+								if ((it.isSeam() && (isNormalSeam(it.edge()) || it.isTextureSeam()))) {
+									externalBoundaryLength += l;
+								} else {
+									m_sharedBoundaryLengths[neighborChart] += l;
+								}
+								m_sharedBoundaryLengthsNoSeams[neighborChart] += l;
+								m_sharedBoundaryEdgeCountNoSeams[neighborChart]++;
+							}
+						}
+					}
+				}
+				for (int cc = chartCount - 1; cc >= 0; cc--) {
+					if (cc == c)
+						continue;
+					Chart *chart2 = m_charts[cc];
+					if (chart2 == nullptr)
+						continue;
+					// Must share a boundary.
+					if (m_sharedBoundaryLengths[cc] <= 0.0f)
+						continue;
+					// Compare proxies.
+					if (dot(chart2->basis.normal, chart->basis.normal) < XA_MERGE_CHARTS_MIN_NORMAL_DEVIATION)
+						continue;
+					// Obey max chart area and boundary length.
+					if (m_data.options.maxChartArea > 0.0f && chart->area + chart2->area > m_data.options.maxChartArea)
+						continue;
+					if (m_data.options.maxBoundaryLength > 0.0f && chart->boundaryLength + chart2->boundaryLength - m_sharedBoundaryLengthsNoSeams[cc] > m_data.options.maxBoundaryLength)
+						continue;
+					// Merge if chart2 has a single face.
+					// chart1 must have more than 1 face.
+					// chart2 area must be <= 10% of chart1 area.
+					if (m_sharedBoundaryLengthsNoSeams[cc] > 0.0f && chart->faces.size() > 1 && chart2->faces.size() == 1 && chart2->area <= chart->area * 0.1f)
+						goto merge;
+					// Merge if chart2 has two faces (probably a quad), and chart1 bounds at least 2 of its edges.
+					if (chart2->faces.size() == 2 && m_sharedBoundaryEdgeCountNoSeams[cc] >= 2)
+						goto merge;
+					// Merge if chart2 is wholely inside chart1, ignoring seams.
+					if (m_sharedBoundaryLengthsNoSeams[cc] > 0.0f && equal(m_sharedBoundaryLengthsNoSeams[cc], chart2->boundaryLength, kEpsilon))
+						goto merge;
+					if (m_sharedBoundaryLengths[cc] > 0.2f * max(0.0f, chart->boundaryLength - externalBoundaryLength) ||
+						m_sharedBoundaryLengths[cc] > 0.75f * chart2->boundaryLength)
+						goto merge;
+					continue;
+				merge:
+					if (!mergeChart(chart, chart2, m_sharedBoundaryLengthsNoSeams[cc]))
+						continue;
+					merged = true;
+					break;
+				}
+				if (merged)
+					break;
+			}
+			if (!merged)
+				break;
+		}
+		// Remove deleted charts.
+		for (int c = 0; c < int32_t(m_charts.size()); /*do not increment if removed*/) {
+			if (m_charts[c] == nullptr) {
+				m_charts.removeAt(c);
+				// Update m_faceCharts.
+				const uint32_t faceCount = m_faceCharts.size();
+				for (uint32_t i = 0; i < faceCount; i++) {
+					XA_DEBUG_ASSERT(m_faceCharts[i] != c);
+					XA_DEBUG_ASSERT(m_faceCharts[i] <= int32_t(m_charts.size()));
+					if (m_faceCharts[i] > c) {
+						m_faceCharts[i]--;
+					}
+				}
+			} else {
+				m_charts[c]->id = c;
+				c++;
+			}
+		}
+		XA_PROFILE_END(clusteredChartsMerge)
+	}
+#endif
+
+private:
+	void createChart(float threshold)
+	{
+		Chart *chart = XA_NEW(MemTag::Default, Chart);
+		chart->id = (int)m_charts.size();
+		m_charts.push_back(chart);
+		// Pick a face not used by any chart yet, belonging to the largest planar region.
+		chart->seed = 0;
+		float largestArea = 0.0f;
+		for (uint32_t f = 0; f < m_data.mesh->faceCount(); f++) {
+			if (m_data.isFaceInChart.get(f))
+				continue;
+			const float area = m_planarCharts.regionArea(m_planarCharts.regionIdFromFace(f));
+			if (area > largestArea) {
+				largestArea = area;
+				chart->seed = f;
+			}
+		}
+		addFaceToChart(chart, chart->seed);
+		// Grow the chart as much as possible within the given threshold.
+		for (;;) {
+			if (chart->candidates.count() == 0 || chart->candidates.peekCost() > threshold)
+				break;
+			const uint32_t f = chart->candidates.pop();
+			if (m_data.isFaceInChart.get(f))
+				continue;
+			if (!addFaceToChart(chart, f)) {
+				chart->failedPlanarRegions.push_back(m_planarCharts.regionIdFromFace(f));
+				continue;
+			}
+		}
+	}
+
+	bool isChartBoundaryEdge(const Chart *chart, uint32_t edge) const
+	{
+		const uint32_t oppositeEdge = m_data.mesh->oppositeEdge(edge);
+		const uint32_t oppositeFace = meshEdgeFace(oppositeEdge);
+		return oppositeEdge == UINT32_MAX || m_faceCharts[oppositeFace] != chart->id;
+	}
+
+	bool computeChartBasis(Chart *chart, Basis *basis)
+	{
+		const uint32_t faceCount = chart->faces.size();
+		m_tempPoints.resize(chart->faces.size() * 3);
+		for (uint32_t i = 0; i < faceCount; i++) {
+			const uint32_t f = chart->faces[i];
+			for (uint32_t j = 0; j < 3; j++)
+				m_tempPoints[i * 3 + j] = m_data.mesh->position(m_data.mesh->vertexAt(f * 3 + j));
+		}
+		return Fit::computeBasis(m_tempPoints, basis);
+	}
+
+	bool isFaceFlipped(uint32_t face) const
+	{
+		const Vector2 &v1 = m_texcoords[face * 3 + 0];
+		const Vector2 &v2 = m_texcoords[face * 3 + 1];
+		const Vector2 &v3 = m_texcoords[face * 3 + 2];
+		const float parametricArea = ((v2.x - v1.x) * (v3.y - v1.y) - (v3.x - v1.x) * (v2.y - v1.y)) * 0.5f;
+		return parametricArea < 0.0f;
+	}
+
+	void parameterizeChart(const Chart *chart)
+	{
+		const uint32_t faceCount = chart->faces.size();
+		for (uint32_t i = 0; i < faceCount; i++) {
+			const uint32_t face = chart->faces[i];
+			for (uint32_t j = 0; j < 3; j++) {
+				const uint32_t offset = face * 3 + j;
+				const Vector3 &pos = m_data.mesh->position(m_data.mesh->vertexAt(offset));
+				m_texcoords[offset] = Vector2(dot(chart->basis.tangent, pos), dot(chart->basis.bitangent, pos));
+			}
+		}
+	}
+
+	// m_faceCharts for the chart faces must be set to the chart ID. Needed to compute boundary edges.
+	bool isChartParameterizationValid(const Chart *chart)
+	{
+		const uint32_t faceCount = chart->faces.size();
+		// Check for flipped faces in the parameterization. OK if all are flipped.
+		uint32_t flippedFaceCount = 0;
+		for (uint32_t i = 0; i < faceCount; i++) {
+			if (isFaceFlipped(chart->faces[i]))
+				flippedFaceCount++;
+		}
+		if (flippedFaceCount != 0 && flippedFaceCount != faceCount)
+			return false;
+		// Check for boundary intersection in the parameterization.
+		XA_PROFILE_START(clusteredChartsPlaceSeedsBoundaryIntersection)
+		XA_PROFILE_START(clusteredChartsGrowBoundaryIntersection)
+		m_boundaryGrid.reset(m_texcoords);
+		for (uint32_t i = 0; i < faceCount; i++) {
+			const uint32_t f = chart->faces[i];
+			for (uint32_t j = 0; j < 3; j++) {
+				const uint32_t edge = f * 3 + j;
+				if (isChartBoundaryEdge(chart, edge))
+					m_boundaryGrid.append(edge);
+			}
+		}
+		const bool intersection = m_boundaryGrid.intersect(m_data.mesh->epsilon());
+#if XA_PROFILE
+		if (m_placingSeeds)
+			XA_PROFILE_END(clusteredChartsPlaceSeedsBoundaryIntersection)
+		else
+			XA_PROFILE_END(clusteredChartsGrowBoundaryIntersection)
+#endif
+		if (intersection)
+			return false;
+		return true;
+	}
+
+	bool addFaceToChart(Chart *chart, uint32_t face)
+	{
+		XA_DEBUG_ASSERT(!m_data.isFaceInChart.get(face));
+		const uint32_t oldFaceCount = chart->faces.size();
+		const bool firstFace = oldFaceCount == 0;
+		// Append the face and any coplanar connected faces to the chart faces array.
+		chart->faces.push_back(face);
+		uint32_t coplanarFace = m_planarCharts.nextRegionFace(face);
+		while (coplanarFace != face) {
+			XA_DEBUG_ASSERT(!m_data.isFaceInChart.get(coplanarFace));
+			chart->faces.push_back(coplanarFace);
+			coplanarFace = m_planarCharts.nextRegionFace(coplanarFace);
+		}
+		const uint32_t faceCount = chart->faces.size();
+		// Compute basis.
+		Basis basis;
+		if (firstFace) {
+			// Use the first face normal.
+			// Use any edge as the tangent vector.
+			basis.normal = m_data.faceNormals[face];
+			basis.tangent = normalize(m_data.mesh->position(m_data.mesh->vertexAt(face * 3 + 0)) - m_data.mesh->position(m_data.mesh->vertexAt(face * 3 + 1)));
+			basis.bitangent = cross(basis.normal, basis.tangent);
+		} else {
+			// Use best fit normal.
+			if (!computeChartBasis(chart, &basis)) {
+				chart->faces.resize(oldFaceCount);
+				return false;
+			}
+			if (dot(basis.normal, m_data.faceNormals[face]) < 0.0f) // Flip normal if oriented in the wrong direction.
+				basis.normal = -basis.normal;
+		}
+		if (!firstFace) {
+			// Compute orthogonal parameterization and check that it is valid.
+			parameterizeChart(chart);
+			for (uint32_t i = oldFaceCount; i < faceCount; i++)
+				m_faceCharts[chart->faces[i]] = chart->id;
+			if (!isChartParameterizationValid(chart)) {
+				for (uint32_t i = oldFaceCount; i < faceCount; i++)
+					m_faceCharts[chart->faces[i]] = -1;
+				chart->faces.resize(oldFaceCount);
+				return false;
+			}
+		}
+		// Add face(s) to chart.
+		chart->basis = basis;
+		chart->area = computeArea(chart, face);
+		chart->boundaryLength = computeBoundaryLength(chart, face);
+		for (uint32_t i = oldFaceCount; i < faceCount; i++) {
+			const uint32_t f = chart->faces[i];
+			m_faceCharts[f] = chart->id;
+			m_facesLeft--;
+			m_data.isFaceInChart.set(f);
+			chart->centroidSum += m_data.mesh->computeFaceCenter(f);
+		}
+		chart->centroid = chart->centroidSum / float(chart->faces.size());
+		// Refresh candidates.
+		chart->candidates.clear();
+		for (uint32_t i = 0; i < faceCount; i++) {
+			// Traverse neighboring faces, add the ones that do not belong to any chart yet.
+			const uint32_t f = chart->faces[i];
+			for (uint32_t j = 0; j < 3; j++) {
+				const uint32_t edge = f * 3 + j;
+				const uint32_t oedge = m_data.mesh->oppositeEdge(edge);
+				if (oedge == UINT32_MAX)
+					continue; // Boundary edge.
+				const uint32_t oface = meshEdgeFace(oedge);
+				if (m_data.isFaceInChart.get(oface))
+					continue; // Face belongs to another chart.
+				if (chart->failedPlanarRegions.contains(m_planarCharts.regionIdFromFace(oface)))
+					continue; // Failed to add this faces planar region to the chart before.
+				const float cost = computeCost(chart, oface);
+				if (cost < FLT_MAX)
+					chart->candidates.push(cost, oface);
+			}
+		}
+		return true;
+	}
+
+	// Returns true if the seed has changed.
+	bool relocateSeed(Chart *chart)
+	{
+		// Find the first N triangles that fit the proxy best.
+		const uint32_t faceCount = chart->faces.size();
+		m_bestTriangles.clear();
+		for (uint32_t i = 0; i < faceCount; i++) {
+			const float cost = computeNormalDeviationMetric(chart, chart->faces[i]);
+			m_bestTriangles.push(cost, chart->faces[i]);
+		}
+		// Of those, choose the most central triangle.
+		uint32_t mostCentral = 0;
+		float minDistance = FLT_MAX;
+		for (;;) {
+			if (m_bestTriangles.count() == 0)
+				break;
+			const uint32_t face = m_bestTriangles.pop();
+			Vector3 faceCentroid = m_data.mesh->computeFaceCenter(face);
+			const float distance = length(chart->centroid - faceCentroid);
+			if (distance < minDistance) {
+				minDistance = distance;
+				mostCentral = face;
+			}
+		}
+		XA_DEBUG_ASSERT(minDistance < FLT_MAX);
+		if (mostCentral == chart->seed)
+			return false;
+		chart->seed = mostCentral;
+		return true;
+	}
+
+	// Cost is combined metrics * weights.
+	float computeCost(Chart *chart, uint32_t face) const
+	{
+		// Estimate boundary length and area:
+		const float newChartArea = computeArea(chart, face);
+		const float newBoundaryLength = computeBoundaryLength(chart, face);
+		// Enforce limits strictly:
+		if (m_data.options.maxChartArea > 0.0f && newChartArea > m_data.options.maxChartArea)
+			return FLT_MAX;
+		if (m_data.options.maxBoundaryLength > 0.0f && newBoundaryLength > m_data.options.maxBoundaryLength)
+			return FLT_MAX;
+		// Compute metrics.
+		float cost = 0.0f;
+		const float normalDeviation = computeNormalDeviationMetric(chart, face);
+		if (normalDeviation >= 0.707f) // ~75 degrees
+			return FLT_MAX;
+		cost += m_data.options.normalDeviationWeight * normalDeviation;
+		// Penalize faces that cross seams, reward faces that close seams or reach boundaries.
+		// Make sure normal seams are fully respected:
+		const float normalSeam = computeNormalSeamMetric(chart, face);
+		if (m_data.options.normalSeamWeight >= 1000.0f && normalSeam > 0.0f)
+			return FLT_MAX;
+		cost += m_data.options.normalSeamWeight * normalSeam;
+		cost += m_data.options.roundnessWeight * computeRoundnessMetric(chart, newBoundaryLength, newChartArea);
+		cost += m_data.options.straightnessWeight * computeStraightnessMetric(chart, face);
+		cost += m_data.options.textureSeamWeight * computeTextureSeamMetric(chart, face);
+		//float R = evaluateCompletenessMetric(chart, face);
+		//float D = evaluateDihedralAngleMetric(chart, face);
+		// @@ Add a metric based on local dihedral angle.
+		// @@ Tweaking the normal and texture seam metrics.
+		// - Cause more impedance. Never cross 90 degree edges.
+		XA_DEBUG_ASSERT(isFinite(cost));
+		return cost;
+	}
+
+	// Returns a value in [0-1].
+	// 0 if face normal is coplanar to the chart's best fit normal.
+	// 1 if face normal is perpendicular.
+	float computeNormalDeviationMetric(Chart *chart, uint32_t face) const
+	{
+		// All faces in coplanar regions have the same normal, can use any face.
+		const Vector3 faceNormal = m_data.faceNormals[face];
+		// Use plane fitting metric for now:
+		return min(1.0f - dot(faceNormal, chart->basis.normal), 1.0f); // @@ normal deviations should be weighted by face area
+	}
+
+	float computeRoundnessMetric(Chart *chart, float newBoundaryLength, float newChartArea) const
+	{
+		const float oldRoundness = square(chart->boundaryLength) / chart->area;
+		const float newRoundness = square(newBoundaryLength) / newChartArea;
+		return 1.0f - oldRoundness / newRoundness;
+	}
+
+	float computeStraightnessMetric(Chart *chart, uint32_t firstFace) const
+	{
+		float l_out = 0.0f; // Length of firstFace planar region boundary that doesn't border the chart.
+		float l_in = 0.0f; // Length that does border the chart.
+		const uint32_t planarRegionId = m_planarCharts.regionIdFromFace(firstFace);
+		uint32_t face = firstFace;
+		for (;;) {
+			for (Mesh::FaceEdgeIterator it(m_data.mesh, face); !it.isDone(); it.advance()) {
+				const float l = m_data.edgeLengths[it.edge()];
+				if (it.isBoundary()) {
+					l_out += l;
+				} else if (m_planarCharts.regionIdFromFace(it.oppositeFace()) != planarRegionId) {
+					if (m_faceCharts[it.oppositeFace()] != chart->id)
+						l_out += l;
+					else
+						l_in += l;
+				}
+			}
+			face = m_planarCharts.nextRegionFace(face);
+			if (face == firstFace)
+				break;
+		}
+#if 1
+		float ratio = (l_out - l_in) / (l_out + l_in);
+		return min(ratio, 0.0f); // Only use the straightness metric to close gaps.
+#else
+		return 1.0f - l_in / l_out;
+#endif
+	}
+
+	bool isNormalSeam(uint32_t edge) const
+	{
+		const uint32_t oppositeEdge = m_data.mesh->oppositeEdge(edge);
+		if (oppositeEdge == UINT32_MAX)
+			return false; // boundary edge
+		if (m_data.mesh->flags() & MeshFlags::HasNormals) {
+			const uint32_t v0 = m_data.mesh->vertexAt(meshEdgeIndex0(edge));
+			const uint32_t v1 = m_data.mesh->vertexAt(meshEdgeIndex1(edge));
+			const uint32_t ov0 = m_data.mesh->vertexAt(meshEdgeIndex0(oppositeEdge));
+			const uint32_t ov1 = m_data.mesh->vertexAt(meshEdgeIndex1(oppositeEdge));
+			if (v0 == ov1 && v1 == ov0)
+				return false;
+			return !equal(m_data.mesh->normal(v0), m_data.mesh->normal(ov1), kNormalEpsilon) || !equal(m_data.mesh->normal(v1), m_data.mesh->normal(ov0), kNormalEpsilon);
+		}
+		const uint32_t f0 = meshEdgeFace(edge);
+		const uint32_t f1 = meshEdgeFace(oppositeEdge);
+		if (m_planarCharts.regionIdFromFace(f0) == m_planarCharts.regionIdFromFace(f1))
+			return false;
+		return !equal(m_data.faceNormals[f0], m_data.faceNormals[f1], kNormalEpsilon);
+	}
+
+	float computeNormalSeamMetric(Chart *chart, uint32_t firstFace) const
+	{
+		float seamFactor = 0.0f, totalLength = 0.0f;
+		uint32_t face = firstFace;
+		for (;;) {
+			for (Mesh::FaceEdgeIterator it(m_data.mesh, face); !it.isDone(); it.advance()) {
+				if (it.isBoundary())
+					continue;
+				if (m_faceCharts[it.oppositeFace()] != chart->id)
+					continue;
+				float l = m_data.edgeLengths[it.edge()];
+				totalLength += l;
+				if (!it.isSeam())
+					continue;
+				// Make sure it's a normal seam.
+				if (isNormalSeam(it.edge())) {
+					float d;
+					if (m_data.mesh->flags() & MeshFlags::HasNormals) {
+						const Vector3 &n0 = m_data.mesh->normal(it.vertex0());
+						const Vector3 &n1 = m_data.mesh->normal(it.vertex1());
+						const Vector3 &on0 = m_data.mesh->normal(m_data.mesh->vertexAt(meshEdgeIndex0(it.oppositeEdge())));
+						const Vector3 &on1 = m_data.mesh->normal(m_data.mesh->vertexAt(meshEdgeIndex1(it.oppositeEdge())));
+						const float d0 = clamp(dot(n0, on1), 0.0f, 1.0f);
+						const float d1 = clamp(dot(n1, on0), 0.0f, 1.0f);
+						d = (d0 + d1) * 0.5f;
+					} else {
+						d = clamp(dot(m_data.faceNormals[face], m_data.faceNormals[meshEdgeFace(it.oppositeEdge())]), 0.0f, 1.0f);
+					}
+					l *= 1 - d;
+					seamFactor += l;
+				}
+			}
+			face = m_planarCharts.nextRegionFace(face);
+			if (face == firstFace)
+				break;
+		}
+		if (seamFactor <= 0.0f)
+			return 0.0f;
+		return seamFactor / totalLength;
+	}
+
+	float computeTextureSeamMetric(Chart *chart, uint32_t firstFace) const
+	{
+		float seamLength = 0.0f, totalLength = 0.0f;
+		uint32_t face = firstFace;
+		for (;;) {
+			for (Mesh::FaceEdgeIterator it(m_data.mesh, face); !it.isDone(); it.advance()) {
+				if (it.isBoundary())
+					continue;
+				if (m_faceCharts[it.oppositeFace()] != chart->id)
+					continue;
+				float l = m_data.edgeLengths[it.edge()];
+				totalLength += l;
+				if (!it.isSeam())
+					continue;
+				// Make sure it's a texture seam.
+				if (it.isTextureSeam())
+					seamLength += l;
+			}
+			face = m_planarCharts.nextRegionFace(face);
+			if (face == firstFace)
+				break;
+		}
+		if (seamLength <= 0.0f)
+			return 0.0f; // Avoid division by zero.
+		return seamLength / totalLength;
+	}
+
+	float computeArea(Chart *chart, uint32_t firstFace) const
+	{
+		float area = chart->area;
+		uint32_t face = firstFace;
+		for (;;) {
+			area += m_data.faceAreas[face];
+			face = m_planarCharts.nextRegionFace(face);
+			if (face == firstFace)
+				break;
+		}
+		return area;
+	}
+
+	float computeBoundaryLength(Chart *chart, uint32_t firstFace) const
+	{
+		float boundaryLength = chart->boundaryLength;
+		// Add new edges, subtract edges shared with the chart.
+		const uint32_t planarRegionId = m_planarCharts.regionIdFromFace(firstFace);
+		uint32_t face = firstFace;
+		for (;;) {
+			for (Mesh::FaceEdgeIterator it(m_data.mesh, face); !it.isDone(); it.advance()) {
+				const float edgeLength = m_data.edgeLengths[it.edge()];
+				if (it.isBoundary()) {
+					boundaryLength += edgeLength;
+				} else if (m_planarCharts.regionIdFromFace(it.oppositeFace()) != planarRegionId) {
+					if (m_faceCharts[it.oppositeFace()] != chart->id)
+						boundaryLength += edgeLength;
+					else
+						boundaryLength -= edgeLength;
+				}
+			}
+			face = m_planarCharts.nextRegionFace(face);
+			if (face == firstFace)
+				break;
+		}
+		return max(0.0f, boundaryLength);  // @@ Hack!
+	}
+
+	bool mergeChart(Chart *owner, Chart *chart, float sharedBoundaryLength)
+	{
+		const uint32_t oldOwnerFaceCount = owner->faces.size();
+		const uint32_t chartFaceCount = chart->faces.size();
+		owner->faces.push_back(chart->faces);
+		for (uint32_t i = 0; i < chartFaceCount; i++) {
+			XA_DEBUG_ASSERT(m_faceCharts[chart->faces[i]] == chart->id);
+			m_faceCharts[chart->faces[i]] = owner->id;
+		}
+		// Compute basis using best fit normal.
+		Basis basis;
+		if (!computeChartBasis(owner, &basis)) {
+			owner->faces.resize(oldOwnerFaceCount);
+			for (uint32_t i = 0; i < chartFaceCount; i++)
+				m_faceCharts[chart->faces[i]] = chart->id;
+			return false;
+		}
+		if (dot(basis.normal, m_data.faceNormals[owner->faces[0]]) < 0.0f) // Flip normal if oriented in the wrong direction.
+			basis.normal = -basis.normal;
+		// Compute orthogonal parameterization and check that it is valid.
+		parameterizeChart(owner);
+		if (!isChartParameterizationValid(owner)) {
+			owner->faces.resize(oldOwnerFaceCount);
+			for (uint32_t i = 0; i < chartFaceCount; i++)
+				m_faceCharts[chart->faces[i]] = chart->id;
+			return false;
+		}
+		// Merge chart.
+		owner->basis = basis;
+		owner->failedPlanarRegions.push_back(chart->failedPlanarRegions);
+		// Update adjacencies?
+		owner->area += chart->area;
+		owner->boundaryLength += chart->boundaryLength - sharedBoundaryLength;
+		// Delete chart.
+		m_charts[chart->id] = nullptr;
+		chart->~Chart();
+		XA_FREE(chart);
+		return true;
+	}
+
+private:
+	AtlasData &m_data;
+	const PlanarCharts &m_planarCharts;
+	Array<Vector2> m_texcoords;
+	uint32_t m_facesLeft;
+	Array<int> m_faceCharts;
+	Array<Chart *> m_charts;
+	CostQueue m_bestTriangles;
+	Array<Vector3> m_tempPoints;
+	UniformGrid2 m_boundaryGrid;
+#if XA_MERGE_CHARTS
+	// mergeCharts
+	Array<float> m_sharedBoundaryLengths;
+	Array<float> m_sharedBoundaryLengthsNoSeams;
+	Array<uint32_t> m_sharedBoundaryEdgeCountNoSeams;
+#endif
+	bool m_placingSeeds;
+};
+
+struct ChartGeneratorType
+{
+	enum Enum
+	{
+		OriginalUv,
+		Planar,
+		Clustered,
+		Piecewise
+	};
+};
+
+struct Atlas
+{
+	Atlas() : m_originalUvCharts(m_data), m_planarCharts(m_data), m_clusteredCharts(m_data, m_planarCharts) {}
+
+	uint32_t chartCount() const
+	{
+		return m_originalUvCharts.chartCount() + m_planarCharts.chartCount() + m_clusteredCharts.chartCount();
+	}
+
+	ConstArrayView<uint32_t> chartFaces(uint32_t chartIndex) const
+	{
+		if (chartIndex < m_originalUvCharts.chartCount())
+			return m_originalUvCharts.chartFaces(chartIndex);
+		chartIndex -= m_originalUvCharts.chartCount();
+		if (chartIndex < m_planarCharts.chartCount())
+			return m_planarCharts.chartFaces(chartIndex);
+		chartIndex -= m_planarCharts.chartCount();
+		return m_clusteredCharts.chartFaces(chartIndex);
+	}
+
+	const Basis &chartBasis(uint32_t chartIndex) const
+	{
+		if (chartIndex < m_originalUvCharts.chartCount())
+			return m_originalUvCharts.chartBasis(chartIndex);
+		chartIndex -= m_originalUvCharts.chartCount();
+		if (chartIndex < m_planarCharts.chartCount())
+			return m_planarCharts.chartBasis(chartIndex);
+		chartIndex -= m_planarCharts.chartCount();
+		return m_clusteredCharts.chartBasis(chartIndex);
+	}
+
+	ChartGeneratorType::Enum chartGeneratorType(uint32_t chartIndex) const
+	{
+		if (chartIndex < m_originalUvCharts.chartCount())
+			return ChartGeneratorType::OriginalUv;
+		chartIndex -= m_originalUvCharts.chartCount();
+		if (chartIndex < m_planarCharts.chartCount())
+			return ChartGeneratorType::Planar;
+		return ChartGeneratorType::Clustered;
+	}
+
+	void reset(const Mesh *mesh, const ChartOptions &options)
+	{
+		XA_PROFILE_START(buildAtlasInit)
+		m_data.options = options;
+		m_data.mesh = mesh;
+		m_data.compute();
+		XA_PROFILE_END(buildAtlasInit)
+	}
+
+	void compute()
+	{
+		if (m_data.options.useInputMeshUvs) {
+			XA_PROFILE_START(originalUvCharts)
+			m_originalUvCharts.compute();
+			XA_PROFILE_END(originalUvCharts)
+		}
+		XA_PROFILE_START(planarCharts)
+		m_planarCharts.compute();
+		XA_PROFILE_END(planarCharts)
+		XA_PROFILE_START(clusteredCharts)
+		m_clusteredCharts.compute();
+		XA_PROFILE_END(clusteredCharts)
+	}
+
+private:
+	AtlasData m_data;
+	OriginalUvCharts m_originalUvCharts;
+	PlanarCharts m_planarCharts;
+	ClusteredCharts m_clusteredCharts;
+};
+
+struct ComputeUvMeshChartsTaskArgs
+{
+	UvMesh *mesh;
+	Progress *progress;
+};
+
+// Charts are found by floodfilling faces without crossing UV seams.
+struct ComputeUvMeshChartsTask
+{
+	ComputeUvMeshChartsTask(ComputeUvMeshChartsTaskArgs *args) : m_mesh(args->mesh), m_progress(args->progress), m_uvToEdgeMap(MemTag::Default, m_mesh->indices.size()), m_faceAssigned(m_mesh->indices.size() / 3) {}
+
+	void run()
+	{
+		const uint32_t vertexCount = m_mesh->texcoords.size();
+		const uint32_t indexCount = m_mesh->indices.size();
+		const uint32_t faceCount = indexCount / 3;
+		// A vertex can only be assigned to one chart.
+		m_mesh->vertexToChartMap.resize(vertexCount);
+		m_mesh->vertexToChartMap.fill(UINT32_MAX);
+		// Map vertex UV to edge. Face is then edge / 3.
+		for (uint32_t i = 0; i < indexCount; i++)
+			m_uvToEdgeMap.add(m_mesh->texcoords[m_mesh->indices[i]]);
+		// Find charts.
+		m_faceAssigned.zeroOutMemory();
+		for (uint32_t f = 0; f < faceCount; f++) {
+			if (m_progress->cancel)
+				return;
+			m_progress->increment(1);
+			// Found an unassigned face, see if it can be added.
+			const uint32_t chartIndex = m_mesh->charts.size();
+			if (!canAddFaceToChart(chartIndex, f))
+				continue;
+			// Face is OK, create a new chart with the face.
+			UvMeshChart *chart = XA_NEW(MemTag::Default, UvMeshChart);
+			m_mesh->charts.push_back(chart);
+			chart->material = m_mesh->faceMaterials.isEmpty() ? 0 : m_mesh->faceMaterials[f];
+			addFaceToChart(chartIndex, f);
+			// Walk incident faces and assign them to the chart.
+			uint32_t f2 = 0;
+			for (;;) {
+				bool newFaceAssigned = false;
+				const uint32_t faceCount2 = chart->faces.size();
+				for (; f2 < faceCount2; f2++) {
+					const uint32_t face = chart->faces[f2];
+					for (uint32_t i = 0; i < 3; i++) {
+						// Add any valid faces with colocal UVs to the chart.
+						const Vector2 &uv = m_mesh->texcoords[m_mesh->indices[face * 3 + i]];
+						uint32_t edge = m_uvToEdgeMap.get(uv);
+						while (edge != UINT32_MAX) {
+							const uint32_t newFace = edge / 3;
+							if (canAddFaceToChart(chartIndex, newFace)) {
+								addFaceToChart(chartIndex, newFace);
+								newFaceAssigned = true;
+							}
+							edge = m_uvToEdgeMap.getNext(uv, edge);
+						}
+					}
+				}
+				if (!newFaceAssigned)
+					break;
+			}
+		}
+	}
+
+private:
+	// The chart at chartIndex doesn't have to exist yet.
+	bool canAddFaceToChart(uint32_t chartIndex, uint32_t face) const
+	{
+		if (m_faceAssigned.get(face))
+			return false; // Already assigned to a chart.
+		if (m_mesh->faceIgnore.get(face))
+			return false; // Face is ignored (zero area or nan UVs).
+		if (!m_mesh->faceMaterials.isEmpty() && chartIndex < m_mesh->charts.size()) {
+			if (m_mesh->faceMaterials[face] != m_mesh->charts[chartIndex]->material)
+				return false; // Materials don't match.
+		}
+		for (uint32_t i = 0; i < 3; i++) {
+			const uint32_t vertex = m_mesh->indices[face * 3 + i];
+			if (m_mesh->vertexToChartMap[vertex] != UINT32_MAX && m_mesh->vertexToChartMap[vertex] != chartIndex)
+				return false; // Vertex already assigned to another chart.
+		}
+		return true;
+	}
+
+	void addFaceToChart(uint32_t chartIndex, uint32_t face)
+	{
+		UvMeshChart *chart = m_mesh->charts[chartIndex];
+		m_faceAssigned.set(face);
+		chart->faces.push_back(face);
+		for (uint32_t i = 0; i < 3; i++) {
+			const uint32_t vertex = m_mesh->indices[face * 3 + i];
+			m_mesh->vertexToChartMap[vertex] = chartIndex;
+			chart->indices.push_back(vertex);
+		}
+	}
+
+	UvMesh * const m_mesh;
+	Progress * const m_progress;
+	HashMap<Vector2> m_uvToEdgeMap; // Face is edge / 3.
+	BitArray m_faceAssigned;
+};
+
+static void runComputeUvMeshChartsTask(void * /*groupUserData*/, void *taskUserData)
+{
+	XA_PROFILE_START(computeChartsThread)
+	ComputeUvMeshChartsTask task((ComputeUvMeshChartsTaskArgs *)taskUserData);
+	task.run();
+	XA_PROFILE_END(computeChartsThread)
+}
+
+static bool computeUvMeshCharts(TaskScheduler *taskScheduler, ArrayView<UvMesh *> meshes, ProgressFunc progressFunc, void *progressUserData)
+{
+	uint32_t totalFaceCount = 0;
+	for (uint32_t i = 0; i < meshes.length; i++)
+		totalFaceCount += meshes[i]->indices.size() / 3;
+	Progress progress(ProgressCategory::ComputeCharts, progressFunc, progressUserData, totalFaceCount);
+	TaskGroupHandle taskGroup = taskScheduler->createTaskGroup(nullptr, meshes.length);
+	Array<ComputeUvMeshChartsTaskArgs> taskArgs;
+	taskArgs.resize(meshes.length);
+	for (uint32_t i = 0; i < meshes.length; i++)
+	{
+		ComputeUvMeshChartsTaskArgs &args = taskArgs[i];
+		args.mesh = meshes[i];
+		args.progress = &progress;
+		Task task;
+		task.userData = &args;
+		task.func = runComputeUvMeshChartsTask;
+		taskScheduler->run(taskGroup, task);
+	}
+	taskScheduler->wait(&taskGroup);
+	return !progress.cancel;
+}
+
+} // namespace segment
+
+namespace param {
+
+// Fast sweep in 3 directions
+static bool findApproximateDiameterVertices(Mesh *mesh, uint32_t *a, uint32_t *b)
+{
+	XA_DEBUG_ASSERT(a != nullptr);
+	XA_DEBUG_ASSERT(b != nullptr);
+	const uint32_t vertexCount = mesh->vertexCount();
+	uint32_t minVertex[3];
+	uint32_t maxVertex[3];
+	minVertex[0] = minVertex[1] = minVertex[2] = UINT32_MAX;
+	maxVertex[0] = maxVertex[1] = maxVertex[2] = UINT32_MAX;
+	for (uint32_t v = 1; v < vertexCount; v++) {
+		if (mesh->isBoundaryVertex(v)) {
+			minVertex[0] = minVertex[1] = minVertex[2] = v;
+			maxVertex[0] = maxVertex[1] = maxVertex[2] = v;
+			break;
+		}
+	}
+	if (minVertex[0] == UINT32_MAX) {
+		// Input mesh has not boundaries.
+		return false;
+	}
+	for (uint32_t v = 1; v < vertexCount; v++) {
+		if (!mesh->isBoundaryVertex(v)) {
+			// Skip interior vertices.
+			continue;
+		}
+		const Vector3 &pos = mesh->position(v);
+		if (pos.x < mesh->position(minVertex[0]).x)
+			minVertex[0] = v;
+		else if (pos.x > mesh->position(maxVertex[0]).x)
+			maxVertex[0] = v;
+		if (pos.y < mesh->position(minVertex[1]).y)
+			minVertex[1] = v;
+		else if (pos.y > mesh->position(maxVertex[1]).y)
+			maxVertex[1] = v;
+		if (pos.z < mesh->position(minVertex[2]).z)
+			minVertex[2] = v;
+		else if (pos.z > mesh->position(maxVertex[2]).z)
+			maxVertex[2] = v;
+	}
+	float lengths[3];
+	for (int i = 0; i < 3; i++) {
+		lengths[i] = length(mesh->position(minVertex[i]) - mesh->position(maxVertex[i]));
+	}
+	if (lengths[0] > lengths[1] && lengths[0] > lengths[2]) {
+		*a = minVertex[0];
+		*b = maxVertex[0];
+	} else if (lengths[1] > lengths[2]) {
+		*a = minVertex[1];
+		*b = maxVertex[1];
+	} else {
+		*a = minVertex[2];
+		*b = maxVertex[2];
+	}
+	return true;
+}
+
+// From OpenNL LSCM example.
+// Computes the coordinates of the vertices of a triangle in a local 2D orthonormal basis of the triangle's plane.
+static void projectTriangle(Vector3 p0, Vector3 p1, Vector3 p2, Vector2 *z0, Vector2 *z1, Vector2 *z2)
+{
+	Vector3 X = normalize(p1 - p0);
+	Vector3 Z = normalize(cross(X, p2 - p0));
+	Vector3 Y = cross(Z, X);
+	Vector3 &O = p0;
+	*z0 = Vector2(0, 0);
+	*z1 = Vector2(length(p1 - O), 0);
+	*z2 = Vector2(dot(p2 - O, X), dot(p2 - O, Y));
+}
+
+// Conformal relations from Brecht Van Lommel (based on ABF):
+
+static float vec_angle_cos(const Vector3 &v1, const Vector3 &v2, const Vector3 &v3)
+{
+	Vector3 d1 = v1 - v2;
+	Vector3 d2 = v3 - v2;
+	return clamp(dot(d1, d2) / (length(d1) * length(d2)), -1.0f, 1.0f);
+}
+
+static float vec_angle(const Vector3 &v1, const Vector3 &v2, const Vector3 &v3)
+{
+	float dot = vec_angle_cos(v1, v2, v3);
+	return acosf(dot);
+}
+
+static void triangle_angles(const Vector3 &v1, const Vector3 &v2, const Vector3 &v3, float *a1, float *a2, float *a3)
+{
+	*a1 = vec_angle(v3, v1, v2);
+	*a2 = vec_angle(v1, v2, v3);
+	*a3 = kPi - *a2 - *a1;
+}
+
+static bool setup_abf_relations(opennl::NLContext *context, int id0, int id1, int id2, const Vector3 &p0, const Vector3 &p1, const Vector3 &p2)
+{
+	// @@ IC: Wouldn't it be more accurate to return cos and compute 1-cos^2?
+	// It does indeed seem to be a little bit more robust.
+	// @@ Need to revisit this more carefully!
+	float a0, a1, a2;
+	triangle_angles(p0, p1, p2, &a0, &a1, &a2);
+	if (a0 == 0.0f || a1 == 0.0f || a2 == 0.0f)
+		return false;
+	float s0 = sinf(a0);
+	float s1 = sinf(a1);
+	float s2 = sinf(a2);
+	if (s1 > s0 && s1 > s2) {
+		swap(s1, s2);
+		swap(s0, s1);
+		swap(a1, a2);
+		swap(a0, a1);
+		swap(id1, id2);
+		swap(id0, id1);
+	} else if (s0 > s1 && s0 > s2) {
+		swap(s0, s2);
+		swap(s0, s1);
+		swap(a0, a2);
+		swap(a0, a1);
+		swap(id0, id2);
+		swap(id0, id1);
+	}
+	float c0 = cosf(a0);
+	float ratio = (s2 == 0.0f) ? 1.0f : s1 / s2;
+	float cosine = c0 * ratio;
+	float sine = s0 * ratio;
+	// Note  : 2*id + 0 --> u
+	//         2*id + 1 --> v
+	int u0_id = 2 * id0 + 0;
+	int v0_id = 2 * id0 + 1;
+	int u1_id = 2 * id1 + 0;
+	int v1_id = 2 * id1 + 1;
+	int u2_id = 2 * id2 + 0;
+	int v2_id = 2 * id2 + 1;
+	// Real part
+	opennl::nlBegin(context, NL_ROW);
+	opennl::nlCoefficient(context, u0_id, cosine - 1.0f);
+	opennl::nlCoefficient(context, v0_id, -sine);
+	opennl::nlCoefficient(context, u1_id, -cosine);
+	opennl::nlCoefficient(context, v1_id, sine);
+	opennl::nlCoefficient(context, u2_id, 1);
+	opennl::nlEnd(context, NL_ROW);
+	// Imaginary part
+	opennl::nlBegin(context, NL_ROW);
+	opennl::nlCoefficient(context, u0_id, sine);
+	opennl::nlCoefficient(context, v0_id, cosine - 1.0f);
+	opennl::nlCoefficient(context, u1_id, -sine);
+	opennl::nlCoefficient(context, v1_id, -cosine);
+	opennl::nlCoefficient(context, v2_id, 1);
+	opennl::nlEnd(context, NL_ROW);
+	return true;
+}
+
+static bool computeLeastSquaresConformalMap(Mesh *mesh)
+{
+	uint32_t lockedVertex0, lockedVertex1;
+	if (!findApproximateDiameterVertices(mesh, &lockedVertex0, &lockedVertex1)) {
+		// Mesh has no boundaries.
+		return false;
+	}
+	const uint32_t vertexCount = mesh->vertexCount();
+	opennl::NLContext *context = opennl::nlNewContext();
+	opennl::nlSolverParameteri(context, NL_NB_VARIABLES, int(2 * vertexCount));
+	opennl::nlSolverParameteri(context, NL_MAX_ITERATIONS, int(5 * vertexCount));
+	opennl::nlBegin(context, NL_SYSTEM);
+	ArrayView<Vector2> texcoords = mesh->texcoords();
+	for (uint32_t i = 0; i < vertexCount; i++) {
+		opennl::nlSetVariable(context, 2 * i, texcoords[i].x);
+		opennl::nlSetVariable(context, 2 * i + 1, texcoords[i].y);
+		if (i == lockedVertex0 || i == lockedVertex1) {
+			opennl::nlLockVariable(context, 2 * i);
+			opennl::nlLockVariable(context, 2 * i + 1);
+		}
+	}
+	opennl::nlBegin(context, NL_MATRIX);
+	const uint32_t faceCount = mesh->faceCount();
+	ConstArrayView<Vector3> positions = mesh->positions();
+	ConstArrayView<uint32_t> indices = mesh->indices();
+	for (uint32_t f = 0; f < faceCount; f++) {
+		const uint32_t v0 = indices[f * 3 + 0];
+		const uint32_t v1 = indices[f * 3 + 1];
+		const uint32_t v2 = indices[f * 3 + 2];
+		if (!setup_abf_relations(context, v0, v1, v2, positions[v0], positions[v1], positions[v2])) {
+			Vector2 z0, z1, z2;
+			projectTriangle(positions[v0], positions[v1], positions[v2], &z0, &z1, &z2);
+			double a = z1.x - z0.x;
+			double b = z1.y - z0.y;
+			double c = z2.x - z0.x;
+			double d = z2.y - z0.y;
+			XA_DEBUG_ASSERT(b == 0.0);
+			// Note  : 2*id + 0 --> u
+			//         2*id + 1 --> v
+			uint32_t u0_id = 2 * v0;
+			uint32_t v0_id = 2 * v0 + 1;
+			uint32_t u1_id = 2 * v1;
+			uint32_t v1_id = 2 * v1 + 1;
+			uint32_t u2_id = 2 * v2;
+			uint32_t v2_id = 2 * v2 + 1;
+			// Note : b = 0
+			// Real part
+			opennl::nlBegin(context, NL_ROW);
+			opennl::nlCoefficient(context, u0_id, -a+c) ;
+			opennl::nlCoefficient(context, v0_id, b-d) ;
+			opennl::nlCoefficient(context, u1_id, -c) ;
+			opennl::nlCoefficient(context, v1_id, d) ;
+			opennl::nlCoefficient(context, u2_id, a);
+			opennl::nlEnd(context, NL_ROW);
+			// Imaginary part
+			opennl::nlBegin(context, NL_ROW);
+			opennl::nlCoefficient(context, u0_id, -b+d);
+			opennl::nlCoefficient(context, v0_id, -a+c);
+			opennl::nlCoefficient(context, u1_id, -d);
+			opennl::nlCoefficient(context, v1_id, -c);
+			opennl::nlCoefficient(context, v2_id, a);
+			opennl::nlEnd(context, NL_ROW);
+		}
+	}
+	opennl::nlEnd(context, NL_MATRIX);
+	opennl::nlEnd(context, NL_SYSTEM);
+	if (!opennl::nlSolve(context)) {
+		opennl::nlDeleteContext(context);
+		return false;
+	}
+	for (uint32_t i = 0; i < vertexCount; i++) {
+		const double u = opennl::nlGetVariable(context, 2 * i);
+		const double v = opennl::nlGetVariable(context, 2 * i + 1);
+		texcoords[i] = Vector2((float)u, (float)v);
+		XA_DEBUG_ASSERT(!isNan(mesh->texcoord(i).x));
+		XA_DEBUG_ASSERT(!isNan(mesh->texcoord(i).y));
+	}
+	opennl::nlDeleteContext(context);
+	return true;
+}
+
+struct PiecewiseParam
+{
+	void reset(const Mesh *mesh)
+	{
+		m_mesh = mesh;
+		const uint32_t faceCount = m_mesh->faceCount();
+		const uint32_t vertexCount = m_mesh->vertexCount();
+		m_texcoords.resize(vertexCount);
+		m_patch.reserve(faceCount);
+		m_candidates.reserve(faceCount);
+		m_faceInAnyPatch.resize(faceCount);
+		m_faceInAnyPatch.zeroOutMemory();
+		m_faceInvalid.resize(faceCount);
+		m_faceInPatch.resize(faceCount);
+		m_vertexInPatch.resize(vertexCount);
+		m_faceToCandidate.resize(faceCount);
+	}
+
+	ConstArrayView<uint32_t> chartFaces() const { return m_patch; }
+	ConstArrayView<Vector2> texcoords() const { return m_texcoords; }
+
+	bool computeChart()
+	{
+		// Clear per-patch state.
+		m_patch.clear();
+		m_candidates.clear();
+		m_faceToCandidate.zeroOutMemory();
+		m_faceInvalid.zeroOutMemory();
+		m_faceInPatch.zeroOutMemory();
+		m_vertexInPatch.zeroOutMemory();
+		// Add the seed face (first unassigned face) to the patch.
+		const uint32_t faceCount = m_mesh->faceCount();
+		uint32_t seed = UINT32_MAX;
+		for (uint32_t f = 0; f < faceCount; f++) {
+			if (m_faceInAnyPatch.get(f))
+				continue;
+			seed = f;
+			// Add all 3 vertices.
+			Vector2 texcoords[3];
+			orthoProjectFace(seed, texcoords);
+			for (uint32_t i = 0; i < 3; i++) {
+				const uint32_t vertex = m_mesh->vertexAt(seed * 3 + i);
+				m_vertexInPatch.set(vertex);
+				m_texcoords[vertex] = texcoords[i];
+			}
+			addFaceToPatch(seed);
+			// Initialize the boundary grid.
+			m_boundaryGrid.reset(m_texcoords, m_mesh->indices());
+			for (Mesh::FaceEdgeIterator it(m_mesh, seed); !it.isDone(); it.advance())
+				m_boundaryGrid.append(it.edge());
+			break;
+		}
+		if (seed == UINT32_MAX)
+			return false;
+		for (;;) {
+			// Find the candidate with the lowest cost.
+			float lowestCost = FLT_MAX;
+			Candidate *bestCandidate = nullptr;
+			for (uint32_t i = 0; i < m_candidates.size(); i++) {
+				Candidate *candidate = m_candidates[i];
+				if (candidate->maxCost < lowestCost) {
+					lowestCost = candidate->maxCost;
+					bestCandidate = candidate;
+				}
+			}
+			if (!bestCandidate)
+				break;
+			XA_DEBUG_ASSERT(!bestCandidate->prev); // Must be head of linked candidates.
+			// Compute the position by averaging linked candidates (candidates that share the same free vertex).
+			Vector2 position(0.0f);
+			uint32_t n = 0;
+			for (CandidateIterator it(bestCandidate); !it.isDone(); it.advance()) {
+				position += it.current()->position;
+				n++;
+			}
+			position *= 1.0f / (float)n;
+			const uint32_t freeVertex = bestCandidate->vertex;
+			XA_DEBUG_ASSERT(!isNan(position.x));
+			XA_DEBUG_ASSERT(!isNan(position.y));
+			m_texcoords[freeVertex] = position;
+			// Check for flipped faces. This is also done when candidates are first added, but the averaged position of the free vertex is different now, so check again.
+			bool invalid = false;
+			for (CandidateIterator it(bestCandidate); !it.isDone(); it.advance()) {
+				const uint32_t vertex0 = m_mesh->vertexAt(meshEdgeIndex0(it.current()->patchEdge));
+				const uint32_t vertex1 = m_mesh->vertexAt(meshEdgeIndex1(it.current()->patchEdge));
+				const float freeVertexOrient = orientToEdge(m_texcoords[vertex0], m_texcoords[vertex1], position);
+				if ((it.current()->patchVertexOrient < 0.0f && freeVertexOrient < 0.0f) || (it.current()->patchVertexOrient > 0.0f && freeVertexOrient > 0.0f)) {
+					invalid = true;
+					break;
+				}
+			}
+			// Check for zero area and flipped faces (using area).
+			for (CandidateIterator it(bestCandidate); !it.isDone(); it.advance()) {
+				const Vector2 a = m_texcoords[m_mesh->vertexAt(it.current()->face * 3 + 0)];
+				const Vector2 b = m_texcoords[m_mesh->vertexAt(it.current()->face * 3 + 1)];
+				const Vector2 c = m_texcoords[m_mesh->vertexAt(it.current()->face * 3 + 2)];
+				const float area = triangleArea(a, b, c);
+				if (area <= 0.0f) {
+					invalid = true;
+					break;
+				}
+			}
+			// Check for boundary intersection.
+			if (!invalid) {
+				XA_PROFILE_START(parameterizeChartsPiecewiseBoundaryIntersection)
+				// Test candidate edges that would form part of the new patch boundary.
+				// Ignore boundary edges that would become internal if the candidate faces were added to the patch.
+				m_newBoundaryEdges.clear();
+				m_ignoreBoundaryEdges.clear();
+				for (CandidateIterator candidateIt(bestCandidate); !candidateIt.isDone(); candidateIt.advance()) {
+					for (Mesh::FaceEdgeIterator it(m_mesh, candidateIt.current()->face); !it.isDone(); it.advance()) {
+						const uint32_t oface = it.oppositeFace();
+						if (oface == UINT32_MAX || !m_faceInPatch.get(oface))
+							m_newBoundaryEdges.push_back(it.edge());
+						if (oface != UINT32_MAX && m_faceInPatch.get(oface))
+							m_ignoreBoundaryEdges.push_back(it.oppositeEdge());
+					}
+				}
+				invalid = m_boundaryGrid.intersect(m_mesh->epsilon(), m_newBoundaryEdges, m_ignoreBoundaryEdges);
+				XA_PROFILE_END(parameterizeChartsPiecewiseBoundaryIntersection)
+			}
+			if (invalid) {
+				// Mark all faces of linked candidates as invalid.
+				for (CandidateIterator it(bestCandidate); !it.isDone(); it.advance())
+					m_faceInvalid.set(it.current()->face);
+				removeLinkedCandidates(bestCandidate);
+			} else {
+				// Add vertex to the patch.
+				m_vertexInPatch.set(freeVertex);
+				// Add faces to the patch.
+				for (CandidateIterator it(bestCandidate); !it.isDone(); it.advance())
+					addFaceToPatch(it.current()->face);
+				// Successfully added candidate face(s) to patch.
+				removeLinkedCandidates(bestCandidate);
+				// Reset the grid with all edges on the patch boundary.
+				XA_PROFILE_START(parameterizeChartsPiecewiseBoundaryIntersection)
+				m_boundaryGrid.reset(m_texcoords, m_mesh->indices());
+				for (uint32_t i = 0; i < m_patch.size(); i++) {
+					for (Mesh::FaceEdgeIterator it(m_mesh, m_patch[i]); !it.isDone(); it.advance()) {
+						const uint32_t oface = it.oppositeFace();
+						if (oface == UINT32_MAX || !m_faceInPatch.get(oface))
+							m_boundaryGrid.append(it.edge());
+					}
+				}
+				XA_PROFILE_END(parameterizeChartsPiecewiseBoundaryIntersection)
+			}
+		}
+		return true;
+	}
+
+private:
+	struct Candidate
+	{
+		uint32_t face, vertex;
+		Candidate *prev, *next; // The previous/next candidate with the same vertex.
+		Vector2 position;
+		float cost;
+		float maxCost; // Of all linked candidates.
+		uint32_t patchEdge;
+		float patchVertexOrient;
+	};
+
+	struct CandidateIterator
+	{
+		CandidateIterator(Candidate *head) : m_current(head) { XA_DEBUG_ASSERT(!head->prev); }
+		void advance() { if (m_current != nullptr) { m_current = m_current->next; } }
+		bool isDone() const { return !m_current; }
+		Candidate *current() { return m_current; }
+
+	private:
+		Candidate *m_current;
+	};
+
+	const Mesh *m_mesh;
+	Array<Vector2> m_texcoords;
+	BitArray m_faceInAnyPatch; // Face is in a previous chart patch or the current patch.
+	Array<Candidate *> m_candidates; // Incident faces to the patch.
+	Array<Candidate *> m_faceToCandidate;
+	Array<uint32_t> m_patch; // The current chart patch.
+	BitArray m_faceInPatch, m_vertexInPatch; // Face/vertex is in the current patch.
+	BitArray m_faceInvalid; // Face cannot be added to the patch - flipped, cost too high or causes boundary intersection.
+	UniformGrid2 m_boundaryGrid;
+	Array<uint32_t> m_newBoundaryEdges, m_ignoreBoundaryEdges; // Temp arrays used when testing for boundary intersection.
+
+	void addFaceToPatch(uint32_t face)
+	{
+		XA_DEBUG_ASSERT(!m_faceInPatch.get(face));
+		XA_DEBUG_ASSERT(!m_faceInAnyPatch.get(face));
+		m_patch.push_back(face);
+		m_faceInPatch.set(face);
+		m_faceInAnyPatch.set(face);
+		// Find new candidate faces on the patch incident to the newly added face.
+		for (Mesh::FaceEdgeIterator it(m_mesh, face); !it.isDone(); it.advance()) {
+			const uint32_t oface = it.oppositeFace();
+			if (oface == UINT32_MAX || m_faceInAnyPatch.get(oface) || m_faceToCandidate[oface])
+				continue;
+			// Found an active edge on the patch front.
+			// Find the free vertex (the vertex that isn't on the active edge).
+			// Compute the orientation of the other patch face vertex to the active edge.
+			uint32_t freeVertex = UINT32_MAX;
+			float orient = 0.0f;
+			for (uint32_t j = 0; j < 3; j++) {
+				const uint32_t vertex = m_mesh->vertexAt(oface * 3 + j);
+				if (vertex != it.vertex0() && vertex != it.vertex1()) {
+					freeVertex = vertex;
+					orient = orientToEdge(m_texcoords[it.vertex0()], m_texcoords[it.vertex1()], m_texcoords[m_mesh->vertexAt(face * 3 + j)]);
+					break;
+				}
+			}
+			XA_DEBUG_ASSERT(freeVertex != UINT32_MAX);
+			if (m_vertexInPatch.get(freeVertex)) {
+#if 0
+				// If the free vertex is already in the patch, the face is enclosed by the patch. Add the face to the patch - don't need to assign texcoords.
+				freeVertex = UINT32_MAX;
+				addFaceToPatch(oface);
+#endif
+				continue;
+			}
+			// Check this here rather than above so faces enclosed by the patch are always added.
+			if (m_faceInvalid.get(oface))
+				continue;
+			addCandidateFace(it.edge(), orient, oface, it.oppositeEdge(), freeVertex);
+		}
+	}
+
+	void addCandidateFace(uint32_t patchEdge, float patchVertexOrient, uint32_t face, uint32_t edge, uint32_t freeVertex)
+	{
+		XA_DEBUG_ASSERT(!m_faceToCandidate[face]);
+		Vector2 texcoords[3];
+		orthoProjectFace(face, texcoords);
+		// Find corresponding vertices between the patch edge and candidate edge.
+		const uint32_t vertex0 = m_mesh->vertexAt(meshEdgeIndex0(patchEdge));
+		const uint32_t vertex1 = m_mesh->vertexAt(meshEdgeIndex1(patchEdge));
+		uint32_t localVertex0 = UINT32_MAX, localVertex1 = UINT32_MAX, localFreeVertex = UINT32_MAX;
+		for (uint32_t i = 0; i < 3; i++) {
+			const uint32_t vertex = m_mesh->vertexAt(face * 3 + i);
+			if (vertex == m_mesh->vertexAt(meshEdgeIndex1(edge)))
+				localVertex0 = i;
+			else if (vertex == m_mesh->vertexAt(meshEdgeIndex0(edge)))
+				localVertex1 = i;
+			else
+				localFreeVertex = i;
+		}
+		// Scale orthogonal projection to match the patch edge.
+		const Vector2 patchEdgeVec = m_texcoords[vertex1] - m_texcoords[vertex0];
+		const Vector2 localEdgeVec = texcoords[localVertex1] - texcoords[localVertex0];
+		const float len1 = length(patchEdgeVec);
+		const float len2 = length(localEdgeVec);
+		if (len1 <= 0.0f || len2 <= 0.0f)
+			return; // Zero length edge.
+		const float scale = len1 / len2;
+		for (uint32_t i = 0; i < 3; i++)
+			texcoords[i] *= scale;
+		// Translate to the first vertex on the patch edge.
+		const Vector2 translate = m_texcoords[vertex0] - texcoords[localVertex0];
+		for (uint32_t i = 0; i < 3; i++)
+			texcoords[i] += translate;
+		// Compute the angle between the patch edge and the corresponding local edge.
+		const float angle = atan2f(patchEdgeVec.y, patchEdgeVec.x) - atan2f(localEdgeVec.y, localEdgeVec.x);
+		// Rotate so the patch edge and the corresponding local edge occupy the same space.
+		for (uint32_t i = 0; i < 3; i++) {
+			if (i == localVertex0)
+				continue;
+			Vector2 &uv = texcoords[i];
+			uv -= texcoords[localVertex0]; // Rotate around the first vertex.
+			const float c = cosf(angle);
+			const float s = sinf(angle);
+			const float x = uv.x * c - uv.y * s;
+			const float y = uv.y * c + uv.x * s;
+			uv.x = x + texcoords[localVertex0].x;
+			uv.y = y + texcoords[localVertex0].y;
+		}
+		if (isNan(texcoords[localFreeVertex].x) || isNan(texcoords[localFreeVertex].y)) {
+			m_faceInvalid.set(face);
+			return;
+		}
+		// Check for local overlap (flipped triangle).
+		// The patch face vertex that isn't on the active edge and the free vertex should be oriented on opposite sides to the active edge.
+		const float freeVertexOrient = orientToEdge(m_texcoords[vertex0], m_texcoords[vertex1], texcoords[localFreeVertex]);
+		if ((patchVertexOrient < 0.0f && freeVertexOrient < 0.0f) || (patchVertexOrient > 0.0f && freeVertexOrient > 0.0f)) {
+			m_faceInvalid.set(face);
+			return;
+		}
+		const float stretch = computeStretch(m_mesh->position(vertex0), m_mesh->position(vertex1), m_mesh->position(freeVertex), texcoords[0], texcoords[1], texcoords[2]);
+		if (stretch >= FLT_MAX) {
+			m_faceInvalid.set(face);
+			return;
+		}
+		const float cost = fabsf(stretch - 1.0f);
+		if (cost > 0.5f) {
+			m_faceInvalid.set(face);
+			return;
+		}
+		// Add the candidate.
+		Candidate *candidate = XA_ALLOC(MemTag::Default, Candidate);
+		candidate->face = face;
+		candidate->vertex = freeVertex;
+		candidate->position = texcoords[localFreeVertex];
+		candidate->prev = candidate->next = nullptr;
+		candidate->cost = candidate->maxCost = cost;
+		candidate->patchEdge = patchEdge;
+		candidate->patchVertexOrient = patchVertexOrient;
+		m_candidates.push_back(candidate);
+		m_faceToCandidate[face] = candidate;
+		// Link with candidates that share the same vertex. Append to tail.
+		for (uint32_t i = 0; i < m_candidates.size() - 1; i++) {
+			if (m_candidates[i]->vertex == candidate->vertex) {
+				Candidate *tail = m_candidates[i];
+				for (;;) {
+					if (tail->next)
+						tail = tail->next;
+					else
+						break;
+				}
+				candidate->prev = tail;
+				candidate->next = nullptr;
+				tail->next = candidate;
+				break;
+			}
+		}
+		// Set max cost for linked candidates.
+		Candidate *head = linkedCandidateHead(candidate);
+		float maxCost = 0.0f;
+		for (CandidateIterator it(head); !it.isDone(); it.advance())
+			maxCost = max(maxCost, it.current()->cost);
+		for (CandidateIterator it(head); !it.isDone(); it.advance())
+			it.current()->maxCost = maxCost;
+	}
+
+	Candidate *linkedCandidateHead(Candidate *candidate)
+	{
+		Candidate *current = candidate;
+		for (;;) {
+			if (!current->prev)
+				break;
+			current = current->prev;
+		}
+		return current;
+	}
+
+	void removeLinkedCandidates(Candidate *head)
+	{
+		XA_DEBUG_ASSERT(!head->prev);
+		Candidate *current = head;
+		while (current) {
+			Candidate *next = current->next;
+			m_faceToCandidate[current->face] = nullptr;
+			for (uint32_t i = 0; i < m_candidates.size(); i++) {
+				if (m_candidates[i] == current) {
+					m_candidates.removeAt(i);
+					break;
+				}
+			}
+			XA_FREE(current);
+			current = next;
+		}
+	}
+
+	void orthoProjectFace(uint32_t face, Vector2 *texcoords) const
+	{
+		const Vector3 normal = -m_mesh->computeFaceNormal(face);
+		const Vector3 tangent = normalize(m_mesh->position(m_mesh->vertexAt(face * 3 + 1)) - m_mesh->position(m_mesh->vertexAt(face * 3 + 0)));
+		const Vector3 bitangent = cross(normal, tangent);
+		for (uint32_t i = 0; i < 3; i++) {
+			const Vector3 &pos = m_mesh->position(m_mesh->vertexAt(face * 3 + i));
+			texcoords[i] = Vector2(dot(tangent, pos), dot(bitangent, pos));
+		}
+	}
+
+	float parametricArea(const Vector2 *texcoords) const
+	{
+		const Vector2 &v1 = texcoords[0];
+		const Vector2 &v2 = texcoords[1];
+		const Vector2 &v3 = texcoords[2];
+		return ((v2.x - v1.x) * (v3.y - v1.y) - (v3.x - v1.x) * (v2.y - v1.y)) * 0.5f;
+	}
+
+	float computeStretch(Vector3 p1, Vector3 p2, Vector3 p3, Vector2 t1, Vector2 t2, Vector2 t3) const
+	{
+		float parametricArea = ((t2.y - t1.y) * (t3.x - t1.x) - (t3.y - t1.y) * (t2.x - t1.x)) * 0.5f;
+		if (isZero(parametricArea, kAreaEpsilon))
+			return FLT_MAX;
+		if (parametricArea < 0.0f)
+			parametricArea = fabsf(parametricArea);
+		const float geometricArea = length(cross(p2 - p1, p3 - p1)) * 0.5f;
+		if (parametricArea <= geometricArea)
+			return parametricArea / geometricArea;
+		else
+			return geometricArea / parametricArea;
+	}
+
+	// Return value is positive if the point is one side of the edge, negative if on the other side.
+	float orientToEdge(Vector2 edgeVertex0, Vector2 edgeVertex1, Vector2 point) const
+	{
+		return (edgeVertex0.x - point.x) * (edgeVertex1.y - point.y) - (edgeVertex0.y - point.y) * (edgeVertex1.x - point.x);
+	}
+};
+
+// Estimate quality of existing parameterization.
+struct Quality
+{
+	// computeBoundaryIntersection
+	bool boundaryIntersection = false;
+
+	// computeFlippedFaces
+	uint32_t totalTriangleCount = 0;
+	uint32_t flippedTriangleCount = 0;
+	uint32_t zeroAreaTriangleCount = 0;
+
+	// computeMetrics
+	float totalParametricArea = 0.0f;
+	float totalGeometricArea = 0.0f;
+	float stretchMetric = 0.0f;
+	float maxStretchMetric = 0.0f;
+	float conformalMetric = 0.0f;
+	float authalicMetric = 0.0f;
+
+	void computeBoundaryIntersection(const Mesh *mesh, UniformGrid2 &boundaryGrid)
+	{
+		const Array<uint32_t> &boundaryEdges = mesh->boundaryEdges();
+		const uint32_t boundaryEdgeCount = boundaryEdges.size();
+		boundaryGrid.reset(mesh->texcoords(), mesh->indices(), boundaryEdgeCount);
+		for (uint32_t i = 0; i < boundaryEdgeCount; i++)
+			boundaryGrid.append(boundaryEdges[i]);
+		boundaryIntersection = boundaryGrid.intersect(mesh->epsilon());
+#if XA_DEBUG_EXPORT_BOUNDARY_GRID
+		static int exportIndex = 0;
+		char filename[256];
+		XA_SPRINTF(filename, sizeof(filename), "debug_boundary_grid_%03d.tga", exportIndex);
+		boundaryGrid.debugExport(filename);
+		exportIndex++;
+#endif
+	}
+
+	void computeFlippedFaces(const Mesh *mesh, Array<uint32_t> *flippedFaces)
+	{
+		totalTriangleCount = flippedTriangleCount = zeroAreaTriangleCount = 0;
+		if (flippedFaces)
+			flippedFaces->clear();
+		const uint32_t faceCount = mesh->faceCount();
+		for (uint32_t f = 0; f < faceCount; f++) {
+			Vector2 texcoord[3];
+			for (int i = 0; i < 3; i++) {
+				const uint32_t v = mesh->vertexAt(f * 3 + i);
+				texcoord[i] = mesh->texcoord(v);
+			}
+			totalTriangleCount++;
+			const float t1 = texcoord[0].x;
+			const float s1 = texcoord[0].y;
+			const float t2 = texcoord[1].x;
+			const float s2 = texcoord[1].y;
+			const float t3 = texcoord[2].x;
+			const float s3 = texcoord[2].y;
+			const float parametricArea = ((s2 - s1) * (t3 - t1) - (s3 - s1) * (t2 - t1)) * 0.5f;
+			if (isZero(parametricArea, kAreaEpsilon)) {
+				zeroAreaTriangleCount++;
+				continue;
+			}
+			if (parametricArea < 0.0f) {
+				// Count flipped triangles.
+				flippedTriangleCount++;
+				if (flippedFaces)
+					flippedFaces->push_back(f);
+			}
+		}
+		if (flippedTriangleCount + zeroAreaTriangleCount == totalTriangleCount) {
+			// If all triangles are flipped, then none are.
+			if (flippedFaces)
+				flippedFaces->clear();
+			flippedTriangleCount = 0;
+		}
+		if (flippedTriangleCount > totalTriangleCount / 2)
+		{
+			// If more than half the triangles are flipped, reverse the flipped / not flipped classification.
+			flippedTriangleCount = totalTriangleCount - flippedTriangleCount;
+			if (flippedFaces) {
+				Array<uint32_t> temp;
+				flippedFaces->copyTo(temp);
+				flippedFaces->clear();
+				for (uint32_t f = 0; f < faceCount; f++) {
+					bool match = false;
+					for (uint32_t ff = 0; ff < temp.size(); ff++) {
+						if (temp[ff] == f) {
+							match = true;
+							break;
+						}
+					}
+					if (!match)
+						flippedFaces->push_back(f);
+				}
+			}
+		}
+	}
+
+	void computeMetrics(const Mesh *mesh)
+	{
+		totalGeometricArea = totalParametricArea = 0.0f;
+		stretchMetric = maxStretchMetric = conformalMetric = authalicMetric = 0.0f;
+		const uint32_t faceCount = mesh->faceCount();
+		for (uint32_t f = 0; f < faceCount; f++) {
+			Vector3 pos[3];
+			Vector2 texcoord[3];
+			for (int i = 0; i < 3; i++) {
+				const uint32_t v = mesh->vertexAt(f * 3 + i);
+				pos[i] = mesh->position(v);
+				texcoord[i] = mesh->texcoord(v);
+			}
+			// Evaluate texture stretch metric. See:
+			// - "Texture Mapping Progressive Meshes", Sander, Snyder, Gortler & Hoppe
+			// - "Mesh Parameterization: Theory and Practice", Siggraph'07 Course Notes, Hormann, Levy & Sheffer.
+			const float t1 = texcoord[0].x;
+			const float s1 = texcoord[0].y;
+			const float t2 = texcoord[1].x;
+			const float s2 = texcoord[1].y;
+			const float t3 = texcoord[2].x;
+			const float s3 = texcoord[2].y;
+			float parametricArea = ((s2 - s1) * (t3 - t1) - (s3 - s1) * (t2 - t1)) * 0.5f;
+			if (isZero(parametricArea, kAreaEpsilon))
+				continue;
+			if (parametricArea < 0.0f)
+				parametricArea = fabsf(parametricArea);
+			const float geometricArea = length(cross(pos[1] - pos[0], pos[2] - pos[0])) / 2;
+			const Vector3 Ss = (pos[0] * (t2 - t3) + pos[1] * (t3 - t1) + pos[2] * (t1 - t2)) / (2 * parametricArea);
+			const Vector3 St = (pos[0] * (s3 - s2) + pos[1] * (s1 - s3) + pos[2] * (s2 - s1)) / (2 * parametricArea);
+			const float a = dot(Ss, Ss); // E
+			const float b = dot(Ss, St); // F
+			const float c = dot(St, St); // G
+										 // Compute eigen-values of the first fundamental form:
+			const float sigma1 = sqrtf(0.5f * max(0.0f, a + c - sqrtf(square(a - c) + 4 * square(b)))); // gamma uppercase, min eigenvalue.
+			const float sigma2 = sqrtf(0.5f * max(0.0f, a + c + sqrtf(square(a - c) + 4 * square(b)))); // gamma lowercase, max eigenvalue.
+			XA_ASSERT(sigma2 > sigma1 || equal(sigma1, sigma2, kEpsilon));
+			// isometric: sigma1 = sigma2 = 1
+			// conformal: sigma1 / sigma2 = 1
+			// authalic: sigma1 * sigma2 = 1
+			const float rmsStretch = sqrtf((a + c) * 0.5f);
+			const float rmsStretch2 = sqrtf((square(sigma1) + square(sigma2)) * 0.5f);
+			XA_DEBUG_ASSERT(equal(rmsStretch, rmsStretch2, 0.01f));
+			XA_UNUSED(rmsStretch2);
+			stretchMetric += square(rmsStretch) * geometricArea;
+			maxStretchMetric = max(maxStretchMetric, sigma2);
+			if (!isZero(sigma1, 0.000001f)) {
+				// sigma1 is zero when geometricArea is zero.
+				conformalMetric += (sigma2 / sigma1) * geometricArea;
+			}
+			authalicMetric += (sigma1 * sigma2) * geometricArea;
+			// Accumulate total areas.
+			totalGeometricArea += geometricArea;
+			totalParametricArea += parametricArea;
+		}
+		XA_DEBUG_ASSERT(isFinite(totalParametricArea) && totalParametricArea >= 0);
+		XA_DEBUG_ASSERT(isFinite(totalGeometricArea) && totalGeometricArea >= 0);
+		XA_DEBUG_ASSERT(isFinite(stretchMetric));
+		XA_DEBUG_ASSERT(isFinite(maxStretchMetric));
+		XA_DEBUG_ASSERT(isFinite(conformalMetric));
+		XA_DEBUG_ASSERT(isFinite(authalicMetric));
+		if (totalGeometricArea > 0.0f) {
+			const float normFactor = sqrtf(totalParametricArea / totalGeometricArea);
+			stretchMetric = sqrtf(stretchMetric / totalGeometricArea) * normFactor;
+			maxStretchMetric  *= normFactor;
+			conformalMetric = sqrtf(conformalMetric / totalGeometricArea);
+			authalicMetric = sqrtf(authalicMetric / totalGeometricArea);
+		}
+	}
+};
+
+struct ChartCtorBuffers
+{
+	Array<uint32_t> chartMeshIndices;
+	Array<uint32_t> unifiedMeshIndices;
+};
+
+class Chart
+{
+public:
+	Chart(const Basis &basis, segment::ChartGeneratorType::Enum generatorType, ConstArrayView<uint32_t> faces, const Mesh *sourceMesh, uint32_t chartGroupId, uint32_t chartId) : m_basis(basis), m_unifiedMesh(nullptr), m_type(ChartType::LSCM), m_generatorType(generatorType), m_tjunctionCount(0), m_originalVertexCount(0), m_isInvalid(false)
+	{
+		XA_UNUSED(chartGroupId);
+		XA_UNUSED(chartId);
+		m_faceToSourceFaceMap.copyFrom(faces.data, faces.length);
+		const uint32_t approxVertexCount = min(faces.length * 3, sourceMesh->vertexCount());
+		m_unifiedMesh = XA_NEW_ARGS(MemTag::Mesh, Mesh, sourceMesh->epsilon(), approxVertexCount, faces.length);
+		HashMap<uint32_t, PassthroughHash<uint32_t>> sourceVertexToUnifiedVertexMap(MemTag::Mesh, approxVertexCount), sourceVertexToChartVertexMap(MemTag::Mesh, approxVertexCount);
+		m_originalIndices.resize(faces.length * 3);
+		// Add geometry.
+		const uint32_t faceCount = faces.length;
+		for (uint32_t f = 0; f < faceCount; f++) {
+			uint32_t unifiedIndices[3];
+			for (uint32_t i = 0; i < 3; i++) {
+				const uint32_t sourceVertex = sourceMesh->vertexAt(m_faceToSourceFaceMap[f] * 3 + i);
+				uint32_t sourceUnifiedVertex = sourceMesh->firstColocalVertex(sourceVertex);
+				if (m_generatorType == segment::ChartGeneratorType::OriginalUv && sourceVertex != sourceUnifiedVertex) {
+					// Original UVs: don't unify vertices with different UVs; we want to preserve UVs.
+					if (!equal(sourceMesh->texcoord(sourceVertex), sourceMesh->texcoord(sourceUnifiedVertex), sourceMesh->epsilon()))
+						sourceUnifiedVertex = sourceVertex;
+				}
+				uint32_t unifiedVertex = sourceVertexToUnifiedVertexMap.get(sourceUnifiedVertex);
+				if (unifiedVertex == UINT32_MAX) {
+					unifiedVertex = sourceVertexToUnifiedVertexMap.add(sourceUnifiedVertex);
+					m_unifiedMesh->addVertex(sourceMesh->position(sourceVertex), Vector3(0.0f), sourceMesh->texcoord(sourceVertex));
+				}
+				if (sourceVertexToChartVertexMap.get(sourceVertex) == UINT32_MAX) {
+					sourceVertexToChartVertexMap.add(sourceVertex);
+					m_vertexToSourceVertexMap.push_back(sourceVertex);
+					m_chartVertexToUnifiedVertexMap.push_back(unifiedVertex);
+					m_originalVertexCount++;
+				}
+				m_originalIndices[f * 3 + i] = sourceVertexToChartVertexMap.get(sourceVertex);;
+				XA_DEBUG_ASSERT(m_originalIndices[f * 3 + i] != UINT32_MAX);
+				unifiedIndices[i] = sourceVertexToUnifiedVertexMap.get(sourceUnifiedVertex);
+				XA_DEBUG_ASSERT(unifiedIndices[i] != UINT32_MAX);
+			}
+			m_unifiedMesh->addFace(unifiedIndices);
+		}
+		m_unifiedMesh->createBoundaries();
+		if (m_generatorType == segment::ChartGeneratorType::Planar) {
+			m_type = ChartType::Planar;
+			return;
+		}
+#if XA_CHECK_T_JUNCTIONS
+		m_tjunctionCount = meshCheckTJunctions(*m_unifiedMesh);
+#if XA_DEBUG_EXPORT_OBJ_TJUNCTION
+		if (m_tjunctionCount > 0) {
+			char filename[256];
+			XA_SPRINTF(filename, sizeof(filename), "debug_mesh_%03u_chartgroup_%03u_chart_%03u_tjunction.obj", sourceMesh->id(), chartGroupId, chartId);
+			m_unifiedMesh->writeObjFile(filename);
+		}
+#endif
+#endif
+	}
+
+	Chart(ChartCtorBuffers &buffers, const Chart *parent, const Mesh *parentMesh, ConstArrayView<uint32_t> faces, ConstArrayView<Vector2> texcoords, const Mesh *sourceMesh) : m_unifiedMesh(nullptr), m_type(ChartType::Piecewise), m_generatorType(segment::ChartGeneratorType::Piecewise), m_tjunctionCount(0), m_originalVertexCount(0), m_isInvalid(false)
+	{
+		const uint32_t faceCount = faces.length;
+		m_faceToSourceFaceMap.resize(faceCount);
+		for (uint32_t i = 0; i < faceCount; i++)
+			m_faceToSourceFaceMap[i] = parent->m_faceToSourceFaceMap[faces[i]]; // Map faces to parent chart source mesh.
+		// Copy face indices.
+		Array<uint32_t> &chartMeshIndices = buffers.chartMeshIndices;
+		chartMeshIndices.resize(sourceMesh->vertexCount());
+		chartMeshIndices.fillBytes(0xff);
+		m_unifiedMesh = XA_NEW_ARGS(MemTag::Mesh, Mesh, sourceMesh->epsilon(), m_faceToSourceFaceMap.size() * 3, m_faceToSourceFaceMap.size());
+		HashMap<uint32_t, PassthroughHash<uint32_t>> sourceVertexToUnifiedVertexMap(MemTag::Mesh, m_faceToSourceFaceMap.size() * 3);
+		// Add vertices.
+		for (uint32_t f = 0; f < faceCount; f++) {
+			for (uint32_t i = 0; i < 3; i++) {
+				const uint32_t vertex = sourceMesh->vertexAt(m_faceToSourceFaceMap[f] * 3 + i);
+				const uint32_t sourceUnifiedVertex = sourceMesh->firstColocalVertex(vertex);
+				const uint32_t parentVertex = parentMesh->vertexAt(faces[f] * 3 + i);
+				uint32_t unifiedVertex = sourceVertexToUnifiedVertexMap.get(sourceUnifiedVertex);
+				if (unifiedVertex == UINT32_MAX) {
+					unifiedVertex = sourceVertexToUnifiedVertexMap.add(sourceUnifiedVertex);
+					m_unifiedMesh->addVertex(sourceMesh->position(vertex), Vector3(0.0f), texcoords[parentVertex]);
+				}
+				if (chartMeshIndices[vertex] == UINT32_MAX) {
+					chartMeshIndices[vertex] = m_originalVertexCount;
+					m_originalVertexCount++;
+					m_vertexToSourceVertexMap.push_back(vertex);
+					m_chartVertexToUnifiedVertexMap.push_back(unifiedVertex);
+				}
+			}
+		}
+		// Add faces.
+		m_originalIndices.resize(faceCount * 3);
+		for (uint32_t f = 0; f < faceCount; f++) {
+			uint32_t unifiedIndices[3];
+			for (uint32_t i = 0; i < 3; i++) {
+				const uint32_t vertex = sourceMesh->vertexAt(m_faceToSourceFaceMap[f] * 3 + i);
+				m_originalIndices[f * 3 + i] = chartMeshIndices[vertex];
+				const uint32_t unifiedVertex = sourceMesh->firstColocalVertex(vertex);
+				unifiedIndices[i] = sourceVertexToUnifiedVertexMap.get(unifiedVertex);
+			}
+			m_unifiedMesh->addFace(unifiedIndices);
+		}
+		m_unifiedMesh->createBoundaries();
+		// Need to store texcoords for backup/restore so packing can be run multiple times.
+		backupTexcoords();
+	}
+
+	~Chart()
+	{
+		if (m_unifiedMesh) {
+			m_unifiedMesh->~Mesh();
+			XA_FREE(m_unifiedMesh);
+			m_unifiedMesh = nullptr;
+		}
+	}
+
+	bool isInvalid() const { return m_isInvalid; }
+	ChartType type() const { return m_type; }
+	segment::ChartGeneratorType::Enum generatorType() const { return m_generatorType; }
+	uint32_t tjunctionCount() const { return m_tjunctionCount; }
+	const Quality &quality() const { return m_quality; }
+#if XA_DEBUG_EXPORT_OBJ_INVALID_PARAMETERIZATION
+	const Array<uint32_t> &paramFlippedFaces() const { return m_paramFlippedFaces; }
+#endif
+	uint32_t mapFaceToSourceFace(uint32_t i) const { return m_faceToSourceFaceMap[i]; }
+	uint32_t mapChartVertexToSourceVertex(uint32_t i) const { return m_vertexToSourceVertexMap[i]; }
+	const Mesh *unifiedMesh() const { return m_unifiedMesh; }
+	Mesh *unifiedMesh() { return m_unifiedMesh; }
+
+	// Vertex count of the chart mesh before unifying vertices.
+	uint32_t originalVertexCount() const { return m_originalVertexCount; }
+
+	uint32_t originalVertexToUnifiedVertex(uint32_t v) const { return m_chartVertexToUnifiedVertexMap[v]; }
+
+	ConstArrayView<uint32_t> originalVertices() const { return m_originalIndices; }
+
+	void parameterize(const ChartOptions &options, UniformGrid2 &boundaryGrid)
+	{
+		const uint32_t unifiedVertexCount = m_unifiedMesh->vertexCount();
+		if (m_generatorType == segment::ChartGeneratorType::OriginalUv) {
+		} else {
+			// Project vertices to plane.
+			XA_PROFILE_START(parameterizeChartsOrthogonal)
+			for (uint32_t i = 0; i < unifiedVertexCount; i++)
+				m_unifiedMesh->texcoord(i) = Vector2(dot(m_basis.tangent, m_unifiedMesh->position(i)), dot(m_basis.bitangent, m_unifiedMesh->position(i)));
+			XA_PROFILE_END(parameterizeChartsOrthogonal)
+			// Computing charts checks for flipped triangles and boundary intersection. Don't need to do that again here if chart is planar.
+			if (m_type != ChartType::Planar && m_generatorType != segment::ChartGeneratorType::OriginalUv) {
+				XA_PROFILE_START(parameterizeChartsEvaluateQuality)
+				m_quality.computeBoundaryIntersection(m_unifiedMesh, boundaryGrid);
+				m_quality.computeFlippedFaces(m_unifiedMesh, nullptr);
+				m_quality.computeMetrics(m_unifiedMesh);
+				XA_PROFILE_END(parameterizeChartsEvaluateQuality)
+				// Use orthogonal parameterization if quality is acceptable.
+				if (!m_quality.boundaryIntersection && m_quality.flippedTriangleCount == 0 && m_quality.zeroAreaTriangleCount == 0 && m_quality.totalGeometricArea > 0.0f && m_quality.stretchMetric <= 1.1f && m_quality.maxStretchMetric <= 1.25f)
+					m_type = ChartType::Ortho;
+			}
+			if (m_type == ChartType::LSCM) {
+				XA_PROFILE_START(parameterizeChartsLSCM)
+				if (options.paramFunc) {
+					options.paramFunc(&m_unifiedMesh->position(0).x, &m_unifiedMesh->texcoord(0).x, m_unifiedMesh->vertexCount(), m_unifiedMesh->indices().data, m_unifiedMesh->indexCount());
+				}
+				else
+					computeLeastSquaresConformalMap(m_unifiedMesh);
+				XA_PROFILE_END(parameterizeChartsLSCM)
+				XA_PROFILE_START(parameterizeChartsEvaluateQuality)
+				m_quality.computeBoundaryIntersection(m_unifiedMesh, boundaryGrid);
+#if XA_DEBUG_EXPORT_OBJ_INVALID_PARAMETERIZATION
+				m_quality.computeFlippedFaces(m_unifiedMesh, &m_paramFlippedFaces);
+#else
+				m_quality.computeFlippedFaces(m_unifiedMesh, nullptr);
+#endif
+				// Don't need to call computeMetrics here, that's only used in evaluateOrthoQuality to determine if quality is acceptable enough to use ortho projection.
+				if (m_quality.boundaryIntersection || m_quality.flippedTriangleCount > 0 || m_quality.zeroAreaTriangleCount > 0)
+					m_isInvalid = true;
+				XA_PROFILE_END(parameterizeChartsEvaluateQuality)
+			}
+		}
+		if (options.fixWinding && m_unifiedMesh->computeFaceParametricArea(0) < 0.0f) {
+			for (uint32_t i = 0; i < unifiedVertexCount; i++)
+				m_unifiedMesh->texcoord(i).x *= -1.0f;
+		}
+#if XA_CHECK_PARAM_WINDING
+		const uint32_t faceCount = m_unifiedMesh->faceCount();
+		uint32_t flippedCount = 0;
+		for (uint32_t i = 0; i < faceCount; i++) {
+			const float area = m_unifiedMesh->computeFaceParametricArea(i);
+			if (area < 0.0f)
+				flippedCount++;
+		}
+		if (flippedCount == faceCount) {
+			XA_PRINT_WARNING("param: all faces flipped\n");
+		} else if (flippedCount > 0) {
+			XA_PRINT_WARNING("param: %u / %u faces flipped\n", flippedCount, faceCount);
+		}
+#endif
+
+#if XA_DEBUG_ALL_CHARTS_INVALID
+		m_isInvalid = true;
+#endif
+		// Need to store texcoords for backup/restore so packing can be run multiple times.
+		backupTexcoords();
+	}
+
+	Vector2 computeParametricBounds() const
+	{
+		Vector2 minCorner(FLT_MAX, FLT_MAX);
+		Vector2 maxCorner(-FLT_MAX, -FLT_MAX);
+		const uint32_t vertexCount = m_unifiedMesh->vertexCount();
+		for (uint32_t v = 0; v < vertexCount; v++) {
+			minCorner = min(minCorner, m_unifiedMesh->texcoord(v));
+			maxCorner = max(maxCorner, m_unifiedMesh->texcoord(v));
+		}
+		return (maxCorner - minCorner) * 0.5f;
+	}
+
+#if XA_CHECK_PIECEWISE_CHART_QUALITY
+	void evaluateQuality(UniformGrid2 &boundaryGrid)
+	{
+		m_quality.computeBoundaryIntersection(m_unifiedMesh, boundaryGrid);
+#if XA_DEBUG_EXPORT_OBJ_INVALID_PARAMETERIZATION
+		m_quality.computeFlippedFaces(m_unifiedMesh, &m_paramFlippedFaces);
+#else
+		m_quality.computeFlippedFaces(m_unifiedMesh, nullptr);
+#endif
+		if (m_quality.boundaryIntersection || m_quality.flippedTriangleCount > 0 || m_quality.zeroAreaTriangleCount > 0)
+			m_isInvalid = true;
+	}
+#endif
+
+	void restoreTexcoords()
+	{
+		memcpy(m_unifiedMesh->texcoords().data, m_backupTexcoords.data(), m_unifiedMesh->vertexCount() * sizeof(Vector2));
+	}
+
+private:
+	void backupTexcoords()
+	{
+		m_backupTexcoords.resize(m_unifiedMesh->vertexCount());
+		memcpy(m_backupTexcoords.data(), m_unifiedMesh->texcoords().data, m_unifiedMesh->vertexCount() * sizeof(Vector2));
+	}
+
+	Basis m_basis;
+	Mesh *m_unifiedMesh;
+	ChartType m_type;
+	segment::ChartGeneratorType::Enum m_generatorType;
+	uint32_t m_tjunctionCount;
+
+	uint32_t m_originalVertexCount;
+	Array<uint32_t> m_originalIndices;
+
+	// List of faces of the source mesh that belong to this chart.
+	Array<uint32_t> m_faceToSourceFaceMap;
+
+	// Map vertices of the chart mesh to vertices of the source mesh.
+	Array<uint32_t> m_vertexToSourceVertexMap;
+
+	Array<uint32_t> m_chartVertexToUnifiedVertexMap;
+
+	Array<Vector2> m_backupTexcoords;
+
+	Quality m_quality;
+#if XA_DEBUG_EXPORT_OBJ_INVALID_PARAMETERIZATION
+	Array<uint32_t> m_paramFlippedFaces;
+#endif
+	bool m_isInvalid;
+};
+
+struct CreateAndParameterizeChartTaskGroupArgs
+{
+	Progress *progress;
+	ThreadLocal<UniformGrid2> *boundaryGrid;
+	ThreadLocal<ChartCtorBuffers> *chartBuffers;
+	const ChartOptions *options;
+	ThreadLocal<PiecewiseParam> *pp;
+};
+
+struct CreateAndParameterizeChartTaskArgs
+{
+	const Basis *basis;
+	Chart *chart; // output
+	Array<Chart *> charts; // output (if more than one chart)
+	segment::ChartGeneratorType::Enum chartGeneratorType;
+	const Mesh *mesh;
+	ConstArrayView<uint32_t> faces;
+	uint32_t chartGroupId;
+	uint32_t chartId;
+};
+
+static void runCreateAndParameterizeChartTask(void *groupUserData, void *taskUserData)
+{
+	XA_PROFILE_START(createChartMeshAndParameterizeThread)
+	auto groupArgs = (CreateAndParameterizeChartTaskGroupArgs *)groupUserData;
+	auto args = (CreateAndParameterizeChartTaskArgs *)taskUserData;
+	XA_PROFILE_START(createChartMesh)
+	args->chart = XA_NEW_ARGS(MemTag::Default, Chart, *args->basis, args->chartGeneratorType, args->faces, args->mesh, args->chartGroupId, args->chartId);
+	XA_PROFILE_END(createChartMesh)
+	XA_PROFILE_START(parameterizeCharts)
+	args->chart->parameterize(*groupArgs->options, groupArgs->boundaryGrid->get());
+	XA_PROFILE_END(parameterizeCharts)
+#if XA_RECOMPUTE_CHARTS
+	if (!args->chart->isInvalid()) {
+		XA_PROFILE_END(createChartMeshAndParameterizeThread)
+		return;
+	}
+	// Recompute charts with invalid parameterizations.
+	XA_PROFILE_START(parameterizeChartsRecompute)
+	Chart *invalidChart = args->chart;
+	const Mesh *invalidMesh = invalidChart->unifiedMesh();
+	PiecewiseParam &pp = groupArgs->pp->get();
+	pp.reset(invalidMesh);
+#if XA_DEBUG_EXPORT_OBJ_RECOMPUTED_CHARTS
+	char filename[256];
+	XA_SPRINTF(filename, sizeof(filename), "debug_mesh_%03u_chartgroup_%03u_chart_%03u_recomputed.obj", args->mesh->id(), args->chartGroupId, args->chartId);
+	FILE *file;
+	XA_FOPEN(file, filename, "w");
+	uint32_t subChartIndex = 0;
+#endif
+	for (;;) {
+		XA_PROFILE_START(parameterizeChartsPiecewise)
+		const bool facesRemaining = pp.computeChart();
+		XA_PROFILE_END(parameterizeChartsPiecewise)
+		if (!facesRemaining)
+			break;
+		Chart *chart = XA_NEW_ARGS(MemTag::Default, Chart, groupArgs->chartBuffers->get(), invalidChart, invalidMesh, pp.chartFaces(), pp.texcoords(), args->mesh);
+#if XA_CHECK_PIECEWISE_CHART_QUALITY
+		chart->evaluateQuality(args->boundaryGrid->get());
+#endif
+		args->charts.push_back(chart);
+#if XA_DEBUG_EXPORT_OBJ_RECOMPUTED_CHARTS
+		if (file) {
+			for (uint32_t j = 0; j < invalidMesh->vertexCount(); j++) {
+				fprintf(file, "v %g %g %g\n", invalidMesh->position(j).x, invalidMesh->position(j).y, invalidMesh->position(j).z);
+				fprintf(file, "vt %g %g\n", pp.texcoords()[j].x, pp.texcoords()[j].y);
+			}
+			fprintf(file, "o chart%03u\n", subChartIndex);
+			fprintf(file, "s off\n");
+			for (uint32_t f = 0; f < pp.chartFaces().length; f++) {
+				fprintf(file, "f ");
+				const uint32_t face = pp.chartFaces()[f];
+				for (uint32_t j = 0; j < 3; j++) {
+					const uint32_t index = invalidMesh->vertexCount() * subChartIndex + invalidMesh->vertexAt(face * 3 + j) + 1; // 1-indexed
+					fprintf(file, "%d/%d/%c", index, index, j == 2 ? '\n' : ' ');
+				}
+			}
+		}
+		subChartIndex++;
+#endif
+	}
+#if XA_DEBUG_EXPORT_OBJ_RECOMPUTED_CHARTS
+	if (file)
+		fclose(file);
+#endif
+	XA_PROFILE_END(parameterizeChartsRecompute)
+#endif // XA_RECOMPUTE_CHARTS
+	XA_PROFILE_END(createChartMeshAndParameterizeThread)
+	// Update progress.
+	groupArgs->progress->increment(args->faces.length);
+}
+
+// Set of charts corresponding to mesh faces in the same face group.
+class ChartGroup
+{
+public:
+	ChartGroup(uint32_t id, const Mesh *sourceMesh, const MeshFaceGroups *sourceMeshFaceGroups, MeshFaceGroups::Handle faceGroup) : m_id(id), m_sourceMesh(sourceMesh), m_sourceMeshFaceGroups(sourceMeshFaceGroups), m_faceGroup(faceGroup)
+	{
+	}
+
+	~ChartGroup()
+	{
+		for (uint32_t i = 0; i < m_charts.size(); i++) {
+			m_charts[i]->~Chart();
+			XA_FREE(m_charts[i]);
+		}
+	}
+
+	uint32_t chartCount() const { return m_charts.size(); }
+	Chart *chartAt(uint32_t i) const { return m_charts[i]; }
+	uint32_t faceCount() const { return m_sourceMeshFaceGroups->faceCount(m_faceGroup); }
+
+	void computeCharts(TaskScheduler *taskScheduler, const ChartOptions &options, Progress *progress, segment::Atlas &atlas, ThreadLocal<UniformGrid2> *boundaryGrid, ThreadLocal<ChartCtorBuffers> *chartBuffers, ThreadLocal<PiecewiseParam> *piecewiseParam)
+	{
+		// This function may be called multiple times, so destroy existing charts.
+		for (uint32_t i = 0; i < m_charts.size(); i++) {
+			m_charts[i]->~Chart();
+			XA_FREE(m_charts[i]);
+		}
+		// Create mesh from source mesh, using only the faces in this face group.
+		XA_PROFILE_START(createChartGroupMesh)
+		Mesh *mesh = createMesh();
+		XA_PROFILE_END(createChartGroupMesh)
+		// Segment mesh into charts (arrays of faces).
+#if XA_DEBUG_SINGLE_CHART
+		XA_UNUSED(options);
+		XA_UNUSED(atlas);
+		const uint32_t chartCount = 1;
+		uint32_t offset;
+		Basis chartBasis;
+		Fit::computeBasis(&mesh->position(0), mesh->vertexCount(), &chartBasis);
+		Array<uint32_t> chartFaces;
+		chartFaces.resize(1 + mesh->faceCount());
+		chartFaces[0] = mesh->faceCount();
+		for (uint32_t i = 0; i < chartFaces.size() - 1; i++)
+			chartFaces[i + 1] = m_faceToSourceFaceMap[i];
+		// Destroy mesh.
+		const uint32_t faceCount = mesh->faceCount();
+		mesh->~Mesh();
+		XA_FREE(mesh);
+#else
+		XA_PROFILE_START(buildAtlas)
+		atlas.reset(mesh, options);
+		atlas.compute();
+		XA_PROFILE_END(buildAtlas)
+		// Update progress.
+		progress->increment(faceCount());
+#if XA_DEBUG_EXPORT_OBJ_CHARTS
+		char filename[256];
+		XA_SPRINTF(filename, sizeof(filename), "debug_mesh_%03u_chartgroup_%03u_charts.obj", m_sourceMesh->id(), m_id);
+		FILE *file;
+		XA_FOPEN(file, filename, "w");
+		if (file) {
+			mesh->writeObjVertices(file);
+			for (uint32_t i = 0; i < atlas.chartCount(); i++) {
+				fprintf(file, "o chart_%04d\n", i);
+				fprintf(file, "s off\n");
+				ConstArrayView<uint32_t> faces = atlas.chartFaces(i);
+				for (uint32_t f = 0; f < faces.length; f++)
+					mesh->writeObjFace(file, faces[f]);
+			}
+			mesh->writeObjBoundaryEges(file);
+			fclose(file);
+		}
+#endif
+		// Destroy mesh.
+		const uint32_t faceCount = mesh->faceCount();
+		mesh->~Mesh();
+		XA_FREE(mesh);
+		XA_PROFILE_START(copyChartFaces)
+		if (progress->cancel)
+			return;
+		// Copy faces from segment::Atlas to m_chartFaces array with <chart 0 face count> <face 0> <face n> <chart 1 face count> etc. encoding.
+		// segment::Atlas faces refer to the chart group mesh. Map them to the input mesh instead.
+		const uint32_t chartCount = atlas.chartCount();
+		Array<uint32_t> chartFaces;
+		chartFaces.resize(chartCount + faceCount);
+		uint32_t offset = 0;
+		for (uint32_t i = 0; i < chartCount; i++) {
+			ConstArrayView<uint32_t> faces = atlas.chartFaces(i);
+			chartFaces[offset++] = faces.length;
+			for (uint32_t j = 0; j < faces.length; j++)
+				chartFaces[offset++] = m_faceToSourceFaceMap[faces[j]];
+		}
+		XA_PROFILE_END(copyChartFaces)
+#endif
+		XA_PROFILE_START(createChartMeshAndParameterizeReal)
+		CreateAndParameterizeChartTaskGroupArgs groupArgs;
+		groupArgs.progress = progress;
+		groupArgs.boundaryGrid = boundaryGrid;
+		groupArgs.chartBuffers = chartBuffers;
+		groupArgs.options = &options;
+		groupArgs.pp = piecewiseParam;
+		TaskGroupHandle taskGroup = taskScheduler->createTaskGroup(&groupArgs, chartCount);
+		Array<CreateAndParameterizeChartTaskArgs> taskArgs;
+		taskArgs.resize(chartCount);
+		taskArgs.runCtors(); // Has Array member.
+		offset = 0;
+		for (uint32_t i = 0; i < chartCount; i++) {
+			CreateAndParameterizeChartTaskArgs &args = taskArgs[i];
+#if XA_DEBUG_SINGLE_CHART
+			args.basis = &chartBasis;
+			args.isPlanar = false;
+#else
+			args.basis = &atlas.chartBasis(i);
+			args.chartGeneratorType = atlas.chartGeneratorType(i);
+#endif
+			args.chart = nullptr;
+			args.chartGroupId = m_id;
+			args.chartId = i;
+			const uint32_t chartFaceCount = chartFaces[offset++];
+			args.faces = ConstArrayView<uint32_t>(&chartFaces[offset], chartFaceCount);
+			offset += chartFaceCount;
+			args.mesh = m_sourceMesh;
+			Task task;
+			task.userData = &args;
+			task.func = runCreateAndParameterizeChartTask;
+			taskScheduler->run(taskGroup, task);
+		}
+		taskScheduler->wait(&taskGroup);
+		XA_PROFILE_END(createChartMeshAndParameterizeReal)
+#if XA_RECOMPUTE_CHARTS
+		// Count charts. Skip invalid ones and include new ones added by recomputing.
+		uint32_t newChartCount = 0;
+		for (uint32_t i = 0; i < chartCount; i++) {
+			if (taskArgs[i].chart->isInvalid())
+				newChartCount += taskArgs[i].charts.size();
+			else
+				newChartCount++;
+		}
+		m_charts.resize(newChartCount);
+		// Add valid charts first. Destroy invalid ones.
+		uint32_t current = 0;
+		for (uint32_t i = 0; i < chartCount; i++) {
+			Chart *chart = taskArgs[i].chart;
+			if (chart->isInvalid()) {
+				chart->~Chart();
+				XA_FREE(chart);
+				continue;
+			}
+			m_charts[current++] = chart;
+		}
+		// Now add new charts.
+		for (uint32_t i = 0; i < chartCount; i++) {
+			CreateAndParameterizeChartTaskArgs &args = taskArgs[i];
+			for (uint32_t j = 0; j < args.charts.size(); j++)
+				m_charts[current++] = args.charts[j];
+		}
+#else // XA_RECOMPUTE_CHARTS
+		m_charts.resize(chartCount);
+		for (uint32_t i = 0; i < chartCount; i++)
+			m_charts[i] = taskArgs[i].chart;
+#endif // XA_RECOMPUTE_CHARTS
+		taskArgs.runDtors(); // Has Array member.
+	}
+
+private:
+	Mesh *createMesh()
+	{
+		XA_DEBUG_ASSERT(m_faceGroup != MeshFaceGroups::kInvalid);
+		// Create new mesh from the source mesh, using faces that belong to this group.
+		m_faceToSourceFaceMap.reserve(m_sourceMeshFaceGroups->faceCount(m_faceGroup));
+		for (MeshFaceGroups::Iterator it(m_sourceMeshFaceGroups, m_faceGroup); !it.isDone(); it.advance())
+			m_faceToSourceFaceMap.push_back(it.face());
+		// Only initial meshes has ignored faces. The only flag we care about is HasNormals.
+		const uint32_t faceCount = m_faceToSourceFaceMap.size();
+		XA_DEBUG_ASSERT(faceCount > 0);
+		const uint32_t approxVertexCount = min(faceCount * 3, m_sourceMesh->vertexCount());
+		Mesh *mesh = XA_NEW_ARGS(MemTag::Mesh, Mesh, m_sourceMesh->epsilon(), approxVertexCount, faceCount, m_sourceMesh->flags() & MeshFlags::HasNormals);
+		HashMap<uint32_t, PassthroughHash<uint32_t>> sourceVertexToVertexMap(MemTag::Mesh, approxVertexCount);
+		for (uint32_t f = 0; f < faceCount; f++) {
+			const uint32_t face = m_faceToSourceFaceMap[f];
+			for (uint32_t i = 0; i < 3; i++) {
+				const uint32_t vertex = m_sourceMesh->vertexAt(face * 3 + i);
+				if (sourceVertexToVertexMap.get(vertex) == UINT32_MAX) {
+					sourceVertexToVertexMap.add(vertex);
+					Vector3 normal(0.0f);
+					if (m_sourceMesh->flags() & MeshFlags::HasNormals)
+						normal = m_sourceMesh->normal(vertex);
+					mesh->addVertex(m_sourceMesh->position(vertex), normal, m_sourceMesh->texcoord(vertex));
+				}
+			}
+		}
+		// Add faces.
+		for (uint32_t f = 0; f < faceCount; f++) {
+			const uint32_t face = m_faceToSourceFaceMap[f];
+			XA_DEBUG_ASSERT(!m_sourceMesh->isFaceIgnored(face));
+			uint32_t indices[3];
+			for (uint32_t i = 0; i < 3; i++) {
+				const uint32_t vertex = m_sourceMesh->vertexAt(face * 3 + i);
+				indices[i] = sourceVertexToVertexMap.get(vertex);
+				XA_DEBUG_ASSERT(indices[i] != UINT32_MAX);
+			}
+			// Don't copy flags - ignored faces aren't used by chart groups, they are handled by InvalidMeshGeometry.
+			mesh->addFace(indices);
+		}
+		XA_PROFILE_START(createChartGroupMeshColocals)
+		mesh->createColocals();
+		XA_PROFILE_END(createChartGroupMeshColocals)
+		XA_PROFILE_START(createChartGroupMeshBoundaries)
+		mesh->createBoundaries();
+		mesh->destroyEdgeMap(); // Only needed it for createBoundaries.
+		XA_PROFILE_END(createChartGroupMeshBoundaries)
+#if XA_DEBUG_EXPORT_OBJ_CHART_GROUPS
+		char filename[256];
+		XA_SPRINTF(filename, sizeof(filename), "debug_mesh_%03u_chartgroup_%03u.obj", m_sourceMesh->id(), m_id);
+		mesh->writeObjFile(filename);
+#endif
+		return mesh;
+	}
+
+	const uint32_t m_id;
+	const Mesh * const m_sourceMesh;
+	const MeshFaceGroups * const m_sourceMeshFaceGroups;
+	const MeshFaceGroups::Handle m_faceGroup;
+	Array<uint32_t> m_faceToSourceFaceMap; // List of faces of the source mesh that belong to this chart group.
+	Array<Chart *> m_charts;
+};
+
+struct ChartGroupComputeChartsTaskGroupArgs
+{
+	ThreadLocal<segment::Atlas> *atlas;
+	const ChartOptions *options;
+	Progress *progress;
+	TaskScheduler *taskScheduler;
+	ThreadLocal<UniformGrid2> *boundaryGrid;
+	ThreadLocal<ChartCtorBuffers> *chartBuffers;
+	ThreadLocal<PiecewiseParam> *piecewiseParam;
+};
+
+static void runChartGroupComputeChartsTask(void *groupUserData, void *taskUserData)
+{
+	auto args = (ChartGroupComputeChartsTaskGroupArgs *)groupUserData;
+	auto chartGroup = (ChartGroup *)taskUserData;
+	if (args->progress->cancel)
+		return;
+	XA_PROFILE_START(chartGroupComputeChartsThread)
+	chartGroup->computeCharts(args->taskScheduler, *args->options, args->progress, args->atlas->get(), args->boundaryGrid, args->chartBuffers, args->piecewiseParam);
+	XA_PROFILE_END(chartGroupComputeChartsThread)
+}
+
+struct MeshComputeChartsTaskGroupArgs
+{
+	ThreadLocal<segment::Atlas> *atlas;
+	const ChartOptions *options;
+	Progress *progress;
+	TaskScheduler *taskScheduler;
+	ThreadLocal<UniformGrid2> *boundaryGrid;
+	ThreadLocal<ChartCtorBuffers> *chartBuffers;
+	ThreadLocal<PiecewiseParam> *piecewiseParam;
+};
+
+struct MeshComputeChartsTaskArgs
+{
+	const Mesh *sourceMesh;
+	Array<ChartGroup *> *chartGroups; // output
+	InvalidMeshGeometry *invalidMeshGeometry; // output
+};
+
+#if XA_DEBUG_EXPORT_OBJ_FACE_GROUPS
+static uint32_t s_faceGroupsCurrentVertex = 0;
+#endif
+
+static void runMeshComputeChartsTask(void *groupUserData, void *taskUserData)
+{
+	auto groupArgs = (MeshComputeChartsTaskGroupArgs *)groupUserData;
+	auto args = (MeshComputeChartsTaskArgs *)taskUserData;
+	if (groupArgs->progress->cancel)
+		return;
+	XA_PROFILE_START(computeChartsThread)
+	// Create face groups.
+	XA_PROFILE_START(createFaceGroups)
+	MeshFaceGroups *meshFaceGroups = XA_NEW_ARGS(MemTag::Mesh, MeshFaceGroups, args->sourceMesh);
+	meshFaceGroups->compute();
+	const uint32_t chartGroupCount = meshFaceGroups->groupCount();
+	XA_PROFILE_END(createFaceGroups)
+	if (groupArgs->progress->cancel)
+		goto cleanup;
+#if XA_DEBUG_EXPORT_OBJ_FACE_GROUPS
+	{
+		static std::mutex s_mutex;
+		std::lock_guard<std::mutex> lock(s_mutex);
+		char filename[256];
+		XA_SPRINTF(filename, sizeof(filename), "debug_face_groups.obj");
+		FILE *file;
+		XA_FOPEN(file, filename, s_faceGroupsCurrentVertex == 0 ? "w" : "a");
+		if (file) {
+			const Mesh *mesh = args->sourceMesh;
+			mesh->writeObjVertices(file);
+			// groups
+			uint32_t numGroups = 0;
+			for (uint32_t i = 0; i < mesh->faceCount(); i++) {
+				if (meshFaceGroups->groupAt(i) != MeshFaceGroups::kInvalid)
+					numGroups = max(numGroups, meshFaceGroups->groupAt(i) + 1);
+			}
+			for (uint32_t i = 0; i < numGroups; i++) {
+				fprintf(file, "o mesh_%03u_group_%04d\n", mesh->id(), i);
+				fprintf(file, "s off\n");
+				for (uint32_t f = 0; f < mesh->faceCount(); f++) {
+					if (meshFaceGroups->groupAt(f) == i)
+						mesh->writeObjFace(file, f, s_faceGroupsCurrentVertex);
+				}
+			}
+			fprintf(file, "o mesh_%03u_group_ignored\n", mesh->id());
+			fprintf(file, "s off\n");
+			for (uint32_t f = 0; f < mesh->faceCount(); f++) {
+				if (meshFaceGroups->groupAt(f) == MeshFaceGroups::kInvalid)
+					mesh->writeObjFace(file, f, s_faceGroupsCurrentVertex);
+			}
+			mesh->writeObjBoundaryEges(file);
+			s_faceGroupsCurrentVertex += mesh->vertexCount();
+			fclose(file);
+		}
+	}
+#endif
+	// Create a chart group for each face group.
+	args->chartGroups->resize(chartGroupCount);
+	for (uint32_t i = 0; i < chartGroupCount; i++)
+		(*args->chartGroups)[i] = XA_NEW_ARGS(MemTag::Default, ChartGroup, i, args->sourceMesh, meshFaceGroups, MeshFaceGroups::Handle(i));
+	// Extract invalid geometry via the invalid face group (MeshFaceGroups::kInvalid).
+	{
+		XA_PROFILE_START(extractInvalidMeshGeometry)
+		args->invalidMeshGeometry->extract(args->sourceMesh, meshFaceGroups);
+		XA_PROFILE_END(extractInvalidMeshGeometry)
+	}
+	// One task for each chart group - compute charts.
+	{
+		XA_PROFILE_START(chartGroupComputeChartsReal)
+		// Sort chart groups by face count.
+		Array<float> chartGroupSortData;
+		chartGroupSortData.resize(chartGroupCount);
+		for (uint32_t i = 0; i < chartGroupCount; i++)
+			chartGroupSortData[i] = (float)(*args->chartGroups)[i]->faceCount();
+		RadixSort chartGroupSort;
+		chartGroupSort.sort(chartGroupSortData);
+		// Larger chart groups are added first to reduce the chance of thread starvation.
+		ChartGroupComputeChartsTaskGroupArgs taskGroupArgs;
+		taskGroupArgs.atlas = groupArgs->atlas;
+		taskGroupArgs.options = groupArgs->options;
+		taskGroupArgs.progress = groupArgs->progress;
+		taskGroupArgs.taskScheduler = groupArgs->taskScheduler;
+		taskGroupArgs.boundaryGrid = groupArgs->boundaryGrid;
+		taskGroupArgs.chartBuffers = groupArgs->chartBuffers;
+		taskGroupArgs.piecewiseParam = groupArgs->piecewiseParam;
+		TaskGroupHandle taskGroup = groupArgs->taskScheduler->createTaskGroup(&taskGroupArgs, chartGroupCount);
+		for (uint32_t i = 0; i < chartGroupCount; i++) {
+			Task task;
+			task.userData = (*args->chartGroups)[chartGroupCount - i - 1];
+			task.func = runChartGroupComputeChartsTask;
+			groupArgs->taskScheduler->run(taskGroup, task);
+		}
+		groupArgs->taskScheduler->wait(&taskGroup);
+		XA_PROFILE_END(chartGroupComputeChartsReal)
+	}
+	XA_PROFILE_END(computeChartsThread)
+cleanup:
+	if (meshFaceGroups) {
+		meshFaceGroups->~MeshFaceGroups();
+		XA_FREE(meshFaceGroups);
+	}
+}
+
+/// An atlas is a set of chart groups.
+class Atlas
+{
+public:
+	Atlas() : m_chartsComputed(false) {}
+
+	~Atlas()
+	{
+		for (uint32_t i = 0; i < m_meshChartGroups.size(); i++) {
+			for (uint32_t j = 0; j < m_meshChartGroups[i].size(); j++) {
+				m_meshChartGroups[i][j]->~ChartGroup();
+				XA_FREE(m_meshChartGroups[i][j]);
+			}
+		}
+		m_meshChartGroups.runDtors();
+		m_invalidMeshGeometry.runDtors();
+	}
+
+	uint32_t meshCount() const { return m_meshes.size(); }
+	const InvalidMeshGeometry &invalidMeshGeometry(uint32_t meshIndex) const { return m_invalidMeshGeometry[meshIndex]; }
+	bool chartsComputed() const { return m_chartsComputed; }
+	uint32_t chartGroupCount(uint32_t mesh) const { return m_meshChartGroups[mesh].size(); }
+	const ChartGroup *chartGroupAt(uint32_t mesh, uint32_t group) const { return m_meshChartGroups[mesh][group]; }
+
+	void addMesh(const Mesh *mesh)
+	{
+		m_meshes.push_back(mesh);
+	}
+
+	bool computeCharts(TaskScheduler *taskScheduler, const ChartOptions &options, ProgressFunc progressFunc, void *progressUserData)
+	{
+		XA_PROFILE_START(computeChartsReal)
+#if XA_DEBUG_EXPORT_OBJ_PLANAR_REGIONS
+		segment::s_planarRegionsCurrentRegion = segment::s_planarRegionsCurrentVertex = 0;
+#endif
+		// Progress is per-face x 2 (1 for chart faces, 1 for parameterized chart faces).
+		const uint32_t meshCount = m_meshes.size();
+		uint32_t totalFaceCount = 0;
+		for (uint32_t i = 0; i < meshCount; i++)
+			totalFaceCount += m_meshes[i]->faceCount();
+		Progress progress(ProgressCategory::ComputeCharts, progressFunc, progressUserData, totalFaceCount * 2);
+		m_chartsComputed = false;
+		// Clear chart groups, since this function may be called multiple times.
+		if (!m_meshChartGroups.isEmpty()) {
+			for (uint32_t i = 0; i < m_meshChartGroups.size(); i++) {
+				for (uint32_t j = 0; j < m_meshChartGroups[i].size(); j++) {
+					m_meshChartGroups[i][j]->~ChartGroup();
+					XA_FREE(m_meshChartGroups[i][j]);
+				}
+				m_meshChartGroups[i].clear();
+			}
+			XA_ASSERT(m_meshChartGroups.size() == meshCount); // The number of meshes shouldn't have changed.
+		}
+		m_meshChartGroups.resize(meshCount);
+		m_meshChartGroups.runCtors();
+		m_invalidMeshGeometry.resize(meshCount);
+		m_invalidMeshGeometry.runCtors();
+		// One task per mesh.
+		Array<MeshComputeChartsTaskArgs> taskArgs;
+		taskArgs.resize(meshCount);
+		for (uint32_t i = 0; i < meshCount; i++) {
+			MeshComputeChartsTaskArgs &args = taskArgs[i];
+			args.sourceMesh = m_meshes[i];
+			args.chartGroups = &m_meshChartGroups[i];
+			args.invalidMeshGeometry = &m_invalidMeshGeometry[i];
+		}
+		// Sort meshes by indexCount.
+		Array<float> meshSortData;
+		meshSortData.resize(meshCount);
+		for (uint32_t i = 0; i < meshCount; i++)
+			meshSortData[i] = (float)m_meshes[i]->indexCount();
+		RadixSort meshSort;
+		meshSort.sort(meshSortData);
+		// Larger meshes are added first to reduce the chance of thread starvation.
+		ThreadLocal<segment::Atlas> atlas;
+		ThreadLocal<UniformGrid2> boundaryGrid; // For Quality boundary intersection.
+		ThreadLocal<ChartCtorBuffers> chartBuffers;
+		ThreadLocal<PiecewiseParam> piecewiseParam;
+		MeshComputeChartsTaskGroupArgs taskGroupArgs;
+		taskGroupArgs.atlas = &atlas;
+		taskGroupArgs.options = &options;
+		taskGroupArgs.progress = &progress;
+		taskGroupArgs.taskScheduler = taskScheduler;
+		taskGroupArgs.boundaryGrid = &boundaryGrid;
+		taskGroupArgs.chartBuffers = &chartBuffers;
+		taskGroupArgs.piecewiseParam = &piecewiseParam;
+		TaskGroupHandle taskGroup = taskScheduler->createTaskGroup(&taskGroupArgs, meshCount);
+		for (uint32_t i = 0; i < meshCount; i++) {
+			Task task;
+			task.userData = &taskArgs[meshSort.ranks()[meshCount - i - 1]];
+			task.func = runMeshComputeChartsTask;
+			taskScheduler->run(taskGroup, task);
+		}
+		taskScheduler->wait(&taskGroup);
+		XA_PROFILE_END(computeChartsReal)
+		if (progress.cancel)
+			return false;
+		m_chartsComputed = true;
+		return true;
+	}
+
+private:
+	Array<const Mesh *> m_meshes;
+	Array<InvalidMeshGeometry> m_invalidMeshGeometry; // 1 per mesh.
+	Array<Array<ChartGroup *> > m_meshChartGroups;
+	bool m_chartsComputed;
+};
+
+} // namespace param
+
+namespace pack {
+
+class AtlasImage
+{
+public:
+	AtlasImage(uint32_t width, uint32_t height) : m_width(width), m_height(height)
+	{
+		m_data.resize(m_width * m_height);
+		memset(m_data.data(), 0, sizeof(uint32_t) * m_data.size());
+	}
+
+	void resize(uint32_t width, uint32_t height)
+	{
+		Array<uint32_t> data;
+		data.resize(width * height);
+		memset(data.data(), 0, sizeof(uint32_t) * data.size());
+		for (uint32_t y = 0; y < min(m_height, height); y++)
+			memcpy(&data[y * width], &m_data[y * m_width], min(m_width, width) * sizeof(uint32_t));
+		m_width = width;
+		m_height = height;
+		data.moveTo(m_data);
+	}
+
+	void addChart(uint32_t chartIndex, const BitImage *image, const BitImage *imageBilinear, const BitImage *imagePadding, int atlas_w, int atlas_h, int offset_x, int offset_y)
+	{
+		const int w = image->width();
+		const int h = image->height();
+		for (int y = 0; y < h; y++) {
+			const int yy = y + offset_y;
+			if (yy < 0)
+				continue;
+			for (int x = 0; x < w; x++) {
+				const int xx = x + offset_x;
+				if (xx >= 0 && xx < atlas_w && yy < atlas_h) {
+					const uint32_t dataOffset = xx + yy * m_width;
+					if (image->get(x, y)) {
+						XA_DEBUG_ASSERT(m_data[dataOffset] == 0);
+						m_data[dataOffset] = chartIndex | kImageHasChartIndexBit;
+					} else if (imageBilinear && imageBilinear->get(x, y)) {
+						XA_DEBUG_ASSERT(m_data[dataOffset] == 0);
+						m_data[dataOffset] = chartIndex | kImageHasChartIndexBit | kImageIsBilinearBit;
+					} else if (imagePadding && imagePadding->get(x, y)) {
+						XA_DEBUG_ASSERT(m_data[dataOffset] == 0);
+						m_data[dataOffset] = chartIndex | kImageHasChartIndexBit | kImageIsPaddingBit;
+					}
+				}
+			}
+		}
+	}
+
+	void copyTo(uint32_t *dest, uint32_t destWidth, uint32_t destHeight, int padding) const
+	{
+		for (uint32_t y = 0; y < destHeight; y++)
+			memcpy(&dest[y * destWidth], &m_data[padding + (y + padding) * m_width], destWidth * sizeof(uint32_t));
+	}
+
+#if XA_DEBUG_EXPORT_ATLAS_IMAGES
+	void writeTga(const char *filename, uint32_t width, uint32_t height) const
+	{
+		Array<uint8_t> image;
+		image.resize(width * height * 3);
+		for (uint32_t y = 0; y < height; y++) {
+			if (y >= m_height)
+				continue;
+			for (uint32_t x = 0; x < width; x++) {
+				if (x >= m_width)
+					continue;
+				const uint32_t data = m_data[x + y * m_width];
+				uint8_t *bgr = &image[(x + y * width) * 3];
+				if (data == 0) {
+					bgr[0] = bgr[1] = bgr[2] = 0;
+					continue;
+				}
+				const uint32_t chartIndex = data & kImageChartIndexMask;
+				if (data & kImageIsPaddingBit) {
+					bgr[0] = 0;
+					bgr[1] = 0;
+					bgr[2] = 255;
+				} else if (data & kImageIsBilinearBit) {
+					bgr[0] = 0;
+					bgr[1] = 255;
+					bgr[2] = 0;
+				} else {
+					const int mix = 192;
+					srand((unsigned int)chartIndex);
+					bgr[0] = uint8_t((rand() % 255 + mix) * 0.5f);
+					bgr[1] = uint8_t((rand() % 255 + mix) * 0.5f);
+					bgr[2] = uint8_t((rand() % 255 + mix) * 0.5f);
+				}
+			}
+		}
+		WriteTga(filename, image.data(), width, height);
+	}
+#endif
+
+private:
+	uint32_t m_width, m_height;
+	Array<uint32_t> m_data;
+};
+
+struct Chart
+{
+	int32_t atlasIndex;
+	uint32_t material;
+	ConstArrayView<uint32_t> indices;
+	float parametricArea;
+	float surfaceArea;
+	ArrayView<Vector2> vertices;
+	Array<uint32_t> uniqueVertices;
+	// bounding box
+	Vector2 majorAxis, minorAxis, minCorner, maxCorner;
+	// Mesh only
+	const Array<uint32_t> *boundaryEdges;
+	// UvMeshChart only
+	Array<uint32_t> faces;
+
+	Vector2 &uniqueVertexAt(uint32_t v) { return uniqueVertices.isEmpty() ? vertices[v] : vertices[uniqueVertices[v]]; }
+	uint32_t uniqueVertexCount() const { return uniqueVertices.isEmpty() ? vertices.length : uniqueVertices.size(); }
+};
+
+struct AddChartTaskArgs
+{
+	param::Chart *paramChart;
+	Chart *chart; // out
+};
+
+static void runAddChartTask(void *groupUserData, void *taskUserData)
+{
+	XA_PROFILE_START(packChartsAddChartsThread)
+	auto boundingBox = (ThreadLocal<BoundingBox2D> *)groupUserData;
+	auto args = (AddChartTaskArgs *)taskUserData;
+	param::Chart *paramChart = args->paramChart;
+	XA_PROFILE_START(packChartsAddChartsRestoreTexcoords)
+	paramChart->restoreTexcoords();
+	XA_PROFILE_END(packChartsAddChartsRestoreTexcoords)
+	Mesh *mesh = paramChart->unifiedMesh();
+	Chart *chart = args->chart = XA_NEW(MemTag::Default, Chart);
+	chart->atlasIndex = -1;
+	chart->material = 0;
+	chart->indices = mesh->indices();
+	chart->parametricArea = mesh->computeParametricArea();
+	if (chart->parametricArea < kAreaEpsilon) {
+		// When the parametric area is too small we use a rough approximation to prevent divisions by very small numbers.
+		const Vector2 bounds = paramChart->computeParametricBounds();
+		chart->parametricArea = bounds.x * bounds.y;
+	}
+	chart->surfaceArea = mesh->computeSurfaceArea();
+	chart->vertices = mesh->texcoords();
+	chart->boundaryEdges = &mesh->boundaryEdges();
+	// Compute bounding box of chart.
+	BoundingBox2D &bb = boundingBox->get();
+	bb.clear();
+	for (uint32_t v = 0; v < chart->vertices.length; v++) {
+		if (mesh->isBoundaryVertex(v))
+			bb.appendBoundaryVertex(mesh->texcoord(v));
+	}
+	bb.compute(mesh->texcoords());
+	chart->majorAxis = bb.majorAxis;
+	chart->minorAxis = bb.minorAxis;
+	chart->minCorner = bb.minCorner;
+	chart->maxCorner = bb.maxCorner;
+	XA_PROFILE_END(packChartsAddChartsThread)
+}
+
+struct Atlas
+{
+	~Atlas()
+	{
+		for (uint32_t i = 0; i < m_atlasImages.size(); i++) {
+			m_atlasImages[i]->~AtlasImage();
+			XA_FREE(m_atlasImages[i]);
+		}
+		for (uint32_t i = 0; i < m_bitImages.size(); i++) {
+			m_bitImages[i]->~BitImage();
+			XA_FREE(m_bitImages[i]);
+		}
+		for (uint32_t i = 0; i < m_charts.size(); i++) {
+			m_charts[i]->~Chart();
+			XA_FREE(m_charts[i]);
+		}
+	}
+
+	uint32_t getWidth() const { return m_width; }
+	uint32_t getHeight() const { return m_height; }
+	uint32_t getNumAtlases() const { return m_bitImages.size(); }
+	float getTexelsPerUnit() const { return m_texelsPerUnit; }
+	const Chart *getChart(uint32_t index) const { return m_charts[index]; }
+	uint32_t getChartCount() const { return m_charts.size(); }
+	const Array<AtlasImage *> &getImages() const { return m_atlasImages; }
+	float getUtilization(uint32_t atlas) const { return m_utilization[atlas]; }
+
+	void addCharts(TaskScheduler *taskScheduler, param::Atlas *paramAtlas)
+	{
+		// Count charts.
+		uint32_t chartCount = 0;
+		for (uint32_t i = 0; i < paramAtlas->meshCount(); i++) {
+			const uint32_t chartGroupsCount = paramAtlas->chartGroupCount(i);
+			for (uint32_t j = 0; j < chartGroupsCount; j++) {
+				const param::ChartGroup *chartGroup = paramAtlas->chartGroupAt(i, j);
+				chartCount += chartGroup->chartCount();
+			}
+		}
+		if (chartCount == 0)
+			return;
+		// Run one task per chart.
+		ThreadLocal<BoundingBox2D> boundingBox;
+		TaskGroupHandle taskGroup = taskScheduler->createTaskGroup(&boundingBox, chartCount);
+		Array<AddChartTaskArgs> taskArgs;
+		taskArgs.resize(chartCount);
+		uint32_t chartIndex = 0;
+		for (uint32_t i = 0; i < paramAtlas->meshCount(); i++) {
+			const uint32_t chartGroupsCount = paramAtlas->chartGroupCount(i);
+			for (uint32_t j = 0; j < chartGroupsCount; j++) {
+				const param::ChartGroup *chartGroup = paramAtlas->chartGroupAt(i, j);
+				const uint32_t count = chartGroup->chartCount();
+				for (uint32_t k = 0; k < count; k++) {
+					AddChartTaskArgs &args = taskArgs[chartIndex];
+					args.paramChart = chartGroup->chartAt(k);
+					Task task;
+					task.userData = &taskArgs[chartIndex];
+					task.func = runAddChartTask;
+					taskScheduler->run(taskGroup, task);
+					chartIndex++;
+				}
+			}
+		}
+		taskScheduler->wait(&taskGroup);
+		// Get task output.
+		m_charts.resize(chartCount);
+		for (uint32_t i = 0; i < chartCount; i++)
+			m_charts[i] = taskArgs[i].chart;
+	}
+
+	void addUvMeshCharts(UvMeshInstance *mesh)
+	{
+		// Copy texcoords from mesh.
+		mesh->texcoords.resize(mesh->mesh->texcoords.size());
+		memcpy(mesh->texcoords.data(), mesh->mesh->texcoords.data(), mesh->texcoords.size() * sizeof(Vector2));
+		BitArray vertexUsed(mesh->texcoords.size());
+		BoundingBox2D boundingBox;
+		for (uint32_t c = 0; c < mesh->mesh->charts.size(); c++) {
+			UvMeshChart *uvChart = mesh->mesh->charts[c];
+			Chart *chart = XA_NEW(MemTag::Default, Chart);
+			chart->atlasIndex = -1;
+			chart->material = uvChart->material;
+			chart->indices = uvChart->indices;
+			chart->vertices = mesh->texcoords;
+			chart->boundaryEdges = nullptr;
+			chart->faces.resize(uvChart->faces.size());
+			memcpy(chart->faces.data(), uvChart->faces.data(), sizeof(uint32_t) * uvChart->faces.size());
+			// Find unique vertices.
+			vertexUsed.zeroOutMemory();
+			for (uint32_t i = 0; i < chart->indices.length; i++) {
+				const uint32_t vertex = chart->indices[i];
+				if (!vertexUsed.get(vertex)) {
+					vertexUsed.set(vertex);
+					chart->uniqueVertices.push_back(vertex);
+				}
+			}
+			// Compute parametric and surface areas.
+			chart->parametricArea = 0.0f;
+			for (uint32_t f = 0; f < chart->indices.length / 3; f++) {
+				const Vector2 &v1 = chart->vertices[chart->indices[f * 3 + 0]];
+				const Vector2 &v2 = chart->vertices[chart->indices[f * 3 + 1]];
+				const Vector2 &v3 = chart->vertices[chart->indices[f * 3 + 2]];
+				chart->parametricArea += fabsf(triangleArea(v1, v2, v3));
+			}
+			chart->parametricArea *= 0.5f;
+			if (chart->parametricArea < kAreaEpsilon) {
+				// When the parametric area is too small we use a rough approximation to prevent divisions by very small numbers.
+				Vector2 minCorner(FLT_MAX, FLT_MAX);
+				Vector2 maxCorner(-FLT_MAX, -FLT_MAX);
+				for (uint32_t v = 0; v < chart->uniqueVertexCount(); v++) {
+					minCorner = min(minCorner, chart->uniqueVertexAt(v));
+					maxCorner = max(maxCorner, chart->uniqueVertexAt(v));
+				}
+				const Vector2 bounds = (maxCorner - minCorner) * 0.5f;
+				chart->parametricArea = bounds.x * bounds.y;
+			}
+			XA_DEBUG_ASSERT(isFinite(chart->parametricArea));
+			XA_DEBUG_ASSERT(!isNan(chart->parametricArea));
+			chart->surfaceArea = chart->parametricArea; // Identical for UV meshes.
+			// Compute bounding box of chart.
+			// Using all unique vertices for simplicity, can compute real boundaries if this is too slow.
+			boundingBox.clear();
+			for (uint32_t v = 0; v < chart->uniqueVertexCount(); v++)
+				boundingBox.appendBoundaryVertex(chart->uniqueVertexAt(v));
+			boundingBox.compute();
+			chart->majorAxis = boundingBox.majorAxis;
+			chart->minorAxis = boundingBox.minorAxis;
+			chart->minCorner = boundingBox.minCorner;
+			chart->maxCorner = boundingBox.maxCorner;
+			m_charts.push_back(chart);
+		}
+	}
+
+	// Pack charts in the smallest possible rectangle.
+	bool packCharts(const PackOptions &options, ProgressFunc progressFunc, void *progressUserData)
+	{
+		if (progressFunc) {
+			if (!progressFunc(ProgressCategory::PackCharts, 0, progressUserData))
+				return false;
+		}
+		const uint32_t chartCount = m_charts.size();
+		XA_PRINT("Packing %u charts\n", chartCount);
+		if (chartCount == 0) {
+			if (progressFunc) {
+				if (!progressFunc(ProgressCategory::PackCharts, 100, progressUserData))
+					return false;
+			}
+			return true;
+		}
+		// Estimate resolution and/or texels per unit if not specified.
+		m_texelsPerUnit = options.texelsPerUnit;
+		uint32_t resolution = options.resolution > 0 ? options.resolution + options.padding * 2 : 0;
+		const uint32_t maxResolution = m_texelsPerUnit > 0.0f ? resolution : 0;
+		if (resolution <= 0 || m_texelsPerUnit <= 0) {
+			if (resolution <= 0 && m_texelsPerUnit <= 0)
+				resolution = 1024;
+			float meshArea = 0;
+			for (uint32_t c = 0; c < chartCount; c++)
+				meshArea += m_charts[c]->surfaceArea;
+			if (resolution <= 0) {
+				// Estimate resolution based on the mesh surface area and given texel scale.
+				const float texelCount = max(1.0f, meshArea * square(m_texelsPerUnit) / 0.75f); // Assume 75% utilization.
+				resolution = max(1u, nextPowerOfTwo(uint32_t(sqrtf(texelCount))));
+			}
+			if (m_texelsPerUnit <= 0) {
+				// Estimate a suitable texelsPerUnit to fit the given resolution.
+				const float texelCount = max(1.0f, meshArea / 0.75f); // Assume 75% utilization.
+				m_texelsPerUnit = sqrtf((resolution * resolution) / texelCount);
+				XA_PRINT("   Estimating texelsPerUnit as %g\n", m_texelsPerUnit);
+			}
+		}
+		Array<float> chartOrderArray;
+		chartOrderArray.resize(chartCount);
+		Array<Vector2> chartExtents;
+		chartExtents.resize(chartCount);
+		float minChartPerimeter = FLT_MAX, maxChartPerimeter = 0.0f;
+		for (uint32_t c = 0; c < chartCount; c++) {
+			Chart *chart = m_charts[c];
+			// Compute chart scale
+			float scale = 1.0f;
+			if (chart->parametricArea != 0.0f) {
+				scale = sqrtf(chart->surfaceArea / chart->parametricArea) * m_texelsPerUnit;
+				XA_ASSERT(isFinite(scale));
+			}
+			// Translate, rotate and scale vertices. Compute extents.
+			Vector2 minCorner(FLT_MAX, FLT_MAX);
+			if (!options.rotateChartsToAxis) {
+				for (uint32_t i = 0; i < chart->uniqueVertexCount(); i++)
+					minCorner = min(minCorner, chart->uniqueVertexAt(i));
+			}
+			Vector2 extents(0.0f);
+			for (uint32_t i = 0; i < chart->uniqueVertexCount(); i++) {
+				Vector2 &texcoord = chart->uniqueVertexAt(i);
+				if (options.rotateChartsToAxis) {
+					const float x = dot(texcoord, chart->majorAxis);
+					const float y = dot(texcoord, chart->minorAxis);
+					texcoord.x = x;
+					texcoord.y = y;
+					texcoord -= chart->minCorner;
+				} else {
+					texcoord -= minCorner;
+				}
+				texcoord *= scale;
+				XA_DEBUG_ASSERT(texcoord.x >= 0.0f && texcoord.y >= 0.0f);
+				XA_DEBUG_ASSERT(isFinite(texcoord.x) && isFinite(texcoord.y));
+				extents = max(extents, texcoord);
+			}
+			XA_DEBUG_ASSERT(extents.x >= 0 && extents.y >= 0);
+			// Scale the charts to use the entire texel area available. So, if the width is 0.1 we could scale it to 1 without increasing the lightmap usage and making a better use of it. In many cases this also improves the look of the seams, since vertices on the chart boundaries have more chances of being aligned with the texel centers.
+			if (extents.x > 0.0f && extents.y > 0.0f) {
+				// Block align: align all chart extents to 4x4 blocks, but taking padding and texel center offset into account.
+				const int blockAlignSizeOffset = options.padding * 2 + 1;
+				int width = ftoi_ceil(extents.x);
+				if (options.blockAlign)
+					width = align(width + blockAlignSizeOffset, 4) - blockAlignSizeOffset;
+				int height = ftoi_ceil(extents.y);
+				if (options.blockAlign)
+					height = align(height + blockAlignSizeOffset, 4) - blockAlignSizeOffset;
+				for (uint32_t v = 0; v < chart->uniqueVertexCount(); v++) {
+					Vector2 &texcoord = chart->uniqueVertexAt(v);
+					texcoord.x = texcoord.x / extents.x * (float)width;
+					texcoord.y = texcoord.y / extents.y * (float)height;
+				}
+				extents.x = (float)width;
+				extents.y = (float)height;
+			}
+			// Limit chart size, either to PackOptions::maxChartSize or maxResolution (if set), whichever is smaller.
+			// If limiting chart size to maxResolution, print a warning, since that may not be desirable to the user.
+			uint32_t maxChartSize = options.maxChartSize;
+			bool warnChartResized = false;
+			if (maxResolution > 0 && (maxChartSize == 0 || maxResolution < maxChartSize)) {
+				maxChartSize = maxResolution - options.padding * 2; // Don't include padding.
+				warnChartResized = true;
+			}
+			if (maxChartSize > 0) {
+				const float realMaxChartSize = (float)maxChartSize - 1.0f; // Aligning to texel centers increases texel footprint by 1.
+				if (extents.x > realMaxChartSize || extents.y > realMaxChartSize) {
+					if (warnChartResized)
+						XA_PRINT("   Resizing chart %u from %gx%g to %ux%u to fit atlas\n", c, extents.x, extents.y, maxChartSize, maxChartSize);
+					scale = realMaxChartSize / max(extents.x, extents.y);
+					for (uint32_t i = 0; i < chart->uniqueVertexCount(); i++) {
+						Vector2 &texcoord = chart->uniqueVertexAt(i);
+						texcoord = min(texcoord * scale, Vector2(realMaxChartSize));
+					}
+				}
+			}
+			// Align to texel centers and add padding offset.
+			extents.x = extents.y = 0.0f;
+			for (uint32_t v = 0; v < chart->uniqueVertexCount(); v++) {
+				Vector2 &texcoord = chart->uniqueVertexAt(v);
+				texcoord.x += 0.5f + options.padding;
+				texcoord.y += 0.5f + options.padding;
+				extents = max(extents, texcoord);
+			}
+			if (extents.x > resolution || extents.y > resolution)
+				XA_PRINT("   Chart %u extents are large (%gx%g)\n", c, extents.x, extents.y);
+			chartExtents[c] = extents;
+			chartOrderArray[c] = extents.x + extents.y; // Use perimeter for chart sort key.
+			minChartPerimeter = min(minChartPerimeter, chartOrderArray[c]);
+			maxChartPerimeter = max(maxChartPerimeter, chartOrderArray[c]);
+		}
+		// Sort charts by perimeter.
+		m_radix.sort(chartOrderArray);
+		const uint32_t *ranks = m_radix.ranks();
+		// Divide chart perimeter range into buckets.
+		const float chartPerimeterBucketSize = (maxChartPerimeter - minChartPerimeter) / 16.0f;
+		uint32_t currentChartBucket = 0;
+		Array<Vector2i> chartStartPositions; // per atlas
+		chartStartPositions.push_back(Vector2i(0, 0));
+		// Pack sorted charts.
+#if XA_DEBUG_EXPORT_ATLAS_IMAGES
+		const bool createImage = true;
+#else
+		const bool createImage = options.createImage;
+#endif
+		// chartImage: result from conservative rasterization
+		// chartImageBilinear: chartImage plus any texels that would be sampled by bilinear filtering.
+		// chartImagePadding: either chartImage or chartImageBilinear depending on options, with a dilate filter applied options.padding times.
+		// Rotated versions swap x and y.
+		BitImage chartImage, chartImageBilinear, chartImagePadding;
+		BitImage chartImageRotated, chartImageBilinearRotated, chartImagePaddingRotated;
+		UniformGrid2 boundaryEdgeGrid;
+		Array<Vector2i> atlasSizes;
+		atlasSizes.push_back(Vector2i(0, 0));
+		int progress = 0;
+		for (uint32_t i = 0; i < chartCount; i++) {
+			uint32_t c = ranks[chartCount - i - 1]; // largest chart first
+			Chart *chart = m_charts[c];
+			// @@ Add special cases for dot and line charts. @@ Lightmap rasterizer also needs to handle these special cases.
+			// @@ We could also have a special case for chart quads. If the quad surface <= 4 texels, align vertices with texel centers and do not add padding. May be very useful for foliage.
+			// @@ In general we could reduce the padding of all charts by one texel by using a rasterizer that takes into account the 2-texel footprint of the tent bilinear filter. For example,
+			// if we have a chart that is less than 1 texel wide currently we add one texel to the left and one texel to the right creating a 3-texel-wide bitImage. However, if we know that the
+			// chart is only 1 texel wide we could align it so that it only touches the footprint of two texels:
+			//      |   |      <- Touches texels 0, 1 and 2.
+			//    |   |        <- Only touches texels 0 and 1.
+			// \   \ / \ /   /
+			//  \   X   X   /
+			//   \ / \ / \ /
+			//    V   V   V
+			//    0   1   2
+			XA_PROFILE_START(packChartsRasterize)
+			// Resize and clear (discard = true) chart images.
+			// Leave room for padding at extents.
+			chartImage.resize(ftoi_ceil(chartExtents[c].x) + options.padding, ftoi_ceil(chartExtents[c].y) + options.padding, true);
+			if (options.rotateCharts)
+				chartImageRotated.resize(chartImage.height(), chartImage.width(), true);
+			if (options.bilinear) {
+				chartImageBilinear.resize(chartImage.width(), chartImage.height(), true);
+				if (options.rotateCharts)
+					chartImageBilinearRotated.resize(chartImage.height(), chartImage.width(), true);
+			}
+			// Rasterize chart faces.
+			const uint32_t faceCount = chart->indices.length / 3;
+			for (uint32_t f = 0; f < faceCount; f++) {
+				Vector2 vertices[3];
+				for (uint32_t v = 0; v < 3; v++)
+					vertices[v] = chart->vertices[chart->indices[f * 3 + v]];
+				DrawTriangleCallbackArgs args;
+				args.chartBitImage = &chartImage;
+				args.chartBitImageRotated = options.rotateCharts ? &chartImageRotated : nullptr;
+				raster::drawTriangle(Vector2((float)chartImage.width(), (float)chartImage.height()), vertices, drawTriangleCallback, &args);
+			}
+			// Expand chart by pixels sampled by bilinear interpolation.
+			if (options.bilinear)
+				bilinearExpand(chart, &chartImage, &chartImageBilinear, options.rotateCharts ? &chartImageBilinearRotated : nullptr, boundaryEdgeGrid);
+			// Expand chart by padding pixels (dilation).
+			if (options.padding > 0) {
+				// Copy into the same BitImage instances for every chart to avoid reallocating BitImage buffers (largest chart is packed first).
+				XA_PROFILE_START(packChartsDilate)
+				if (options.bilinear)
+					chartImageBilinear.copyTo(chartImagePadding);
+				else
+					chartImage.copyTo(chartImagePadding);
+				chartImagePadding.dilate(options.padding);
+				if (options.rotateCharts) {
+					if (options.bilinear)
+						chartImageBilinearRotated.copyTo(chartImagePaddingRotated);
+					else
+						chartImageRotated.copyTo(chartImagePaddingRotated);
+					chartImagePaddingRotated.dilate(options.padding);
+				}
+				XA_PROFILE_END(packChartsDilate)
+			}
+			XA_PROFILE_END(packChartsRasterize)
+			// Update brute force bucketing.
+			if (options.bruteForce) {
+				if (chartOrderArray[c] > minChartPerimeter && chartOrderArray[c] <= maxChartPerimeter - (chartPerimeterBucketSize * (currentChartBucket + 1))) {
+					// Moved to a smaller bucket, reset start location.
+					for (uint32_t j = 0; j < chartStartPositions.size(); j++)
+						chartStartPositions[j] = Vector2i(0, 0);
+					currentChartBucket++;
+				}
+			}
+			// Find a location to place the chart in the atlas.
+			BitImage *chartImageToPack, *chartImageToPackRotated;
+			if (options.padding > 0) {
+				chartImageToPack = &chartImagePadding;
+				chartImageToPackRotated = &chartImagePaddingRotated;
+			} else if (options.bilinear) {
+				chartImageToPack = &chartImageBilinear;
+				chartImageToPackRotated = &chartImageBilinearRotated;
+			} else {
+				chartImageToPack = &chartImage;
+				chartImageToPackRotated = &chartImageRotated;
+			}
+			uint32_t currentAtlas = 0;
+			int best_x = 0, best_y = 0;
+			int best_cw = 0, best_ch = 0;
+			int best_r = 0;
+			for (;;)
+			{
+#if XA_DEBUG
+				bool firstChartInBitImage = false;
+#endif
+				if (currentAtlas + 1 > m_bitImages.size()) {
+					// Chart doesn't fit in the current bitImage, create a new one.
+					BitImage *bi = XA_NEW_ARGS(MemTag::Default, BitImage, resolution, resolution);
+					m_bitImages.push_back(bi);
+					atlasSizes.push_back(Vector2i(0, 0));
+#if XA_DEBUG
+					firstChartInBitImage = true;
+#endif
+					if (createImage)
+						m_atlasImages.push_back(XA_NEW_ARGS(MemTag::Default, AtlasImage, resolution, resolution));
+					// Start positions are per-atlas, so create a new one of those too.
+					chartStartPositions.push_back(Vector2i(0, 0));
+				}
+				XA_PROFILE_START(packChartsFindLocation)
+				const bool foundLocation = findChartLocation(options, chartStartPositions[currentAtlas], m_bitImages[currentAtlas], chartImageToPack, chartImageToPackRotated, atlasSizes[currentAtlas].x, atlasSizes[currentAtlas].y, &best_x, &best_y, &best_cw, &best_ch, &best_r, maxResolution);
+				XA_PROFILE_END(packChartsFindLocation)
+				XA_DEBUG_ASSERT(!(firstChartInBitImage && !foundLocation)); // Chart doesn't fit in an empty, newly allocated bitImage. Shouldn't happen, since charts are resized if they are too big to fit in the atlas.
+				if (maxResolution == 0) {
+					XA_DEBUG_ASSERT(foundLocation); // The atlas isn't limited to a fixed resolution, a chart location should be found on the first attempt.
+					break;
+				}
+				if (foundLocation)
+					break;
+				// Chart doesn't fit in the current bitImage, try the next one.
+				currentAtlas++;
+			}
+			// Update brute force start location.
+			if (options.bruteForce) {
+				// Reset start location if the chart expanded the atlas.
+				if (best_x + best_cw > atlasSizes[currentAtlas].x || best_y + best_ch > atlasSizes[currentAtlas].y) {
+					for (uint32_t j = 0; j < chartStartPositions.size(); j++)
+						chartStartPositions[j] = Vector2i(0, 0);
+				}
+				else {
+					chartStartPositions[currentAtlas] = Vector2i(best_x, best_y);
+				}
+			}
+			// Update parametric extents.
+			atlasSizes[currentAtlas].x = max(atlasSizes[currentAtlas].x, best_x + best_cw);
+			atlasSizes[currentAtlas].y = max(atlasSizes[currentAtlas].y, best_y + best_ch);
+			// Resize bitImage if necessary.
+			// If maxResolution > 0, the bitImage is always set to maxResolutionIncludingPadding on creation and doesn't need to be dynamically resized.
+			if (maxResolution == 0) {
+				const uint32_t w = (uint32_t)atlasSizes[currentAtlas].x;
+				const uint32_t h = (uint32_t)atlasSizes[currentAtlas].y;
+				if (w > m_bitImages[0]->width() || h > m_bitImages[0]->height()) {
+					m_bitImages[0]->resize(nextPowerOfTwo(w), nextPowerOfTwo(h), false);
+					if (createImage)
+						m_atlasImages[0]->resize(m_bitImages[0]->width(), m_bitImages[0]->height());
+				}
+			} else {
+				XA_DEBUG_ASSERT(atlasSizes[currentAtlas].x <= (int)maxResolution);
+				XA_DEBUG_ASSERT(atlasSizes[currentAtlas].y <= (int)maxResolution);
+			}
+			XA_PROFILE_START(packChartsBlit)
+			addChart(m_bitImages[currentAtlas], chartImageToPack, chartImageToPackRotated, atlasSizes[currentAtlas].x, atlasSizes[currentAtlas].y, best_x, best_y, best_r);
+			XA_PROFILE_END(packChartsBlit)
+			if (createImage) {
+				if (best_r == 0) {
+					m_atlasImages[currentAtlas]->addChart(c, &chartImage, options.bilinear ? &chartImageBilinear : nullptr, options.padding > 0 ? &chartImagePadding : nullptr, atlasSizes[currentAtlas].x, atlasSizes[currentAtlas].y, best_x, best_y);
+				} else {
+					m_atlasImages[currentAtlas]->addChart(c, &chartImageRotated, options.bilinear ? &chartImageBilinearRotated : nullptr, options.padding > 0 ? &chartImagePaddingRotated : nullptr, atlasSizes[currentAtlas].x, atlasSizes[currentAtlas].y, best_x, best_y);
+				}
+#if XA_DEBUG_EXPORT_ATLAS_IMAGES && XA_DEBUG_EXPORT_ATLAS_IMAGES_PER_CHART
+				for (uint32_t j = 0; j < m_atlasImages.size(); j++) {
+					char filename[256];
+					XA_SPRINTF(filename, sizeof(filename), "debug_atlas_image%02u_chart%04u.tga", j, i);
+					m_atlasImages[j]->writeTga(filename, (uint32_t)atlasSizes[j].x, (uint32_t)atlasSizes[j].y);
+				}
+#endif
+			}
+			chart->atlasIndex = (int32_t)currentAtlas;
+			// Modify texture coordinates:
+			//  - rotate if the chart should be rotated
+			//  - translate to chart location
+			//  - translate to remove padding from top and left atlas edges (unless block aligned)
+			for (uint32_t v = 0; v < chart->uniqueVertexCount(); v++) {
+				Vector2 &texcoord = chart->uniqueVertexAt(v);
+				Vector2 t = texcoord;
+				if (best_r) {
+					XA_DEBUG_ASSERT(options.rotateCharts);
+					swap(t.x, t.y);
+				}
+				texcoord.x = best_x + t.x;
+				texcoord.y = best_y + t.y;
+				texcoord.x -= (float)options.padding;
+				texcoord.y -= (float)options.padding;
+				XA_ASSERT(texcoord.x >= 0 && texcoord.y >= 0);
+				XA_ASSERT(isFinite(texcoord.x) && isFinite(texcoord.y));
+			}
+			if (progressFunc) {
+				const int newProgress = int((i + 1) / (float)chartCount * 100.0f);
+				if (newProgress != progress) {
+					progress = newProgress;
+					if (!progressFunc(ProgressCategory::PackCharts, progress, progressUserData))
+						return false;
+				}
+			}
+		}
+		// Remove padding from outer edges.
+		if (maxResolution == 0) {
+			m_width = max(0, atlasSizes[0].x - (int)options.padding * 2);
+			m_height = max(0, atlasSizes[0].y - (int)options.padding * 2);
+		} else {
+			m_width = m_height = maxResolution - (int)options.padding * 2;
+		}
+		XA_PRINT("   %dx%d resolution\n", m_width, m_height);
+		m_utilization.resize(m_bitImages.size());
+		for (uint32_t i = 0; i < m_utilization.size(); i++) {
+			if (m_width == 0 || m_height == 0)
+				m_utilization[i] = 0.0f;
+			else {
+				uint32_t count = 0;
+				for (uint32_t y = 0; y < m_height; y++) {
+					for (uint32_t x = 0; x < m_width; x++)
+						count += m_bitImages[i]->get(x, y);
+				}
+				m_utilization[i] = float(count) / (m_width * m_height);
+			}
+			if (m_utilization.size() > 1) {
+				XA_PRINT("   %u: %f%% utilization\n", i, m_utilization[i] * 100.0f);
+			}
+			else {
+				XA_PRINT("   %f%% utilization\n", m_utilization[i] * 100.0f);
+			}
+		}
+#if XA_DEBUG_EXPORT_ATLAS_IMAGES
+		for (uint32_t i = 0; i < m_atlasImages.size(); i++) {
+			char filename[256];
+			XA_SPRINTF(filename, sizeof(filename), "debug_atlas_image%02u.tga", i);
+			m_atlasImages[i]->writeTga(filename, m_width, m_height);
+		}
+#endif
+		if (progressFunc && progress != 100) {
+			if (!progressFunc(ProgressCategory::PackCharts, 100, progressUserData))
+				return false;
+		}
+		return true;
+	}
+
+private:
+	bool findChartLocation(const PackOptions &options, const Vector2i &startPosition, const BitImage *atlasBitImage, const BitImage *chartBitImage, const BitImage *chartBitImageRotated, int w, int h, int *best_x, int *best_y, int *best_w, int *best_h, int *best_r, uint32_t maxResolution)
+	{
+		const int attempts = 4096;
+		if (options.bruteForce || attempts >= w * h)
+			return findChartLocation_bruteForce(options, startPosition, atlasBitImage, chartBitImage, chartBitImageRotated, w, h, best_x, best_y, best_w, best_h, best_r, maxResolution);
+		return findChartLocation_random(options, atlasBitImage, chartBitImage, chartBitImageRotated, w, h, best_x, best_y, best_w, best_h, best_r, attempts, maxResolution);
+	}
+
+	bool findChartLocation_bruteForce(const PackOptions &options, const Vector2i &startPosition, const BitImage *atlasBitImage, const BitImage *chartBitImage, const BitImage *chartBitImageRotated, int w, int h, int *best_x, int *best_y, int *best_w, int *best_h, int *best_r, uint32_t maxResolution)
+	{
+		const int stepSize = options.blockAlign ? 4 : 1;
+		int best_metric = INT_MAX;
+		// Try two different orientations.
+		for (int r = 0; r < 2; r++) {
+			int cw = chartBitImage->width();
+			int ch = chartBitImage->height();
+			if (r == 1) {
+				if (options.rotateCharts)
+					swap(cw, ch);
+				else
+					break;
+			}
+			for (int y = startPosition.y; y <= h + stepSize; y += stepSize) {
+				if (maxResolution > 0 && y > (int)maxResolution - ch)
+					break;
+				for (int x = (y == startPosition.y ? startPosition.x : 0); x <= w + stepSize; x += stepSize) {
+					if (maxResolution > 0 && x > (int)maxResolution - cw)
+						break;
+					// Early out if metric is not better.
+					const int extentX = max(w, x + cw), extentY = max(h, y + ch);
+					const int area = extentX * extentY;
+					const int extents = max(extentX, extentY);
+					const int metric = extents * extents + area;
+					if (metric > best_metric)
+						continue;
+					// If metric is the same, pick the one closest to the origin.
+					if (metric == best_metric && max(x, y) >= max(*best_x, *best_y))
+						continue;
+					if (!atlasBitImage->canBlit(r == 1 ? *chartBitImageRotated : *chartBitImage, x, y))
+						continue;
+					best_metric = metric;
+					*best_x = x;
+					*best_y = y;
+					*best_w = cw;
+					*best_h = ch;
+					*best_r = r;
+					if (area == w * h)
+						return true; // Chart is completely inside, do not look at any other location.
+				}
+			}
+		}
+		return best_metric != INT_MAX;
+	}
+
+	bool findChartLocation_random(const PackOptions &options, const BitImage *atlasBitImage, const BitImage *chartBitImage, const BitImage *chartBitImageRotated, int w, int h, int *best_x, int *best_y, int *best_w, int *best_h, int *best_r, int attempts, uint32_t maxResolution)
+	{
+		bool result = false;
+		const int BLOCK_SIZE = 4;
+		int best_metric = INT_MAX;
+		for (int i = 0; i < attempts; i++) {
+			int cw = chartBitImage->width();
+			int ch = chartBitImage->height();
+			int r = options.rotateCharts ? m_rand.getRange(1) : 0;
+			if (r == 1)
+				swap(cw, ch);
+			// + 1 to extend atlas in case atlas full. We may want to use a higher number to increase probability of extending atlas.
+			int xRange = w + 1;
+			int yRange = h + 1;
+			// Clamp to max resolution.
+			if (maxResolution > 0) {
+				xRange = min(xRange, (int)maxResolution - cw);
+				yRange = min(yRange, (int)maxResolution - ch);
+			}
+			int x = m_rand.getRange(xRange);
+			int y = m_rand.getRange(yRange);
+			if (options.blockAlign) {
+				x = align(x, BLOCK_SIZE);
+				y = align(y, BLOCK_SIZE);
+				if (maxResolution > 0 && (x > (int)maxResolution - cw || y > (int)maxResolution - ch))
+					continue; // Block alignment pushed the chart outside the atlas.
+			}
+			// Early out.
+			int area = max(w, x + cw) * max(h, y + ch);
+			//int perimeter = max(w, x+cw) + max(h, y+ch);
+			int extents = max(max(w, x + cw), max(h, y + ch));
+			int metric = extents * extents + area;
+			if (metric > best_metric) {
+				continue;
+			}
+			if (metric == best_metric && min(x, y) > min(*best_x, *best_y)) {
+				// If metric is the same, pick the one closest to the origin.
+				continue;
+			}
+			if (atlasBitImage->canBlit(r == 1 ? *chartBitImageRotated : *chartBitImage, x, y)) {
+				result = true;
+				best_metric = metric;
+				*best_x = x;
+				*best_y = y;
+				*best_w = cw;
+				*best_h = ch;
+				*best_r = options.rotateCharts ? r : 0;
+				if (area == w * h) {
+					// Chart is completely inside, do not look at any other location.
+					break;
+				}
+			}
+		}
+		return result;
+	}
+
+	void addChart(BitImage *atlasBitImage, const BitImage *chartBitImage, const BitImage *chartBitImageRotated, int atlas_w, int atlas_h, int offset_x, int offset_y, int r)
+	{
+		XA_DEBUG_ASSERT(r == 0 || r == 1);
+		const BitImage *image = r == 0 ? chartBitImage : chartBitImageRotated;
+		const int w = image->width();
+		const int h = image->height();
+		for (int y = 0; y < h; y++) {
+			int yy = y + offset_y;
+			if (yy >= 0) {
+				for (int x = 0; x < w; x++) {
+					int xx = x + offset_x;
+					if (xx >= 0) {
+						if (image->get(x, y)) {
+							if (xx < atlas_w && yy < atlas_h) {
+								XA_DEBUG_ASSERT(atlasBitImage->get(xx, yy) == false);
+								atlasBitImage->set(xx, yy);
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+
+	void bilinearExpand(const Chart *chart, BitImage *source, BitImage *dest, BitImage *destRotated, UniformGrid2 &boundaryEdgeGrid) const
+	{
+		boundaryEdgeGrid.reset(chart->vertices, chart->indices);
+		if (chart->boundaryEdges) {
+			const uint32_t edgeCount = chart->boundaryEdges->size();
+			for (uint32_t i = 0; i < edgeCount; i++)
+				boundaryEdgeGrid.append((*chart->boundaryEdges)[i]);
+		} else {
+			for (uint32_t i = 0; i < chart->indices.length; i++)
+				boundaryEdgeGrid.append(i);
+		}
+		const int xOffsets[] = { -1, 0, 1, -1, 1, -1, 0, 1 };
+		const int yOffsets[] = { -1, -1, -1, 0, 0, 1, 1, 1 };
+		for (uint32_t y = 0; y < source->height(); y++) {
+			for (uint32_t x = 0; x < source->width(); x++) {
+				// Copy pixels from source.
+				if (source->get(x, y))
+					goto setPixel;
+				// Empty pixel. If none of of the surrounding pixels are set, this pixel can't be sampled by bilinear interpolation.
+				{
+					uint32_t s = 0;
+					for (; s < 8; s++) {
+						const int sx = (int)x + xOffsets[s];
+						const int sy = (int)y + yOffsets[s];
+						if (sx < 0 || sy < 0 || sx >= (int)source->width() || sy >= (int)source->height())
+							continue;
+						if (source->get((uint32_t)sx, (uint32_t)sy))
+							break;
+					}
+					if (s == 8)
+						continue;
+				}
+				{
+					// If a 2x2 square centered on the pixels centroid intersects the triangle, this pixel will be sampled by bilinear interpolation.
+					// See "Precomputed Global Illumination in Frostbite (GDC 2018)" page 95
+					const Vector2 centroid((float)x + 0.5f, (float)y + 0.5f);
+					const Vector2 squareVertices[4] = {
+						Vector2(centroid.x - 1.0f, centroid.y - 1.0f),
+						Vector2(centroid.x + 1.0f, centroid.y - 1.0f),
+						Vector2(centroid.x + 1.0f, centroid.y + 1.0f),
+						Vector2(centroid.x - 1.0f, centroid.y + 1.0f)
+					};
+					for (uint32_t j = 0; j < 4; j++) {
+						if (boundaryEdgeGrid.intersect(squareVertices[j], squareVertices[(j + 1) % 4], 0.0f))
+							goto setPixel;
+					}
+				}
+				continue;
+			setPixel:
+				dest->set(x, y);
+				if (destRotated)
+					destRotated->set(y, x);
+			}
+		}
+	}
+
+	struct DrawTriangleCallbackArgs
+	{
+		BitImage *chartBitImage, *chartBitImageRotated;
+	};
+
+	static bool drawTriangleCallback(void *param, int x, int y)
+	{
+		auto args = (DrawTriangleCallbackArgs *)param;
+		args->chartBitImage->set(x, y);
+		if (args->chartBitImageRotated)
+			args->chartBitImageRotated->set(y, x);
+		return true;
+	}
+
+	Array<AtlasImage *> m_atlasImages;
+	Array<float> m_utilization;
+	Array<BitImage *> m_bitImages;
+	Array<Chart *> m_charts;
+	RadixSort m_radix;
+	uint32_t m_width = 0;
+	uint32_t m_height = 0;
+	float m_texelsPerUnit = 0.0f;
+	KISSRng m_rand;
+};
+
+} // namespace pack
+} // namespace internal
+
+// Used to map triangulated polygons back to polygons.
+struct MeshPolygonMapping
+{
+	internal::Array<uint8_t> faceVertexCount; // Copied from MeshDecl::faceVertexCount.
+	internal::Array<uint32_t> triangleToPolygonMap; // Triangle index (mesh face index) to polygon index.
+	internal::Array<uint32_t> triangleToPolygonIndicesMap; // Triangle indices to polygon indices.
+};
+
+struct Context
+{
+	Atlas atlas;
+	internal::Progress *addMeshProgress = nullptr;
+	internal::TaskGroupHandle addMeshTaskGroup;
+	internal::param::Atlas paramAtlas;
+	ProgressFunc progressFunc = nullptr;
+	void *progressUserData = nullptr;
+	internal::TaskScheduler *taskScheduler;
+	internal::Array<internal::Mesh *> meshes;
+	internal::Array<MeshPolygonMapping *> meshPolygonMappings;
+	internal::Array<internal::UvMesh *> uvMeshes;
+	internal::Array<internal::UvMeshInstance *> uvMeshInstances;
+	bool uvMeshChartsComputed = false;
+};
+
+Atlas *Create()
+{
+	Context *ctx = XA_NEW(internal::MemTag::Default, Context);
+	memset(&ctx->atlas, 0, sizeof(Atlas));
+	ctx->taskScheduler = XA_NEW(internal::MemTag::Default, internal::TaskScheduler);
+	return &ctx->atlas;
+}
+
+static void DestroyOutputMeshes(Context *ctx)
+{
+	if (!ctx->atlas.meshes)
+		return;
+	for (int i = 0; i < (int)ctx->atlas.meshCount; i++) {
+		Mesh &mesh = ctx->atlas.meshes[i];
+		if (mesh.chartArray) {
+			for (uint32_t j = 0; j < mesh.chartCount; j++) {
+				if (mesh.chartArray[j].faceArray)
+					XA_FREE(mesh.chartArray[j].faceArray);
+			}
+			XA_FREE(mesh.chartArray);
+		}
+		if (mesh.vertexArray)
+			XA_FREE(mesh.vertexArray);
+		if (mesh.indexArray)
+			XA_FREE(mesh.indexArray);
+	}
+	XA_FREE(ctx->atlas.meshes);
+	ctx->atlas.meshes = nullptr;
+}
+
+void Destroy(Atlas *atlas)
+{
+	XA_DEBUG_ASSERT(atlas);
+	Context *ctx = (Context *)atlas;
+	if (atlas->utilization)
+		XA_FREE(atlas->utilization);
+	if (atlas->image)
+		XA_FREE(atlas->image);
+	DestroyOutputMeshes(ctx);
+	if (ctx->addMeshProgress) {
+		ctx->addMeshProgress->cancel = true;
+		AddMeshJoin(atlas); // frees addMeshProgress
+	}
+	ctx->taskScheduler->~TaskScheduler();
+	XA_FREE(ctx->taskScheduler);
+	for (uint32_t i = 0; i < ctx->meshes.size(); i++) {
+		internal::Mesh *mesh = ctx->meshes[i];
+		mesh->~Mesh();
+		XA_FREE(mesh);
+	}
+	for (uint32_t i = 0; i < ctx->meshPolygonMappings.size(); i++) {
+		MeshPolygonMapping *mapping = ctx->meshPolygonMappings[i];
+		if (mapping) {
+			mapping->~MeshPolygonMapping();
+			XA_FREE(mapping);
+		}
+	}
+	for (uint32_t i = 0; i < ctx->uvMeshes.size(); i++) {
+		internal::UvMesh *mesh = ctx->uvMeshes[i];
+		for (uint32_t j = 0; j < mesh->charts.size(); j++) {
+			mesh->charts[j]->~UvMeshChart();
+			XA_FREE(mesh->charts[j]);
+		}
+		mesh->~UvMesh();
+		XA_FREE(mesh);
+	}
+	for (uint32_t i = 0; i < ctx->uvMeshInstances.size(); i++) {
+		internal::UvMeshInstance *mesh = ctx->uvMeshInstances[i];
+		mesh->~UvMeshInstance();
+		XA_FREE(mesh);
+	}
+	ctx->~Context();
+	XA_FREE(ctx);
+#if XA_DEBUG_HEAP
+	internal::ReportLeaks();
+#endif
+}
+
+static void runAddMeshTask(void *groupUserData, void *taskUserData)
+{
+	XA_PROFILE_START(addMeshThread)
+	auto ctx = (Context *)groupUserData;
+	auto mesh = (internal::Mesh *)taskUserData;
+	internal::Progress *progress = ctx->addMeshProgress;
+	if (progress->cancel) {
+		XA_PROFILE_END(addMeshThread)
+			return;
+	}
+	XA_PROFILE_START(addMeshCreateColocals)
+	mesh->createColocals();
+	XA_PROFILE_END(addMeshCreateColocals)
+	if (progress->cancel) {
+		XA_PROFILE_END(addMeshThread)
+		return;
+	}
+	progress->increment(1);
+	XA_PROFILE_END(addMeshThread)
+}
+
+static internal::Vector3 DecodePosition(const MeshDecl &meshDecl, uint32_t index)
+{
+	XA_DEBUG_ASSERT(meshDecl.vertexPositionData);
+	XA_DEBUG_ASSERT(meshDecl.vertexPositionStride > 0);
+	return *((const internal::Vector3 *)&((const uint8_t *)meshDecl.vertexPositionData)[meshDecl.vertexPositionStride * index]);
+}
+
+static internal::Vector3 DecodeNormal(const MeshDecl &meshDecl, uint32_t index)
+{
+	XA_DEBUG_ASSERT(meshDecl.vertexNormalData);
+	XA_DEBUG_ASSERT(meshDecl.vertexNormalStride > 0);
+	return *((const internal::Vector3 *)&((const uint8_t *)meshDecl.vertexNormalData)[meshDecl.vertexNormalStride * index]);
+}
+
+static internal::Vector2 DecodeUv(const MeshDecl &meshDecl, uint32_t index)
+{
+	XA_DEBUG_ASSERT(meshDecl.vertexUvData);
+	XA_DEBUG_ASSERT(meshDecl.vertexUvStride > 0);
+	return *((const internal::Vector2 *)&((const uint8_t *)meshDecl.vertexUvData)[meshDecl.vertexUvStride * index]);
+}
+
+static uint32_t DecodeIndex(IndexFormat format, const void *indexData, int32_t offset, uint32_t i)
+{
+	XA_DEBUG_ASSERT(indexData);
+	if (format == IndexFormat::UInt16)
+		return uint16_t((int32_t)((const uint16_t *)indexData)[i] + offset);
+	return uint32_t((int32_t)((const uint32_t *)indexData)[i] + offset);
+}
+
+AddMeshError AddMesh(Atlas *atlas, const MeshDecl &meshDecl, uint32_t meshCountHint)
+{
+	XA_DEBUG_ASSERT(atlas);
+	if (!atlas) {
+		XA_PRINT_WARNING("AddMesh: atlas is null.\n");
+		return AddMeshError::Error;
+	}
+	Context *ctx = (Context *)atlas;
+	if (!ctx->uvMeshes.isEmpty()) {
+		XA_PRINT_WARNING("AddMesh: Meshes and UV meshes cannot be added to the same atlas.\n");
+		return AddMeshError::Error;
+	}
+#if XA_PROFILE
+	if (ctx->meshes.isEmpty())
+		internal::s_profile.addMeshRealStart = std::chrono::high_resolution_clock::now();
+#endif
+	// Don't know how many times AddMesh will be called, so progress needs to adjusted each time.
+	if (!ctx->addMeshProgress) {
+		ctx->addMeshProgress = XA_NEW_ARGS(internal::MemTag::Default, internal::Progress, ProgressCategory::AddMesh, ctx->progressFunc, ctx->progressUserData, 1);
+	}
+	else {
+		ctx->addMeshProgress->setMaxValue(internal::max(ctx->meshes.size() + 1, meshCountHint));
+	}
+	XA_PROFILE_START(addMeshCopyData)
+	const bool hasIndices = meshDecl.indexCount > 0;
+	const uint32_t indexCount = hasIndices ? meshDecl.indexCount : meshDecl.vertexCount;
+	uint32_t faceCount = indexCount / 3;
+	if (meshDecl.faceVertexCount) {
+		faceCount = meshDecl.faceCount;
+		XA_PRINT("Adding mesh %d: %u vertices, %u polygons\n", ctx->meshes.size(), meshDecl.vertexCount, faceCount);
+		for (uint32_t f = 0; f < faceCount; f++) {
+			if (meshDecl.faceVertexCount[f] < 3)
+				return AddMeshError::InvalidFaceVertexCount;
+		}
+	} else {
+		XA_PRINT("Adding mesh %d: %u vertices, %u triangles\n", ctx->meshes.size(), meshDecl.vertexCount, faceCount);
+		// Expecting triangle faces unless otherwise specified.
+		if ((indexCount % 3) != 0)
+			return AddMeshError::InvalidIndexCount;
+	}
+	uint32_t meshFlags = internal::MeshFlags::HasIgnoredFaces;
+	if (meshDecl.vertexNormalData)
+		meshFlags |= internal::MeshFlags::HasNormals;
+	if (meshDecl.faceMaterialData)
+		meshFlags |= internal::MeshFlags::HasMaterials;
+	internal::Mesh *mesh = XA_NEW_ARGS(internal::MemTag::Mesh, internal::Mesh, meshDecl.epsilon, meshDecl.vertexCount, indexCount / 3, meshFlags, ctx->meshes.size());
+	for (uint32_t i = 0; i < meshDecl.vertexCount; i++) {
+		internal::Vector3 normal(0.0f);
+		internal::Vector2 texcoord(0.0f);
+		if (meshDecl.vertexNormalData)
+			normal = DecodeNormal(meshDecl, i);
+		if (meshDecl.vertexUvData)
+			texcoord = DecodeUv(meshDecl, i);
+		mesh->addVertex(DecodePosition(meshDecl, i), normal, texcoord);
+	}
+	MeshPolygonMapping *meshPolygonMapping = nullptr;
+	if (meshDecl.faceVertexCount) {
+		meshPolygonMapping = XA_NEW(internal::MemTag::Default, MeshPolygonMapping);
+		// Copy MeshDecl::faceVertexCount so it can be used later when building output meshes.
+		meshPolygonMapping->faceVertexCount.copyFrom(meshDecl.faceVertexCount, meshDecl.faceCount);
+		// There should be at least as many triangles as polygons.
+		meshPolygonMapping->triangleToPolygonMap.reserve(meshDecl.faceCount);
+		meshPolygonMapping->triangleToPolygonIndicesMap.reserve(meshDecl.indexCount);
+	}
+	const uint32_t kMaxWarnings = 50;
+	uint32_t warningCount = 0;
+	internal::Array<uint32_t> triIndices;
+	internal::Triangulator triangulator;
+	for (uint32_t face = 0; face < faceCount; face++) {
+		// Decode face indices.
+		const uint32_t faceVertexCount = meshDecl.faceVertexCount ? (uint32_t)meshDecl.faceVertexCount[face] : 3;
+		uint32_t polygon[UINT8_MAX];
+		for (uint32_t i = 0; i < faceVertexCount; i++) {
+			if (hasIndices) {
+				polygon[i] = DecodeIndex(meshDecl.indexFormat, meshDecl.indexData, meshDecl.indexOffset, face * faceVertexCount + i);
+				// Check if any index is out of range.
+				if (polygon[i] >= meshDecl.vertexCount) {
+					mesh->~Mesh();
+					XA_FREE(mesh);
+					return AddMeshError::IndexOutOfRange;
+				}
+			} else {
+				polygon[i] = face * faceVertexCount + i;
+			}
+		}
+		// Ignore faces with degenerate or zero length edges.
+		bool ignore = false;
+		for (uint32_t i = 0; i < faceVertexCount; i++) {
+			const uint32_t index1 = polygon[i];
+			const uint32_t index2 = polygon[(i + 1) % 3];
+			if (index1 == index2) {
+				ignore = true;
+				if (++warningCount <= kMaxWarnings)
+					XA_PRINT("   Degenerate edge: index %d, index %d\n", index1, index2);
+				break;
+			}
+			const internal::Vector3 &pos1 = mesh->position(index1);
+			const internal::Vector3 &pos2 = mesh->position(index2);
+			if (internal::length(pos2 - pos1) <= 0.0f) {
+				ignore = true;
+				if (++warningCount <= kMaxWarnings)
+					XA_PRINT("   Zero length edge: index %d position (%g %g %g), index %d position (%g %g %g)\n", index1, pos1.x, pos1.y, pos1.z, index2, pos2.x, pos2.y, pos2.z);
+				break;
+			}
+		}
+		// Ignore faces with any nan vertex attributes.
+		if (!ignore) {
+			for (uint32_t i = 0; i < faceVertexCount; i++) {
+				const internal::Vector3 &pos = mesh->position(polygon[i]);
+				if (internal::isNan(pos.x) || internal::isNan(pos.y) || internal::isNan(pos.z)) {
+					if (++warningCount <= kMaxWarnings)
+						XA_PRINT("   NAN position in face: %d\n", face);
+					ignore = true;
+					break;
+				}
+				if (meshDecl.vertexNormalData) {
+					const internal::Vector3 &normal = mesh->normal(polygon[i]);
+					if (internal::isNan(normal.x) || internal::isNan(normal.y) || internal::isNan(normal.z)) {
+						if (++warningCount <= kMaxWarnings)
+							XA_PRINT("   NAN normal in face: %d\n", face);
+						ignore = true;
+						break;
+					}
+				}
+				if (meshDecl.vertexUvData) {
+					const internal::Vector2 &uv = mesh->texcoord(polygon[i]);
+					if (internal::isNan(uv.x) || internal::isNan(uv.y)) {
+						if (++warningCount <= kMaxWarnings)
+							XA_PRINT("   NAN texture coordinate in face: %d\n", face);
+						ignore = true;
+						break;
+					}
+				}
+			}
+		}
+		// Triangulate if necessary.
+		triIndices.clear();
+		if (faceVertexCount == 3) {
+			triIndices.push_back(polygon[0]);
+			triIndices.push_back(polygon[1]);
+			triIndices.push_back(polygon[2]);
+		} else {
+			triangulator.triangulatePolygon(mesh->positions(), internal::ConstArrayView<uint32_t>(polygon, faceVertexCount), triIndices);
+		}
+		// Check for zero area faces.
+		if (!ignore) {
+			for (uint32_t i = 0; i < triIndices.size(); i += 3) {
+				const internal::Vector3 &a = mesh->position(triIndices[i + 0]);
+				const internal::Vector3 &b = mesh->position(triIndices[i + 1]);
+				const internal::Vector3 &c = mesh->position(triIndices[i + 2]);
+				const float area = internal::length(internal::cross(b - a, c - a)) * 0.5f;
+				if (area <= internal::kAreaEpsilon) {
+					ignore = true;
+					if (++warningCount <= kMaxWarnings)
+						XA_PRINT("   Zero area face: %d, area is %f\n", face, area);
+					break;
+				}
+			}
+		}
+		// User face ignore.
+		if (meshDecl.faceIgnoreData && meshDecl.faceIgnoreData[face])
+			ignore = true;
+		// User material.
+		uint32_t material = UINT32_MAX;
+		if (meshDecl.faceMaterialData)
+			material = meshDecl.faceMaterialData[face];
+		// Add the face(s).
+		for (uint32_t i = 0; i < triIndices.size(); i += 3) {
+			mesh->addFace(&triIndices[i], ignore, material);
+			if (meshPolygonMapping)
+				meshPolygonMapping->triangleToPolygonMap.push_back(face);
+		}
+		if (meshPolygonMapping) {
+			for (uint32_t i = 0; i < triIndices.size(); i++)
+				meshPolygonMapping->triangleToPolygonIndicesMap.push_back(triIndices[i]);
+		}
+	}
+	if (warningCount > kMaxWarnings)
+		XA_PRINT("   %u additional warnings truncated\n", warningCount - kMaxWarnings);
+	XA_PROFILE_END(addMeshCopyData)
+	ctx->meshes.push_back(mesh);
+	ctx->meshPolygonMappings.push_back(meshPolygonMapping);
+	ctx->paramAtlas.addMesh(mesh);
+	if (ctx->addMeshTaskGroup.value == UINT32_MAX)
+		ctx->addMeshTaskGroup = ctx->taskScheduler->createTaskGroup(ctx);
+	internal::Task task;
+	task.userData = mesh;
+	task.func = runAddMeshTask;
+	ctx->taskScheduler->run(ctx->addMeshTaskGroup, task);
+	return AddMeshError::Success;
+}
+
+void AddMeshJoin(Atlas *atlas)
+{
+	XA_DEBUG_ASSERT(atlas);
+	if (!atlas) {
+		XA_PRINT_WARNING("AddMeshJoin: atlas is null.\n");
+		return;
+	}
+	Context *ctx = (Context *)atlas;
+	if (!ctx->uvMeshes.isEmpty()) {
+#if XA_PROFILE
+		XA_PRINT("Added %u UV meshes\n", ctx->uvMeshes.size());
+		internal::s_profile.addMeshReal = uint64_t(std::chrono::duration_cast<std::chrono::microseconds>(std::chrono::high_resolution_clock::now() - internal::s_profile.addMeshRealStart).count());
+#endif
+		XA_PROFILE_PRINT_AND_RESET("   Total: ", addMeshReal)
+		XA_PROFILE_PRINT_AND_RESET("      Copy data: ", addMeshCopyData)
+#if XA_PROFILE_ALLOC
+		XA_PROFILE_PRINT_AND_RESET("   Alloc: ", alloc)
+#endif
+		XA_PRINT_MEM_USAGE
+	} else {
+		if (!ctx->addMeshProgress)
+			return;
+		ctx->taskScheduler->wait(&ctx->addMeshTaskGroup);
+		ctx->addMeshProgress->~Progress();
+		XA_FREE(ctx->addMeshProgress);
+		ctx->addMeshProgress = nullptr;
+#if XA_PROFILE
+		XA_PRINT("Added %u meshes\n", ctx->meshes.size());
+		internal::s_profile.addMeshReal = uint64_t(std::chrono::duration_cast<std::chrono::microseconds>(std::chrono::high_resolution_clock::now() - internal::s_profile.addMeshRealStart).count());
+#endif
+		XA_PROFILE_PRINT_AND_RESET("   Total (real): ", addMeshReal)
+		XA_PROFILE_PRINT_AND_RESET("      Copy data: ", addMeshCopyData)
+		XA_PROFILE_PRINT_AND_RESET("   Total (thread): ", addMeshThread)
+		XA_PROFILE_PRINT_AND_RESET("      Create colocals: ", addMeshCreateColocals)
+#if XA_PROFILE_ALLOC
+		XA_PROFILE_PRINT_AND_RESET("   Alloc: ", alloc)
+#endif
+		XA_PRINT_MEM_USAGE
+#if XA_DEBUG_EXPORT_OBJ_FACE_GROUPS
+		internal::param::s_faceGroupsCurrentVertex = 0;
+#endif
+	}
+}
+
+AddMeshError AddUvMesh(Atlas *atlas, const UvMeshDecl &decl)
+{
+	XA_DEBUG_ASSERT(atlas);
+	if (!atlas) {
+		XA_PRINT_WARNING("AddUvMesh: atlas is null.\n");
+		return AddMeshError::Error;
+	}
+	Context *ctx = (Context *)atlas;
+	if (!ctx->meshes.isEmpty()) {
+		XA_PRINT_WARNING("AddUvMesh: Meshes and UV meshes cannot be added to the same atlas.\n");
+		return AddMeshError::Error;
+	}
+#if XA_PROFILE
+	if (ctx->uvMeshInstances.isEmpty())
+		internal::s_profile.addMeshRealStart = std::chrono::high_resolution_clock::now();
+#endif
+	XA_PROFILE_START(addMeshCopyData)
+	const bool hasIndices = decl.indexCount > 0;
+	const uint32_t indexCount = hasIndices ? decl.indexCount : decl.vertexCount;
+	XA_PRINT("Adding UV mesh %d: %u vertices, %u triangles\n", ctx->uvMeshes.size(), decl.vertexCount, indexCount / 3);
+	// Expecting triangle faces.
+	if ((indexCount % 3) != 0)
+		return AddMeshError::InvalidIndexCount;
+	if (hasIndices) {
+		// Check if any index is out of range.
+		for (uint32_t i = 0; i < indexCount; i++) {
+			const uint32_t index = DecodeIndex(decl.indexFormat, decl.indexData, decl.indexOffset, i);
+			if (index >= decl.vertexCount)
+				return AddMeshError::IndexOutOfRange;
+		}
+	}
+	// Create a mesh instance.
+	internal::UvMeshInstance *meshInstance = XA_NEW(internal::MemTag::Default, internal::UvMeshInstance);
+	meshInstance->mesh = nullptr;
+	ctx->uvMeshInstances.push_back(meshInstance);
+	// See if this is an instance of an already existing mesh.
+	internal::UvMesh *mesh = nullptr;
+	for (uint32_t m = 0; m < ctx->uvMeshes.size(); m++) {
+		if (memcmp(&ctx->uvMeshes[m]->decl, &decl, sizeof(UvMeshDecl)) == 0) {
+			mesh = ctx->uvMeshes[m];
+			XA_PRINT("   instance of a previous UV mesh\n");
+			break;
+		}
+	}
+	if (!mesh) {
+		// Copy geometry to mesh.
+		mesh = XA_NEW(internal::MemTag::Default, internal::UvMesh);
+		ctx->uvMeshes.push_back(mesh);
+		mesh->decl = decl;
+		if (decl.faceMaterialData) {
+			mesh->faceMaterials.resize(decl.indexCount / 3);
+			memcpy(mesh->faceMaterials.data(), decl.faceMaterialData, mesh->faceMaterials.size() * sizeof(uint32_t));
+		}
+		mesh->indices.resize(decl.indexCount);
+		for (uint32_t i = 0; i < indexCount; i++)
+			mesh->indices[i] = hasIndices ? DecodeIndex(decl.indexFormat, decl.indexData, decl.indexOffset, i) : i;
+		mesh->texcoords.resize(decl.vertexCount);
+		for (uint32_t i = 0; i < decl.vertexCount; i++)
+			mesh->texcoords[i] = *((const internal::Vector2 *)&((const uint8_t *)decl.vertexUvData)[decl.vertexStride * i]);
+		// Validate.
+		mesh->faceIgnore.resize(decl.indexCount / 3);
+		mesh->faceIgnore.zeroOutMemory();
+		const uint32_t kMaxWarnings = 50;
+		uint32_t warningCount = 0;
+		for (uint32_t f = 0; f < indexCount / 3; f++) {
+			bool ignore = false;
+			uint32_t tri[3];
+			for (uint32_t i = 0; i < 3; i++)
+				tri[i] = mesh->indices[f * 3 + i];
+			// Check for nan UVs.
+			for (uint32_t i = 0; i < 3; i++) {
+				const uint32_t vertex = tri[i];
+				if (internal::isNan(mesh->texcoords[vertex].x) || internal::isNan(mesh->texcoords[vertex].y)) {
+					ignore = true;
+					if (++warningCount <= kMaxWarnings)
+						XA_PRINT("   NAN texture coordinate in vertex %u\n", vertex);
+					break;
+				}
+			}
+			// Check for zero area faces.
+			if (!ignore) {
+				const internal::Vector2 &v1 = mesh->texcoords[tri[0]];
+				const internal::Vector2 &v2 = mesh->texcoords[tri[1]];
+				const internal::Vector2 &v3 = mesh->texcoords[tri[2]];
+				const float area = fabsf(((v2.x - v1.x) * (v3.y - v1.y) - (v3.x - v1.x) * (v2.y - v1.y)) * 0.5f);
+				if (area <= internal::kAreaEpsilon) {
+					ignore = true;
+					if (++warningCount <= kMaxWarnings)
+						XA_PRINT("   Zero area face: %d, indices (%d %d %d), area is %f\n", f, tri[0], tri[1], tri[2], area);
+				}
+			}
+			if (ignore)
+				mesh->faceIgnore.set(f);
+		}
+		if (warningCount > kMaxWarnings)
+			XA_PRINT("   %u additional warnings truncated\n", warningCount - kMaxWarnings);
+	}
+	meshInstance->mesh = mesh;
+	XA_PROFILE_END(addMeshCopyData)
+	return AddMeshError::Success;
+}
+
+void ComputeCharts(Atlas *atlas, ChartOptions options)
+{
+	if (!atlas) {
+		XA_PRINT_WARNING("ComputeCharts: atlas is null.\n");
+		return;
+	}
+	Context *ctx = (Context *)atlas;
+	AddMeshJoin(atlas);
+	if (ctx->meshes.isEmpty() && ctx->uvMeshInstances.isEmpty()) {
+		XA_PRINT_WARNING("ComputeCharts: No meshes. Call AddMesh or AddUvMesh first.\n");
+		return;
+	}
+	// Reset atlas state. This function may be called multiple times, or again after PackCharts.
+	if (atlas->utilization)
+		XA_FREE(atlas->utilization);
+	if (atlas->image)
+		XA_FREE(atlas->image);
+	DestroyOutputMeshes(ctx);
+	memset(&ctx->atlas, 0, sizeof(Atlas));
+	XA_PRINT("Computing charts\n");
+	if (!ctx->meshes.isEmpty()) {
+		if (!ctx->paramAtlas.computeCharts(ctx->taskScheduler, options, ctx->progressFunc, ctx->progressUserData)) {
+			XA_PRINT("   Cancelled by user\n");
+			return;
+		}
+		uint32_t chartsWithTJunctionsCount = 0, tJunctionCount = 0, orthoChartsCount = 0, planarChartsCount = 0, lscmChartsCount = 0, piecewiseChartsCount = 0, originalUvChartsCount = 0;
+		uint32_t chartCount = 0;
+		const uint32_t meshCount = ctx->meshes.size();
+		for (uint32_t i = 0; i < meshCount; i++) {
+			for (uint32_t j = 0; j < ctx->paramAtlas.chartGroupCount(i); j++) {
+				const internal::param::ChartGroup *chartGroup = ctx->paramAtlas.chartGroupAt(i, j);
+				for (uint32_t k = 0; k < chartGroup->chartCount(); k++) {
+					const internal::param::Chart *chart = chartGroup->chartAt(k);
+					tJunctionCount += chart->tjunctionCount();
+					if (chart->tjunctionCount() > 0)
+						chartsWithTJunctionsCount++;
+					if (chart->type() == ChartType::Planar)
+						planarChartsCount++;
+					else if (chart->type() == ChartType::Ortho)
+						orthoChartsCount++;
+					else if (chart->type() == ChartType::LSCM)
+						lscmChartsCount++;
+					else if (chart->type() == ChartType::Piecewise)
+						piecewiseChartsCount++;
+					if (chart->generatorType() == internal::segment::ChartGeneratorType::OriginalUv)
+						originalUvChartsCount++;
+				}
+				chartCount += chartGroup->chartCount();
+			}
+		}
+		if (tJunctionCount > 0)
+			XA_PRINT("   %u t-junctions found in %u charts\n", tJunctionCount, chartsWithTJunctionsCount);
+		XA_PRINT("   %u charts\n", chartCount);
+		XA_PRINT("      %u planar, %u ortho, %u LSCM, %u piecewise\n", planarChartsCount, orthoChartsCount, lscmChartsCount, piecewiseChartsCount);
+		if (originalUvChartsCount > 0)
+			XA_PRINT("      %u with original UVs\n", originalUvChartsCount);
+		uint32_t chartIndex = 0, invalidParamCount = 0;
+		for (uint32_t i = 0; i < meshCount; i++) {
+			for (uint32_t j = 0; j < ctx->paramAtlas.chartGroupCount(i); j++) {
+				const internal::param::ChartGroup *chartGroup = ctx->paramAtlas.chartGroupAt(i, j);
+				for (uint32_t k = 0; k < chartGroup->chartCount(); k++) {
+					internal::param::Chart *chart = chartGroup->chartAt(k);
+					const internal::param::Quality &quality = chart->quality();
+#if XA_DEBUG_EXPORT_OBJ_CHARTS_AFTER_PARAMETERIZATION
+					{
+						char filename[256];
+						XA_SPRINTF(filename, sizeof(filename), "debug_chart_%03u_after_parameterization.obj", chartIndex);
+						chart->unifiedMesh()->writeObjFile(filename);
+					}
+#endif
+					const char *type = "LSCM";
+					if (chart->type() == ChartType::Planar)
+						type = "planar";
+					else if (chart->type() == ChartType::Ortho)
+						type = "ortho";
+					else if (chart->type() == ChartType::Piecewise)
+						type = "piecewise";
+					if (chart->isInvalid()) {
+						if (quality.boundaryIntersection) {
+							XA_PRINT_WARNING("   Chart %u (mesh %u, group %u, id %u) (%s): invalid parameterization, self-intersecting boundary.\n", chartIndex, i, j, k, type);
+						}
+						if (quality.flippedTriangleCount > 0) {
+							XA_PRINT_WARNING("   Chart %u  (mesh %u, group %u, id %u) (%s): invalid parameterization, %u / %u flipped triangles.\n", chartIndex, i, j, k, type, quality.flippedTriangleCount, quality.totalTriangleCount);
+						}
+						if (quality.zeroAreaTriangleCount > 0) {
+							XA_PRINT_WARNING("   Chart %u  (mesh %u, group %u, id %u) (%s): invalid parameterization, %u / %u zero area triangles.\n", chartIndex, i, j, k, type, quality.zeroAreaTriangleCount, quality.totalTriangleCount);
+						}
+						invalidParamCount++;
+#if XA_DEBUG_EXPORT_OBJ_INVALID_PARAMETERIZATION
+						char filename[256];
+						XA_SPRINTF(filename, sizeof(filename), "debug_chart_%03u_invalid_parameterization.obj", chartIndex);
+						const internal::Mesh *mesh = chart->unifiedMesh();
+						FILE *file;
+						XA_FOPEN(file, filename, "w");
+						if (file) {
+							mesh->writeObjVertices(file);
+							fprintf(file, "s off\n");
+							fprintf(file, "o object\n");
+							for (uint32_t f = 0; f < mesh->faceCount(); f++)
+								mesh->writeObjFace(file, f);
+							if (!chart->paramFlippedFaces().isEmpty()) {
+								fprintf(file, "o flipped_faces\n");
+								for (uint32_t f = 0; f < chart->paramFlippedFaces().size(); f++)
+									mesh->writeObjFace(file, chart->paramFlippedFaces()[f]);
+							}
+							mesh->writeObjBoundaryEges(file);
+							fclose(file);
+						}
+#endif
+					}
+					chartIndex++;
+				}
+			}
+		}
+		if (invalidParamCount > 0)
+			XA_PRINT_WARNING("   %u charts with invalid parameterizations\n", invalidParamCount);
+#if XA_PROFILE
+		XA_PRINT("   Chart groups\n");
+		uint32_t chartGroupCount = 0;
+		for (uint32_t i = 0; i < meshCount; i++) {
+#if 0
+			XA_PRINT("      Mesh %u: %u chart groups\n", i, ctx->paramAtlas.chartGroupCount(i));
+#endif
+			chartGroupCount += ctx->paramAtlas.chartGroupCount(i);
+		}
+		XA_PRINT("      %u total\n", chartGroupCount);
+#endif
+		XA_PROFILE_PRINT_AND_RESET("   Compute charts total (real): ", computeChartsReal)
+		XA_PROFILE_PRINT_AND_RESET("   Compute charts total (thread): ", computeChartsThread)
+		XA_PROFILE_PRINT_AND_RESET("      Create face groups: ", createFaceGroups)
+		XA_PROFILE_PRINT_AND_RESET("      Extract invalid mesh geometry: ", extractInvalidMeshGeometry)
+		XA_PROFILE_PRINT_AND_RESET("      Chart group compute charts (real): ", chartGroupComputeChartsReal)
+		XA_PROFILE_PRINT_AND_RESET("      Chart group compute charts (thread): ", chartGroupComputeChartsThread)
+		XA_PROFILE_PRINT_AND_RESET("         Create chart group mesh: ", createChartGroupMesh)
+		XA_PROFILE_PRINT_AND_RESET("            Create colocals: ", createChartGroupMeshColocals)
+		XA_PROFILE_PRINT_AND_RESET("            Create boundaries: ", createChartGroupMeshBoundaries)
+		XA_PROFILE_PRINT_AND_RESET("         Build atlas: ", buildAtlas)
+		XA_PROFILE_PRINT_AND_RESET("            Init: ", buildAtlasInit)
+		XA_PROFILE_PRINT_AND_RESET("            Planar charts: ", planarCharts)
+		if (options.useInputMeshUvs) {
+			XA_PROFILE_PRINT_AND_RESET("            Original UV charts: ", originalUvCharts)
+		}
+		XA_PROFILE_PRINT_AND_RESET("            Clustered charts: ", clusteredCharts)
+		XA_PROFILE_PRINT_AND_RESET("               Place seeds: ", clusteredChartsPlaceSeeds)
+		XA_PROFILE_PRINT_AND_RESET("                  Boundary intersection: ", clusteredChartsPlaceSeedsBoundaryIntersection)
+		XA_PROFILE_PRINT_AND_RESET("               Relocate seeds: ", clusteredChartsRelocateSeeds)
+		XA_PROFILE_PRINT_AND_RESET("               Reset: ", clusteredChartsReset)
+		XA_PROFILE_PRINT_AND_RESET("               Grow: ", clusteredChartsGrow)
+		XA_PROFILE_PRINT_AND_RESET("                  Boundary intersection: ", clusteredChartsGrowBoundaryIntersection)
+		XA_PROFILE_PRINT_AND_RESET("               Merge: ", clusteredChartsMerge)
+		XA_PROFILE_PRINT_AND_RESET("               Fill holes: ", clusteredChartsFillHoles)
+		XA_PROFILE_PRINT_AND_RESET("         Copy chart faces: ", copyChartFaces)
+		XA_PROFILE_PRINT_AND_RESET("      Create chart mesh and parameterize (real): ", createChartMeshAndParameterizeReal)
+		XA_PROFILE_PRINT_AND_RESET("      Create chart mesh and parameterize (thread): ", createChartMeshAndParameterizeThread)
+		XA_PROFILE_PRINT_AND_RESET("         Create chart mesh: ", createChartMesh)
+		XA_PROFILE_PRINT_AND_RESET("         Parameterize charts: ", parameterizeCharts)
+		XA_PROFILE_PRINT_AND_RESET("            Orthogonal: ", parameterizeChartsOrthogonal)
+		XA_PROFILE_PRINT_AND_RESET("            LSCM: ", parameterizeChartsLSCM)
+		XA_PROFILE_PRINT_AND_RESET("            Recompute: ", parameterizeChartsRecompute)
+		XA_PROFILE_PRINT_AND_RESET("               Piecewise: ", parameterizeChartsPiecewise)
+		XA_PROFILE_PRINT_AND_RESET("                  Boundary intersection: ", parameterizeChartsPiecewiseBoundaryIntersection)
+		XA_PROFILE_PRINT_AND_RESET("            Evaluate quality: ", parameterizeChartsEvaluateQuality)
+#if XA_PROFILE_ALLOC
+		XA_PROFILE_PRINT_AND_RESET("   Alloc: ", alloc)
+#endif
+		XA_PRINT_MEM_USAGE
+	} else {
+		XA_PROFILE_START(computeChartsReal)
+		if (!internal::segment::computeUvMeshCharts(ctx->taskScheduler, ctx->uvMeshes, ctx->progressFunc, ctx->progressUserData)) {
+			XA_PRINT("   Cancelled by user\n");
+			return;
+		}
+		XA_PROFILE_END(computeChartsReal)
+		ctx->uvMeshChartsComputed = true;
+		// Count charts.
+		uint32_t chartCount = 0;
+		const uint32_t meshCount = ctx->uvMeshes.size();
+		for (uint32_t i = 0; i < meshCount; i++)
+			chartCount += ctx->uvMeshes[i]->charts.size();
+		XA_PRINT("   %u charts\n", chartCount);
+		XA_PROFILE_PRINT_AND_RESET("   Total (real): ", computeChartsReal)
+		XA_PROFILE_PRINT_AND_RESET("   Total (thread): ", computeChartsThread)
+	}
+#if XA_PROFILE_ALLOC
+	XA_PROFILE_PRINT_AND_RESET("   Alloc: ", alloc)
+#endif
+	XA_PRINT_MEM_USAGE
+}
+
+void PackCharts(Atlas *atlas, PackOptions packOptions)
+{
+	// Validate arguments and context state.
+	if (!atlas) {
+		XA_PRINT_WARNING("PackCharts: atlas is null.\n");
+		return;
+	}
+	Context *ctx = (Context *)atlas;
+	if (ctx->meshes.isEmpty() && ctx->uvMeshInstances.isEmpty()) {
+		XA_PRINT_WARNING("PackCharts: No meshes. Call AddMesh or AddUvMesh first.\n");
+		return;
+	}
+	if (ctx->uvMeshInstances.isEmpty()) {
+		if (!ctx->paramAtlas.chartsComputed()) {
+			XA_PRINT_WARNING("PackCharts: ComputeCharts must be called first.\n");
+			return;
+		}
+	} else if (!ctx->uvMeshChartsComputed) {
+		XA_PRINT_WARNING("PackCharts: ComputeCharts must be called first.\n");
+		return;
+	}
+	if (packOptions.texelsPerUnit < 0.0f) {
+		XA_PRINT_WARNING("PackCharts: PackOptions::texelsPerUnit is negative.\n");
+		packOptions.texelsPerUnit = 0.0f;
+	}
+	// Cleanup atlas.
+	DestroyOutputMeshes(ctx);
+	if (atlas->utilization) {
+		XA_FREE(atlas->utilization);
+		atlas->utilization = nullptr;
+	}
+	if (atlas->image) {
+		XA_FREE(atlas->image);
+		atlas->image = nullptr;
+	}
+	atlas->meshCount = 0;
+	// Pack charts.
+	XA_PROFILE_START(packChartsAddCharts)
+	internal::pack::Atlas packAtlas;
+	if (!ctx->uvMeshInstances.isEmpty()) {
+		for (uint32_t i = 0; i < ctx->uvMeshInstances.size(); i++)
+			packAtlas.addUvMeshCharts(ctx->uvMeshInstances[i]);
+	}
+	else
+		packAtlas.addCharts(ctx->taskScheduler, &ctx->paramAtlas);
+	XA_PROFILE_END(packChartsAddCharts)
+	XA_PROFILE_START(packCharts)
+	if (!packAtlas.packCharts(packOptions, ctx->progressFunc, ctx->progressUserData))
+		return;
+	XA_PROFILE_END(packCharts)
+	// Populate atlas object with pack results.
+	atlas->atlasCount = packAtlas.getNumAtlases();
+	atlas->chartCount = packAtlas.getChartCount();
+	atlas->width = packAtlas.getWidth();
+	atlas->height = packAtlas.getHeight();
+	atlas->texelsPerUnit = packAtlas.getTexelsPerUnit();
+	if (atlas->atlasCount > 0) {
+		atlas->utilization = XA_ALLOC_ARRAY(internal::MemTag::Default, float, atlas->atlasCount);
+		for (uint32_t i = 0; i < atlas->atlasCount; i++)
+			atlas->utilization[i] = packAtlas.getUtilization(i);
+	}
+	if (packOptions.createImage) {
+		atlas->image = XA_ALLOC_ARRAY(internal::MemTag::Default, uint32_t, atlas->atlasCount * atlas->width * atlas->height);
+		for (uint32_t i = 0; i < atlas->atlasCount; i++)
+			packAtlas.getImages()[i]->copyTo(&atlas->image[atlas->width * atlas->height * i], atlas->width, atlas->height, packOptions.padding);
+	}
+	XA_PROFILE_PRINT_AND_RESET("   Total: ", packCharts)
+	XA_PROFILE_PRINT_AND_RESET("      Add charts (real): ", packChartsAddCharts)
+	XA_PROFILE_PRINT_AND_RESET("      Add charts (thread): ", packChartsAddChartsThread)
+	XA_PROFILE_PRINT_AND_RESET("         Restore texcoords: ", packChartsAddChartsRestoreTexcoords)
+	XA_PROFILE_PRINT_AND_RESET("      Rasterize: ", packChartsRasterize)
+	XA_PROFILE_PRINT_AND_RESET("      Dilate (padding): ", packChartsDilate)
+	XA_PROFILE_PRINT_AND_RESET("      Find location: ", packChartsFindLocation)
+	XA_PROFILE_PRINT_AND_RESET("      Blit: ", packChartsBlit)
+#if XA_PROFILE_ALLOC
+	XA_PROFILE_PRINT_AND_RESET("   Alloc: ", alloc)
+#endif
+	XA_PRINT_MEM_USAGE
+	XA_PRINT("Building output meshes\n");
+	XA_PROFILE_START(buildOutputMeshes)
+	int progress = 0;
+	if (ctx->progressFunc) {
+		if (!ctx->progressFunc(ProgressCategory::BuildOutputMeshes, 0, ctx->progressUserData))
+			return;
+	}
+	if (ctx->uvMeshInstances.isEmpty())
+		atlas->meshCount = ctx->meshes.size();
+	else
+		atlas->meshCount = ctx->uvMeshInstances.size();
+	atlas->meshes = XA_ALLOC_ARRAY(internal::MemTag::Default, Mesh, atlas->meshCount);
+	memset(atlas->meshes, 0, sizeof(Mesh) * atlas->meshCount);
+	if (ctx->uvMeshInstances.isEmpty()) {
+		uint32_t chartIndex = 0;
+		for (uint32_t i = 0; i < atlas->meshCount; i++) {
+			Mesh &outputMesh = atlas->meshes[i];
+			MeshPolygonMapping *meshPolygonMapping = ctx->meshPolygonMappings[i];
+			// One polygon can have many triangles. Don't want to process the same polygon more than once when counting indices, building chart faces etc.
+			internal::BitArray polygonTouched;
+			if (meshPolygonMapping) {
+				polygonTouched.resize(meshPolygonMapping->faceVertexCount.size());
+				polygonTouched.zeroOutMemory();
+			}
+			// Count and alloc arrays.
+			const internal::InvalidMeshGeometry &invalid = ctx->paramAtlas.invalidMeshGeometry(i);
+			outputMesh.vertexCount += invalid.vertices().length;
+			outputMesh.indexCount += invalid.faces().length * 3;
+			for (uint32_t cg = 0; cg < ctx->paramAtlas.chartGroupCount(i); cg++) {
+				const internal::param::ChartGroup *chartGroup = ctx->paramAtlas.chartGroupAt(i, cg);
+				for (uint32_t c = 0; c < chartGroup->chartCount(); c++) {
+					const internal::param::Chart *chart = chartGroup->chartAt(c);
+					outputMesh.vertexCount += chart->originalVertexCount();
+					const uint32_t faceCount = chart->unifiedMesh()->faceCount();
+					if (meshPolygonMapping) {
+						// Map triangles back to polygons and count the polygon vertices.
+						for (uint32_t f = 0; f < faceCount; f++) {
+							const uint32_t polygon = meshPolygonMapping->triangleToPolygonMap[chart->mapFaceToSourceFace(f)];
+							if (!polygonTouched.get(polygon)) {
+								polygonTouched.set(polygon);
+								outputMesh.indexCount += meshPolygonMapping->faceVertexCount[polygon];
+							}
+						}
+					} else {
+						outputMesh.indexCount += faceCount * 3;
+					}
+					outputMesh.chartCount++;
+				}
+			}
+			outputMesh.vertexArray = XA_ALLOC_ARRAY(internal::MemTag::Default, Vertex, outputMesh.vertexCount);
+			outputMesh.indexArray = XA_ALLOC_ARRAY(internal::MemTag::Default, uint32_t, outputMesh.indexCount);
+			outputMesh.chartArray = XA_ALLOC_ARRAY(internal::MemTag::Default, Chart, outputMesh.chartCount);
+			XA_PRINT("   Mesh %u: %u vertices, %u triangles, %u charts\n", i, outputMesh.vertexCount, outputMesh.indexCount / 3, outputMesh.chartCount);
+			// Copy mesh data.
+			uint32_t firstVertex = 0;
+			{
+				const internal::InvalidMeshGeometry &mesh = ctx->paramAtlas.invalidMeshGeometry(i);
+				internal::ConstArrayView<uint32_t> faces = mesh.faces();
+				internal::ConstArrayView<uint32_t> indices = mesh.indices();
+				internal::ConstArrayView<uint32_t> vertices = mesh.vertices();
+				// Vertices.
+				for (uint32_t v = 0; v < vertices.length; v++) {
+					Vertex &vertex = outputMesh.vertexArray[v];
+					vertex.atlasIndex = -1;
+					vertex.chartIndex = -1;
+					vertex.uv[0] = vertex.uv[1] = 0.0f;
+					vertex.xref = vertices[v];
+				}
+				// Indices.
+				for (uint32_t f = 0; f < faces.length; f++) {
+					const uint32_t indexOffset = faces[f] * 3;
+					for (uint32_t j = 0; j < 3; j++)
+						outputMesh.indexArray[indexOffset + j] = indices[f * 3 + j];
+				}
+				firstVertex = vertices.length;
+			}
+			uint32_t meshChartIndex = 0;
+			for (uint32_t cg = 0; cg < ctx->paramAtlas.chartGroupCount(i); cg++) {
+				const internal::param::ChartGroup *chartGroup = ctx->paramAtlas.chartGroupAt(i, cg);
+				for (uint32_t c = 0; c < chartGroup->chartCount(); c++) {
+					const internal::param::Chart *chart = chartGroup->chartAt(c);
+					const internal::Mesh *unifiedMesh = chart->unifiedMesh();
+					const uint32_t faceCount = unifiedMesh->faceCount();
+#if XA_CHECK_PARAM_WINDING
+					uint32_t flippedCount = 0;
+					for (uint32_t f = 0; f < faceCount; f++) {
+						const float area = mesh->computeFaceParametricArea(f);
+						if (area < 0.0f)
+							flippedCount++;
+					}
+					const char *type = "LSCM";
+					if (chart->type() == ChartType::Planar)
+						type = "planar";
+					else if (chart->type() == ChartType::Ortho)
+						type = "ortho";
+					else if (chart->type() == ChartType::Piecewise)
+						type = "piecewise";
+					if (flippedCount > 0) {
+						if (flippedCount == faceCount) {
+							XA_PRINT_WARNING("chart %u (%s): all face flipped\n", chartIndex, type);
+						} else {
+							XA_PRINT_WARNING("chart %u (%s): %u / %u faces flipped\n", chartIndex, type, flippedCount, faceCount);
+						}
+					}
+#endif
+					// Vertices.
+					for (uint32_t v = 0; v < chart->originalVertexCount(); v++) {
+						Vertex &vertex = outputMesh.vertexArray[firstVertex + v];
+						vertex.atlasIndex = packAtlas.getChart(chartIndex)->atlasIndex;
+						XA_DEBUG_ASSERT(vertex.atlasIndex >= 0);
+						vertex.chartIndex = (int32_t)chartIndex;
+						const internal::Vector2 &uv = unifiedMesh->texcoord(chart->originalVertexToUnifiedVertex(v));
+						vertex.uv[0] = internal::max(0.0f, uv.x);
+						vertex.uv[1] = internal::max(0.0f, uv.y);
+						vertex.xref = chart->mapChartVertexToSourceVertex(v);
+					}
+					// Indices.
+					for (uint32_t f = 0; f < faceCount; f++) {
+						const uint32_t indexOffset = chart->mapFaceToSourceFace(f) * 3;
+						for (uint32_t j = 0; j < 3; j++) {
+							uint32_t outIndex = indexOffset + j;
+							if (meshPolygonMapping)
+								outIndex = meshPolygonMapping->triangleToPolygonIndicesMap[outIndex];
+							outputMesh.indexArray[outIndex] = firstVertex + chart->originalVertices()[f * 3 + j];
+						}
+					}
+					// Charts.
+					Chart *outputChart = &outputMesh.chartArray[meshChartIndex];
+					const int32_t atlasIndex = packAtlas.getChart(chartIndex)->atlasIndex;
+					XA_DEBUG_ASSERT(atlasIndex >= 0);
+					outputChart->atlasIndex = (uint32_t)atlasIndex;
+					outputChart->type = chart->isInvalid() ? ChartType::Invalid : chart->type();
+					if (meshPolygonMapping) {
+						// Count polygons.
+						polygonTouched.zeroOutMemory();
+						outputChart->faceCount = 0;
+						for (uint32_t f = 0; f < faceCount; f++) {
+							const uint32_t polygon = meshPolygonMapping->triangleToPolygonMap[chart->mapFaceToSourceFace(f)];
+							if (!polygonTouched.get(polygon)) {
+								polygonTouched.set(polygon);
+								outputChart->faceCount++;
+							}
+						}
+						// Write polygons.
+						outputChart->faceArray = XA_ALLOC_ARRAY(internal::MemTag::Default, uint32_t, outputChart->faceCount);
+						polygonTouched.zeroOutMemory();
+						uint32_t of = 0;
+						for (uint32_t f = 0; f < faceCount; f++) {
+							const uint32_t polygon = meshPolygonMapping->triangleToPolygonMap[chart->mapFaceToSourceFace(f)];
+							if (!polygonTouched.get(polygon)) {
+								polygonTouched.set(polygon);
+								outputChart->faceArray[of++] = polygon;
+							}
+						}
+					} else {
+						outputChart->faceCount = faceCount;
+						outputChart->faceArray = XA_ALLOC_ARRAY(internal::MemTag::Default, uint32_t, outputChart->faceCount);
+						for (uint32_t f = 0; f < outputChart->faceCount; f++)
+							outputChart->faceArray[f] = chart->mapFaceToSourceFace(f);
+					}
+					outputChart->material = 0;
+					meshChartIndex++;
+					chartIndex++;
+					firstVertex += chart->originalVertexCount();
+				}
+			}
+			XA_DEBUG_ASSERT(outputMesh.vertexCount == firstVertex);
+			XA_DEBUG_ASSERT(outputMesh.chartCount == meshChartIndex);
+			if (ctx->progressFunc) {
+				const int newProgress = int((i + 1) / (float)atlas->meshCount * 100.0f);
+				if (newProgress != progress) {
+					progress = newProgress;
+					if (!ctx->progressFunc(ProgressCategory::BuildOutputMeshes, progress, ctx->progressUserData))
+						return;
+				}
+			}
+		}
+	} else {
+		uint32_t chartIndex = 0;
+		for (uint32_t m = 0; m < ctx->uvMeshInstances.size(); m++) {
+			Mesh &outputMesh = atlas->meshes[m];
+			const internal::UvMeshInstance *mesh = ctx->uvMeshInstances[m];
+			// Alloc arrays.
+			outputMesh.vertexCount = mesh->texcoords.size();
+			outputMesh.indexCount = mesh->mesh->indices.size();
+			outputMesh.chartCount = mesh->mesh->charts.size();
+			outputMesh.vertexArray = XA_ALLOC_ARRAY(internal::MemTag::Default, Vertex, outputMesh.vertexCount);
+			outputMesh.indexArray = XA_ALLOC_ARRAY(internal::MemTag::Default, uint32_t, outputMesh.indexCount);
+			outputMesh.chartArray = XA_ALLOC_ARRAY(internal::MemTag::Default, Chart, outputMesh.chartCount);
+			XA_PRINT("   UV mesh %u: %u vertices, %u triangles, %u charts\n", m, outputMesh.vertexCount, outputMesh.indexCount / 3, outputMesh.chartCount);
+			// Copy mesh data.
+			// Vertices.
+			for (uint32_t v = 0; v < mesh->texcoords.size(); v++) {
+				Vertex &vertex = outputMesh.vertexArray[v];
+				vertex.uv[0] = mesh->texcoords[v].x;
+				vertex.uv[1] = mesh->texcoords[v].y;
+				vertex.xref = v;
+				const uint32_t meshChartIndex = mesh->mesh->vertexToChartMap[v];
+				if (meshChartIndex == UINT32_MAX) {
+					// Vertex doesn't exist in any chart.
+					vertex.atlasIndex = -1;
+					vertex.chartIndex = -1;
+				} else {
+					const internal::pack::Chart *chart = packAtlas.getChart(chartIndex + meshChartIndex);
+					vertex.atlasIndex = chart->atlasIndex;
+					vertex.chartIndex = (int32_t)chartIndex + meshChartIndex;
+				}
+			}
+			// Indices.
+			memcpy(outputMesh.indexArray, mesh->mesh->indices.data(), mesh->mesh->indices.size() * sizeof(uint32_t));
+			// Charts.
+			for (uint32_t c = 0; c < mesh->mesh->charts.size(); c++) {
+				Chart *outputChart = &outputMesh.chartArray[c];
+				const internal::pack::Chart *chart = packAtlas.getChart(chartIndex);
+				XA_DEBUG_ASSERT(chart->atlasIndex >= 0);
+				outputChart->atlasIndex = (uint32_t)chart->atlasIndex;
+				outputChart->faceCount = chart->faces.size();
+				outputChart->faceArray = XA_ALLOC_ARRAY(internal::MemTag::Default, uint32_t, outputChart->faceCount);
+				outputChart->material = chart->material;
+				for (uint32_t f = 0; f < outputChart->faceCount; f++)
+					outputChart->faceArray[f] = chart->faces[f];
+				chartIndex++;
+			}
+			if (ctx->progressFunc) {
+				const int newProgress = int((m + 1) / (float)atlas->meshCount * 100.0f);
+				if (newProgress != progress) {
+					progress = newProgress;
+					if (!ctx->progressFunc(ProgressCategory::BuildOutputMeshes, progress, ctx->progressUserData))
+						return;
+				}
+			}
+		}
+	}
+	if (ctx->progressFunc && progress != 100)
+		ctx->progressFunc(ProgressCategory::BuildOutputMeshes, 100, ctx->progressUserData);
+	XA_PROFILE_END(buildOutputMeshes)
+	XA_PROFILE_PRINT_AND_RESET("   Total: ", buildOutputMeshes)
+#if XA_PROFILE_ALLOC
+	XA_PROFILE_PRINT_AND_RESET("   Alloc: ", alloc)
+#endif
+	XA_PRINT_MEM_USAGE
+}
+
+void Generate(Atlas *atlas, ChartOptions chartOptions, PackOptions packOptions)
+{
+	if (!atlas) {
+		XA_PRINT_WARNING("Generate: atlas is null.\n");
+		return;
+	}
+	Context *ctx = (Context *)atlas;
+	if (ctx->meshes.isEmpty() && ctx->uvMeshInstances.isEmpty()) {
+		XA_PRINT_WARNING("Generate: No meshes. Call AddMesh or AddUvMesh first.\n");
+		return;
+	}
+	ComputeCharts(atlas, chartOptions);
+	PackCharts(atlas, packOptions);
+}
+
+void SetProgressCallback(Atlas *atlas, ProgressFunc progressFunc, void *progressUserData)
+{
+	if (!atlas) {
+		XA_PRINT_WARNING("SetProgressCallback: atlas is null.\n");
+		return;
+	}
+	Context *ctx = (Context *)atlas;
+	ctx->progressFunc = progressFunc;
+	ctx->progressUserData = progressUserData;
+}
+
+void SetAlloc(ReallocFunc reallocFunc, FreeFunc freeFunc)
+{
+	internal::s_realloc = reallocFunc;
+	internal::s_free = freeFunc;
+}
+
+void SetPrint(PrintFunc print, bool verbose)
+{
+	internal::s_print = print;
+	internal::s_printVerbose = verbose;
+}
+
+const char *StringForEnum(AddMeshError error)
+{
+	if (error == AddMeshError::Error)
+		return "Unspecified error";
+	if (error == AddMeshError::IndexOutOfRange)
+		return "Index out of range";
+	if (error == AddMeshError::InvalidFaceVertexCount)
+		return "Invalid face vertex count";
+	if (error == AddMeshError::InvalidIndexCount)
+		return "Invalid index count";
+	return "Success";
+}
+
+const char *StringForEnum(ProgressCategory category)
+{
+	if (category == ProgressCategory::AddMesh)
+		return "Adding mesh(es)";
+	if (category == ProgressCategory::ComputeCharts)
+		return "Computing charts";
+	if (category == ProgressCategory::PackCharts)
+		return "Packing charts";
+	if (category == ProgressCategory::BuildOutputMeshes)
+		return "Building output meshes";
+	return "";
+}
+
+} // namespace xatlas
+
+#if XATLAS_C_API
+static_assert(sizeof(xatlas::Chart) == sizeof(xatlasChart), "xatlasChart size mismatch");
+static_assert(sizeof(xatlas::Vertex) == sizeof(xatlasVertex), "xatlasVertex size mismatch");
+static_assert(sizeof(xatlas::Mesh) == sizeof(xatlasMesh), "xatlasMesh size mismatch");
+static_assert(sizeof(xatlas::Atlas) == sizeof(xatlasAtlas), "xatlasAtlas size mismatch");
+static_assert(sizeof(xatlas::MeshDecl) == sizeof(xatlasMeshDecl), "xatlasMeshDecl size mismatch");
+static_assert(sizeof(xatlas::UvMeshDecl) == sizeof(xatlasUvMeshDecl), "xatlasUvMeshDecl size mismatch");
+static_assert(sizeof(xatlas::ChartOptions) == sizeof(xatlasChartOptions), "xatlasChartOptions size mismatch");
+static_assert(sizeof(xatlas::PackOptions) == sizeof(xatlasPackOptions), "xatlasPackOptions size mismatch");
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+xatlasAtlas *xatlasCreate()
+{
+	return (xatlasAtlas *)xatlas::Create();
+}
+
+void xatlasDestroy(xatlasAtlas *atlas)
+{
+	xatlas::Destroy((xatlas::Atlas *)atlas);
+}
+
+xatlasAddMeshError xatlasAddMesh(xatlasAtlas *atlas, const xatlasMeshDecl *meshDecl, uint32_t meshCountHint)
+{
+	return (xatlasAddMeshError)xatlas::AddMesh((xatlas::Atlas *)atlas, *(const xatlas::MeshDecl *)meshDecl, meshCountHint);
+}
+
+void xatlasAddMeshJoin(xatlasAtlas *atlas)
+{
+	xatlas::AddMeshJoin((xatlas::Atlas *)atlas);
+}
+
+xatlasAddMeshError xatlasAddUvMesh(xatlasAtlas *atlas, const xatlasUvMeshDecl *decl)
+{
+	return (xatlasAddMeshError)xatlas::AddUvMesh((xatlas::Atlas *)atlas, *(const xatlas::UvMeshDecl *)decl);
+}
+
+void xatlasComputeCharts(xatlasAtlas *atlas, const xatlasChartOptions *chartOptions)
+{
+	xatlas::ComputeCharts((xatlas::Atlas *)atlas, chartOptions ? *(xatlas::ChartOptions *)chartOptions : xatlas::ChartOptions());
+}
+
+void xatlasPackCharts(xatlasAtlas *atlas, const xatlasPackOptions *packOptions)
+{
+	xatlas::PackCharts((xatlas::Atlas *)atlas, packOptions ? *(xatlas::PackOptions *)packOptions : xatlas::PackOptions());
+}
+
+void xatlasGenerate(xatlasAtlas *atlas, const xatlasChartOptions *chartOptions, const xatlasPackOptions *packOptions)
+{
+	xatlas::Generate((xatlas::Atlas *)atlas, chartOptions ? *(xatlas::ChartOptions *)chartOptions : xatlas::ChartOptions(), packOptions ? *(xatlas::PackOptions *)packOptions : xatlas::PackOptions());
+}
+
+void xatlasSetProgressCallback(xatlasAtlas *atlas, xatlasProgressFunc progressFunc, void *progressUserData)
+{
+	xatlas::ProgressFunc pf;
+	*(void **)&pf = (void *)progressFunc;
+	xatlas::SetProgressCallback((xatlas::Atlas *)atlas, pf, progressUserData);
+}
+
+void xatlasSetAlloc(xatlasReallocFunc reallocFunc, xatlasFreeFunc freeFunc)
+{
+	xatlas::SetAlloc((xatlas::ReallocFunc)reallocFunc, (xatlas::FreeFunc)freeFunc);
+}
+
+void xatlasSetPrint(xatlasPrintFunc print, bool verbose)
+{
+	xatlas::SetPrint((xatlas::PrintFunc)print, verbose);
+}
+
+const char *xatlasAddMeshErrorString(xatlasAddMeshError error)
+{
+	return xatlas::StringForEnum((xatlas::AddMeshError)error);
+}
+
+const char *xatlasProgressCategoryString(xatlasProgressCategory category)
+{
+	return xatlas::StringForEnum((xatlas::ProgressCategory)category);
+}
+
+void xatlasMeshDeclInit(xatlasMeshDecl *meshDecl)
+{
+	xatlas::MeshDecl init;
+	memcpy(meshDecl, &init, sizeof(init));
+}
+
+void xatlasUvMeshDeclInit(xatlasUvMeshDecl *uvMeshDecl)
+{
+	xatlas::UvMeshDecl init;
+	memcpy(uvMeshDecl, &init, sizeof(init));
+}
+
+void xatlasChartOptionsInit(xatlasChartOptions *chartOptions)
+{
+	xatlas::ChartOptions init;
+	memcpy(chartOptions, &init, sizeof(init));
+}
+
+void xatlasPackOptionsInit(xatlasPackOptions *packOptions)
+{
+	xatlas::PackOptions init;
+	memcpy(packOptions, &init, sizeof(init));
+}
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+#endif // XATLAS_C_API
diff --git a/third_party/xatlas/xatlas.h b/third_party/xatlas/xatlas.h
new file mode 100644
index 0000000..d66a96d
--- /dev/null
+++ b/third_party/xatlas/xatlas.h
@@ -0,0 +1,269 @@
+/*
+MIT License
+
+Copyright (c) 2018-2020 Jonathan Young
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+*/
+/*
+thekla_atlas
+MIT License
+https://github.com/Thekla/thekla_atlas
+Copyright (c) 2013 Thekla, Inc
+Copyright NVIDIA Corporation 2006 -- Ignacio Castano <icastano@nvidia.com>
+*/
+#pragma once
+#ifndef XATLAS_H
+#define XATLAS_H
+#include <stddef.h>
+#include <stdint.h>
+
+namespace xatlas {
+
+enum class ChartType
+{
+	Planar,
+	Ortho,
+	LSCM,
+	Piecewise,
+	Invalid
+};
+
+// A group of connected faces, belonging to a single atlas.
+struct Chart
+{
+	uint32_t *faceArray;
+	uint32_t atlasIndex; // Sub-atlas index.
+	uint32_t faceCount;
+	ChartType type;
+	uint32_t material;
+};
+
+// Output vertex.
+struct Vertex
+{
+	int32_t atlasIndex; // Sub-atlas index. -1 if the vertex doesn't exist in any atlas.
+	int32_t chartIndex; // -1 if the vertex doesn't exist in any chart.
+	float uv[2]; // Not normalized - values are in Atlas width and height range.
+	uint32_t xref; // Index of input vertex from which this output vertex originated.
+};
+
+// Output mesh.
+struct Mesh
+{
+	Chart *chartArray;
+	uint32_t *indexArray;
+	Vertex *vertexArray;
+	uint32_t chartCount;
+	uint32_t indexCount;
+	uint32_t vertexCount;
+};
+
+static const uint32_t kImageChartIndexMask = 0x1FFFFFFF;
+static const uint32_t kImageHasChartIndexBit = 0x80000000;
+static const uint32_t kImageIsBilinearBit = 0x40000000;
+static const uint32_t kImageIsPaddingBit = 0x20000000;
+
+// Empty on creation. Populated after charts are packed.
+struct Atlas
+{
+	uint32_t *image;
+	Mesh *meshes; // The output meshes, corresponding to each AddMesh call.
+	float *utilization; // Normalized atlas texel utilization array. E.g. a value of 0.8 means 20% empty space. atlasCount in length.
+	uint32_t width; // Atlas width in texels.
+	uint32_t height; // Atlas height in texels.
+	uint32_t atlasCount; // Number of sub-atlases. Equal to 0 unless PackOptions resolution is changed from default (0).
+	uint32_t chartCount; // Total number of charts in all meshes.
+	uint32_t meshCount; // Number of output meshes. Equal to the number of times AddMesh was called.
+	float texelsPerUnit; // Equal to PackOptions texelsPerUnit if texelsPerUnit > 0, otherwise an estimated value to match PackOptions resolution.
+};
+
+// Create an empty atlas.
+Atlas *Create();
+
+void Destroy(Atlas *atlas);
+
+enum class IndexFormat
+{
+	UInt16,
+	UInt32
+};
+
+// Input mesh declaration.
+struct MeshDecl
+{
+	const void *vertexPositionData = nullptr;
+	const void *vertexNormalData = nullptr; // optional
+	const void *vertexUvData = nullptr; // optional. The input UVs are provided as a hint to the chart generator.
+	const void *indexData = nullptr; // optional
+
+	// Optional. Must be faceCount in length.
+	// Don't atlas faces set to true. Ignored faces still exist in the output meshes, Vertex uv is set to (0, 0) and Vertex atlasIndex to -1.
+	const bool *faceIgnoreData = nullptr;
+
+	// Optional. Must be faceCount in length.
+	// Only faces with the same material will be assigned to the same chart.
+	const uint32_t *faceMaterialData = nullptr;
+
+	// Optional. Must be faceCount in length.
+	// Polygon / n-gon support. Faces are assumed to be triangles if this is null.
+	const uint8_t *faceVertexCount = nullptr;
+
+	uint32_t vertexCount = 0;
+	uint32_t vertexPositionStride = 0;
+	uint32_t vertexNormalStride = 0; // optional
+	uint32_t vertexUvStride = 0; // optional
+	uint32_t indexCount = 0;
+	int32_t indexOffset = 0; // optional. Add this offset to all indices.
+	uint32_t faceCount = 0; // Optional if faceVertexCount is null. Otherwise assumed to be indexCount / 3.
+	IndexFormat indexFormat = IndexFormat::UInt16;
+
+	// Vertex positions within epsilon distance of each other are considered colocal.
+	float epsilon = 1.192092896e-07F;
+};
+
+enum class AddMeshError
+{
+	Success, // No error.
+	Error, // Unspecified error.
+	IndexOutOfRange, // An index is >= MeshDecl vertexCount.
+	InvalidFaceVertexCount, // Must be >= 3.
+	InvalidIndexCount // Not evenly divisible by 3 - expecting triangles.
+};
+
+// Add a mesh to the atlas. MeshDecl data is copied, so it can be freed after AddMesh returns.
+AddMeshError AddMesh(Atlas *atlas, const MeshDecl &meshDecl, uint32_t meshCountHint = 0);
+
+// Wait for AddMesh async processing to finish. ComputeCharts / Generate call this internally.
+void AddMeshJoin(Atlas *atlas);
+
+struct UvMeshDecl
+{
+	const void *vertexUvData = nullptr;
+	const void *indexData = nullptr; // optional
+	const uint32_t *faceMaterialData = nullptr; // Optional. Overlapping UVs should be assigned a different material. Must be indexCount / 3 in length.
+	uint32_t vertexCount = 0;
+	uint32_t vertexStride = 0;
+	uint32_t indexCount = 0;
+	int32_t indexOffset = 0; // optional. Add this offset to all indices.
+	IndexFormat indexFormat = IndexFormat::UInt16;
+};
+
+AddMeshError AddUvMesh(Atlas *atlas, const UvMeshDecl &decl);
+
+// Custom parameterization function. texcoords initial values are an orthogonal parameterization.
+typedef void (*ParameterizeFunc)(const float *positions, float *texcoords, uint32_t vertexCount, const uint32_t *indices, uint32_t indexCount);
+
+struct ChartOptions
+{
+	ParameterizeFunc paramFunc = nullptr;
+
+	float maxChartArea = 0.0f; // Don't grow charts to be larger than this. 0 means no limit.
+	float maxBoundaryLength = 0.0f; // Don't grow charts to have a longer boundary than this. 0 means no limit.
+
+	// Weights determine chart growth. Higher weights mean higher cost for that metric.
+	float normalDeviationWeight = 2.0f; // Angle between face and average chart normal.
+	float roundnessWeight = 0.01f;
+	float straightnessWeight = 6.0f;
+	float normalSeamWeight = 4.0f; // If > 1000, normal seams are fully respected.
+	float textureSeamWeight = 0.5f;
+
+	float maxCost = 2.0f; // If total of all metrics * weights > maxCost, don't grow chart. Lower values result in more charts.
+	uint32_t maxIterations = 1; // Number of iterations of the chart growing and seeding phases. Higher values result in better charts.
+
+	bool useInputMeshUvs = false; // Use MeshDecl::vertexUvData for charts.
+	bool fixWinding = false; // Enforce consistent texture coordinate winding.
+};
+
+// Call after all AddMesh calls. Can be called multiple times to recompute charts with different options.
+void ComputeCharts(Atlas *atlas, ChartOptions options = ChartOptions());
+
+struct PackOptions
+{
+	// Charts larger than this will be scaled down. 0 means no limit.
+	uint32_t maxChartSize = 0;
+
+	// Number of pixels to pad charts with.
+	uint32_t padding = 0;
+
+	// Unit to texel scale. e.g. a 1x1 quad with texelsPerUnit of 32 will take up approximately 32x32 texels in the atlas.
+	// If 0, an estimated value will be calculated to approximately match the given resolution.
+	// If resolution is also 0, the estimated value will approximately match a 1024x1024 atlas.
+	float texelsPerUnit = 0.0f;
+
+	// If 0, generate a single atlas with texelsPerUnit determining the final resolution.
+	// If not 0, and texelsPerUnit is not 0, generate one or more atlases with that exact resolution.
+	// If not 0, and texelsPerUnit is 0, texelsPerUnit is estimated to approximately match the resolution.
+	uint32_t resolution = 0;
+
+	// Leave space around charts for texels that would be sampled by bilinear filtering.
+	bool bilinear = true;
+
+	// Align charts to 4x4 blocks. Also improves packing speed, since there are fewer possible chart locations to consider.
+	bool blockAlign = false;
+
+	// Slower, but gives the best result. If false, use random chart placement.
+	bool bruteForce = false;
+
+	// Create Atlas::image
+	bool createImage = false;
+
+	// Rotate charts to the axis of their convex hull.
+	bool rotateChartsToAxis = true;
+
+	// Rotate charts to improve packing.
+	bool rotateCharts = true;
+};
+
+// Call after ComputeCharts. Can be called multiple times to re-pack charts with different options.
+void PackCharts(Atlas *atlas, PackOptions packOptions = PackOptions());
+
+// Equivalent to calling ComputeCharts and PackCharts in sequence. Can be called multiple times to regenerate with different options.
+void Generate(Atlas *atlas, ChartOptions chartOptions = ChartOptions(), PackOptions packOptions = PackOptions());
+
+// Progress tracking.
+enum class ProgressCategory
+{
+	AddMesh,
+	ComputeCharts,
+	PackCharts,
+	BuildOutputMeshes
+};
+
+// May be called from any thread. Return false to cancel.
+typedef bool (*ProgressFunc)(ProgressCategory category, int progress, void *userData);
+
+void SetProgressCallback(Atlas *atlas, ProgressFunc progressFunc = nullptr, void *progressUserData = nullptr);
+
+// Custom memory allocation.
+typedef void *(*ReallocFunc)(void *, size_t);
+typedef void (*FreeFunc)(void *);
+void SetAlloc(ReallocFunc reallocFunc, FreeFunc freeFunc = nullptr);
+
+// Custom print function.
+typedef int (*PrintFunc)(const char *, ...);
+void SetPrint(PrintFunc print, bool verbose);
+
+// Helper functions for error messages.
+const char *StringForEnum(AddMeshError error);
+const char *StringForEnum(ProgressCategory category);
+
+} // namespace xatlas
+
+#endif // XATLAS_H
diff --git a/trellis2.cpp b/trellis2.cpp
index 405c334..79511d6 100644
--- a/trellis2.cpp
+++ b/trellis2.cpp
@@ -7,14 +7,19 @@
 #include "gguf.h"
 
 #include <vector>
+#include <algorithm>
+#include <array>
 
+#include <chrono>
 #include <cmath>
 #include <cstdint>
 #include <cstdio>
 #include <cstring>
 #include <fstream>
 #include <limits>
+#include <cstdlib>
 #include <random>
+#include <thread>
 #include <unordered_map>
 
 /*****************************************************************************
@@ -107,6 +112,11 @@ bool trellis2_load_dinodata(const std::string & path,
         return false;
     }
 
+    // The shape product is attacker-controlled and must not wrap: cap the
+    // element count well above any real conditioning tensor but far below
+    // anything that could overflow want_bytes or exhaust memory.
+    const int64_t MAX_ELEMS = (int64_t) 1 << 31;
+
     std::vector<int64_t> shape(ndim);
     int64_t total = 1;
     for (uint32_t i = 0; i < ndim; ++i) {
@@ -115,6 +125,10 @@ bool trellis2_load_dinodata(const std::string & path,
             set_error(error, "truncated shape");
             return false;
         }
+        if (dim == 0 || (int64_t) dim > MAX_ELEMS || total > MAX_ELEMS / (int64_t) dim) {
+            set_error(error, "implausible shape (zero or overflowing element count)");
+            return false;
+        }
         shape[i] = (int64_t) dim;
         total   *= (int64_t) dim;
     }
@@ -192,7 +206,14 @@ namespace {
 // Pick the best available compute backend: the first GPU device exposed by the
 // ggml backend registry (CUDA / Metal / Vulkan / ...), falling back to CPU.
 // Mirrors sam3.cpp's "use a GPU backend automatically if one is available".
-ggml_backend_t init_best_backend(std::string & name_out) {
+// device: nullptr/"auto" = GPU if available else CPU; "cpu" = force CPU.
+// The TRELLIS2_DEVICE env var overrides "auto".
+ggml_backend_t init_best_backend(std::string & name_out, const char * device = nullptr) {
+    std::string want = device ? device : "";
+    if (want.empty() || want == "auto") {
+        if (const char * env = std::getenv("TRELLIS2_DEVICE")) want = env;
+    }
+    if (want != "cpu")
     for (size_t i = 0; i < ggml_backend_dev_count(); ++i) {
         ggml_backend_dev_t dev = ggml_backend_dev_get(i);
         if (ggml_backend_dev_type(dev) == GGML_BACKEND_DEVICE_TYPE_GPU) {
@@ -205,7 +226,15 @@ ggml_backend_t init_best_backend(std::string & name_out) {
         }
     }
     name_out = "CPU";
-    return ggml_backend_cpu_init();
+    ggml_backend_t cpu = ggml_backend_cpu_init();
+    // ggml defaults to 4 threads; use every core (TRELLIS2_N_THREADS overrides).
+    int n_threads = (int) std::thread::hardware_concurrency();
+    if (const char * env = std::getenv("TRELLIS2_N_THREADS")) {
+        const int v = std::atoi(env);
+        if (v > 0) n_threads = v;
+    }
+    if (n_threads > 0) ggml_backend_cpu_set_n_threads(cpu, n_threads);
+    return cpu;
 }
 
 // KV readers with defaults (return the default if the key is absent).
@@ -228,8 +257,17 @@ const char * kv_str(const gguf_context * g, const char * key, const char * def)
 
 } // namespace
 
+size_t trellis2_gpu_free_vram(void) {
+    ggml_backend_dev_t dev = ggml_backend_dev_by_type(GGML_BACKEND_DEVICE_TYPE_GPU);
+    if (!dev) return 0;                       // CPU-only build/host
+    size_t free = 0, total = 0;
+    ggml_backend_dev_memory(dev, &free, &total);
+    return free;
+}
+
 trellis2_ss_flow_model *
-trellis2_ss_flow_load(const std::string & path, bool load_tensors, std::string * error) {
+trellis2_ss_flow_load(const std::string & path, bool load_tensors, std::string * error,
+                      const char * device) {
     auto * m = new trellis2_ss_flow_model();
 
     // Always parse metadata only; the weights are then allocated on the chosen
@@ -285,7 +323,7 @@ trellis2_ss_flow_load(const std::string & path, bool load_tensors, std::string *
     if (load_tensors) {
         // Allocate all weights on the auto-selected backend, then stream the
         // payloads from the file into that buffer.
-        m->backend = init_best_backend(m->backend_name);
+        m->backend = init_best_backend(m->backend_name, device);
         m->weights_buf = ggml_backend_alloc_ctx_tensors(m->ctx, m->backend);
         if (!m->weights_buf) {
             set_error(error, "failed to allocate weights on backend " + m->backend_name);
@@ -381,6 +419,37 @@ bool trellis2_ss_flow_has_tensor(const trellis2_ss_flow_model * m,
 
 namespace {
 
+// Scaled dot-product attention via ggml_flash_attn_ext (tiled online softmax,
+// O(L) memory). q3/k3/v3 are [head_dim, n_head, L]; returns [n_head*head_dim, L_q].
+//
+// Flash is the default for both flow DiTs: it is bit-faithful to full softmax on
+// CPU with F32 accumulation (validated to ~1e-4 rel-L2, identical to the exact
+// materialized path) but avoids the [L_k, L_q, heads] score matrix — which is
+// both the memory wall (the HR cascade's ~49k voxels would need >100 GB) and,
+// on GPU, ~30% of the forward's wall time (the softmax + the permute/cont copies
+// around it). On the CUDA F16-MMA kernel flash costs ~3e-3 rel-L2 per forward,
+// immaterial to the final mesh. Set TRELLIS2_SDPA_EXACT to force the old
+// materialized path (e.g. to reproduce the tightest GPU numbers).
+ggml_tensor * sdpa_auto(ggml_context * ctx, ggml_tensor * q3, ggml_tensor * k3,
+                        ggml_tensor * v3, int C, float scale) {
+    ggml_tensor * qp = ggml_cont(ctx, ggml_permute(ctx, q3, 0, 2, 1, 3)); // [hd, Lq, H]
+    ggml_tensor * kp = ggml_cont(ctx, ggml_permute(ctx, k3, 0, 2, 1, 3)); // [hd, Lk, H]
+    ggml_tensor * vp = ggml_cont(ctx, ggml_permute(ctx, v3, 0, 2, 1, 3)); // [hd, Lk, H]
+
+    static const bool exact = std::getenv("TRELLIS2_SDPA_EXACT") != nullptr;
+    if (!exact) {
+        ggml_tensor * o = ggml_flash_attn_ext(ctx, qp, kp, vp, nullptr, scale, 0.0f, 0.0f);
+        ggml_flash_attn_ext_set_prec(o, GGML_PREC_F32);
+        return ggml_reshape_2d(ctx, o, C, o->ne[2]);                      // [C, Lq]
+    }
+    ggml_tensor * sc = ggml_mul_mat(ctx, kp, qp);                         // [Lk, Lq, H]
+    sc = ggml_soft_max_ext(ctx, sc, nullptr, scale, 0.0f);
+    ggml_tensor * vt = ggml_cont(ctx, ggml_permute(ctx, vp, 1, 0, 2, 3)); // [Lk, hd, H]
+    ggml_tensor * o  = ggml_mul_mat(ctx, vt, sc);                         // [hd, Lq, H]
+    o = ggml_cont(ctx, ggml_permute(ctx, o, 0, 2, 1, 3));                 // [hd, H, Lq]
+    return ggml_reshape_2d(ctx, o, C, o->ne[2]);                          // [C, Lq]
+}
+
 // Sinusoidal timestep embedding (cos|sin), matching TimestepEmbedder.
 std::vector<float> timestep_embedding(float t, int dim) {
     std::vector<float> e((size_t) dim, 0.0f);
@@ -439,6 +508,11 @@ bool trellis2_ss_flow_forward(trellis2_ss_flow_model * m,
     if (!hp.share_mod)                         { set_error(error, "only share_mod=true is implemented"); return false; }
     if (cond_channels != hp.cond_channels)     { set_error(error, "cond_channels mismatch"); return false; }
 
+    const bool t2_timing = std::getenv("TRELLIS2_TIMING") != nullptr;
+    auto t_now = [] { return std::chrono::steady_clock::now(); };
+    auto t_ms  = [](auto a, auto b) { return std::chrono::duration<double, std::milli>(b - a).count(); };
+    auto t_start = t_now();
+
     const int   C   = hp.model_channels;     // 1536
     const int   R   = hp.resolution;         // 16
     const int   N   = R * R * R;             // 4096 tokens
@@ -497,17 +571,9 @@ bool trellis2_ss_flow_forward(trellis2_ss_flow_model * m,
     auto qk_norm = [&](ggml_tensor * v3, const std::string & gname) {
         return ggml_mul(ctx, ggml_rms_norm(ctx, v3, 1e-12f), W(gname));
     };
-    // scaled-dot-product attention; q3/k3/v3 are [hd, H, Lq]/[hd, H, Lk].
-    auto sdpa = [&](ggml_tensor * q3, ggml_tensor * k3, ggml_tensor * v3) -> ggml_tensor * {
-        ggml_tensor * qp = ggml_cont(ctx, ggml_permute(ctx, q3, 0, 2, 1, 3)); // [hd, Lq, H]
-        ggml_tensor * kp = ggml_cont(ctx, ggml_permute(ctx, k3, 0, 2, 1, 3)); // [hd, Lk, H]
-        ggml_tensor * vp = ggml_cont(ctx, ggml_permute(ctx, v3, 0, 2, 1, 3)); // [hd, Lk, H]
-        ggml_tensor * sc = ggml_mul_mat(ctx, kp, qp);                         // [Lk, Lq, H]
-        sc = ggml_soft_max_ext(ctx, sc, nullptr, attn_scale, 0.0f);
-        ggml_tensor * vt = ggml_cont(ctx, ggml_permute(ctx, vp, 1, 0, 2, 3)); // [Lk, hd, H]
-        ggml_tensor * o  = ggml_mul_mat(ctx, vt, sc);                         // [hd, Lq, H]
-        o = ggml_cont(ctx, ggml_permute(ctx, o, 0, 2, 1, 3));                 // [hd, H, Lq]
-        return ggml_reshape_2d(ctx, o, C, o->ne[2]);                          // [C, Lq]
+    // scaled-dot-product attention (flash: O(L) memory); q3/k3/v3 are [hd,H,L].
+    auto sdpa = [&](ggml_tensor * q3, ggml_tensor * k3, ggml_tensor * v3) {
+        return sdpa_auto(ctx, q3, k3, v3, C, attn_scale);
     };
 
     const size_t es = sizeof(float);
@@ -577,6 +643,7 @@ bool trellis2_ss_flow_forward(trellis2_ss_flow_model * m,
     }
 
     ggml_build_forward_expand(gf, y);
+    auto t_build = t_now();
 
     // ── allocate + run on the model's backend (GPU if available, else CPU) ────
     ggml_backend_t backend = m->backend;
@@ -586,6 +653,7 @@ bool trellis2_ss_flow_forward(trellis2_ss_flow_model * m,
         ggml_gallocr_free(alloc); ggml_free(ctx);
         return false;
     }
+    auto t_alloc = t_now();
 
     std::vector<float> emb = timestep_embedding(t, 256);
     std::vector<float> cosv, sinv;
@@ -596,11 +664,18 @@ bool trellis2_ss_flow_forward(trellis2_ss_flow_model * m,
     ggml_backend_tensor_set(cos_t, cosv.data(), 0, cosv.size() * es);
     ggml_backend_tensor_set(sin_t, sinv.data(), 0, sinv.size() * es);
     ggml_backend_tensor_set(cnd,   cond,        0, (size_t) cond_channels * Lkv * es);
+    auto t_upload = t_now();
 
     const ggml_status st = ggml_backend_graph_compute(backend, gf);
+    auto t_compute = t_now();
     bool ok = (st == GGML_STATUS_SUCCESS);
     if (ok) {
         ggml_backend_tensor_get(y, out, 0, (size_t) hp.out_channels * N * es);
+        if (t2_timing) {
+            std::fprintf(stderr, "[ss_flow] build=%.1f alloc=%.1f upload=%.1f compute=%.1f read=%.1f total=%.1f ms\n",
+                         t_ms(t_start, t_build), t_ms(t_build, t_alloc), t_ms(t_alloc, t_upload),
+                         t_ms(t_upload, t_compute), t_ms(t_compute, t_now()), t_ms(t_start, t_now()));
+        }
     } else {
         set_error(error, "graph compute failed");
     }
@@ -686,6 +761,8 @@ bool trellis2_ss_flow_sample(trellis2_ss_flow_model * m,
 
     const std::vector<float> zero_cond((size_t) cond_tokens * cond_channels, 0.0f);
     std::vector<float> pred_pos(n), pred_neg(n), pred_v(n), x0_pos(n), x0_cfg(n);
+    std::vector<float> x0_view;   // scratch for the live-preview x_0 estimate
+    if (P.preview) x0_view.resize(n);
 
     auto fwd = [&](double t, const float * c, std::vector<float> & dst) -> bool {
         return trellis2_ss_flow_forward(m, x_t.data(), (float) (1000.0 * t),
@@ -721,6 +798,13 @@ bool trellis2_ss_flow_sample(trellis2_ss_flow_model * m,
             }
         }
 
+        // Live preview: the denoised x_0 estimate at this step (best guess of the
+        // clean latent), computed from x_t@t before the Euler step overwrites it.
+        if (P.preview) {
+            pred_to_xstart(x_t, t, sm, pred_v, x0_view);
+            P.preview(P.preview_user, i + 1, P.steps, x0_view.data(), (int) n);
+        }
+
         // Euler step: x_{t-1} = x_t - (t - t_prev) * v
         const double dt = t - t_prev;
         for (size_t k = 0; k < n; ++k) x_t[k] = (float) (x_t[k] - dt * pred_v[k]);
@@ -730,6 +814,7 @@ bool trellis2_ss_flow_sample(trellis2_ss_flow_model * m,
                          i + 1, P.steps, t, t_prev, in_interval ? "cfg" : "uncond");
             std::fflush(stderr);
         }
+        if (P.progress) P.progress(P.progress_user, i + 1, P.steps);
     }
     if (P.verbose) std::fprintf(stderr, "\n");
 
@@ -766,7 +851,8 @@ struct trellis2_ss_dec_model {
 };
 
 trellis2_ss_dec_model *
-trellis2_ss_dec_load(const std::string & path, bool load_tensors, std::string * error) {
+trellis2_ss_dec_load(const std::string & path, bool load_tensors, std::string * error,
+                     const char * device) {
     auto * m = new trellis2_ss_dec_model();
 
     gguf_init_params params;
@@ -812,7 +898,7 @@ trellis2_ss_dec_load(const std::string & path, bool load_tensors, std::string *
     }
 
     if (load_tensors) {
-        m->backend = init_best_backend(m->backend_name);
+        m->backend = init_best_backend(m->backend_name, device);
         m->weights_buf = ggml_backend_alloc_ctx_tensors(m->ctx, m->backend);
         if (!m->weights_buf) {
             set_error(error, "failed to allocate weights on backend " + m->backend_name);
@@ -1019,3 +1105,2316 @@ bool trellis2_ss_dec_decode(trellis2_ss_dec_model * m,
     ggml_free(ctx);
     return ok;
 }
+
+/*****************************************************************************
+** DINOv3 ViT-L/16 image-conditioning encoder — GGUF loader
+*****************************************************************************/
+
+struct trellis2_dino_model {
+    gguf_context * gguf = nullptr;
+    ggml_context * ctx  = nullptr;
+    trellis2_dino_hparams hp;
+    bool has_data = false;
+
+    ggml_backend_t        backend     = nullptr;
+    ggml_backend_buffer_t weights_buf = nullptr;
+    std::string           backend_name;
+
+    std::unordered_map<std::string, ggml_tensor *> tensors;
+};
+
+trellis2_dino_model *
+trellis2_dino_load(const std::string & path, bool load_tensors, std::string * error,
+                   const char * device) {
+    auto * m = new trellis2_dino_model();
+
+    gguf_init_params params;
+    params.no_alloc = true;
+    params.ctx      = &m->ctx;
+
+    m->gguf = gguf_init_from_file(path.c_str(), params);
+    if (!m->gguf) {
+        set_error(error, "gguf_init_from_file failed (not a GGUF file?): " + path);
+        delete m;
+        return nullptr;
+    }
+
+    const char * arch = kv_str(m->gguf, "general.architecture", "");
+    if (std::strcmp(arch, "trellis2-dino") != 0) {
+        set_error(error, std::string("unexpected architecture '") + arch +
+                         "' (expected 'trellis2-dino')");
+        trellis2_dino_free(m);
+        return nullptr;
+    }
+
+    trellis2_dino_hparams & hp = m->hp;
+    const char * P = "trellis2.dino.";
+    auto K = [&](const char * suffix) { return std::string(P) + suffix; };
+
+    hp.hidden_size         = (int32_t) kv_u32(m->gguf, K("hidden_size").c_str(),         0);
+    hp.n_layers            = (int32_t) kv_u32(m->gguf, K("n_layers").c_str(),            0);
+    hp.n_heads             = (int32_t) kv_u32(m->gguf, K("n_heads").c_str(),             0);
+    hp.intermediate_size   = (int32_t) kv_u32(m->gguf, K("intermediate_size").c_str(),   0);
+    hp.patch_size          = (int32_t) kv_u32(m->gguf, K("patch_size").c_str(),          16);
+    hp.num_register_tokens = (int32_t) kv_u32(m->gguf, K("num_register_tokens").c_str(), 0);
+    hp.layer_norm_eps      =           kv_f32(m->gguf, K("layer_norm_eps").c_str(),      1e-5f);
+    hp.rope_theta          =           kv_f32(m->gguf, K("rope_theta").c_str(),          100.0f);
+    hp.file_type           = (int32_t) kv_u32(m->gguf, "general.file_type", 0);
+    for (int c = 0; c < 3; ++c) {
+        hp.image_mean[c] = kv_f32(m->gguf, (K("image_mean.") + std::to_string(c)).c_str(), hp.image_mean[c]);
+        hp.image_std[c]  = kv_f32(m->gguf, (K("image_std.")  + std::to_string(c)).c_str(), hp.image_std[c]);
+    }
+
+    for (ggml_tensor * t = ggml_get_first_tensor(m->ctx); t != nullptr;
+         t = ggml_get_next_tensor(m->ctx, t)) {
+        m->tensors[t->name] = t;
+    }
+
+    if (load_tensors) {
+        m->backend = init_best_backend(m->backend_name, device);
+        m->weights_buf = ggml_backend_alloc_ctx_tensors(m->ctx, m->backend);
+        if (!m->weights_buf) {
+            set_error(error, "failed to allocate weights on backend " + m->backend_name);
+            trellis2_dino_free(m);
+            return nullptr;
+        }
+
+        std::ifstream fin(path, std::ios::binary);
+        if (!fin) {
+            set_error(error, "cannot reopen file for weight data: " + path);
+            trellis2_dino_free(m);
+            return nullptr;
+        }
+        const size_t data_off = gguf_get_data_offset(m->gguf);
+        const int64_t nt = gguf_get_n_tensors(m->gguf);
+        std::vector<uint8_t> buf;
+        for (int64_t i = 0; i < nt; ++i) {
+            const char * name = gguf_get_tensor_name(m->gguf, i);
+            ggml_tensor * t = m->tensors[name];
+            const size_t nb  = ggml_nbytes(t);
+            const size_t off = data_off + gguf_get_tensor_offset(m->gguf, i);
+            buf.resize(nb);
+            fin.seekg((std::streamoff) off, std::ios::beg);
+            if (!fin.read(reinterpret_cast<char *>(buf.data()), (std::streamsize) nb)) {
+                set_error(error, std::string("failed reading weight '") + name + "' from file");
+                trellis2_dino_free(m);
+                return nullptr;
+            }
+            ggml_backend_tensor_set(t, buf.data(), 0, nb);
+        }
+        m->has_data = true;
+    }
+
+    return m;
+}
+
+void trellis2_dino_free(trellis2_dino_model * m) {
+    if (!m) return;
+    if (m->weights_buf) ggml_backend_buffer_free(m->weights_buf);
+    if (m->backend)     ggml_backend_free(m->backend);
+    if (m->gguf)        gguf_free(m->gguf);
+    if (m->ctx)         ggml_free(m->ctx);
+    delete m;
+}
+
+const char * trellis2_dino_backend_name(const trellis2_dino_model * m) {
+    return (m && !m->backend_name.empty()) ? m->backend_name.c_str() : "none";
+}
+
+const trellis2_dino_hparams &
+trellis2_dino_hparams_of(const trellis2_dino_model * m) {
+    return m->hp;
+}
+
+/*****************************************************************************
+** DINOv3 — forward pass
+**
+** Mirrors DinoV3FeatureExtractor.extract_features:
+**   h = embeddings(pixels)            # patch conv + [CLS | 4 reg | patches]
+**   cos,sin = rope_embeddings(pixels) # axial 2D RoPE over patch centers
+**   for each of 24 layers:            # pre-norm ViT block with LayerScale
+**     h += ls1 * attn(LN1(h))         #   (RoPE on patch tokens only)
+**     h += ls2 * mlp(LN2(h))          #   (exact-GELU MLP)
+**   cond = layer_norm(h)              # affine-free; model.norm NOT applied
+*****************************************************************************/
+
+namespace {
+
+// Axial 2D RoPE tables for a Wp x Hp patch grid, matching HF's
+// DINOv3ViTRopePositionEmbedding in eval mode (no shift/jitter/rescale):
+//   inv_freq[j] = 1 / theta^(4j/hd),  j < hd/4
+//   angles(p)   = 2*pi * [cy, cx] (x) inv_freq   -> [hd/2], tiled to [hd]
+// with (cy, cx) the patch-center coords normalized to [-1, 1].
+// Output buffers are [P][hd] row-major (== ggml ne [hd, 1, P]).
+void dino_rope_tables(int hp_grid, int wp_grid, int head_dim, float theta,
+                      std::vector<float> & cos_t, std::vector<float> & sin_t) {
+    const int quarter = head_dim / 4;
+    std::vector<double> inv_freq((size_t) quarter);
+    for (int j = 0; j < quarter; ++j) {
+        inv_freq[j] = 1.0 / std::pow((double) theta, (double) j * 4.0 / (double) head_dim);
+    }
+
+    const int P = hp_grid * wp_grid;
+    cos_t.resize((size_t) P * head_dim);
+    sin_t.resize((size_t) P * head_dim);
+    for (int py = 0; py < hp_grid; ++py) {
+        const double cy = 2.0 * (((double) py + 0.5) / (double) hp_grid) - 1.0;
+        for (int px = 0; px < wp_grid; ++px) {
+            const double cx = 2.0 * (((double) px + 0.5) / (double) wp_grid) - 1.0;
+            const size_t base = (size_t) (py * wp_grid + px) * head_dim;
+            for (int j = 0; j < quarter; ++j) {
+                const double ay = 2.0 * M_PI * cy * inv_freq[j];
+                const double ax = 2.0 * M_PI * cx * inv_freq[j];
+                // angles layout: [cy*f..., cx*f...] then tiled x2
+                const float cy_c = (float) std::cos(ay), cy_s = (float) std::sin(ay);
+                const float cx_c = (float) std::cos(ax), cx_s = (float) std::sin(ax);
+                cos_t[base + j]               = cy_c;
+                cos_t[base + quarter + j]     = cx_c;
+                cos_t[base + 2 * quarter + j] = cy_c;
+                cos_t[base + 3 * quarter + j] = cx_c;
+                sin_t[base + j]               = cy_s;
+                sin_t[base + quarter + j]     = cx_s;
+                sin_t[base + 2 * quarter + j] = cy_s;
+                sin_t[base + 3 * quarter + j] = cx_s;
+            }
+        }
+    }
+}
+
+} // namespace
+
+bool trellis2_dino_encode(trellis2_dino_model * m,
+                          const float * pixel_values, int image_size,
+                          trellis2_dino_cond & out,
+                          trellis2_dino_taps * taps,
+                          std::string * error) {
+    if (!m)           { set_error(error, "null model"); return false; }
+    if (!m->has_data) { set_error(error, "model loaded metadata-only; reload with load_tensors=true"); return false; }
+
+    const trellis2_dino_hparams & hp = m->hp;
+    const int S = image_size;
+    if (S <= 0 || S % hp.patch_size != 0) {
+        set_error(error, "image_size must be a positive multiple of patch_size");
+        return false;
+    }
+    const int  Wp  = S / hp.patch_size;          // 32 @ 512
+    const int  P   = Wp * Wp;                    // 1024 patch tokens
+    const int  Npre= 1 + hp.num_register_tokens; // CLS + registers
+    const int  N   = Npre + P;                   // 1029 tokens
+    const int  C   = hp.hidden_size;             // 1024
+    const int  H   = hp.n_heads;                 // 16
+    const int  hd  = hp.head_dim();              // 64
+    const float attn_scale = 1.0f / std::sqrt((float) hd);
+    const float eps = hp.layer_norm_eps;
+
+    std::string missing;
+    auto W = [&](const std::string & n) -> ggml_tensor * {
+        auto it = m->tensors.find(n);
+        if (it == m->tensors.end()) { if (missing.empty()) missing = n; return nullptr; }
+        return it->second;
+    };
+    auto Wopt = [&](const std::string & n) -> ggml_tensor * {
+        auto it = m->tensors.find(n);
+        return it == m->tensors.end() ? nullptr : it->second;
+    };
+
+    const size_t mem = ggml_tensor_overhead() * 8192 + ggml_graph_overhead_custom(8192, false);
+    ggml_init_params ip{ mem, nullptr, /*no_alloc*/ true };
+    ggml_context * ctx = ggml_init(ip);
+    ggml_cgraph * gf = ggml_new_graph_custom(ctx, 8192, false);
+
+    // ── input leaves ─────────────────────────────────────────────────────────
+    ggml_tensor * pix   = ggml_new_tensor_4d(ctx, GGML_TYPE_F32, S, S, 3, 1); // CHW flat
+    ggml_tensor * cos_t = ggml_new_tensor_3d(ctx, GGML_TYPE_F32, hd, 1, P);
+    ggml_tensor * sin_t = ggml_new_tensor_3d(ctx, GGML_TYPE_F32, hd, 1, P);
+    ggml_set_input(pix);
+    ggml_set_input(cos_t);
+    ggml_set_input(sin_t);
+
+    // Tap bookkeeping: tensors registered here are marked as graph outputs and
+    // copied to the host after compute. All taps are [C, N]-contiguous, whose
+    // memory order equals the reference's row-major [N, C].
+    std::vector<std::pair<std::string, ggml_tensor *>> tap_list;
+    auto tap = [&](const std::string & name, ggml_tensor * t) {
+        if (!taps) return;
+        ggml_tensor * c = ggml_cont(ctx, t);
+        ggml_set_output(c);
+        ggml_build_forward_expand(gf, c);
+        tap_list.emplace_back(name, c);
+    };
+    tap("rope_0", cos_t);   // [hd,1,P] contiguous == reference's [P, hd]
+    tap("rope_1", sin_t);
+
+    auto lin = [&](ggml_tensor * in, const std::string & pfx) -> ggml_tensor * {
+        ggml_tensor * y = ggml_mul_mat(ctx, W(pfx + ".weight"), in);
+        ggml_tensor * b = Wopt(pfx + ".bias");
+        if (b) y = ggml_add(ctx, y, b);
+        return y;
+    };
+    // affine LayerNorm over channels of a [C, N] tensor
+    auto lnorm = [&](ggml_tensor * h, const std::string & pfx) -> ggml_tensor * {
+        ggml_tensor * y = ggml_norm(ctx, h, eps);
+        y = ggml_mul(ctx, y, W(pfx + ".weight"));
+        y = ggml_add(ctx, y, W(pfx + ".bias"));
+        return y;
+    };
+    // half-split RoPE on a [hd, H, P] tensor: x*cos + rotate_half(x)*sin
+    auto rope = [&](ggml_tensor * q3) -> ggml_tensor * {
+        const size_t half_off = (size_t) (hd / 2) * sizeof(float);
+        ggml_tensor * x1 = ggml_cont(ctx, ggml_view_3d(ctx, q3, hd / 2, H, P,
+                                                       q3->nb[1], q3->nb[2], 0));
+        ggml_tensor * x2 = ggml_cont(ctx, ggml_view_3d(ctx, q3, hd / 2, H, P,
+                                                       q3->nb[1], q3->nb[2], half_off));
+        ggml_tensor * rh = ggml_concat(ctx, ggml_neg(ctx, x2), x1, 0);       // [hd,H,P]
+        return ggml_add(ctx, ggml_mul(ctx, q3, cos_t), ggml_mul(ctx, rh, sin_t));
+    };
+    // RoPE on patch tokens only of a [hd, H, N] tensor (prefix passes through).
+    auto rope_patches = [&](ggml_tensor * q3) -> ggml_tensor * {
+        ggml_tensor * pre = ggml_cont(ctx, ggml_view_3d(ctx, q3, hd, H, Npre,
+                                                        q3->nb[1], q3->nb[2], 0));
+        ggml_tensor * pat = ggml_cont(ctx, ggml_view_3d(ctx, q3, hd, H, P,
+                                                        q3->nb[1], q3->nb[2], (size_t) Npre * q3->nb[2]));
+        return ggml_concat(ctx, pre, rope(pat), 2);
+    };
+    // scaled-dot-product attention; q3/k3/v3 are [hd, H, N].
+    auto sdpa = [&](ggml_tensor * q3, ggml_tensor * k3, ggml_tensor * v3) -> ggml_tensor * {
+        ggml_tensor * qp = ggml_cont(ctx, ggml_permute(ctx, q3, 0, 2, 1, 3)); // [hd, N, H]
+        ggml_tensor * kp = ggml_cont(ctx, ggml_permute(ctx, k3, 0, 2, 1, 3));
+        ggml_tensor * vp = ggml_cont(ctx, ggml_permute(ctx, v3, 0, 2, 1, 3));
+        ggml_tensor * sc = ggml_mul_mat(ctx, kp, qp);                         // [Nk, Nq, H]
+        sc = ggml_soft_max_ext(ctx, sc, nullptr, attn_scale, 0.0f);
+        ggml_tensor * vt = ggml_cont(ctx, ggml_permute(ctx, vp, 1, 0, 2, 3)); // [Nk, hd, H]
+        ggml_tensor * o  = ggml_mul_mat(ctx, vt, sc);                         // [hd, Nq, H]
+        o = ggml_cont(ctx, ggml_permute(ctx, o, 0, 2, 1, 3));                 // [hd, H, Nq]
+        return ggml_reshape_2d(ctx, o, C, o->ne[2]);                          // [C, Nq]
+    };
+
+    // ── embeddings: patch conv + CLS + register tokens ───────────────────────
+    ggml_tensor * pconv = ggml_conv_2d(ctx, W("embeddings.patch_embeddings.weight"), pix,
+                                       hp.patch_size, hp.patch_size, 0, 0, 1, 1); // [Wp, Wp, C, 1]
+    pconv = ggml_reshape_2d(ctx, pconv, P, C);                    // [P, C] (token-fastest)
+    pconv = ggml_cont(ctx, ggml_transpose(ctx, pconv));           // [C, P]
+    pconv = ggml_add(ctx, pconv, W("embeddings.patch_embeddings.bias"));
+
+    ggml_tensor * h = ggml_concat(ctx, W("embeddings.cls_token"),
+                                  ggml_concat(ctx, W("embeddings.register_tokens"), pconv, 1), 1); // [C, N]
+    h = ggml_cont(ctx, h);
+    tap("embd", h);
+
+    // ── transformer layers ───────────────────────────────────────────────────
+    const bool detail_first_last = true;
+    for (int i = 0; i < hp.n_layers; ++i) {
+        const std::string blk = "layer." + std::to_string(i);
+        const bool detail = taps && detail_first_last && (i == 0 || i == hp.n_layers - 1);
+        auto tn = [&](const char * s) { return "l" + std::to_string(i) + "." + s; };
+        (void) tn;
+
+        ggml_tensor * hn = lnorm(h, blk + ".norm1");
+        if (detail) tap(tn("norm1"), hn);
+
+        ggml_tensor * q = ggml_reshape_3d(ctx, lin(hn, blk + ".attention.q_proj"), hd, H, N);
+        ggml_tensor * k = ggml_reshape_3d(ctx, lin(hn, blk + ".attention.k_proj"), hd, H, N);
+        ggml_tensor * v = ggml_reshape_3d(ctx, lin(hn, blk + ".attention.v_proj"), hd, H, N);
+        q = rope_patches(q);
+        k = rope_patches(k);
+        ggml_tensor * sa = lin(sdpa(q, k, v), blk + ".attention.o_proj");     // [C, N]
+        if (detail) tap(tn("attention"), sa);
+
+        ggml_tensor * ls1 = ggml_mul(ctx, sa, W(blk + ".layer_scale1.lambda1"));
+        if (detail) tap(tn("layer_scale1"), ls1);
+        h = ggml_add(ctx, h, ls1);
+
+        ggml_tensor * h2 = lnorm(h, blk + ".norm2");
+        if (detail) tap(tn("norm2"), h2);
+        ggml_tensor * mlp = lin(h2, blk + ".mlp.up_proj");
+        mlp = ggml_gelu_erf(ctx, mlp);
+        mlp = lin(mlp, blk + ".mlp.down_proj");
+        if (detail) tap(tn("mlp"), mlp);
+        ggml_tensor * ls2 = ggml_mul(ctx, mlp, W(blk + ".layer_scale2.lambda1"));
+        if (detail) tap(tn("layer_scale2"), ls2);
+        h = ggml_add(ctx, h, ls2);
+
+        tap("l" + std::to_string(i) + ".out", h);
+    }
+
+    // ── affine-free final LayerNorm (F.layer_norm, eps 1e-5) ─────────────────
+    ggml_tensor * cond = ggml_norm(ctx, h, 1e-5f);
+    cond = ggml_cont(ctx, cond);   // [C, N] contiguous == row-major [N, C]
+    ggml_set_output(cond);
+    tap("cond", cond);
+
+    if (!missing.empty()) {
+        set_error(error, "missing tensor: " + missing);
+        ggml_free(ctx);
+        return false;
+    }
+
+    ggml_build_forward_expand(gf, cond);
+
+    ggml_backend_t backend = m->backend;
+    ggml_gallocr_t alloc   = ggml_gallocr_new(ggml_backend_get_default_buffer_type(backend));
+    if (!ggml_gallocr_alloc_graph(alloc, gf)) {
+        set_error(error, "ggml_gallocr_alloc_graph failed");
+        ggml_gallocr_free(alloc); ggml_free(ctx);
+        return false;
+    }
+
+    std::vector<float> cosv, sinv;
+    dino_rope_tables(Wp, Wp, hd, hp.rope_theta, cosv, sinv);
+
+    const size_t es = sizeof(float);
+    ggml_backend_tensor_set(pix,   pixel_values, 0, (size_t) 3 * S * S * es);
+    ggml_backend_tensor_set(cos_t, cosv.data(),  0, cosv.size() * es);
+    ggml_backend_tensor_set(sin_t, sinv.data(),  0, sinv.size() * es);
+
+    const ggml_status st = ggml_backend_graph_compute(backend, gf);
+    bool ok = (st == GGML_STATUS_SUCCESS);
+    if (ok) {
+        out.shape = {1, (int64_t) N, (int64_t) C};
+        out.data.resize((size_t) N * C);
+        out.format_version = 1;
+        ggml_backend_tensor_get(cond, out.data.data(), 0, out.data.size() * es);
+
+        if (taps) {
+            for (auto & nt : tap_list) {
+                taps->names.push_back(nt.first);
+                std::vector<float> buf(ggml_nelements(nt.second));
+                ggml_backend_tensor_get(nt.second, buf.data(), 0, buf.size() * es);
+                taps->data.push_back(std::move(buf));
+            }
+        }
+    } else {
+        set_error(error, "graph compute failed");
+    }
+
+    ggml_gallocr_free(alloc);
+    ggml_free(ctx);
+    return ok;
+}
+
+bool trellis2_dino_encode_rgb(trellis2_dino_model * m,
+                              const uint8_t * rgb, int image_size,
+                              trellis2_dino_cond & out,
+                              std::string * error) {
+    if (!m) { set_error(error, "null model"); return false; }
+    const trellis2_dino_hparams & hp = m->hp;
+    const size_t S = (size_t) image_size;
+    std::vector<float> pix(3 * S * S);
+    for (int c = 0; c < 3; ++c) {
+        const float mean = hp.image_mean[c], sd = hp.image_std[c];
+        for (size_t i = 0; i < S * S; ++i) {
+            pix[(size_t) c * S * S + i] = ((float) rgb[i * 3 + c] / 255.0f - mean) / sd;
+        }
+    }
+    return trellis2_dino_encode(m, pix.data(), image_size, out, nullptr, error);
+}
+
+/*****************************************************************************
+** Image preprocessing (pipeline.preprocess_image, has_alpha path)
+**
+** The resampler reproduces PIL's 8-bit fixed-point separable Lanczos-3
+** (Pillow Resample.c): double-precision coefficient windows normalized per
+** output pixel, quantized to integers at PRECISION_BITS, horizontal pass then
+** vertical pass with uint8 rounding between passes. This makes the C++
+** preprocessing byte-identical to the Python reference on the same input.
+*****************************************************************************/
+
+namespace {
+
+constexpr int PIL_PRECISION_BITS = 32 - 8 - 2;
+
+inline double pil_sinc(double x) {
+    if (x == 0.0) return 1.0;
+    const double px = M_PI * x;
+    return std::sin(px) / px;
+}
+inline double pil_lanczos3(double x) {
+    if (x >= -3.0 && x < 3.0) return pil_sinc(x) * pil_sinc(x / 3.0);
+    return 0.0;
+}
+
+inline uint8_t pil_clip8(int64_t in) {
+    if (in >= ((int64_t) 1 << PIL_PRECISION_BITS << 8)) return 255;
+    if (in <= 0) return 0;
+    return (uint8_t) (in >> PIL_PRECISION_BITS);
+}
+
+// Coefficient windows for one axis (PIL precompute_coeffs + normalize_8bpc).
+void pil_coeffs(int in_size, int out_size,
+                std::vector<int> & bounds, std::vector<int32_t> & kk, int & ksize) {
+    const double support0 = 3.0; // Lanczos
+    const double scale = (double) in_size / (double) out_size;
+    const double filterscale = scale < 1.0 ? 1.0 : scale;
+    const double support = support0 * filterscale;
+    ksize = (int) std::ceil(support) * 2 + 1;
+
+    std::vector<double> k((size_t) ksize);
+    bounds.resize((size_t) out_size * 2);
+    kk.resize((size_t) out_size * ksize);
+
+    for (int xx = 0; xx < out_size; ++xx) {
+        const double center = ((double) xx + 0.5) * scale;
+        const double ss = 1.0 / filterscale;
+        int xmin = (int) (center - support + 0.5);
+        if (xmin < 0) xmin = 0;
+        int xmax = (int) (center + support + 0.5);
+        if (xmax > in_size) xmax = in_size;
+        xmax -= xmin;
+
+        double ww = 0.0;
+        for (int x = 0; x < xmax; ++x) {
+            const double w = pil_lanczos3(((double) (x + xmin) - center + 0.5) * ss);
+            k[(size_t) x] = w;
+            ww += w;
+        }
+        for (int x = 0; x < xmax; ++x) {
+            if (ww != 0.0) k[(size_t) x] /= ww;
+        }
+        for (int x = 0; x < xmax; ++x) {
+            const double w = k[(size_t) x] * (double) (1 << PIL_PRECISION_BITS);
+            kk[(size_t) xx * ksize + x] = (int32_t) (w < 0 ? w - 0.5 : w + 0.5);
+        }
+        for (int x = xmax; x < ksize; ++x) kk[(size_t) xx * ksize + x] = 0;
+        bounds[(size_t) xx * 2 + 0] = xmin;
+        bounds[(size_t) xx * 2 + 1] = xmax;
+    }
+}
+
+// Separable resample of an interleaved uint8 image (any channel count),
+// horizontal pass then vertical pass, PIL-compatible.
+void pil_resize(const uint8_t * in, int w, int h, int ch,
+                int out_w, int out_h, std::vector<uint8_t> & out) {
+    std::vector<int> bounds;
+    std::vector<int32_t> kk;
+    int ksize = 0;
+
+    // horizontal: [h, w] -> [h, out_w]
+    std::vector<uint8_t> tmp((size_t) h * out_w * ch);
+    pil_coeffs(w, out_w, bounds, kk, ksize);
+    for (int y = 0; y < h; ++y) {
+        const uint8_t * row = in + (size_t) y * w * ch;
+        uint8_t * orow = tmp.data() + (size_t) y * out_w * ch;
+        for (int xx = 0; xx < out_w; ++xx) {
+            const int xmin = bounds[(size_t) xx * 2 + 0];
+            const int xmax = bounds[(size_t) xx * 2 + 1];
+            const int32_t * k = kk.data() + (size_t) xx * ksize;
+            for (int c = 0; c < ch; ++c) {
+                int64_t ss = (int64_t) 1 << (PIL_PRECISION_BITS - 1);
+                for (int x = 0; x < xmax; ++x) {
+                    ss += (int64_t) row[(size_t) (x + xmin) * ch + c] * k[x];
+                }
+                orow[(size_t) xx * ch + c] = pil_clip8(ss);
+            }
+        }
+    }
+
+    // vertical: [h, out_w] -> [out_h, out_w]
+    out.resize((size_t) out_h * out_w * ch);
+    pil_coeffs(h, out_h, bounds, kk, ksize);
+    for (int yy = 0; yy < out_h; ++yy) {
+        const int ymin = bounds[(size_t) yy * 2 + 0];
+        const int ymax = bounds[(size_t) yy * 2 + 1];
+        const int32_t * k = kk.data() + (size_t) yy * ksize;
+        uint8_t * orow = out.data() + (size_t) yy * out_w * ch;
+        for (int xx = 0; xx < out_w; ++xx) {
+            for (int c = 0; c < ch; ++c) {
+                int64_t ss = (int64_t) 1 << (PIL_PRECISION_BITS - 1);
+                for (int y = 0; y < ymax; ++y) {
+                    ss += (int64_t) tmp[(size_t) (y + ymin) * out_w * ch + (size_t) xx * ch + c] * k[y];
+                }
+                orow[(size_t) xx * ch + c] = pil_clip8(ss);
+            }
+        }
+    }
+}
+
+// Python round() (banker's rounding) for the .0/.5 values PIL's crop sees.
+inline int py_round_half_even(double v) {
+    const double fl = std::floor(v);
+    const double frac = v - fl;
+    if (frac < 0.5) return (int) fl;
+    if (frac > 0.5) return (int) fl + 1;
+    const int lo = (int) fl;
+    return (lo % 2 == 0) ? lo : lo + 1;
+}
+
+} // namespace
+
+int trellis2_remove_solid_background_rgba(uint8_t * rgba, int w, int h, int mode) {
+    if (!rgba || w <= 0 || h <= 0 ||
+        mode < TRELLIS2_BACKGROUND_AUTO || mode > TRELLIS2_BACKGROUND_WHITE) {
+        return -1;
+    }
+    if (mode == TRELLIS2_BACKGROUND_KEEP) return 0;
+
+    const size_t count = (size_t) w * h;
+    if (mode == TRELLIS2_BACKGROUND_AUTO) {
+        // An already-masked PNG should be trusted. Requiring more than both 1%
+        // and four pixels avoids treating a stray transparent metadata pixel as
+        // a meaningful subject mask.
+        size_t translucent = 0;
+        for (size_t i = 0; i < count; ++i) translucent += rgba[i * 4 + 3] < 250;
+        if (translucent > std::max<size_t>(4, count / 100)) return 0;
+
+        int border = 0, dark = 0, light = 0;
+        auto sample = [&](int x, int y) {
+            const uint8_t * p = rgba + ((size_t) y * w + x) * 4;
+            const int lo = std::min((int) p[0], std::min((int) p[1], (int) p[2]));
+            const int hi = std::max((int) p[0], std::max((int) p[1], (int) p[2]));
+            ++border;
+            dark  += hi <= 80;
+            light += lo >= 175;
+        };
+        for (int x = 0; x < w; ++x) {
+            sample(x, 0);
+            if (h > 1) sample(x, h - 1);
+        }
+        for (int y = 1; y + 1 < h; ++y) {
+            sample(0, y);
+            if (w > 1) sample(w - 1, y);
+        }
+        int dark_corners = 0, light_corners = 0;
+        const int corners[4][2] = {{0, 0}, {w - 1, 0}, {0, h - 1}, {w - 1, h - 1}};
+        for (const auto & c : corners) {
+            const uint8_t * p = rgba + ((size_t) c[1] * w + c[0]) * 4;
+            const int lo = std::min((int) p[0], std::min((int) p[1], (int) p[2]));
+            const int hi = std::max((int) p[0], std::max((int) p[1], (int) p[2]));
+            dark_corners += hi <= 80;
+            light_corners += lo >= 175;
+        }
+        const bool is_dark = dark * 100 >= border * 55 || dark_corners >= 3;
+        const bool is_light = light * 100 >= border * 55 || light_corners >= 3;
+        if (!is_dark && !is_light) return 0;
+        mode = is_dark && (!is_light || dark >= light)
+             ? TRELLIS2_BACKGROUND_BLACK : TRELLIS2_BACKGROUND_WHITE;
+    }
+
+    auto distance = [&](size_t i) {
+        const uint8_t * p = rgba + i * 4;
+        if (mode == TRELLIS2_BACKGROUND_BLACK) {
+            return std::max((int) p[0], std::max((int) p[1], (int) p[2]));
+        }
+        const int lo = std::min((int) p[0], std::min((int) p[1], (int) p[2]));
+        return 255 - lo;
+    };
+    auto eligible = [&](size_t i) { return distance(i) <= 80; };
+
+    std::vector<uint8_t> seen(count, 0);
+    std::vector<size_t> queue;
+    queue.reserve(std::min<size_t>(count, (size_t) 1 << 20));
+    auto seed = [&](int x, int y) {
+        const size_t i = (size_t) y * w + x;
+        if (!seen[i] && eligible(i)) {
+            seen[i] = 1;
+            queue.push_back(i);
+        }
+    };
+    for (int x = 0; x < w; ++x) {
+        seed(x, 0);
+        if (h > 1) seed(x, h - 1);
+    }
+    for (int y = 1; y + 1 < h; ++y) {
+        seed(0, y);
+        if (w > 1) seed(w - 1, y);
+    }
+
+    int changed = 0;
+    for (size_t head = 0; head < queue.size(); ++head) {
+        const size_t i = queue[head];
+        const int d = distance(i);
+        float t = (float) (d - 12) / (72.0f - 12.0f);
+        t = std::max(0.0f, std::min(1.0f, t));
+        t = t * t * (3.0f - 2.0f * t); // smooth feather, background -> subject
+        uint8_t * p = rgba + i * 4;
+        const uint8_t a = (uint8_t) std::lround((float) p[3] * t);
+        if (a != p[3]) {
+            p[3] = a;
+            ++changed;
+        }
+
+        const int x = (int) (i % (size_t) w), y = (int) (i / (size_t) w);
+        auto visit = [&](size_t n) {
+            if (!seen[n] && eligible(n)) {
+                seen[n] = 1;
+                queue.push_back(n);
+            }
+        };
+        if (x > 0) visit(i - 1);
+        if (x + 1 < w) visit(i + 1);
+        if (y > 0) visit(i - (size_t) w);
+        if (y + 1 < h) visit(i + (size_t) w);
+    }
+    return changed;
+}
+
+bool trellis2_preprocess_rgba(const uint8_t * rgba, int w, int h,
+                              int out_size, std::vector<uint8_t> & out_rgb,
+                              std::string * error) {
+    if (!rgba || w <= 0 || h <= 0 || out_size <= 0) {
+        set_error(error, "invalid arguments");
+        return false;
+    }
+
+    // 1. downscale so max(W, H) <= 1024 (PIL: int(dim * scale) floor)
+    std::vector<uint8_t> img(rgba, rgba + (size_t) w * h * 4);
+    const int max_size = w > h ? w : h;
+    if (max_size > 1024) {
+        const double scale = 1024.0 / (double) max_size;
+        const int nw = (int) ((double) w * scale);
+        const int nh = (int) ((double) h * scale);
+        std::vector<uint8_t> resized;
+        pil_resize(img.data(), w, h, 4, nw, nh, resized);
+        img = std::move(resized);
+        w = nw;
+        h = nh;
+    }
+
+    // 2. bounding box of alpha > 0.8*255, square crop centered on it
+    int x0 = w, y0 = h, x1 = -1, y1 = -1;
+    for (int y = 0; y < h; ++y) {
+        for (int x = 0; x < w; ++x) {
+            if (img[((size_t) y * w + x) * 4 + 3] > 204) {  // 0.8*255 = 204.0
+                if (x < x0) x0 = x;
+                if (x > x1) x1 = x;
+                if (y < y0) y0 = y;
+                if (y > y1) y1 = y;
+            }
+        }
+    }
+    if (x1 < 0) {
+        set_error(error, "image has no pixels with alpha > 0.8 (fully transparent?)");
+        return false;
+    }
+
+    const double cx = (double) (x0 + x1) / 2.0;
+    const double cy = (double) (y0 + y1) / 2.0;
+    const int size = (x1 - x0) > (y1 - y0) ? (x1 - x0) : (y1 - y0);
+    const int half = size / 2;
+
+    const int cx0 = py_round_half_even(cx - half);
+    const int cy0 = py_round_half_even(cy - half);
+    const int cx1 = py_round_half_even(cx + half);
+    const int cy1 = py_round_half_even(cy + half);
+    const int cw = cx1 - cx0;
+    const int chh = cy1 - cy0;
+    if (cw <= 0 || chh <= 0) {
+        set_error(error, "degenerate alpha bounding box");
+        return false;
+    }
+
+    // 3. crop (zero-padded outside the source) + premultiply onto black -> RGB
+    std::vector<uint8_t> rgb((size_t) cw * chh * 3, 0);
+    for (int y = 0; y < chh; ++y) {
+        const int sy = y + cy0;
+        if (sy < 0 || sy >= h) continue;
+        for (int x = 0; x < cw; ++x) {
+            const int sx = x + cx0;
+            if (sx < 0 || sx >= w) continue;
+            const uint8_t * p = &img[((size_t) sy * w + sx) * 4];
+            const float a = (float) p[3] / 255.0f;
+            for (int c = 0; c < 3; ++c) {
+                // matches numpy: ((rgb/255 * alpha/255) * 255).astype(uint8)
+                const float v = ((float) p[c] / 255.0f) * a * 255.0f;
+                rgb[((size_t) y * cw + x) * 3 + c] = (uint8_t) v;
+            }
+        }
+    }
+
+    // 4. LANCZOS resize to out_size x out_size
+    pil_resize(rgb.data(), cw, chh, 3, out_size, out_size, out_rgb);
+    return true;
+}
+
+bool trellis2_save_dinodata(const std::string & path,
+                            const trellis2_dino_cond & cond,
+                            std::string * error) {
+    if (cond.empty() || cond.shape.empty()) {
+        set_error(error, "empty cond");
+        return false;
+    }
+    int64_t total = 1;
+    for (int64_t d : cond.shape) total *= d;
+    if ((size_t) total != cond.data.size()) {
+        set_error(error, "shape/data size mismatch");
+        return false;
+    }
+
+    std::ofstream f(path, std::ios::binary);
+    if (!f) {
+        set_error(error, "cannot open for writing: " + path);
+        return false;
+    }
+    f.write("DINOCOND", 8);
+    const uint32_t version = cond.format_version ? cond.format_version : 1;
+    const uint32_t dtype = 0;  // f32
+    const uint32_t ndim  = (uint32_t) cond.shape.size();
+    auto w32 = [&](uint32_t v) { f.write(reinterpret_cast<const char *>(&v), 4); };
+    w32(version);
+    w32(dtype);
+    w32(ndim);
+    for (int64_t d : cond.shape) w32((uint32_t) d);
+    f.write(reinterpret_cast<const char *>(cond.data.data()),
+            (std::streamsize) (cond.data.size() * sizeof(float)));
+    if (!f) {
+        set_error(error, "short write: " + path);
+        return false;
+    }
+    return true;
+}
+
+/*****************************************************************************
+** Shape-SLAT flow DiT (stage 2) — GGUF loader
+*****************************************************************************/
+
+struct trellis2_slat_flow_model {
+    gguf_context * gguf = nullptr;
+    ggml_context * ctx  = nullptr;
+    trellis2_slat_flow_hparams hp;
+    bool has_data = false;
+
+    ggml_backend_t        backend     = nullptr;
+    ggml_backend_buffer_t weights_buf = nullptr;
+    std::string           backend_name;
+
+    std::unordered_map<std::string, ggml_tensor *> tensors;
+};
+
+trellis2_slat_flow_model *
+trellis2_slat_flow_load(const std::string & path, bool load_tensors, std::string * error,
+                        const char * device) {
+    auto * m = new trellis2_slat_flow_model();
+
+    gguf_init_params params;
+    params.no_alloc = true;
+    params.ctx      = &m->ctx;
+
+    m->gguf = gguf_init_from_file(path.c_str(), params);
+    if (!m->gguf) {
+        set_error(error, "gguf_init_from_file failed (not a GGUF file?): " + path);
+        delete m;
+        return nullptr;
+    }
+
+    const char * arch = kv_str(m->gguf, "general.architecture", "");
+    if (std::strcmp(arch, "trellis2-slat-flow") != 0) {
+        set_error(error, std::string("unexpected architecture '") + arch +
+                         "' (expected 'trellis2-slat-flow')");
+        trellis2_slat_flow_free(m);
+        return nullptr;
+    }
+
+    trellis2_slat_flow_hparams & hp = m->hp;
+    const char * P = "trellis2.slat_flow.";
+    auto K = [&](const std::string & suffix) { return std::string(P) + suffix; };
+
+    hp.resolution        = (int32_t) kv_u32 (m->gguf, K("resolution").c_str(),     0);
+    hp.in_channels       = (int32_t) kv_u32 (m->gguf, K("in_channels").c_str(),    0);
+    hp.out_channels      = (int32_t) kv_u32 (m->gguf, K("out_channels").c_str(),   0);
+    hp.model_channels    = (int32_t) kv_u32 (m->gguf, K("model_channels").c_str(), 0);
+    hp.cond_channels     = (int32_t) kv_u32 (m->gguf, K("cond_channels").c_str(),  0);
+    hp.num_blocks        = (int32_t) kv_u32 (m->gguf, K("num_blocks").c_str(),     0);
+    hp.num_heads         = (int32_t) kv_u32 (m->gguf, K("num_heads").c_str(),      0);
+    hp.mlp_ratio         =           kv_f32 (m->gguf, K("mlp_ratio").c_str(),      0.0f);
+    hp.share_mod         =           kv_bool(m->gguf, K("share_mod").c_str(),         false) ? 1 : 0;
+    hp.qk_rms_norm       =           kv_bool(m->gguf, K("qk_rms_norm").c_str(),       false) ? 1 : 0;
+    hp.qk_rms_norm_cross =           kv_bool(m->gguf, K("qk_rms_norm_cross").c_str(), false) ? 1 : 0;
+    hp.rope_freq_min     =           kv_f32 (m->gguf, K("rope_freq_min").c_str(),  1.0f);
+    hp.rope_freq_base    =           kv_f32 (m->gguf, K("rope_freq_base").c_str(), 10000.0f);
+    hp.file_type         = (int32_t) kv_u32 (m->gguf, "general.file_type", 0);
+    std::snprintf(hp.pe_mode, sizeof(hp.pe_mode), "%s",
+                  kv_str(m->gguf, K("pe_mode").c_str(), "rope"));
+    for (int c = 0; c < hp.out_channels && c < 64; ++c) {
+        hp.norm_mean[c] = kv_f32(m->gguf, K("norm_mean." + std::to_string(c)).c_str(), 0.0f);
+        hp.norm_std[c]  = kv_f32(m->gguf, K("norm_std."  + std::to_string(c)).c_str(), 1.0f);
+    }
+    // Texture SLAT flow: concat_cond. 0/absent on the shape flow. When > 0, the
+    // shape SLAT (concat_norm-normalized) is concatenated onto the noise so the
+    // DiT sees in_channels = out_channels + concat_cond_channels.
+    hp.concat_cond_channels = (int32_t) kv_u32(m->gguf, K("concat_cond_channels").c_str(), 0);
+    for (int c = 0; c < hp.concat_cond_channels && c < 64; ++c) {
+        hp.concat_norm_mean[c] = kv_f32(m->gguf, K("concat_norm_mean." + std::to_string(c)).c_str(), 0.0f);
+        hp.concat_norm_std[c]  = kv_f32(m->gguf, K("concat_norm_std."  + std::to_string(c)).c_str(), 1.0f);
+    }
+
+    for (ggml_tensor * t = ggml_get_first_tensor(m->ctx); t != nullptr;
+         t = ggml_get_next_tensor(m->ctx, t)) {
+        m->tensors[t->name] = t;
+    }
+
+    if (load_tensors) {
+        m->backend = init_best_backend(m->backend_name, device);
+        m->weights_buf = ggml_backend_alloc_ctx_tensors(m->ctx, m->backend);
+        if (!m->weights_buf) {
+            set_error(error, "failed to allocate weights on backend " + m->backend_name);
+            trellis2_slat_flow_free(m);
+            return nullptr;
+        }
+        std::ifstream fin(path, std::ios::binary);
+        if (!fin) {
+            set_error(error, "cannot reopen file for weight data: " + path);
+            trellis2_slat_flow_free(m);
+            return nullptr;
+        }
+        const size_t data_off = gguf_get_data_offset(m->gguf);
+        const int64_t nt = gguf_get_n_tensors(m->gguf);
+        std::vector<uint8_t> buf;
+        for (int64_t i = 0; i < nt; ++i) {
+            const char * name = gguf_get_tensor_name(m->gguf, i);
+            ggml_tensor * t = m->tensors[name];
+            const size_t nb  = ggml_nbytes(t);
+            const size_t off = data_off + gguf_get_tensor_offset(m->gguf, i);
+            buf.resize(nb);
+            fin.seekg((std::streamoff) off, std::ios::beg);
+            if (!fin.read(reinterpret_cast<char *>(buf.data()), (std::streamsize) nb)) {
+                set_error(error, std::string("failed reading weight '") + name + "' from file");
+                trellis2_slat_flow_free(m);
+                return nullptr;
+            }
+            ggml_backend_tensor_set(t, buf.data(), 0, nb);
+        }
+        m->has_data = true;
+    }
+
+    return m;
+}
+
+void trellis2_slat_flow_free(trellis2_slat_flow_model * m) {
+    if (!m) return;
+    if (m->weights_buf) ggml_backend_buffer_free(m->weights_buf);
+    if (m->backend)     ggml_backend_free(m->backend);
+    if (m->gguf)        gguf_free(m->gguf);
+    if (m->ctx)         ggml_free(m->ctx);
+    delete m;
+}
+
+const char * trellis2_slat_flow_backend_name(const trellis2_slat_flow_model * m) {
+    return (m && !m->backend_name.empty()) ? m->backend_name.c_str() : "none";
+}
+
+const trellis2_slat_flow_hparams &
+trellis2_slat_flow_hparams_of(const trellis2_slat_flow_model * m) {
+    return m->hp;
+}
+
+/*****************************************************************************
+** Shape-SLAT flow DiT — forward pass
+**
+** Identical block structure to trellis2_ss_flow_forward, with the dense R^3
+** token grid replaced by the L active voxels: 3D RoPE phases come from each
+** voxel's integer coords, everything else (shared adaLN modulation, QK-RMS
+** norm, cross-attention to the DINO tokens, GELU-tanh FFN) is unchanged.
+*****************************************************************************/
+
+namespace {
+
+// Interleaved 3D-RoPE tables for an explicit voxel-coordinate list. Same
+// layout as rope_tables(): [head_dim, 1, L] with cos[2p] == cos[2p+1].
+void rope_tables_coords(const int32_t * coords, int L, int head_dim,
+                        float freq_min, float freq_base,
+                        std::vector<float> & cos_t, std::vector<float> & sin_t) {
+    const int dim      = 3;
+    const int freq_dim = head_dim / 2 / dim;
+
+    std::vector<float> freqs((size_t) freq_dim);
+    for (int mi = 0; mi < freq_dim; ++mi) {
+        freqs[mi] = freq_min / std::pow(freq_base, (float) mi / (float) freq_dim);
+    }
+
+    cos_t.assign((size_t) head_dim * L, 1.0f);
+    sin_t.assign((size_t) head_dim * L, 0.0f);
+    const int pairs = head_dim / 2;
+    for (int v = 0; v < L; ++v) {
+        for (int p = 0; p < pairs; ++p) {
+            float theta = 0.0f;
+            if (p < dim * freq_dim) {
+                theta = (float) coords[(size_t) v * 3 + p / freq_dim] * freqs[p % freq_dim];
+            }
+            const size_t base = (size_t) v * head_dim + (size_t) 2 * p;
+            cos_t[base] = cos_t[base + 1] = std::cos(theta);
+            sin_t[base] = sin_t[base + 1] = std::sin(theta);
+        }
+    }
+}
+
+} // namespace
+
+bool trellis2_slat_flow_forward(trellis2_slat_flow_model * m,
+                                const float * x, int n_voxels, const int32_t * coords,
+                                float t,
+                                const float * cond, int cond_tokens, int cond_channels,
+                                float * out, std::string * error) {
+    if (!m)           { set_error(error, "null model"); return false; }
+    if (!m->has_data) { set_error(error, "model loaded metadata-only; reload with load_tensors=true"); return false; }
+
+    const trellis2_slat_flow_hparams & hp = m->hp;
+    if (std::strcmp(hp.pe_mode, "rope") != 0) { set_error(error, "only pe_mode=rope is implemented"); return false; }
+    if (!hp.share_mod)                         { set_error(error, "only share_mod=true is implemented"); return false; }
+    if (cond_channels != hp.cond_channels)     { set_error(error, "cond_channels mismatch"); return false; }
+
+    const int   C   = hp.model_channels;
+    const int   N   = n_voxels;
+    const int   H   = hp.num_heads;
+    const int   hd  = hp.head_dim();
+    const int   Lkv = cond_tokens;
+    const float attn_scale = 1.0f / std::sqrt((float) hd);
+
+    std::string missing;
+    auto W = [&](const std::string & n) -> ggml_tensor * {
+        auto it = m->tensors.find(n);
+        if (it == m->tensors.end()) { if (missing.empty()) missing = n; return nullptr; }
+        return it->second;
+    };
+
+    const size_t mem = ggml_tensor_overhead() * 32768 + ggml_graph_overhead_custom(32768, false);
+    ggml_init_params ip{ mem, nullptr, true };
+    ggml_context * ctx = ggml_init(ip);
+    ggml_cgraph * gf = ggml_new_graph_custom(ctx, 32768, false);
+
+    ggml_tensor * x_t   = ggml_new_tensor_2d(ctx, GGML_TYPE_F32, hp.in_channels, N); // voxel-major [L][Cin]
+    ggml_tensor * temb  = ggml_new_tensor_1d(ctx, GGML_TYPE_F32, 256);
+    ggml_tensor * cos_t = ggml_new_tensor_3d(ctx, GGML_TYPE_F32, hd, 1, N);
+    ggml_tensor * sin_t = ggml_new_tensor_3d(ctx, GGML_TYPE_F32, hd, 1, N);
+    ggml_tensor * cnd   = ggml_new_tensor_2d(ctx, GGML_TYPE_F32, cond_channels, Lkv);
+    ggml_set_input(x_t);
+    ggml_set_input(temb);
+    ggml_set_input(cos_t);
+    ggml_set_input(sin_t);
+    ggml_set_input(cnd);
+
+    auto lin = [&](ggml_tensor * in, const std::string & pfx) -> ggml_tensor * {
+        ggml_tensor * y = ggml_mul_mat(ctx, W(pfx + ".weight"), in);
+        ggml_tensor * b = W(pfx + ".bias");
+        if (b) y = ggml_add(ctx, y, b);
+        return y;
+    };
+    auto modulate = [&](ggml_tensor * h, ggml_tensor * scale, ggml_tensor * shift) {
+        return ggml_add(ctx, ggml_add(ctx, ggml_mul(ctx, h, scale), h), shift);
+    };
+    auto rope = [&](ggml_tensor * q3) -> ggml_tensor * {
+        ggml_tensor * q4 = ggml_reshape_4d(ctx, q3, 2, hd / 2, H, N);
+        ggml_tensor * q0 = ggml_cont(ctx, ggml_view_4d(ctx, q4, 1, hd / 2, H, N,
+                                                       q4->nb[1], q4->nb[2], q4->nb[3], 0));
+        ggml_tensor * q1 = ggml_cont(ctx, ggml_view_4d(ctx, q4, 1, hd / 2, H, N,
+                                                       q4->nb[1], q4->nb[2], q4->nb[3], q4->nb[0]));
+        ggml_tensor * swap = ggml_concat(ctx, ggml_neg(ctx, q1), q0, 0);
+        swap = ggml_reshape_3d(ctx, swap, hd, H, N);
+        return ggml_add(ctx, ggml_mul(ctx, q3, cos_t), ggml_mul(ctx, swap, sin_t));
+    };
+    auto qk_norm = [&](ggml_tensor * v3, const std::string & gname) {
+        return ggml_mul(ctx, ggml_rms_norm(ctx, v3, 1e-12f), W(gname));
+    };
+    auto sdpa = [&](ggml_tensor * q3, ggml_tensor * k3, ggml_tensor * v3) {
+        return sdpa_auto(ctx, q3, k3, v3, C, attn_scale);
+    };
+
+    const size_t es = sizeof(float);
+
+    ggml_tensor * h = lin(x_t, "input_layer");                       // [C, N]
+
+    ggml_tensor * te = lin(temb, "t_embedder.mlp.0");
+    te = ggml_silu(ctx, te);
+    te = lin(te, "t_embedder.mlp.2");
+    ggml_tensor * tmod = lin(ggml_silu(ctx, te), "adaLN_modulation.1");
+
+    ggml_tensor * cond_h = cnd;
+
+    for (int b = 0; b < hp.num_blocks; ++b) {
+        const std::string blk = "blocks." + std::to_string(b);
+        ggml_tensor * mods = ggml_add(ctx, W(blk + ".modulation"), tmod);
+        auto chunk = [&](int idx) {
+            return ggml_view_1d(ctx, mods, C, (size_t) idx * C * es);
+        };
+        ggml_tensor * shift_msa = chunk(0), * scale_msa = chunk(1), * gate_msa = chunk(2);
+        ggml_tensor * shift_mlp = chunk(3), * scale_mlp = chunk(4), * gate_mlp = chunk(5);
+
+        ggml_tensor * hn = modulate(ggml_norm(ctx, h, 1e-6f), scale_msa, shift_msa);
+        ggml_tensor * qkv = lin(hn, blk + ".self_attn.to_qkv");
+        ggml_tensor * q = ggml_reshape_3d(ctx, ggml_cont(ctx, ggml_view_2d(ctx, qkv, C, N, qkv->nb[1], 0)),                 hd, H, N);
+        ggml_tensor * k = ggml_reshape_3d(ctx, ggml_cont(ctx, ggml_view_2d(ctx, qkv, C, N, qkv->nb[1], (size_t) C * es)),   hd, H, N);
+        ggml_tensor * v = ggml_reshape_3d(ctx, ggml_cont(ctx, ggml_view_2d(ctx, qkv, C, N, qkv->nb[1], (size_t) 2 * C * es)), hd, H, N);
+        q = rope(qk_norm(q, blk + ".self_attn.q_rms_norm.gamma"));
+        k = rope(qk_norm(k, blk + ".self_attn.k_rms_norm.gamma"));
+        ggml_tensor * sa = lin(sdpa(q, k, v), blk + ".self_attn.to_out");
+        h = ggml_add(ctx, h, ggml_mul(ctx, sa, gate_msa));
+
+        ggml_tensor * h2 = ggml_norm(ctx, h, 1e-6f);
+        h2 = ggml_add(ctx, ggml_mul(ctx, h2, W(blk + ".norm2.weight")), W(blk + ".norm2.bias"));
+        ggml_tensor * cq = ggml_reshape_3d(ctx, lin(h2, blk + ".cross_attn.to_q"), hd, H, N);
+        cq = qk_norm(cq, blk + ".cross_attn.q_rms_norm.gamma");
+        ggml_tensor * kv = lin(cond_h, blk + ".cross_attn.to_kv");
+        ggml_tensor * ck = ggml_reshape_3d(ctx, ggml_cont(ctx, ggml_view_2d(ctx, kv, C, Lkv, kv->nb[1], 0)),               hd, H, Lkv);
+        ggml_tensor * cv = ggml_reshape_3d(ctx, ggml_cont(ctx, ggml_view_2d(ctx, kv, C, Lkv, kv->nb[1], (size_t) C * es)), hd, H, Lkv);
+        ck = qk_norm(ck, blk + ".cross_attn.k_rms_norm.gamma");
+        ggml_tensor * ca = lin(sdpa(cq, ck, cv), blk + ".cross_attn.to_out");
+        h = ggml_add(ctx, h, ca);
+
+        ggml_tensor * hm = modulate(ggml_norm(ctx, h, 1e-6f), scale_mlp, shift_mlp);
+        hm = lin(hm, blk + ".mlp.mlp.0");
+        hm = ggml_gelu(ctx, hm);
+        hm = lin(hm, blk + ".mlp.mlp.2");
+        h = ggml_add(ctx, h, ggml_mul(ctx, hm, gate_mlp));
+    }
+
+    h = ggml_norm(ctx, h, 1e-5f);
+    h = lin(h, "out_layer");                                         // [Cout, N]
+    ggml_tensor * y = ggml_cont(ctx, h);                             // voxel-major [L][Cout]
+    ggml_set_output(y);
+
+    if (!missing.empty()) {
+        set_error(error, "missing tensor: " + missing);
+        ggml_free(ctx);
+        return false;
+    }
+
+    ggml_build_forward_expand(gf, y);
+
+    ggml_backend_t backend = m->backend;
+    ggml_gallocr_t alloc   = ggml_gallocr_new(ggml_backend_get_default_buffer_type(backend));
+    if (!ggml_gallocr_alloc_graph(alloc, gf)) {
+        set_error(error, "ggml_gallocr_alloc_graph failed");
+        ggml_gallocr_free(alloc); ggml_free(ctx);
+        return false;
+    }
+
+    std::vector<float> emb = timestep_embedding(t, 256);
+    std::vector<float> cosv, sinv;
+    rope_tables_coords(coords, N, hd, hp.rope_freq_min, hp.rope_freq_base, cosv, sinv);
+
+    ggml_backend_tensor_set(x_t,   x,           0, (size_t) hp.in_channels * N * es);
+    ggml_backend_tensor_set(temb,  emb.data(),  0, emb.size() * es);
+    ggml_backend_tensor_set(cos_t, cosv.data(), 0, cosv.size() * es);
+    ggml_backend_tensor_set(sin_t, sinv.data(), 0, sinv.size() * es);
+    ggml_backend_tensor_set(cnd,   cond,        0, (size_t) cond_channels * Lkv * es);
+
+    const ggml_status st = ggml_backend_graph_compute(backend, gf);
+    bool ok = (st == GGML_STATUS_SUCCESS);
+    if (ok) {
+        ggml_backend_tensor_get(y, out, 0, (size_t) hp.out_channels * N * es);
+    } else {
+        set_error(error, "graph compute failed");
+    }
+
+    ggml_gallocr_free(alloc);
+    ggml_free(ctx);
+    return ok;
+}
+
+bool trellis2_slat_flow_sample(trellis2_slat_flow_model * m,
+                               int n_voxels, const int32_t * coords,
+                               const float * cond, int cond_tokens, int cond_channels,
+                               const trellis2_ss_sampler_params * params_in,
+                               const float * noise, bool denormalize,
+                               float * out_latent, std::string * error) {
+    if (!m)           { set_error(error, "null model"); return false; }
+    if (!m->has_data) { set_error(error, "model loaded metadata-only; reload with load_tensors=true"); return false; }
+
+    trellis2_ss_sampler_params P;
+    if (params_in) P = *params_in;
+
+    const trellis2_slat_flow_hparams & hp = m->hp;
+    const size_t n = (size_t) hp.in_channels * n_voxels;
+    const double sm = P.sigma_min;
+
+    std::vector<float> x_t(n);
+    if (noise) {
+        std::memcpy(x_t.data(), noise, n * sizeof(float));
+    } else {
+        std::mt19937_64 rng(P.seed);
+        std::normal_distribution<float> nd(0.0f, 1.0f);
+        for (size_t i = 0; i < n; ++i) x_t[i] = nd(rng);
+    }
+
+    std::vector<double> ts((size_t) P.steps + 1);
+    for (int i = 0; i <= P.steps; ++i) {
+        const double lin = 1.0 - (double) i / (double) P.steps;
+        ts[i] = P.rescale_t * lin / (1.0 + (P.rescale_t - 1.0) * lin);
+    }
+
+    const std::vector<float> zero_cond((size_t) cond_tokens * cond_channels, 0.0f);
+    std::vector<float> pred_pos(n), pred_neg(n), pred_v(n), x0_pos(n), x0_cfg(n);
+
+    auto fwd = [&](double t, const float * c, std::vector<float> & dst) -> bool {
+        return trellis2_slat_flow_forward(m, x_t.data(), n_voxels, coords,
+                                          (float) (1000.0 * t),
+                                          c, cond_tokens, cond_channels, dst.data(), error);
+    };
+
+    for (int i = 0; i < P.steps; ++i) {
+        const double t = ts[i], t_prev = ts[i + 1];
+        const bool in_interval = (t >= P.guidance_interval_min && t <= P.guidance_interval_max);
+        const float gs = in_interval ? P.guidance_strength : 1.0f;
+
+        if (gs == 1.0f) {
+            if (!fwd(t, cond, pred_v)) return false;
+        } else if (gs == 0.0f) {
+            if (!fwd(t, zero_cond.data(), pred_v)) return false;
+        } else {
+            if (!fwd(t, cond, pred_pos)) return false;
+            if (!fwd(t, zero_cond.data(), pred_neg)) return false;
+            for (size_t k = 0; k < n; ++k) pred_v[k] = gs * pred_pos[k] + (1.0f - gs) * pred_neg[k];
+
+            if (P.guidance_rescale > 0.0f) {
+                pred_to_xstart(x_t, t, sm, pred_pos, x0_pos);
+                pred_to_xstart(x_t, t, sm, pred_v,   x0_cfg);
+                const double std_pos = unbiased_std(x0_pos);
+                const double std_cfg = unbiased_std(x0_cfg);
+                const double ratio = (std_cfg != 0.0) ? std_pos / std_cfg : 1.0;
+                const float  gr = P.guidance_rescale;
+                for (size_t k = 0; k < n; ++k) {
+                    const double rescaled = x0_cfg[k] * ratio;
+                    x0_cfg[k] = (float) (gr * rescaled + (1.0 - gr) * x0_cfg[k]);
+                }
+                xstart_to_pred(x_t, t, sm, x0_cfg, pred_v);
+            }
+        }
+
+        const double dt = t - t_prev;
+        for (size_t k = 0; k < n; ++k) x_t[k] = (float) (x_t[k] - dt * pred_v[k]);
+
+        if (P.verbose) {
+            std::fprintf(stderr, "\r[slat sample] step %2d/%d  t=%.4f->%.4f  %s   ",
+                         i + 1, P.steps, t, t_prev, in_interval ? "cfg" : "uncond");
+            std::fflush(stderr);
+        }
+        if (P.progress) P.progress(P.progress_user, i + 1, P.steps);
+    }
+    if (P.verbose) std::fprintf(stderr, "\n");
+
+    if (denormalize) {
+        const int C = hp.in_channels;
+        for (int v = 0; v < n_voxels; ++v) {
+            for (int c = 0; c < C; ++c) {
+                x_t[(size_t) v * C + c] = x_t[(size_t) v * C + c] * hp.norm_std[c] + hp.norm_mean[c];
+            }
+        }
+    }
+
+    std::memcpy(out_latent, x_t.data(), n * sizeof(float));
+    return true;
+}
+
+// Texture-SLAT flow sampling with concat_cond. Same flow-Euler loop, but the
+// diffused variable is out_channels (32) and each forward is fed a fresh
+// [noise(32) | normalized shape-SLAT(32)] = in_channels (64) input.
+bool trellis2_slat_flow_sample_tex(trellis2_slat_flow_model * m,
+                                   int n_voxels, const int32_t * coords,
+                                   const float * cond, int cond_tokens, int cond_channels,
+                                   const float * shape_slat,
+                                   const trellis2_ss_sampler_params * params_in,
+                                   const float * noise, bool denormalize,
+                                   float * out_latent, std::string * error) {
+    if (!m)           { set_error(error, "null model"); return false; }
+    if (!m->has_data) { set_error(error, "model loaded metadata-only; reload with load_tensors=true"); return false; }
+
+    const trellis2_slat_flow_hparams & hp = m->hp;
+    const int Cin = hp.in_channels, Cout = hp.out_channels, Ccat = hp.concat_cond_channels;
+    if (Ccat <= 0 || Cin != Cout + Ccat) {
+        set_error(error, "model is not a concat_cond (texture) flow"); return false;
+    }
+
+    trellis2_ss_sampler_params P;
+    if (params_in) P = *params_in;
+    const size_t n = (size_t) Cout * n_voxels;   // diffused variable
+    const double sm = P.sigma_min;
+
+    std::vector<float> x_t(n);
+    if (noise) {
+        std::memcpy(x_t.data(), noise, n * sizeof(float));
+    } else {
+        std::mt19937_64 rng(P.seed);
+        std::normal_distribution<float> nd(0.0f, 1.0f);
+        for (size_t i = 0; i < n; ++i) x_t[i] = nd(rng);
+    }
+
+    // shape SLAT normalized by concat_norm (once); concatenated onto the noise.
+    std::vector<float> shape_n((size_t) Ccat * n_voxels);
+    for (int v = 0; v < n_voxels; ++v)
+        for (int c = 0; c < Ccat; ++c)
+            shape_n[(size_t) v * Ccat + c] =
+                (shape_slat[(size_t) v * Ccat + c] - hp.concat_norm_mean[c]) / hp.concat_norm_std[c];
+
+    std::vector<double> ts((size_t) P.steps + 1);
+    for (int i = 0; i <= P.steps; ++i) {
+        const double lin = 1.0 - (double) i / (double) P.steps;
+        ts[i] = P.rescale_t * lin / (1.0 + (P.rescale_t - 1.0) * lin);
+    }
+
+    const std::vector<float> zero_cond((size_t) cond_tokens * cond_channels, 0.0f);
+    std::vector<float> pred_pos(n), pred_neg(n), pred_v(n), x0_pos(n), x0_cfg(n);
+    std::vector<float> xin((size_t) Cin * n_voxels);
+
+    auto fwd = [&](double t, const float * c, std::vector<float> & dst) -> bool {
+        for (int v = 0; v < n_voxels; ++v) {
+            float * d = xin.data() + (size_t) v * Cin;
+            std::memcpy(d, x_t.data() + (size_t) v * Cout, (size_t) Cout * sizeof(float));
+            std::memcpy(d + Cout, shape_n.data() + (size_t) v * Ccat, (size_t) Ccat * sizeof(float));
+        }
+        return trellis2_slat_flow_forward(m, xin.data(), n_voxels, coords,
+                                          (float) (1000.0 * t),
+                                          c, cond_tokens, cond_channels, dst.data(), error);
+    };
+
+    for (int i = 0; i < P.steps; ++i) {
+        const double t = ts[i], t_prev = ts[i + 1];
+        const bool in_interval = (t >= P.guidance_interval_min && t <= P.guidance_interval_max);
+        const float gs = in_interval ? P.guidance_strength : 1.0f;
+
+        if (gs == 1.0f) {
+            if (!fwd(t, cond, pred_v)) return false;
+        } else if (gs == 0.0f) {
+            if (!fwd(t, zero_cond.data(), pred_v)) return false;
+        } else {
+            if (!fwd(t, cond, pred_pos)) return false;
+            if (!fwd(t, zero_cond.data(), pred_neg)) return false;
+            for (size_t k = 0; k < n; ++k) pred_v[k] = gs * pred_pos[k] + (1.0f - gs) * pred_neg[k];
+
+            if (P.guidance_rescale > 0.0f) {
+                pred_to_xstart(x_t, t, sm, pred_pos, x0_pos);
+                pred_to_xstart(x_t, t, sm, pred_v,   x0_cfg);
+                const double std_pos = unbiased_std(x0_pos);
+                const double std_cfg = unbiased_std(x0_cfg);
+                const double ratio = (std_cfg != 0.0) ? std_pos / std_cfg : 1.0;
+                const float  gr = P.guidance_rescale;
+                for (size_t k = 0; k < n; ++k) {
+                    const double rescaled = x0_cfg[k] * ratio;
+                    x0_cfg[k] = (float) (gr * rescaled + (1.0 - gr) * x0_cfg[k]);
+                }
+                xstart_to_pred(x_t, t, sm, x0_cfg, pred_v);
+            }
+        }
+
+        const double dt = t - t_prev;
+        for (size_t k = 0; k < n; ++k) x_t[k] = (float) (x_t[k] - dt * pred_v[k]);
+
+        if (P.verbose) {
+            std::fprintf(stderr, "\r[tex slat sample] step %2d/%d  t=%.4f->%.4f  %s   ",
+                         i + 1, P.steps, t, t_prev, in_interval ? "cfg" : "uncond");
+            std::fflush(stderr);
+        }
+        if (P.progress) P.progress(P.progress_user, i + 1, P.steps);
+    }
+    if (P.verbose) std::fprintf(stderr, "\n");
+
+    if (denormalize) {
+        for (int v = 0; v < n_voxels; ++v)
+            for (int c = 0; c < Cout; ++c)
+                x_t[(size_t) v * Cout + c] = x_t[(size_t) v * Cout + c] * hp.norm_std[c] + hp.norm_mean[c];
+    }
+
+    std::memcpy(out_latent, x_t.data(), n * sizeof(float));
+    return true;
+}
+
+/*****************************************************************************
+** Shape-SLAT VAE decoder (FlexiDualGridVaeDecoder) — GGUF loader
+*****************************************************************************/
+
+struct trellis2_shape_dec_model {
+    gguf_context * gguf = nullptr;
+    ggml_context * ctx  = nullptr;
+    trellis2_shape_dec_hparams hp;
+    bool has_data = false;
+
+    ggml_backend_t        backend     = nullptr;
+    ggml_backend_buffer_t weights_buf = nullptr;
+    std::string           backend_name;
+
+    std::unordered_map<std::string, ggml_tensor *> tensors;
+};
+
+static trellis2_shape_dec_model *
+dec_load_impl(const std::string & path, bool load_tensors, std::string * error,
+              const char * device, const char * expect_arch, const char * kv_prefix) {
+    auto * m = new trellis2_shape_dec_model();
+
+    gguf_init_params params;
+    params.no_alloc = true;
+    params.ctx      = &m->ctx;
+
+    m->gguf = gguf_init_from_file(path.c_str(), params);
+    if (!m->gguf) {
+        set_error(error, "gguf_init_from_file failed (not a GGUF file?): " + path);
+        delete m;
+        return nullptr;
+    }
+
+    const char * arch = kv_str(m->gguf, "general.architecture", "");
+    if (std::strcmp(arch, expect_arch) != 0) {
+        set_error(error, std::string("unexpected architecture '") + arch +
+                         "' (expected '" + expect_arch + "')");
+        trellis2_shape_dec_free(m);
+        return nullptr;
+    }
+
+    trellis2_shape_dec_hparams & hp = m->hp;
+    const char * P = kv_prefix;
+    auto K = [&](const std::string & suffix) { return std::string(P) + suffix; };
+
+    hp.latent_channels = (int32_t) kv_u32(m->gguf, K("latent_channels").c_str(), 0);
+    hp.out_channels    = (int32_t) kv_u32(m->gguf, K("out_channels").c_str(),    0);
+    hp.n_levels        = (int32_t) kv_u32(m->gguf, K("n_levels").c_str(),        0);
+    hp.norm_eps        =           kv_f32(m->gguf, K("norm_eps").c_str(),        1e-6f);
+    hp.voxel_margin    =           kv_f32(m->gguf, K("voxel_margin").c_str(),    0.5f);
+    hp.file_type       = (int32_t) kv_u32(m->gguf, "general.file_type", 0);
+    for (int i = 0; i < hp.n_levels && i < 8; ++i) {
+        hp.channels[i]   = (int32_t) kv_u32(m->gguf, K("channels."   + std::to_string(i)).c_str(), 0);
+        hp.num_blocks[i] = (int32_t) kv_u32(m->gguf, K("num_blocks." + std::to_string(i)).c_str(), 0);
+    }
+
+    for (ggml_tensor * t = ggml_get_first_tensor(m->ctx); t != nullptr;
+         t = ggml_get_next_tensor(m->ctx, t)) {
+        m->tensors[t->name] = t;
+    }
+
+    if (load_tensors) {
+        m->backend = init_best_backend(m->backend_name, device);
+        m->weights_buf = ggml_backend_alloc_ctx_tensors(m->ctx, m->backend);
+        if (!m->weights_buf) {
+            set_error(error, "failed to allocate weights on backend " + m->backend_name);
+            trellis2_shape_dec_free(m);
+            return nullptr;
+        }
+        std::ifstream fin(path, std::ios::binary);
+        if (!fin) {
+            set_error(error, "cannot reopen file for weight data: " + path);
+            trellis2_shape_dec_free(m);
+            return nullptr;
+        }
+        const size_t data_off = gguf_get_data_offset(m->gguf);
+        const int64_t nt = gguf_get_n_tensors(m->gguf);
+        std::vector<uint8_t> buf;
+        for (int64_t i = 0; i < nt; ++i) {
+            const char * name = gguf_get_tensor_name(m->gguf, i);
+            ggml_tensor * t = m->tensors[name];
+            const size_t nb  = ggml_nbytes(t);
+            const size_t off = data_off + gguf_get_tensor_offset(m->gguf, i);
+            buf.resize(nb);
+            fin.seekg((std::streamoff) off, std::ios::beg);
+            if (!fin.read(reinterpret_cast<char *>(buf.data()), (std::streamsize) nb)) {
+                set_error(error, std::string("failed reading weight '") + name + "' from file");
+                trellis2_shape_dec_free(m);
+                return nullptr;
+            }
+            ggml_backend_tensor_set(t, buf.data(), 0, nb);
+        }
+        m->has_data = true;
+    }
+
+    return m;
+}
+
+trellis2_shape_dec_model *
+trellis2_shape_dec_load(const std::string & path, bool load_tensors, std::string * error,
+                        const char * device) {
+    return dec_load_impl(path, load_tensors, error, device,
+                         "trellis2-shape-dec", "trellis2.shape_dec.");
+}
+
+// The texture decoder is the same struct/driver as the shape decoder (out=6,
+// pred_subdiv=False supplied at decode time via trellis2_tex_dec_decode).
+trellis2_shape_dec_model *
+trellis2_tex_dec_load(const std::string & path, bool load_tensors, std::string * error,
+                      const char * device) {
+    return dec_load_impl(path, load_tensors, error, device,
+                         "trellis2-tex-dec", "trellis2.tex_dec.");
+}
+
+void trellis2_shape_dec_free(trellis2_shape_dec_model * m) {
+    if (!m) return;
+    if (m->weights_buf) ggml_backend_buffer_free(m->weights_buf);
+    if (m->backend)     ggml_backend_free(m->backend);
+    if (m->gguf)        gguf_free(m->gguf);
+    if (m->ctx)         ggml_free(m->ctx);
+    delete m;
+}
+
+const char * trellis2_shape_dec_backend_name(const trellis2_shape_dec_model * m) {
+    return (m && !m->backend_name.empty()) ? m->backend_name.c_str() : "none";
+}
+
+const trellis2_shape_dec_hparams &
+trellis2_shape_dec_hparams_of(const trellis2_shape_dec_model * m) {
+    return m->hp;
+}
+
+/*****************************************************************************
+** Shape-SLAT VAE decoder — forward
+**
+** Mirrors SparseUnetVaeDecoder.forward level by level. Submanifold sparse
+** 3x3x3 convolutions are expressed as 27 x (get_rows gather + GEMM): the
+** neighbor row index of every voxel for each kernel offset is precomputed on
+** the host with a hash map (missing neighbors point at an appended zero row).
+** The subdivision decision of each up-block crosses the device boundary (its
+** logits pick which children exist), so each level runs as its own graph and
+** the feature matrix round-trips through host memory between levels.
+*****************************************************************************/
+
+namespace {
+
+// key for a voxel coordinate (10 bits per axis is plenty: res <= 1024)
+inline uint64_t voxel_key(int32_t c1, int32_t c2, int32_t c3) {
+    return ((uint64_t) (uint32_t) c1 << 40) |
+           ((uint64_t) (uint32_t) c2 << 20) |
+           (uint64_t) (uint32_t) c3;
+}
+
+// Neighbor row indices for all 27 offsets of a 3^3 submanifold conv.
+// idx[k][v] = row of voxel v's neighbor at offset k, or L (the zero row).
+// Kernel flattening matches the [Co, kD, kH, kW, Ci] weight layout with
+// kD -> c1, kH -> c2, kW -> c3.
+void build_neighbor_indices(const std::vector<int32_t> & coords, int L,
+                            std::vector<std::vector<int32_t>> & idx) {
+    std::unordered_map<uint64_t, int32_t> map;
+    map.reserve((size_t) L * 2);
+    for (int v = 0; v < L; ++v) {
+        map[voxel_key(coords[(size_t) v * 3], coords[(size_t) v * 3 + 1], coords[(size_t) v * 3 + 2])] = v;
+    }
+    idx.assign(27, std::vector<int32_t>((size_t) L));
+    for (int k = 0; k < 27; ++k) {
+        const int d1 = k / 9 - 1, d2 = (k / 3) % 3 - 1, d3 = k % 3 - 1;
+        std::vector<int32_t> & ik = idx[k];
+        for (int v = 0; v < L; ++v) {
+            const int32_t c1 = coords[(size_t) v * 3]     + d1;
+            const int32_t c2 = coords[(size_t) v * 3 + 1] + d2;
+            const int32_t c3 = coords[(size_t) v * 3 + 2] + d3;
+            if (c1 < 0 || c2 < 0 || c3 < 0) { ik[v] = L; continue; }
+            auto it = map.find(voxel_key(c1, c2, c3));
+            ik[v] = (it == map.end()) ? L : it->second;
+        }
+    }
+}
+
+} // namespace
+
+// Shared driver for the shape decoder. upsample_times < 0 runs the full decode
+// (all levels + output layer; fills out_feats and out_coords) — the validated
+// behavior. upsample_times in [1, n_levels-1] runs only that many subdivision
+// levels and returns the expanded coordinate set in out_coords (out_feats
+// untouched) — mirrors FlexiDualGridVaeDecoder.upsample().
+static bool shape_dec_run(trellis2_shape_dec_model * m,
+                          const float * slat, int n_voxels, const int32_t * coords_in,
+                          int upsample_times,
+                          const std::vector<trellis2_subdiv_level> * guide,
+                          std::vector<trellis2_subdiv_level> * predicted_subs,
+                          bool pbr_scale,
+                          std::vector<float> & out_feats,
+                          std::vector<int32_t> & out_coords,
+                          trellis2_shape_dec_taps * taps,
+                          std::string * error) {
+    if (!m)           { set_error(error, "null model"); return false; }
+    if (!m->has_data) { set_error(error, "model loaded metadata-only; reload with load_tensors=true"); return false; }
+    // Texture decoder (pred_subdiv=False): the per-level subdivision is supplied
+    // by the integrated shape decoder or standalone shape encoder (`guide`)
+    // instead of predicted by a to_subdiv head.
+    if (guide && (int) guide->size() < m->hp.n_levels - 1) {
+        set_error(error, "guide subdivisions shorter than n_levels-1"); return false;
+    }
+
+    const trellis2_shape_dec_hparams & hp = m->hp;
+    const int n_levels = hp.n_levels;
+    const float eps = hp.norm_eps;
+    const size_t es = sizeof(float);
+
+    if (upsample_times >= 0 && (upsample_times < 1 || upsample_times > n_levels - 1)) {
+        set_error(error, "upsample_times out of range [1, n_levels-1]");
+        return false;
+    }
+    if (predicted_subs) predicted_subs->assign((size_t) std::max(0, n_levels - 1), {});
+
+    std::string missing;
+
+    // host-side level state
+    std::vector<int32_t> coords(coords_in, coords_in + (size_t) n_voxels * 3);
+    int L = n_voxels;
+    std::vector<float> feats;   // [L * C] voxel-major, current level features
+
+    auto cap = [&](const std::string & name, const float * data, size_t count) {
+        if (!taps) return;
+        taps->names.push_back(name);
+        taps->data.emplace_back(data, data + count);
+    };
+    auto cap_coords = [&](const std::string & name) {
+        if (!taps) return;
+        std::vector<float> c4((size_t) L * 4, 0.0f);
+        for (int v = 0; v < L; ++v) {
+            c4[(size_t) v * 4 + 1] = (float) coords[(size_t) v * 3];
+            c4[(size_t) v * 4 + 2] = (float) coords[(size_t) v * 3 + 1];
+            c4[(size_t) v * 4 + 3] = (float) coords[(size_t) v * 3 + 2];
+        }
+        cap(name, c4.data(), c4.size());
+    };
+
+    // The previous up-block's outputs, already gathered down to the surviving
+    // children (see the host_gather at the bottom of the loop): up_hch is the
+    // conv1 output [C_next, L_child], up_xch the skip source [C/8, L_child].
+    // Pre-gathering here — instead of reading back the full [C_next*8, L] conv
+    // output and gathering in the next graph — keeps the finest level's ~8 GB
+    // conv output from being duplicated in host RAM.
+    std::vector<float> up_hch, up_xch, up_subdiv;
+    int prev_C = 0, prev_L = 0;
+
+    const bool t2_timing = std::getenv("TRELLIS2_TIMING") != nullptr;
+    double ms_nbr = 0, ms_graph = 0, ms_gather = 0;
+    auto t_now = [] { return std::chrono::steady_clock::now(); };
+    auto ms_since = [](std::chrono::steady_clock::time_point a) {
+        return std::chrono::duration<double, std::milli>(
+                   std::chrono::steady_clock::now() - a).count();
+    };
+
+    for (int lvl = 0; lvl < n_levels; ++lvl) {
+        const int C = hp.channels[lvl];
+        const bool has_up = lvl < n_levels - 1;
+        const int C_next = has_up ? hp.channels[lvl + 1] : 0;
+
+        // ── host: neighbor maps for this level's coords ─────────────────────
+        std::vector<std::vector<int32_t>> nidx;
+        const bool needs_conv = hp.num_blocks[lvl] > 0 || has_up || lvl > 0;
+        if (needs_conv) {
+            auto t0 = t_now();
+            build_neighbor_indices(coords, L, nidx);
+            ms_nbr += ms_since(t0);
+        }
+
+        // ── graph: [child head from previous level] + blocks + up part A ────
+        const size_t gsize = 65536;
+        const size_t mem = ggml_tensor_overhead() * gsize + ggml_graph_overhead_custom(gsize, false);
+        ggml_init_params ip{ mem, nullptr, true };
+        ggml_context * ctx = ggml_init(ip);
+        ggml_cgraph * gf = ggml_new_graph_custom(ctx, gsize, false);
+
+        auto W = [&](const std::string & n) -> ggml_tensor * {
+            auto it = m->tensors.find(n);
+            if (it == m->tensors.end()) { if (missing.empty()) missing = n; return nullptr; }
+            return it->second;
+        };
+        auto lin = [&](ggml_tensor * in, const std::string & pfx) -> ggml_tensor * {
+            ggml_tensor * y = ggml_mul_mat(ctx, W(pfx + ".weight"), in);
+            ggml_tensor * b = W(pfx + ".bias");
+            if (b) y = ggml_add(ctx, y, b);
+            return y;
+        };
+        auto ln_affine = [&](ggml_tensor * h, const std::string & pfx) -> ggml_tensor * {
+            ggml_tensor * y = ggml_norm(ctx, h, eps);
+            y = ggml_mul(ctx, y, W(pfx + ".weight"));
+            y = ggml_add(ctx, y, W(pfx + ".bias"));
+            return y;
+        };
+
+        // Per-offset neighbor leaves, shared by every conv in this level. A
+        // missing neighbor is handled without an appended zero row (the CUDA
+        // CONCAT/PAD kernels abort past 65535 voxels): idx_t[k] holds the
+        // neighbor row *clamped* into [0, L) and mask_t[k] is 0 there, 1 for a
+        // real neighbor — so get_rows gathers a valid (harmless) row and the
+        // mask multiply zeroes the missing contributions. Numerically identical
+        // to gathering an explicit zero row, but every op (get_rows, broadcast
+        // mul, mul_mat) stays within ggml kernels that tile the voxel dimension,
+        // so the decoder runs on the GPU as well as the CPU.
+        std::vector<ggml_tensor *> idx_t(27, nullptr), mask_t(27, nullptr);
+        if (needs_conv) {
+            for (int k = 0; k < 27; ++k) {
+                idx_t[k]  = ggml_new_tensor_1d(ctx, GGML_TYPE_I32, L);
+                mask_t[k] = ggml_new_tensor_2d(ctx, GGML_TYPE_F32, 1, L);  // [1, L]
+                ggml_set_input(idx_t[k]);
+                ggml_set_input(mask_t[k]);
+            }
+        }
+
+        // submanifold conv: x [Cin, L] -> [Cout, L]
+        auto conv = [&](ggml_tensor * x, const std::string & pfx) -> ggml_tensor * {
+            ggml_tensor * w = W(pfx + ".weight");   // ne [Ci, 27, Co]
+            ggml_tensor * b = W(pfx + ".bias");     // [Co]
+            if (!w || !b) return x;
+            const int64_t Ci = w->ne[0], Co = w->ne[2];
+            ggml_tensor * acc = nullptr;
+            for (int k = 0; k < 27; ++k) {
+                ggml_tensor * wk = ggml_cont(ctx, ggml_view_3d(ctx, w, Ci, 1, Co,
+                                                               w->nb[1], w->nb[2], (size_t) k * w->nb[1]));
+                wk = ggml_reshape_2d(ctx, wk, Ci, Co);
+                ggml_tensor * g = ggml_get_rows(ctx, x, idx_t[k]);   // [Ci, L]
+                g = ggml_mul(ctx, g, mask_t[k]);                     // zero missing (broadcast [1,L])
+                ggml_tensor * y = ggml_mul_mat(ctx, wk, g);          // [Co, L]
+                acc = acc ? ggml_add(ctx, acc, y) : y;
+            }
+            return ggml_add(ctx, acc, b);
+        };
+
+        // ConvNeXt block: x + mlp(LN(conv(x)))
+        auto convnext = [&](ggml_tensor * x, const std::string & pfx) -> ggml_tensor * {
+            ggml_tensor * h = conv(x, pfx + ".conv");
+            h = ln_affine(h, pfx + ".norm");
+            h = lin(h, pfx + ".mlp.0");
+            h = ggml_silu(ctx, h);
+            h = lin(h, pfx + ".mlp.2");
+            return ggml_add(ctx, h, x);
+        };
+
+        ggml_tensor * h = nullptr;
+        ggml_tensor * in_a = nullptr, * in_hch = nullptr, * in_xch = nullptr;
+
+        if (lvl == 0) {
+            // from_latent on the input slat
+            in_a = ggml_new_tensor_2d(ctx, GGML_TYPE_F32, hp.latent_channels, L);
+            ggml_set_input(in_a);
+            h = lin(in_a, "from_latent");
+        } else {
+            // child head of the previous level's up-block. The surviving
+            // children were already gathered on host (up_hch/up_xch), so we
+            // receive hch [C, L] and xch [prev_C/8, L] directly — no on-device
+            // get_rows over the full [C*8, prev_L]:
+            //   h = conv2(silu(LN_free(hch))) + repeat_interleave(xch)
+            const std::string up = "blocks." + std::to_string(lvl - 1) + "." +
+                                   std::to_string(hp.num_blocks[lvl - 1]);
+            in_hch = ggml_new_tensor_2d(ctx, GGML_TYPE_F32, C, L);            // hch
+            in_xch = ggml_new_tensor_2d(ctx, GGML_TYPE_F32, prev_C / 8, L);   // xch
+            ggml_set_input(in_hch);
+            ggml_set_input(in_xch);
+
+            const int r = C / (prev_C / 8);   // repeat_interleave factor
+            ggml_tensor * skip = ggml_reshape_3d(ctx, in_xch, 1, prev_C / 8, L);
+            skip = ggml_repeat(ctx, skip, ggml_new_tensor_3d(ctx, GGML_TYPE_F32, r, prev_C / 8, L));
+            skip = ggml_reshape_2d(ctx, skip, C, L);
+
+            ggml_tensor * hn = ggml_norm(ctx, in_hch, eps);   // norm2, affine-free
+            hn = ggml_silu(ctx, hn);
+            hn = conv(hn, up + ".conv2");
+            h = ggml_add(ctx, hn, skip);
+        }
+
+        for (int b = 0; b < hp.num_blocks[lvl]; ++b) {
+            const std::string pfx = "blocks." + std::to_string(lvl) + "." + std::to_string(b);
+            h = convnext(h, pfx);
+        }
+
+        std::vector<std::pair<std::string, ggml_tensor *>> outs;
+        if (has_up) {
+            const std::string up = "blocks." + std::to_string(lvl) + "." +
+                                   std::to_string(hp.num_blocks[lvl]);
+            if (!guide) {   // shape decoder: predict which children exist
+                ggml_tensor * subdiv = lin(h, up + ".to_subdiv");            // [8, L]
+                outs.emplace_back("subdiv", ggml_cont(ctx, subdiv));
+            }
+            ggml_tensor * hn = ln_affine(h, up + ".norm1");
+            hn = ggml_silu(ctx, hn);
+            ggml_tensor * h1 = conv(hn, up + ".conv1");                       // [C_next*8, L]
+            outs.emplace_back("h1", ggml_cont(ctx, h1));
+            outs.emplace_back("x", ggml_cont(ctx, h));
+        } else {
+            // final: affine-free LN (eps 1e-5) + output projection
+            ggml_tensor * hn = ggml_norm(ctx, h, 1e-5f);
+            ggml_tensor * o = lin(hn, "output_layer");                        // [7, L]
+            outs.emplace_back("out", ggml_cont(ctx, o));
+        }
+        if (taps) outs.emplace_back("pre_up", ggml_cont(ctx, h));
+
+        for (auto & o : outs) {
+            ggml_set_output(o.second);
+            ggml_build_forward_expand(gf, o.second);
+        }
+
+        if (!missing.empty()) {
+            set_error(error, "missing tensor: " + missing + " (level " + std::to_string(lvl) + ")");
+            ggml_free(ctx);
+            return false;
+        }
+
+        ggml_gallocr_t alloc = ggml_gallocr_new(ggml_backend_get_default_buffer_type(m->backend));
+        if (!ggml_gallocr_alloc_graph(alloc, gf)) {
+            set_error(error, "ggml_gallocr_alloc_graph failed (level " + std::to_string(lvl) + ")");
+            ggml_gallocr_free(alloc); ggml_free(ctx);
+            return false;
+        }
+
+        // upload inputs: clamp the missing-neighbor sentinel (L) into range and
+        // build its 0/1 mask (see the conv leaves above).
+        if (needs_conv) {
+            std::vector<int32_t> clamped((size_t) L);
+            std::vector<float>   mask((size_t) L);
+            for (int k = 0; k < 27; ++k) {
+                const std::vector<int32_t> & ik = nidx[k];
+                for (int v = 0; v < L; ++v) {
+                    const bool miss = ik[(size_t) v] >= L;
+                    clamped[(size_t) v] = miss ? 0 : ik[(size_t) v];
+                    mask[(size_t) v]    = miss ? 0.0f : 1.0f;
+                }
+                ggml_backend_tensor_set(idx_t[k],  clamped.data(), 0, (size_t) L * sizeof(int32_t));
+                ggml_backend_tensor_set(mask_t[k], mask.data(),    0, (size_t) L * sizeof(float));
+            }
+        }
+        if (lvl == 0) {
+            ggml_backend_tensor_set(in_a, slat, 0, (size_t) hp.latent_channels * L * es);
+        } else {
+            // pre-gathered by the previous level (host_gather below)
+            ggml_backend_tensor_set(in_hch, up_hch.data(), 0, up_hch.size() * es);
+            ggml_backend_tensor_set(in_xch, up_xch.data(), 0, up_xch.size() * es);
+        }
+
+        auto t_g = t_now();
+        const ggml_status st = ggml_backend_graph_compute(m->backend, gf);
+        if (t2_timing) ms_graph += ms_since(t_g);
+        if (st != GGML_STATUS_SUCCESS) {
+            set_error(error, "graph compute failed (level " + std::to_string(lvl) + ")");
+            ggml_gallocr_free(alloc); ggml_free(ctx);
+            return false;
+        }
+
+        // taps + read-back
+        if (taps) {
+            cap_coords("lvl" + std::to_string(lvl) + ".in_coords");
+        }
+        for (auto & o : outs) {
+            if (o.first == "pre_up") {
+                std::vector<float> buf((size_t) ggml_nelements(o.second));
+                ggml_backend_tensor_get(o.second, buf.data(), 0, buf.size() * es);
+                cap("lvl" + std::to_string(lvl) + ".pre_up", buf.data(), buf.size());
+            }
+        }
+
+        if (has_up) {
+            ggml_tensor * h1_o = nullptr, * x_o = nullptr, * subdiv_o = nullptr;
+            for (auto & o : outs) {
+                if (o.first == "subdiv") subdiv_o = o.second;
+                if (o.first == "h1")     h1_o = o.second;
+                if (o.first == "x")      x_o  = o.second;
+            }
+            if (!guide) {   // shape decoder: read the predicted subdivision logits
+                up_subdiv.resize((size_t) 8 * L);
+                ggml_backend_tensor_get(subdiv_o, up_subdiv.data(), 0, up_subdiv.size() * es);
+                if (taps) cap("lvl" + std::to_string(lvl) + ".subdiv", up_subdiv.data(), up_subdiv.size());
+            }
+
+            // The surviving children + their gather index (child slot o + 8*parent,
+            // in [0, 8L)). Shape decoder: expand from predicted subdivision logits.
+            // Texture decoder: replay the encoder's recorded subdivision (`guide`),
+            // which also reproduces the encoder's exact input voxel order.
+            std::vector<int32_t> child_coords, cidx;
+            if (guide) {
+                const trellis2_subdiv_level & g = (*guide)[lvl];
+                child_coords = g.fine_coords;
+                cidx = g.cidx;
+            } else {
+                child_coords.reserve((size_t) L * 3);
+                cidx.reserve((size_t) L);
+                for (int v = 0; v < L; ++v) {
+                    for (int o = 0; o < 8; ++o) {
+                        if (up_subdiv[(size_t) v * 8 + o] > 0.0f) {
+                            cidx.push_back(o + 8 * v);
+                            child_coords.push_back(2 * coords[(size_t) v * 3]     + (o & 1));
+                            child_coords.push_back(2 * coords[(size_t) v * 3 + 1] + ((o >> 1) & 1));
+                            child_coords.push_back(2 * coords[(size_t) v * 3 + 2] + ((o >> 2) & 1));
+                        }
+                    }
+                }
+            }
+            if (predicted_subs) {
+                trellis2_subdiv_level & sub = (*predicted_subs)[(size_t) lvl];
+                sub.fine_coords = child_coords;
+                sub.cidx = cidx;
+            }
+            const int L_child = (int) cidx.size();
+            if (L_child == 0) {
+                set_error(error, "no children at level " + std::to_string(lvl));
+                ggml_gallocr_free(alloc); ggml_free(ctx);
+                return false;
+            }
+
+            // Gather the surviving children of h1 [C_next*8, L] (viewed as
+            // [C_next, 8L]) and x [C, L] (viewed as [C/8, 8L]) — byte-identical
+            // to get_rows(cidx) on the reshaped tensors. On the CPU backend the
+            // conv output is already in host memory, so we read it in place
+            // instead of duplicating the full [C_next*8, L] (~8 GB at 1024^3).
+            auto host_gather = [&](ggml_tensor * t, int chans, std::vector<float> & out) {
+                out.resize((size_t) chans * L_child);
+                if (t->buffer && ggml_backend_buffer_is_host(t->buffer)) {
+                    const float * d = (const float *) t->data;
+                    for (int j = 0; j < L_child; ++j)
+                        std::memcpy(out.data() + (size_t) j * chans,
+                                    d + (size_t) cidx[(size_t) j] * chans, (size_t) chans * es);
+                } else {
+                    std::vector<float> full((size_t) ggml_nelements(t));
+                    ggml_backend_tensor_get(t, full.data(), 0, full.size() * es);
+                    for (int j = 0; j < L_child; ++j)
+                        std::memcpy(out.data() + (size_t) j * chans,
+                                    full.data() + (size_t) cidx[(size_t) j] * chans, (size_t) chans * es);
+                }
+            };
+            auto t_gh = t_now();
+            host_gather(h1_o, C_next, up_hch);   // [C_next, L_child]
+            host_gather(x_o,  C / 8,  up_xch);   // [C/8,     L_child]
+            if (t2_timing) ms_gather += ms_since(t_gh);
+
+            prev_C = C;
+            prev_L = L;
+            coords = std::move(child_coords);
+            L = L_child;
+        } else {
+            out_feats.resize((size_t) hp.out_channels * L);
+            for (auto & o : outs) {
+                if (o.first == "out") {
+                    ggml_backend_tensor_get(o.second, out_feats.data(), 0, out_feats.size() * es);
+                }
+            }
+            if (pbr_scale)   // tex decoder: map to [0,1] like the reference *0.5+0.5
+                for (float & f : out_feats) f = f * 0.5f + 0.5f;
+            out_coords = coords;
+            if (taps) {
+                cap(pbr_scale ? "pbr" : "out7", out_feats.data(), out_feats.size());
+                cap_coords("out_coords");
+            }
+        }
+
+        ggml_gallocr_free(alloc);
+        ggml_free(ctx);
+
+        // upsample-to-level-N: at this point `coords` holds the child set this
+        // level's up-block produced (has_up is always true for lvl < n_levels-1,
+        // which upsample_times-1 always is), so return it and skip the rest.
+        if (upsample_times >= 0 && lvl == upsample_times - 1) {
+            out_coords = coords;
+            if (t2_timing)
+                std::fprintf(stderr, "[shape_dec] nbr=%.0f graph=%.0f gather=%.0f ms\n",
+                             ms_nbr, ms_graph, ms_gather);
+            return true;
+        }
+    }
+
+    if (t2_timing)
+        std::fprintf(stderr, "[shape_dec] nbr=%.0f graph=%.0f gather=%.0f ms\n",
+                     ms_nbr, ms_graph, ms_gather);
+    return true;
+}
+
+bool trellis2_shape_dec_decode(trellis2_shape_dec_model * m,
+                               const float * slat, int n_voxels, const int32_t * coords_in,
+                               std::vector<float> & out_feats,
+                               std::vector<int32_t> & out_coords,
+                               trellis2_shape_dec_taps * taps,
+                               std::string * error) {
+    return shape_dec_run(m, slat, n_voxels, coords_in, /*upsample_times*/ -1,
+                         /*guide*/ nullptr, /*predicted_subs*/ nullptr, /*pbr_scale*/ false,
+                         out_feats, out_coords, taps, error);
+}
+
+bool trellis2_shape_dec_decode_with_subs(trellis2_shape_dec_model * m,
+                                         const float * slat, int n_voxels, const int32_t * coords_in,
+                                         std::vector<float> & out_feats,
+                                         std::vector<int32_t> & out_coords,
+                                         std::vector<trellis2_subdiv_level> & out_subs,
+                                         trellis2_shape_dec_taps * taps,
+                                         std::string * error) {
+    return shape_dec_run(m, slat, n_voxels, coords_in, /*upsample_times*/ -1,
+                         /*guide*/ nullptr, &out_subs, /*pbr_scale*/ false,
+                         out_feats, out_coords, taps, error);
+}
+
+bool trellis2_shape_dec_upsample(trellis2_shape_dec_model * m,
+                                 const float * slat, int n_voxels, const int32_t * coords,
+                                 int upsample_times,
+                                 std::vector<int32_t> & out_coords,
+                                 std::string * error) {
+    std::vector<float> unused;
+    return shape_dec_run(m, slat, n_voxels, coords, upsample_times,
+                         /*guide*/ nullptr, /*predicted_subs*/ nullptr, /*pbr_scale*/ false,
+                         unused, out_coords, /*taps*/ nullptr, error);
+}
+
+// Texture decoder: the shape-decoder driver with the supplied shape subdivision
+// replayed (guide) and the PBR [0,1] output scale.
+bool trellis2_tex_dec_decode(trellis2_shape_dec_model * m,
+                             const float * slat, int n_voxels, const int32_t * coords,
+                             const std::vector<trellis2_subdiv_level> & subs,
+                             std::vector<float> & out_feats,
+                             std::vector<int32_t> & out_coords,
+                             std::string * error) {
+    return shape_dec_run(m, slat, n_voxels, coords, /*upsample_times*/ -1,
+                         &subs, /*predicted_subs*/ nullptr, /*pbr_scale*/ true,
+                         out_feats, out_coords, /*taps*/ nullptr, error);
+}
+
+/*****************************************************************************
+** Shape-SLAT VAE encoder (FlexiDualGridVaeEncoder) — the mirror of the shape
+** decoder. The 6-channel dual grid at resolution R is downsampled 16x through
+** SparseSpatial2Channel (S2C) blocks into the 32-channel shape SLAT at R/16.
+** Unlike the decoder, an S2C step needs no learned decision — the parent set is
+** determined by the coordinates alone — so a whole level (ConvNeXt blocks + the
+** down-block's fine conv1, the S2C gather, and the coarse conv2) runs as one
+** graph. The per-level subdivision (which fine child maps to which coarse
+** parent) is recorded for the texture decoder to replay.
+*****************************************************************************/
+
+struct trellis2_shape_enc_model {
+    gguf_context * gguf = nullptr;
+    ggml_context * ctx  = nullptr;
+    trellis2_shape_enc_hparams hp;
+    bool has_data = false;
+
+    ggml_backend_t        backend     = nullptr;
+    ggml_backend_buffer_t weights_buf = nullptr;
+    std::string           backend_name;
+
+    std::unordered_map<std::string, ggml_tensor *> tensors;
+};
+
+trellis2_shape_enc_model *
+trellis2_shape_enc_load(const std::string & path, bool load_tensors, std::string * error,
+                        const char * device) {
+    auto * m = new trellis2_shape_enc_model();
+
+    gguf_init_params params;
+    params.no_alloc = true;
+    params.ctx      = &m->ctx;
+    m->gguf = gguf_init_from_file(path.c_str(), params);
+    if (!m->gguf) {
+        set_error(error, "gguf_init_from_file failed (not a GGUF file?): " + path);
+        delete m; return nullptr;
+    }
+
+    const char * arch = kv_str(m->gguf, "general.architecture", "");
+    if (std::strcmp(arch, "trellis2-shape-enc") != 0) {
+        set_error(error, std::string("unexpected architecture '") + arch +
+                         "' (expected 'trellis2-shape-enc')");
+        trellis2_shape_enc_free(m); return nullptr;
+    }
+
+    trellis2_shape_enc_hparams & hp = m->hp;
+    const char * P = "trellis2.shape_enc.";
+    auto K = [&](const std::string & s) { return std::string(P) + s; };
+    hp.in_channels     = (int32_t) kv_u32(m->gguf, K("in_channels").c_str(),     6);
+    hp.latent_channels = (int32_t) kv_u32(m->gguf, K("latent_channels").c_str(), 0);
+    hp.n_levels        = (int32_t) kv_u32(m->gguf, K("n_levels").c_str(),        0);
+    hp.norm_eps        =           kv_f32(m->gguf, K("norm_eps").c_str(),        1e-6f);
+    hp.file_type       = (int32_t) kv_u32(m->gguf, "general.file_type", 0);
+    for (int i = 0; i < hp.n_levels && i < 8; ++i) {
+        hp.channels[i]   = (int32_t) kv_u32(m->gguf, K("channels."   + std::to_string(i)).c_str(), 0);
+        hp.num_blocks[i] = (int32_t) kv_u32(m->gguf, K("num_blocks." + std::to_string(i)).c_str(), 0);
+    }
+
+    for (ggml_tensor * t = ggml_get_first_tensor(m->ctx); t != nullptr;
+         t = ggml_get_next_tensor(m->ctx, t)) {
+        m->tensors[t->name] = t;
+    }
+
+    if (load_tensors) {
+        m->backend = init_best_backend(m->backend_name, device);
+        m->weights_buf = ggml_backend_alloc_ctx_tensors(m->ctx, m->backend);
+        if (!m->weights_buf) {
+            set_error(error, "failed to allocate weights on backend " + m->backend_name);
+            trellis2_shape_enc_free(m); return nullptr;
+        }
+        std::ifstream fin(path, std::ios::binary);
+        if (!fin) { set_error(error, "cannot reopen file for weight data: " + path); trellis2_shape_enc_free(m); return nullptr; }
+        const size_t data_off = gguf_get_data_offset(m->gguf);
+        const int64_t nt = gguf_get_n_tensors(m->gguf);
+        std::vector<uint8_t> buf;
+        for (int64_t i = 0; i < nt; ++i) {
+            const char * name = gguf_get_tensor_name(m->gguf, i);
+            ggml_tensor * t = m->tensors[name];
+            const size_t nb = ggml_nbytes(t);
+            const size_t off = data_off + gguf_get_tensor_offset(m->gguf, i);
+            buf.resize(nb);
+            fin.seekg((std::streamoff) off, std::ios::beg);
+            if (!fin.read(reinterpret_cast<char *>(buf.data()), (std::streamsize) nb)) {
+                set_error(error, std::string("failed reading weight '") + name + "' from file");
+                trellis2_shape_enc_free(m); return nullptr;
+            }
+            ggml_backend_tensor_set(t, buf.data(), 0, nb);
+        }
+        m->has_data = true;
+    }
+    return m;
+}
+
+void trellis2_shape_enc_free(trellis2_shape_enc_model * m) {
+    if (!m) return;
+    if (m->weights_buf) ggml_backend_buffer_free(m->weights_buf);
+    if (m->backend)     ggml_backend_free(m->backend);
+    if (m->gguf)        gguf_free(m->gguf);
+    if (m->ctx)         ggml_free(m->ctx);
+    delete m;
+}
+
+const char * trellis2_shape_enc_backend_name(const trellis2_shape_enc_model * m) {
+    return (m && !m->backend_name.empty()) ? m->backend_name.c_str() : "none";
+}
+
+const trellis2_shape_enc_hparams &
+trellis2_shape_enc_hparams_of(const trellis2_shape_enc_model * m) { return m->hp; }
+
+bool trellis2_shape_enc_encode(trellis2_shape_enc_model * m,
+                               const float * in6, int n_voxels, const int32_t * coords_in,
+                               std::vector<float> & out_slat,
+                               std::vector<int32_t> & out_coords,
+                               std::vector<trellis2_subdiv_level> & out_subs,
+                               trellis2_shape_dec_taps * taps,
+                               std::string * error) {
+    if (!m)           { set_error(error, "null model"); return false; }
+    if (!m->has_data) { set_error(error, "model loaded metadata-only; reload with load_tensors=true"); return false; }
+
+    const trellis2_shape_enc_hparams & hp = m->hp;
+    const int n_levels = hp.n_levels;
+    const float eps = hp.norm_eps;
+    const size_t es = sizeof(float);
+    std::string missing;
+
+    // host-side level state
+    std::vector<int32_t> coords(coords_in, coords_in + (size_t) n_voxels * 3);
+    int L = n_voxels;
+    std::vector<float> feats;   // [L * C] voxel-major, current level features
+
+    // input to the network: (dual-vertex offset, intersected) - 0.5
+    std::vector<float> in_shift((size_t) L * hp.in_channels);
+    for (size_t i = 0; i < in_shift.size(); ++i) in_shift[i] = in6[i] - 0.5f;
+
+    out_subs.assign(std::max(0, n_levels - 1), {});
+
+    auto cap = [&](const std::string & name, const float * d, size_t n) {
+        if (!taps) return;
+        taps->names.push_back(name); taps->data.emplace_back(d, d + n);
+    };
+
+    for (int lvl = 0; lvl < n_levels; ++lvl) {
+        const int C_in = hp.channels[lvl];
+        const bool has_down = lvl < n_levels - 1;
+        const int C_out = has_down ? hp.channels[lvl + 1] : 0;
+
+        // ── host: fine neighbor maps (ConvNeXt + down conv1) ────────────────
+        std::vector<std::vector<int32_t>> nfine;
+        build_neighbor_indices(coords, L, nfine);
+
+        // ── host: S2C child map + coarse coords + coarse neighbor maps ──────
+        // coarse parent = fine // 2, subidx = bit-packed (x&1,y&1,z&1). Coarse
+        // coords are lexicographically sorted to match the reference's unique().
+        std::vector<int32_t> coarse_coords;   // [Lc*3]
+        std::vector<int32_t> childidx;        // [Lc*8]  fine row of child (or -1)
+        std::vector<int32_t> cidx;            // [L]     8*parent_row + subidx (decoder replay)
+        int Lc = 0;
+        std::vector<std::vector<int32_t>> ncoarse;
+        if (has_down) {
+            std::unordered_map<uint64_t, int32_t> fine_map;
+            fine_map.reserve((size_t) L * 2);
+            for (int v = 0; v < L; ++v)
+                fine_map[voxel_key(coords[(size_t) v*3], coords[(size_t) v*3+1], coords[(size_t) v*3+2])] = v;
+            // unique parents
+            std::unordered_map<uint64_t, int32_t> parent_seen;
+            parent_seen.reserve((size_t) L);
+            std::vector<std::array<int32_t,3>> parents;
+            for (int v = 0; v < L; ++v) {
+                const int32_t px = coords[(size_t) v*3] >> 1,   // // 2 (coords >= 0)
+                              py = coords[(size_t) v*3+1] >> 1,
+                              pz = coords[(size_t) v*3+2] >> 1;
+                const uint64_t pk = voxel_key(px, py, pz);
+                if (parent_seen.emplace(pk, 0).second) parents.push_back({px, py, pz});
+            }
+            std::sort(parents.begin(), parents.end());   // lexicographic (x,y,z)
+            Lc = (int) parents.size();
+            coarse_coords.resize((size_t) Lc * 3);
+            std::unordered_map<uint64_t, int32_t> coarse_map;
+            coarse_map.reserve((size_t) Lc * 2);
+            for (int p = 0; p < Lc; ++p) {
+                coarse_coords[(size_t) p*3] = parents[p][0];
+                coarse_coords[(size_t) p*3+1] = parents[p][1];
+                coarse_coords[(size_t) p*3+2] = parents[p][2];
+                coarse_map[voxel_key(parents[p][0], parents[p][1], parents[p][2])] = p;
+            }
+            // childidx[pr*8+o] = fine row of child (or -1 sentinel for missing)
+            childidx.assign((size_t) Lc * 8, -1);
+            for (int p = 0; p < Lc; ++p) {
+                for (int o = 0; o < 8; ++o) {
+                    const int32_t cx = 2*parents[p][0] + (o & 1),
+                                  cy = 2*parents[p][1] + ((o >> 1) & 1),
+                                  cz = 2*parents[p][2] + ((o >> 2) & 1);
+                    auto it = fine_map.find(voxel_key(cx, cy, cz));
+                    if (it != fine_map.end()) childidx[(size_t) p*8 + o] = it->second;
+                }
+            }
+            // decoder replay: for each fine voxel, its coarse parent row + subidx
+            cidx.resize((size_t) L);
+            for (int v = 0; v < L; ++v) {
+                const int32_t px = coords[(size_t) v*3] >> 1,
+                              py = coords[(size_t) v*3+1] >> 1,
+                              pz = coords[(size_t) v*3+2] >> 1;
+                const int o = (coords[(size_t) v*3] & 1)
+                            | ((coords[(size_t) v*3+1] & 1) << 1)
+                            | ((coords[(size_t) v*3+2] & 1) << 2);
+                cidx[(size_t) v] = 8 * coarse_map[voxel_key(px, py, pz)] + o;
+            }
+            build_neighbor_indices(coarse_coords, Lc, ncoarse);
+        }
+
+        // ── graph ───────────────────────────────────────────────────────────
+        const size_t gsize = 65536;
+        const size_t mem = ggml_tensor_overhead() * gsize + ggml_graph_overhead_custom(gsize, false);
+        ggml_init_params ip{ mem, nullptr, true };
+        ggml_context * ctx = ggml_init(ip);
+        ggml_cgraph * gf = ggml_new_graph_custom(ctx, gsize, false);
+
+        auto W = [&](const std::string & n) -> ggml_tensor * {
+            auto it = m->tensors.find(n);
+            if (it == m->tensors.end()) { if (missing.empty()) missing = n; return nullptr; }
+            return it->second;
+        };
+        auto lin = [&](ggml_tensor * in, const std::string & pfx) -> ggml_tensor * {
+            ggml_tensor * y = ggml_mul_mat(ctx, W(pfx + ".weight"), in);
+            ggml_tensor * b = W(pfx + ".bias");
+            if (b) y = ggml_add(ctx, y, b);
+            return y;
+        };
+        auto ln_affine = [&](ggml_tensor * h, const std::string & pfx) -> ggml_tensor * {
+            ggml_tensor * y = ggml_norm(ctx, h, eps);
+            y = ggml_mul(ctx, y, W(pfx + ".weight"));
+            y = ggml_add(ctx, y, W(pfx + ".bias"));
+            return y;
+        };
+
+        // 27 fine + 27 coarse neighbor leaves
+        std::vector<ggml_tensor *> idx_f(27), mask_f(27), idx_c(27), mask_c(27);
+        for (int k = 0; k < 27; ++k) {
+            idx_f[k]  = ggml_new_tensor_1d(ctx, GGML_TYPE_I32, L);
+            mask_f[k] = ggml_new_tensor_2d(ctx, GGML_TYPE_F32, 1, L);
+            ggml_set_input(idx_f[k]); ggml_set_input(mask_f[k]);
+        }
+        if (has_down) {
+            for (int k = 0; k < 27; ++k) {
+                idx_c[k]  = ggml_new_tensor_1d(ctx, GGML_TYPE_I32, Lc);
+                mask_c[k] = ggml_new_tensor_2d(ctx, GGML_TYPE_F32, 1, Lc);
+                ggml_set_input(idx_c[k]); ggml_set_input(mask_c[k]);
+            }
+        }
+        auto conv = [&](ggml_tensor * x, const std::string & pfx,
+                        std::vector<ggml_tensor *> & idxs, std::vector<ggml_tensor *> & masks) -> ggml_tensor * {
+            ggml_tensor * w = W(pfx + ".weight");   // ne [Ci, 27, Co]
+            ggml_tensor * b = W(pfx + ".bias");
+            if (!w || !b) return x;
+            const int64_t Ci = w->ne[0], Co = w->ne[2];
+            ggml_tensor * acc = nullptr;
+            for (int k = 0; k < 27; ++k) {
+                ggml_tensor * wk = ggml_cont(ctx, ggml_view_3d(ctx, w, Ci, 1, Co, w->nb[1], w->nb[2], (size_t) k*w->nb[1]));
+                wk = ggml_reshape_2d(ctx, wk, Ci, Co);
+                ggml_tensor * g = ggml_get_rows(ctx, x, idxs[k]);
+                g = ggml_mul(ctx, g, masks[k]);
+                ggml_tensor * y = ggml_mul_mat(ctx, wk, g);
+                acc = acc ? ggml_add(ctx, acc, y) : y;
+            }
+            return ggml_add(ctx, acc, b);
+        };
+        auto convnext = [&](ggml_tensor * x, const std::string & pfx) -> ggml_tensor * {
+            ggml_tensor * h = conv(x, pfx + ".conv", idx_f, mask_f);
+            h = ln_affine(h, pfx + ".norm");
+            h = lin(h, pfx + ".mlp.0");
+            h = ggml_silu(ctx, h);
+            h = lin(h, pfx + ".mlp.2");
+            return ggml_add(ctx, h, x);
+        };
+
+        // input for this level: 6-channel dual grid at lvl 0 (through input_layer),
+        // else the previous level's [C_in, L] features.
+        const int in_dim = (lvl == 0) ? hp.in_channels : C_in;
+        ggml_tensor * in_a = ggml_new_tensor_2d(ctx, GGML_TYPE_F32, in_dim, L);
+        ggml_set_input(in_a);
+        ggml_tensor * h = (lvl == 0) ? lin(in_a, "input_layer") : in_a;
+
+        for (int b = 0; b < hp.num_blocks[lvl]; ++b)
+            h = convnext(h, "blocks." + std::to_string(lvl) + "." + std::to_string(b));
+
+        // S2C child-gather leaves (shared by the h1 and skip-x gathers)
+        ggml_tensor * cidx_t = nullptr, * cmask_t = nullptr;
+        ggml_tensor * out_h = nullptr;
+        if (has_down) {
+            const std::string down = "blocks." + std::to_string(lvl) + "." + std::to_string(hp.num_blocks[lvl]);
+            cidx_t  = ggml_new_tensor_1d(ctx, GGML_TYPE_I32, (int64_t) Lc * 8);
+            cmask_t = ggml_new_tensor_2d(ctx, GGML_TYPE_F32, 1, (int64_t) Lc * 8);
+            ggml_set_input(cidx_t); ggml_set_input(cmask_t);
+
+            ggml_tensor * hn1 = ggml_silu(ctx, ln_affine(h, down + ".norm1"));
+            ggml_tensor * h1 = conv(hn1, down + ".conv1", idx_f, mask_f);       // [C_out/8, L]
+            // S2C gather: [ch, L] -> [ch, Lc*8] (masked) -> reshape [ch*8, Lc]
+            auto s2c = [&](ggml_tensor * t, int ch) -> ggml_tensor * {
+                ggml_tensor * g = ggml_get_rows(ctx, t, cidx_t);               // [ch, Lc*8]
+                g = ggml_mul(ctx, g, cmask_t);
+                return ggml_reshape_2d(ctx, ggml_cont(ctx, g), (int64_t) ch * 8, Lc);
+            };
+            ggml_tensor * h1c = s2c(h1, C_out / 8);                            // [C_out, Lc]
+            ggml_tensor * xc  = s2c(h, C_in);                                  // [C_in*8, Lc]
+            ggml_tensor * hn2 = ggml_silu(ctx, ggml_norm(ctx, h1c, eps));      // norm2 affine-free
+            ggml_tensor * h2  = conv(hn2, down + ".conv2", idx_c, mask_c);     // [C_out, Lc]
+            // skip: mean over the (C_in*8 / C_out) group of xc
+            const int gsz = (C_in * 8) / C_out;
+            ggml_tensor * skip = ggml_reshape_3d(ctx, xc, gsz, C_out, Lc);
+            skip = ggml_reshape_2d(ctx, ggml_cont(ctx, ggml_mean(ctx, skip)), C_out, Lc);
+            out_h = ggml_add(ctx, h2, skip);                                   // [C_out, Lc]
+        } else {
+            ggml_tensor * hn = ggml_norm(ctx, h, 1e-5f);                       // F.layer_norm affine-free
+            ggml_tensor * z = lin(hn, "to_latent");                           // [2*latent, L]
+            // take the mean half (posterior mean): channels [0, latent)
+            out_h = ggml_cont(ctx, ggml_view_2d(ctx, z, hp.latent_channels, L, z->nb[1], 0));
+        }
+        out_h = ggml_cont(ctx, out_h);
+        ggml_set_output(out_h);
+        ggml_build_forward_expand(gf, out_h);
+
+        if (!missing.empty()) {
+            set_error(error, "missing tensor: " + missing + " (level " + std::to_string(lvl) + ")");
+            ggml_free(ctx); return false;
+        }
+
+        ggml_gallocr_t alloc = ggml_gallocr_new(ggml_backend_get_default_buffer_type(m->backend));
+        if (!ggml_gallocr_alloc_graph(alloc, gf)) {
+            set_error(error, "ggml_gallocr_alloc_graph failed (enc level " + std::to_string(lvl) + ")");
+            ggml_gallocr_free(alloc); ggml_free(ctx); return false;
+        }
+
+        // upload neighbor leaves (clamp missing to row 0, mask 0)
+        auto upload_nbr = [&](std::vector<std::vector<int32_t>> & nb, int Ln,
+                              std::vector<ggml_tensor *> & idxs, std::vector<ggml_tensor *> & masks) {
+            std::vector<int32_t> cl((size_t) Ln); std::vector<float> mk((size_t) Ln);
+            for (int k = 0; k < 27; ++k) {
+                for (int v = 0; v < Ln; ++v) {
+                    const bool miss = nb[k][(size_t) v] >= Ln;
+                    cl[(size_t) v] = miss ? 0 : nb[k][(size_t) v];
+                    mk[(size_t) v] = miss ? 0.0f : 1.0f;
+                }
+                ggml_backend_tensor_set(idxs[k], cl.data(), 0, (size_t) Ln * sizeof(int32_t));
+                ggml_backend_tensor_set(masks[k], mk.data(), 0, (size_t) Ln * sizeof(float));
+            }
+        };
+        upload_nbr(nfine, L, idx_f, mask_f);
+        if (lvl == 0) ggml_backend_tensor_set(in_a, in_shift.data(), 0, in_shift.size() * es);
+        else          ggml_backend_tensor_set(in_a, feats.data(),   0, feats.size() * es);
+        if (has_down) {
+            upload_nbr(ncoarse, Lc, idx_c, mask_c);
+            std::vector<int32_t> cl((size_t) Lc * 8); std::vector<float> mk((size_t) Lc * 8);
+            for (size_t i = 0; i < cl.size(); ++i) {
+                const bool miss = childidx[i] < 0;
+                cl[i] = miss ? 0 : childidx[i];
+                mk[i] = miss ? 0.0f : 1.0f;
+            }
+            ggml_backend_tensor_set(cidx_t,  cl.data(), 0, cl.size() * sizeof(int32_t));
+            ggml_backend_tensor_set(cmask_t, mk.data(), 0, mk.size() * sizeof(float));
+        }
+
+        if (ggml_backend_graph_compute(m->backend, gf) != GGML_STATUS_SUCCESS) {
+            set_error(error, "enc graph compute failed (level " + std::to_string(lvl) + ")");
+            ggml_gallocr_free(alloc); ggml_free(ctx); return false;
+        }
+
+        const int C_next = has_down ? C_out : hp.latent_channels;
+        const int L_next = has_down ? Lc : L;
+        feats.resize((size_t) C_next * L_next);
+        ggml_backend_tensor_get(out_h, feats.data(), 0, feats.size() * es);
+
+        if (taps) cap("enc_lvl" + std::to_string(lvl), feats.data(), feats.size());
+
+        if (has_down) {
+            // record subdivision for the decoder (decoder order = reverse of encode)
+            trellis2_subdiv_level & sl = out_subs[(size_t)(n_levels - 2 - lvl)];
+            sl.fine_coords = coords;   // this level's (fine) coords, in fine order
+            sl.cidx = std::move(cidx);
+            coords = std::move(coarse_coords);
+            L = Lc;
+        } else {
+            out_slat = feats;
+            out_coords = coords;
+        }
+        ggml_gallocr_free(alloc); ggml_free(ctx);
+    }
+    return true;
+}
diff --git a/trellis2.h b/trellis2.h
index f39e71f..64ae4ce 100644
--- a/trellis2.h
+++ b/trellis2.h
@@ -146,7 +146,8 @@ TRELLIS2_API const char * trellis2_version(void);
 TRELLIS2_API trellis2_ss_flow_model *
 trellis2_ss_flow_load(const std::string & path,
                       bool load_tensors = true,
-                      std::string * error = nullptr);
+                      std::string * error = nullptr,
+                      const char * device = nullptr);
 
 TRELLIS2_API void trellis2_ss_flow_free(trellis2_ss_flow_model * m);
 
@@ -176,6 +177,18 @@ struct trellis2_ss_sampler_params {
     float    sigma_min             = 1e-5f;
     uint64_t seed                  = 0;     // used only when noise is generated internally
     bool     verbose               = true;  // print per-step progress to stderr
+
+    // Optional per-step progress callback (called after each Euler step).
+    void   (*progress)(void * user, int step, int total) = nullptr;
+    void   * progress_user         = nullptr;
+
+    // Optional per-step preview callback: receives the denoised x_0 estimate
+    // (the current best-guess clean latent, [in_channels * resolution^3]) after
+    // each step, so a host can decode it into a live intermediate 3D preview.
+    // `latent` is valid only during the call. Runs on the sampling thread — the
+    // callee must return promptly (it blocks the next step).
+    void   (*preview)(void * user, int step, int total, const float * latent, int n) = nullptr;
+    void   * preview_user          = nullptr;
 };
 
 // Run one forward pass of the SS-flow DiT (CPU backend), i.e. the velocity
@@ -253,7 +266,8 @@ struct trellis2_ss_dec_model;
 TRELLIS2_API trellis2_ss_dec_model *
 trellis2_ss_dec_load(const std::string & path,
                      bool load_tensors = true,
-                     std::string * error = nullptr);
+                     std::string * error = nullptr,
+                     const char * device = nullptr);
 
 TRELLIS2_API void trellis2_ss_dec_free(trellis2_ss_dec_model * m);
 
@@ -281,6 +295,391 @@ trellis2_ss_dec_decode(trellis2_ss_dec_model * m,
                        const float * latent,
                        float * out, std::string * error = nullptr);
 
+/*****************************************************************************
+** Public API – Shape-SLAT flow DiT (stage 2, fine geometry)
+**
+** SLatFlowModel: the same 1.3B DiT block structure as the SS-flow model, but
+** sparse — tokens are the active voxels of the 32^3 scaffold produced by the
+** SS stage, with 3D RoPE over each voxel's integer coordinates. In/out are
+** 32-channel per-voxel structured latents.
+*****************************************************************************/
+
+struct trellis2_slat_flow_hparams {
+    int32_t resolution     = 0;   // 32 for the 512 model
+    int32_t in_channels    = 0;   // 32
+    int32_t out_channels   = 0;   // 32
+    int32_t model_channels = 0;   // 1536
+    int32_t cond_channels  = 0;   // 1024
+    int32_t num_blocks     = 0;   // 30
+    int32_t num_heads      = 0;   // 12
+    float   mlp_ratio      = 0.0f;
+    int32_t share_mod         = 0;
+    int32_t qk_rms_norm       = 0;
+    int32_t qk_rms_norm_cross = 0;
+    float   rope_freq_min  = 1.0f;
+    float   rope_freq_base = 10000.0f;
+    char    pe_mode[16]    = {0};
+    int32_t file_type      = 0;
+
+    // shape_slat_normalization (pipeline.json), baked in by the converter:
+    // decoder input = sampler output * std + mean.
+    float   norm_mean[64]  = {0};
+    float   norm_std[64]   = {0};
+
+    // Texture SLAT flow only (concat_cond). 0 on the shape flow. When > 0 the DiT
+    // is conditioned on the shape via concatenation: in_channels = out_channels +
+    // concat_cond_channels (64 = 32 tex-noise + 32 shape-SLAT). The shape SLAT is
+    // normalized by concat_norm_* before being concatenated onto the noise.
+    int32_t concat_cond_channels = 0;
+    float   concat_norm_mean[64] = {0};
+    float   concat_norm_std[64]  = {0};
+
+    int32_t head_dim() const { return num_heads ? model_channels / num_heads : 0; }
+};
+
+struct trellis2_slat_flow_model;
+
+TRELLIS2_API trellis2_slat_flow_model *
+trellis2_slat_flow_load(const std::string & path,
+                        bool load_tensors = true,
+                        std::string * error = nullptr,
+                        const char * device = nullptr);
+
+TRELLIS2_API void trellis2_slat_flow_free(trellis2_slat_flow_model * m);
+TRELLIS2_API const char * trellis2_slat_flow_backend_name(const trellis2_slat_flow_model * m);
+TRELLIS2_API const trellis2_slat_flow_hparams &
+trellis2_slat_flow_hparams_of(const trellis2_slat_flow_model * m);
+
+// One forward pass v = model(x, t, cond) over L active voxels.
+//   x      : [L * in_channels] floats, voxel-major (x[v*C + c])
+//   coords : [L * 3] int32 voxel coordinates (c1, c2, c3) in [0, resolution)
+//   cond   : [cond_tokens * cond_channels], token-major (.dinodata layout)
+//   out    : [L * out_channels], voxel-major
+TRELLIS2_API bool
+trellis2_slat_flow_forward(trellis2_slat_flow_model * m,
+                           const float * x, int n_voxels, const int32_t * coords,
+                           float t,
+                           const float * cond, int cond_tokens, int cond_channels,
+                           float * out, std::string * error = nullptr);
+
+// Full flow-Euler sampling (CFG + interval + rescale) over the voxel set.
+// Defaults for the shape stage differ from the SS stage: guidance_rescale 0.5,
+// rescale_t 3.0 (set them in `params`; steps 12 / strength 7.5 are shared).
+// When denormalize is true the output is sampler_output * std + mean, ready
+// for the shape decoder.
+TRELLIS2_API bool
+trellis2_slat_flow_sample(trellis2_slat_flow_model * m,
+                          int n_voxels, const int32_t * coords,
+                          const float * cond, int cond_tokens, int cond_channels,
+                          const trellis2_ss_sampler_params * params,
+                          const float * noise, bool denormalize,
+                          float * out_latent, std::string * error = nullptr);
+
+// Texture-SLAT flow sampling with concat_cond (requires concat_cond_channels>0).
+// Diffuses out_channels (32) and, each step, concatenates the shape SLAT
+// (normalized by concat_norm_*) onto the noise so the DiT sees in_channels (64).
+//   shape_slat : [L * concat_cond_channels] the (un-normalized) shape SLAT.
+//   noise      : [L * out_channels] initial noise, or null to seed from params.
+//   out_latent : [L * out_channels]; when denormalize, * norm_std + norm_mean.
+TRELLIS2_API bool
+trellis2_slat_flow_sample_tex(trellis2_slat_flow_model * m,
+                              int n_voxels, const int32_t * coords,
+                              const float * cond, int cond_tokens, int cond_channels,
+                              const float * shape_slat,
+                              const trellis2_ss_sampler_params * params,
+                              const float * noise, bool denormalize,
+                              float * out_latent, std::string * error = nullptr);
+
+/*****************************************************************************
+** Public API – Shape-SLAT VAE decoder (FlexiDualGridVaeDecoder)
+**
+** Sparse ConvNeXt U-Net decoder: 32-channel latent on the 32^3 voxel set ->
+** 7 channels per active voxel at 16x resolution (512^3). The subdivision at
+** each of the 4 upsampling steps is predicted by the network, so the active
+** set grows adaptively. Output channels: [0:3] dual-vertex offset logits
+** (sigmoid+margin applied by the mesher), [3:6] per-axis intersection logits,
+** [6] quad split weight (softplus applied by the mesher).
+*****************************************************************************/
+
+struct trellis2_shape_dec_hparams {
+    int32_t latent_channels = 0;    // 32
+    int32_t out_channels    = 0;    // 7
+    int32_t n_levels        = 0;    // 5
+    int32_t channels[8]     = {0};  // [1024, 512, 256, 128, 64]
+    int32_t num_blocks[8]   = {0};  // [4, 16, 8, 4, 0]
+    float   norm_eps        = 1e-6f;
+    float   voxel_margin    = 0.5f;
+    int32_t file_type       = 0;
+
+    int32_t upscale() const { int u = 1; for (int i = 1; i < n_levels; ++i) u *= 2; return u; }
+};
+
+struct trellis2_shape_dec_model;
+
+TRELLIS2_API trellis2_shape_dec_model *
+trellis2_shape_dec_load(const std::string & path,
+                        bool load_tensors = true,
+                        std::string * error = nullptr,
+                        const char * device = nullptr);
+
+TRELLIS2_API void trellis2_shape_dec_free(trellis2_shape_dec_model * m);
+TRELLIS2_API const char * trellis2_shape_dec_backend_name(const trellis2_shape_dec_model * m);
+TRELLIS2_API const trellis2_shape_dec_hparams &
+trellis2_shape_dec_hparams_of(const trellis2_shape_dec_model * m);
+
+// Optional per-level activation taps for validation (names match
+// scripts/dump_slat_reference.py: "lvl{i}.pre_up", "lvl{i}.subdiv",
+// "lvl{i}.in_coords", "out7", "out_coords").
+struct trellis2_shape_dec_taps {
+    std::vector<std::string>        names;
+    std::vector<std::vector<float>> data;
+};
+
+// One decoder upsample level. For every fine (output) voxel, cidx identifies
+// the selected child in the coarse [C*8, L_coarse] feature tensor. Shape
+// decoding can return these levels so another decoder (notably the texture VAE)
+// can reproduce exactly the same sparse hierarchy.
+struct trellis2_subdiv_level {
+    std::vector<int32_t> fine_coords;   // [Lf * 3]
+    std::vector<int32_t> cidx;          // [Lf]
+};
+
+// Decode the (denormalized) structured latent into per-voxel dual-grid fields.
+//   slat       : [L * latent_channels] floats, voxel-major
+//   coords     : [L * 3] int32 at the input resolution (32^3 scaffold)
+//   out_feats  : filled with [L_out * out_channels] floats, voxel-major
+//   out_coords : filled with [L_out * 3] int32 at input_res * upscale()
+TRELLIS2_API bool
+trellis2_shape_dec_decode(trellis2_shape_dec_model * m,
+                          const float * slat, int n_voxels, const int32_t * coords,
+                          std::vector<float> & out_feats,
+                          std::vector<int32_t> & out_coords,
+                          trellis2_shape_dec_taps * taps = nullptr,
+                          std::string * error = nullptr);
+
+// Full shape decode plus the predicted sparse subdivision hierarchy, in decoder
+// order (out_subs[0] is the first/coarsest upsample). This is the integrated
+// image-to-3D texture path's guide_subs equivalent.
+TRELLIS2_API bool
+trellis2_shape_dec_decode_with_subs(trellis2_shape_dec_model * m,
+                                    const float * slat, int n_voxels, const int32_t * coords,
+                                    std::vector<float> & out_feats,
+                                    std::vector<int32_t> & out_coords,
+                                    std::vector<trellis2_subdiv_level> & out_subs,
+                                    trellis2_shape_dec_taps * taps = nullptr,
+                                    std::string * error = nullptr);
+
+// Predict just the subdivided coordinate set after `upsample_times` levels,
+// without running the output layer — mirrors FlexiDualGridVaeDecoder.upsample(),
+// used by the 1024 cascade to turn the LR (32^3) scaffold into candidate coords.
+//   upsample_times : in [1, n_levels-1] (4 for the cascade: 32^3 -> 512^3)
+//   out_coords     : filled with [L_out * 3] int32 at input_res * 2^upsample_times
+TRELLIS2_API bool
+trellis2_shape_dec_upsample(trellis2_shape_dec_model * m,
+                            const float * slat, int n_voxels, const int32_t * coords,
+                            int upsample_times,
+                            std::vector<int32_t> & out_coords,
+                            std::string * error = nullptr);
+
+/*****************************************************************************
+** Public API – Shape-SLAT VAE encoder (FlexiDualGridVaeEncoder)
+**
+** The mirror of the shape decoder: a 6-channel dual grid ([offset(3),
+** intersected(3)] per active voxel at resolution R) is downsampled 16x through
+** SparseSpatial2Channel (S2C) blocks into a 32-channel latent at R/16 (the
+** "shape SLAT"). This is used by the standalone arbitrary-mesh texturing API
+** and its parity test. Integrated image-to-3D generation retains the original
+** generated shape SLAT and shape-decoder subdivisions instead of performing a
+** lossy decode/encode round trip.
+*****************************************************************************/
+
+struct trellis2_shape_enc_hparams {
+    int32_t in_channels     = 6;    // [offset(3), intersected(3)]
+    int32_t latent_channels = 0;    // 32
+    int32_t n_levels        = 0;    // 5
+    int32_t channels[8]     = {0};  // [64, 128, 256, 512, 1024]
+    int32_t num_blocks[8]   = {0};  // [0, 4, 8, 16, 4]
+    float   norm_eps        = 1e-6f;
+    int32_t file_type       = 0;
+};
+
+struct trellis2_shape_enc_model;
+
+TRELLIS2_API trellis2_shape_enc_model *
+trellis2_shape_enc_load(const std::string & path,
+                        bool load_tensors = true,
+                        std::string * error = nullptr,
+                        const char * device = nullptr);
+
+TRELLIS2_API void trellis2_shape_enc_free(trellis2_shape_enc_model * m);
+TRELLIS2_API const char * trellis2_shape_enc_backend_name(const trellis2_shape_enc_model * m);
+TRELLIS2_API const trellis2_shape_enc_hparams &
+trellis2_shape_enc_hparams_of(const trellis2_shape_enc_model * m);
+
+// Encode the dual grid into the shape SLAT.
+//   in6        : [N * 6] floats voxel-major = [offset(3), intersected(3)] (the
+//                encoder subtracts 0.5 internally, matching the reference).
+//   coords     : [N * 3] int32 at resolution R.
+//   out_slat   : filled with [Nl * latent_channels] floats, voxel-major.
+//   out_coords : filled with [Nl * 3] int32 at R/16.
+//   out_subs   : filled with (n_levels-1) subdivision levels in decoder order.
+TRELLIS2_API bool
+trellis2_shape_enc_encode(trellis2_shape_enc_model * m,
+                          const float * in6, int n_voxels, const int32_t * coords,
+                          std::vector<float> & out_slat,
+                          std::vector<int32_t> & out_coords,
+                          std::vector<trellis2_subdiv_level> & out_subs,
+                          trellis2_shape_dec_taps * taps = nullptr,
+                          std::string * error = nullptr);
+
+/*****************************************************************************
+** Public API – Texture-SLAT VAE decoder (SparseUnetVaeDecoder, pred_subdiv=False)
+**
+** Architecturally the shape decoder with two differences: it does NOT predict
+** the subdivision (it replays the encoder's recorded subdivision via `subs`)
+** and it emits 6 PBR channels (base_color[3], metallic, roughness, alpha),
+** already mapped to [0,1] (the reference's *0.5+0.5). Reuses the shape-decoder
+** model struct/loader/driver.
+*****************************************************************************/
+
+// Load a trellis2-tex-dec GGUF (returns a shape_dec model with out_channels=6).
+TRELLIS2_API trellis2_shape_dec_model *
+trellis2_tex_dec_load(const std::string & path,
+                      bool load_tensors = true,
+                      std::string * error = nullptr,
+                      const char * device = nullptr);
+
+// Decode the (denormalized) texture SLAT into per-voxel PBR, replaying `subs`.
+//   slat       : [L * latent_channels] tex SLAT, voxel-major.
+//   coords     : [L * 3] latent voxels (== the shape SLAT coords).
+//   subs       : shape decoder or encoder per-level subdivisions (decoder order).
+//   out_feats  : [M * 6] PBR, voxel-major, already in [0,1].
+//   out_coords : [M * 3] at R; a permutation-free reproduction of the encoder's
+//                input voxel order (so PBR voxel v == mesh vertex v).
+TRELLIS2_API bool
+trellis2_tex_dec_decode(trellis2_shape_dec_model * m,
+                        const float * slat, int n_voxels, const int32_t * coords,
+                        const std::vector<trellis2_subdiv_level> & subs,
+                        std::vector<float> & out_feats,
+                        std::vector<int32_t> & out_coords,
+                        std::string * error = nullptr);
+
+// Free VRAM (bytes) on the first GPU backend device, or 0 when there is no GPU
+// (CPU-only build/host). Used to auto-place the shape decoder and to decide
+// whether to free the flow DiTs before a decode. Cheap (a cudaMemGetInfo).
+TRELLIS2_API size_t trellis2_gpu_free_vram(void);
+
+/*****************************************************************************
+** Public API – DINOv3 ViT-L/16 image-conditioning encoder
+**
+** The encoder that produces trellis2_dino_cond from an image, replacing the
+** external dump_dinodata.py. Mirrors transformers' DINOv3ViTModel driven the
+** way TRELLIS.2's DinoV3FeatureExtractor drives it: manual embeddings ->
+** axial-2D-RoPE -> 24 layers, and an affine-free LayerNorm on the last layer
+** output (the model's own final `norm` is NOT applied).
+*****************************************************************************/
+
+struct trellis2_dino_hparams {
+    int32_t hidden_size         = 0;
+    int32_t n_layers            = 0;
+    int32_t n_heads             = 0;
+    int32_t intermediate_size   = 0;
+    int32_t patch_size          = 0;
+    int32_t num_register_tokens = 0;
+    float   layer_norm_eps      = 1e-5f;
+    float   rope_theta          = 100.0f;
+    float   image_mean[3]       = {0.485f, 0.456f, 0.406f};
+    float   image_std[3]        = {0.229f, 0.224f, 0.225f};
+    int32_t file_type           = 0;   // 0=f32, 1=f16
+
+    int32_t head_dim() const { return n_heads ? hidden_size / n_heads : 0; }
+};
+
+// Opaque handle to a loaded DINOv3 encoder (weights + metadata).
+struct trellis2_dino_model;
+
+// Optional per-layer activation taps for numerical validation. When a non-null
+// pointer is passed to trellis2_dino_encode, every captured intermediate is
+// appended as (name, row-major f32 buffer). Names match the reference dumper
+// (scripts/dump_dino_reference.py): "embd", "l{i}.out", "cond", plus detail
+// taps "l{i}.{norm1,attention,layer_scale1,norm2,mlp,layer_scale2}" for the
+// first and last layer.
+struct trellis2_dino_taps {
+    std::vector<std::string>        names;
+    std::vector<std::vector<float>> data;
+};
+
+// Load the DINOv3 encoder from a GGUF produced by convert_dino_to_gguf.py.
+TRELLIS2_API trellis2_dino_model *
+trellis2_dino_load(const std::string & path,
+                   bool load_tensors = true,
+                   std::string * error = nullptr,
+                   const char * device = nullptr);
+
+TRELLIS2_API void trellis2_dino_free(trellis2_dino_model * m);
+
+TRELLIS2_API const char * trellis2_dino_backend_name(const trellis2_dino_model * m);
+
+TRELLIS2_API const trellis2_dino_hparams &
+trellis2_dino_hparams_of(const trellis2_dino_model * m);
+
+// Encode ImageNet-normalized pixel values into the conditioning tensor.
+//
+//   pixel_values : [3 * S * S] floats, CHW ((x - mean) / std already applied) —
+//                  exactly the flattened [1, 3, S, S] the Python forward sees.
+//   image_size   : S; must be a multiple of patch_size (512 for the TRELLIS.2
+//                  "512" pipeline -> 1 CLS + 4 register + 1024 patch tokens).
+//   out          : the conditioning tensor, shape {1, N, C}.
+//   taps         : optional activation capture for validation (see above).
+//
+// Returns false on failure and (if `error`) fills it with a reason.
+TRELLIS2_API bool
+trellis2_dino_encode(trellis2_dino_model * m,
+                     const float * pixel_values, int image_size,
+                     trellis2_dino_cond & out,
+                     trellis2_dino_taps * taps = nullptr,
+                     std::string * error = nullptr);
+
+// Convenience wrapper: 8-bit RGB (HWC, [S*S*3]) -> /255 -> ImageNet normalize
+// -> trellis2_dino_encode.
+TRELLIS2_API bool
+trellis2_dino_encode_rgb(trellis2_dino_model * m,
+                         const uint8_t * rgb, int image_size,
+                         trellis2_dino_cond & out,
+                         std::string * error = nullptr);
+
+/*****************************************************************************
+** Public API – Image preprocessing (TRELLIS.2 pipeline.preprocess_image)
+**
+** For an RGBA input with a meaningful alpha channel (the "has_alpha" path):
+** downscale so max(W,H) <= 1024,
+** square-crop around the alpha>0.8 bounding box, premultiply onto black, and
+** LANCZOS-resize to out_size x out_size RGB. The resampler reproduces PIL's
+** fixed-point uint8 Lanczos-3 so results match the Python pipeline.
+*****************************************************************************/
+
+enum trellis2_background_mode {
+    TRELLIS2_BACKGROUND_AUTO  = 0,
+    TRELLIS2_BACKGROUND_KEEP  = 1,
+    TRELLIS2_BACKGROUND_BLACK = 2,
+    TRELLIS2_BACKGROUND_WHITE = 3,
+};
+
+// Replace a near-black/near-white background connected to the image border
+// with softly feathered alpha. AUTO leaves images with meaningful existing
+// alpha or a non-black/non-white border unchanged. Returns pixels whose alpha
+// changed, or -1 for invalid arguments.
+TRELLIS2_API int
+trellis2_remove_solid_background_rgba(uint8_t * rgba, int w, int h,
+                                      int mode = TRELLIS2_BACKGROUND_AUTO);
+
+// rgba: [h * w * 4] bytes. On success out_rgb has out_size*out_size*3 bytes.
+// Fails if the image has no pixels with alpha > 0.8*255.
+TRELLIS2_API bool
+trellis2_preprocess_rgba(const uint8_t * rgba, int w, int h,
+                         int out_size, std::vector<uint8_t> & out_rgb,
+                         std::string * error = nullptr);
+
 /*****************************************************************************
 ** Public API – DINOv3 conditioning (.dinodata)
 *****************************************************************************/
@@ -295,3 +694,8 @@ TRELLIS2_API bool trellis2_load_dinodata(const std::string & path,
 // Compute fingerprints over a loaded cond (min/max/mean/sum/l2/count).
 TRELLIS2_API trellis2_dino_fingerprint
 trellis2_dino_fingerprints(const trellis2_dino_cond & cond);
+
+// Write a cond to a .dinodata file (the format trellis2_load_dinodata reads).
+TRELLIS2_API bool trellis2_save_dinodata(const std::string & path,
+                                         const trellis2_dino_cond & cond,
+                                         std::string * error = nullptr);
diff --git a/trellis2_capi.cpp b/trellis2_capi.cpp
new file mode 100644
index 0000000..1f3a77e
--- /dev/null
+++ b/trellis2_capi.cpp
@@ -0,0 +1,986 @@
+// Flat C ABI wrapper around the trellis2 C++ API (see trellis2_capi.h).
+//
+// Owns the image-bytes decode (stb_image) so hosts can hand us untrusted
+// uploads directly; everything past decode reuses the validated C++ pipeline:
+//   decode -> preprocess -> DINOv3 -> SS-flow sample -> SS-dec -> marching cubes
+
+#include "trellis2_capi.h"
+#include "trellis2.h"
+#include "mesh_export.h"
+#include "pbr_utils.h"
+
+#define STB_IMAGE_IMPLEMENTATION
+#include "stb_image.h"
+#include "marching_cubes.h"
+#include "flexible_dual_grid.h"
+
+#include <algorithm>
+#include <cmath>
+#include <cstdint>
+#include <cstdio>
+#include <cstdlib>
+#include <cstring>
+#include <string>
+#include <unordered_map>
+#include <unordered_set>
+#include <utility>
+#include <vector>
+
+namespace {
+
+void copy_err(char * err, int err_len, const std::string & msg) {
+    if (!err || err_len <= 0) return;
+    std::snprintf(err, (size_t) err_len, "%s", msg.c_str());
+}
+
+// Rough peak VRAM the shape decode's transient buffers need at each tier
+// (measured on the reference image: ~2.4 GB at 512³, ~6.75 GB for the 1024³
+// level-3 conv output; rounded up for headroom). Mesh-dependent, so treated as
+// a threshold, not an exact reservation — the free-flows fallback then gives a
+// several-GB cushion if the estimate is low.
+size_t decode_vram_peak(int pipeline_type) {
+    const double GB = (double) (1ULL << 30);
+    return (size_t) ((pipeline_type == T2_PIPE_1024 ? 7.5 : 3.0) * GB);
+}
+
+} // namespace
+
+struct t2_pipeline {
+    trellis2_dino_model      * dino     = nullptr;
+    trellis2_ss_flow_model   * flow     = nullptr;
+    trellis2_ss_dec_model    * dec      = nullptr;
+    trellis2_slat_flow_model * slat     = nullptr;   // 512 model (fine path)
+    trellis2_slat_flow_model * slat_hr  = nullptr;   // 1024 model (cascade)
+    trellis2_shape_dec_model * shapedec = nullptr;   // shared by 512 + cascade
+    std::string backend;
+    bool fine = false;      // 512 dual-grid available
+    bool cascade = false;   // 1024 cascade available
+    bool texture = false;   // PBR texturing available (shape_enc + tex_dec + tex_flow)
+    int  flags = 0;
+    bool shapedec_gpu = false;   // shape decoder placed on the GPU (VRAM permitting)
+    // gguf paths, so the flow DiTs can be freed to make VRAM room for a GPU
+    // decode and lazily reloaded on the next generate (see ensure_decode_vram).
+    std::string ss_flow_path, slat_path, slat_hr_path;
+    // Texture-stage gguf paths. The tex models (~4 GB) are loaded lazily inside
+    // the texture stage — after the geometry flow DiTs are freed — and freed
+    // again, so they never coexist in VRAM with the geometry flows.
+    std::string shapeenc_path, texdec_path, texflow_path, texflow_hr_path;
+};
+
+// A generated mesh: verts (3/vertex), normals (3/vertex), tris (3/tri), and
+// optional per-vertex PBR (6/vertex: base_color rgb, metallic, roughness, alpha).
+struct t2_mesh_result {
+    std::vector<float> verts;
+    std::vector<float> normals;
+    std::vector<int>   tris;
+    std::vector<float> pbr;   // empty when untextured
+};
+
+namespace {
+
+// Reload any flow DiT freed by a previous GPU decode (see ensure_decode_vram).
+// No-op the common case where nothing was freed (pointers still set).
+bool reload_flows(t2_pipeline * p, std::string & e) {
+    if (!p->flow && !p->ss_flow_path.empty()) {
+        p->flow = trellis2_ss_flow_load(p->ss_flow_path.c_str(), true, &e);
+        if (!p->flow) return false;
+    }
+    if (!p->slat && !p->slat_path.empty()) {
+        p->slat = trellis2_slat_flow_load(p->slat_path.c_str(), true, &e);
+        if (!p->slat) return false;
+    }
+    if (!p->slat_hr && !p->slat_hr_path.empty()) {
+        p->slat_hr = trellis2_slat_flow_load(p->slat_hr_path.c_str(), true, &e);
+        if (!p->slat_hr) return false;
+    }
+    return true;
+}
+
+// Before a GPU shape decode, make room: if the decode's transient buffers would
+// not fit in current free VRAM, free the flow DiTs (all finished by decode time)
+// to reclaim their ~5-7 GB. reload_flows() brings them back on the next
+// generate. No-op for a CPU decoder or when the decode already fits.
+void ensure_decode_vram(t2_pipeline * p, int pipeline_type) {
+    if (!p->shapedec_gpu) return;
+    if (trellis2_gpu_free_vram() >= decode_vram_peak(pipeline_type)) return;
+    trellis2_ss_flow_free(p->flow);      p->flow    = nullptr;
+    trellis2_slat_flow_free(p->slat);    p->slat    = nullptr;
+    trellis2_slat_flow_free(p->slat_hr); p->slat_hr = nullptr;
+}
+
+// ── live intermediate 3D previews (voxel sets) ───────────────────────────────
+//
+// A preview is a self-describing "T2VOX01" blob the host streams to its viewer:
+//   char magic[8] = "T2VOX01\0"; u32 res; u32 nvox; u16 coords[3*nvox] in [0,res)
+// Voxels bound the payload (occupancy is sparse) and read as clearly "coarse"
+// against the final smooth mesh — the stages stay visually distinct.
+
+// Collect the occupied cells (logit > 0) of a dense [res^3] occupancy grid.
+void collect_occupied(const float * occ, int res, std::vector<int32_t> & cells) {
+    cells.clear();
+    for (int x = 0; x < res; ++x)
+    for (int y = 0; y < res; ++y)
+    for (int z = 0; z < res; ++z) {
+        if (occ[((size_t) x * res + y) * res + z] > 0.0f) {
+            cells.push_back(x); cells.push_back(y); cells.push_back(z);
+        }
+    }
+}
+
+// Pack a flat [x,y,z,...] cell list (each in [0,res)) into a T2VOX01 blob.
+void pack_voxels(int res, const std::vector<int32_t> & cells, std::vector<uint8_t> & blob) {
+    const uint32_t nvox = (uint32_t) (cells.size() / 3);
+    const uint32_t r = (uint32_t) res;
+    blob.resize(8 + 4 + 4 + (size_t) nvox * 3 * 2);
+    std::memcpy(blob.data(), "T2VOX01", 8);          // 7 chars + NUL
+    std::memcpy(blob.data() + 8,  &r,    4);
+    std::memcpy(blob.data() + 12, &nvox, 4);
+    uint8_t * dst = blob.data() + 16;
+    for (uint32_t i = 0; i < nvox * 3; ++i) {
+        const uint16_t c = (uint16_t) cells[i];
+        std::memcpy(dst, &c, 2); dst += 2;
+    }
+}
+
+// Pack + hand a voxel preview to the host callback. Best-effort: never fatal.
+void emit_voxels(t2_preview_fn fn, void * user, int stage, int step, int total,
+                 int res, const std::vector<int32_t> & cells) {
+    if (!fn) return;
+    std::vector<uint8_t> blob;
+    pack_voxels(res, cells, blob);
+    fn(user, stage, step, total, blob.data(), (int) blob.size());
+}
+
+// ── intermediate shape-SLAT mesh keyframes (opt-in) ──────────────────────────
+//
+// A keyframe is a coarse marching-cubes mesh (T2MESH01 blob, same layout as the
+// final /api/mesh) of an intermediate shape-flow x_0 estimate — so the surface
+// can be watched forming during the otherwise-invisible SLAT stage. Decoding
+// mid-flow would OOM the 16 GB budget (the flow DiT is resident and can't be
+// freed while its sampler is running), so we CAPTURE the cheap latents during
+// the flow and REPLAY them into meshes AFTER the final decode, when the flow
+// DiTs are freed and the shape decoder owns VRAM.
+
+// Pack an MC mesh into a T2MESH01 blob: magic[8] u32 nv u32 nt
+//   f32[3nv] verts  f32[3nv] normals  i32[3nt] tris  (little-endian).
+void pack_mesh(const mc::Mesh & m, std::vector<uint8_t> & blob) {
+    const uint32_t nv = (uint32_t) (m.verts.size() / 3);
+    const uint32_t nt = (uint32_t) (m.tris.size()  / 3);
+    blob.resize(16 + (size_t) nv * 24 + (size_t) nt * 12);
+    std::memcpy(blob.data(), "T2MESH01", 8);
+    std::memcpy(blob.data() + 8,  &nv, 4);
+    std::memcpy(blob.data() + 12, &nt, 4);
+    size_t o = 16;
+    std::memcpy(blob.data() + o, m.verts.data(),   (size_t) nv * 12); o += (size_t) nv * 12;
+    std::memcpy(blob.data() + o, m.normals.data(), (size_t) nv * 12); o += (size_t) nv * 12;
+    std::memcpy(blob.data() + o, m.tris.data(),    (size_t) nt * 12);
+}
+
+// One shape-flow stage's captured intermediate x_0 latents (denormalized) plus
+// the scaffold they sit on, awaiting post-decode replay.
+struct kf_capture {
+    int stage    = 0;   // T2_STAGE_SLAT_FLOW or T2_STAGE_SLAT_FLOW_HR
+    int res_in   = 0;   // scaffold resolution (32 LR / 64 HR)
+    int levels   = 0;   // upsample levels to the ~128^3 keyframe grid
+    int stride   = 1;   // capture every `stride` steps (plus the last)
+    int channels = 0;   // latent channels (32)
+    const float * norm_mean = nullptr;
+    const float * norm_std  = nullptr;
+    std::vector<int32_t> coords;                // scaffold coords, copied once
+    std::vector<int> steps, totals;             // per capture, for labelling
+    std::vector<std::vector<float>> latents;    // denormalized [L*channels] each
+};
+
+// Sampler preview trampoline: denormalize + stash the step's x_0 estimate.
+void kf_capture_cb(void * u, int step, int total, const float * latent, int n) {
+    auto * c = (kf_capture *) u;
+    if (c->stride < 1) return;
+    if (step != total && (step % c->stride) != 0) return;   // stride, plus the last step
+    const int C = c->channels;
+    std::vector<float> den((size_t) n);
+    for (int i = 0; i < n; ++i) den[i] = latent[i] * c->norm_std[i % C] + c->norm_mean[i % C];
+    c->steps.push_back(step);
+    c->totals.push_back(total);
+    c->latents.push_back(std::move(den));
+}
+
+// Replay captured latents into coarse MC-mesh keyframes and stream each. Runs
+// after the final decode (decoder owns VRAM). Best-effort: skips on any failure.
+void emit_keyframes(trellis2_shape_dec_model * dec, kf_capture & kf,
+                    t2_preview_fn fn, void * user) {
+    if (!fn || kf.latents.empty() || !dec) return;
+    const int L   = (int) (kf.coords.size() / 3);
+    const int tgt = kf.res_in << kf.levels;     // keyframe grid (128^3)
+    for (size_t k = 0; k < kf.latents.size(); ++k) {
+        std::vector<int32_t> up;
+        std::string e;
+        if (!trellis2_shape_dec_upsample(dec, kf.latents[k].data(), L, kf.coords.data(),
+                                         kf.levels, up, &e))
+            continue;
+        std::vector<float> field((size_t) tgt * tgt * tgt, 0.0f);
+        for (size_t i = 0; i + 2 < up.size(); i += 3) {
+            const int x = up[i], y = up[i + 1], z = up[i + 2];
+            if (x >= 0 && x < tgt && y >= 0 && y < tgt && z >= 0 && z < tgt)
+                field[((size_t) x * tgt + y) * tgt + z] = 1.0f;
+        }
+        mc::Mesh m = mc::extract(field.data(), tgt, tgt, tgt, 0.5f);
+        if (m.verts.empty()) continue;
+        const float inv = 1.0f / (float) tgt;
+        for (auto & v : m.verts) v = v * inv - 0.5f;   // -> centered unit cube
+        std::vector<uint8_t> blob;
+        pack_mesh(m, blob);
+        fn(user, kf.stage, kf.steps[k], kf.totals[k], blob.data(), (int) blob.size());
+    }
+}
+
+// Per-step SS preview cadence: T2_PREVIEW_STRIDE if set, else ~4 across the run.
+int preview_stride(int steps) {
+    if (const char * e = std::getenv("T2_PREVIEW_STRIDE")) {
+        const int s = std::atoi(e);
+        if (s > 0) return s;
+    }
+    return std::max(1, steps / 4);
+}
+
+// Context for the (capture-less) SS-sampler preview trampoline: decode the
+// handed-out x_0 estimate into a 64^3 occupancy and stream it as voxels.
+struct ss_preview_ctx {
+    t2_preview_fn         fn     = nullptr;
+    void *                user   = nullptr;
+    trellis2_ss_dec_model * dec   = nullptr;
+    int                   res    = 0;
+    int                   stride = 1;
+    std::vector<float> *  occ    = nullptr;   // scratch [res^3], caller-owned
+};
+
+// PBR-texture stage on the freshly decoded dual grid. Encoding the decoder
+// output again is less direct than replaying the shape decoder's subdivisions,
+// but it is the numerically validated path used by test_texture. In particular,
+// it avoids the all-saturated material regression seen with the first integrated
+// subdivision-guide implementation. The decoded PBR volume is still sampled at
+// the actual mesh vertices rather than copied by voxel index.
+bool run_texture_stage(t2_pipeline * p,
+                       const std::vector<float> & dec_feats,
+                       const std::vector<int32_t> & dec_coords,
+                       const std::vector<float> & mesh_verts, int grid, int pt,
+                       const trellis2_dino_cond & cond, uint64_t seed,
+                       int texture_steps,
+                       t2_progress_fn progress, void * user,
+                       std::vector<float> & pbr_out, std::string & e) {
+    const int nvox = (int) (dec_coords.size() / 3);
+    if (nvox <= 0 || dec_feats.size() != (size_t) nvox * 7) {
+        e = "invalid decoded dual grid"; return false;
+    }
+
+    // Shape-encoder input from the seven-channel dual grid: learned dual-vertex
+    // offset plus the three intersection flags. This matches the standalone
+    // texturing pipeline fixture and preserves its exact subdivision replay.
+    const float mg = 0.5f;
+    std::vector<float> in6((size_t) nvox * 6);
+    for (int v = 0; v < nvox; ++v) {
+        const float * f = dec_feats.data() + (size_t) v * 7;
+        for (int c = 0; c < 3; ++c) {
+            const float s = 1.0f / (1.0f + std::exp(-f[c]));
+            in6[(size_t) v * 6 + c] = (1.0f + 2.0f * mg) * s - mg;
+            in6[(size_t) v * 6 + 3 + c] = f[3 + c] > 0.0f ? 1.0f : 0.0f;
+        }
+    }
+
+    if (progress) progress(user, T2_STAGE_TEXTURE, 0, texture_steps > 0 ? texture_steps : 12);
+    trellis2_shape_enc_model * enc = trellis2_shape_enc_load(p->shapeenc_path.c_str(), true, &e);
+    if (!enc) { e = "shape_enc load: " + e; return false; }
+    std::vector<float> shape_slat;
+    std::vector<int32_t> lat_coords;
+    std::vector<trellis2_subdiv_level> subs;
+    bool ok = trellis2_shape_enc_encode(enc, in6.data(), nvox, dec_coords.data(),
+                                        shape_slat, lat_coords, subs, nullptr, &e);
+    trellis2_shape_enc_free(enc);
+    if (!ok) { e = "shape encode: " + e; return false; }
+
+    const int Nl = (int) (lat_coords.size() / 3);
+    if (Nl <= 0 || shape_slat.size() != (size_t) Nl * 32) {
+        e = "invalid generated shape SLAT"; return false;
+    }
+    if (subs.empty()) { e = "missing shape decoder subdivision guide"; return false; }
+
+    // A 64^3/1024 shape SLAT must use the 1024 material model; feeding it to the
+    // 32^3/512 model is not a valid fallback.
+    if (pt == T2_PIPE_1024 && p->texflow_hr_path.empty()) {
+        e = "1024 texture flow model is not loaded"; return false;
+    }
+    const std::string & fp = pt == T2_PIPE_1024 ? p->texflow_hr_path : p->texflow_path;
+    trellis2_slat_flow_model * flow = trellis2_slat_flow_load(fp.c_str(), true, &e);
+    if (!flow) { e = "tex_flow load: " + e; return false; }
+    std::vector<float> tex_slat((size_t) Nl * 32);
+    trellis2_ss_sampler_params tp;   // texturing_pipeline.json tex_slat_sampler
+    tp.steps = texture_steps > 0 ? texture_steps : 12;
+    tp.guidance_strength = 1.0f; tp.guidance_rescale = 0.0f;
+    tp.guidance_interval_min = 0.6f; tp.guidance_interval_max = 0.9f; tp.rescale_t = 3.0f;
+    tp.seed = seed ^ 0x7e00ULL; tp.verbose = false;
+    struct tex_progress_ctx { t2_progress_fn fn; void * user; } pc{progress, user};
+    if (progress) {
+        progress(user, T2_STAGE_TEXTURE, 0, tp.steps);
+        tp.progress = [](void * u, int step, int total) {
+            auto * c = (tex_progress_ctx *) u;
+            c->fn(c->user, T2_STAGE_TEXTURE, step, total);
+        };
+        tp.progress_user = &pc;
+    }
+    ok = trellis2_slat_flow_sample_tex(flow, Nl, lat_coords.data(),
+                                       cond.data.data(), (int) cond.tokens(), (int) cond.channels(),
+                                       shape_slat.data(), &tp, nullptr, /*denormalize*/ true,
+                                       tex_slat.data(), &e);
+    trellis2_slat_flow_free(flow);
+    if (!ok) { e = "tex sample: " + e; return false; }
+
+    // Texture decoder -> sparse six-channel PBR, replaying the shape decoder's
+    // subdivision hierarchy (upstream's guide_subs).
+    trellis2_shape_dec_model * texdec = trellis2_tex_dec_load(p->texdec_path.c_str(), true, &e);
+    if (!texdec) { e = "tex_dec load: " + e; return false; }
+    std::vector<float> pbr; std::vector<int32_t> pbr_coords;
+    ok = trellis2_tex_dec_decode(texdec, tex_slat.data(), Nl, lat_coords.data(),
+                                 subs, pbr, pbr_coords, &e);
+    trellis2_shape_dec_free(texdec);
+    if (!ok) { e = "tex decode: " + e; return false; }
+
+    // Sample at the actual dual-grid vertex positions, not their parent voxel
+    // coordinates. q = (xyz + 0.5) * grid is upstream's MeshWithVoxel query.
+    const int M = (int) (pbr_coords.size() / 3);
+    if (M <= 0 || pbr.size() != (size_t) M * 6) {
+        e = "texture decoder returned an invalid PBR volume"; return false;
+    }
+    const int nv = (int) (mesh_verts.size() / 3);
+    std::vector<float> query((size_t) nv * 3), weights((size_t) nv);
+    for (int v = 0; v < nv; ++v)
+        for (int c = 0; c < 3; ++c)
+            query[(size_t) v * 3 + c] = (mesh_verts[(size_t) v * 3 + c] + 0.5f) * grid;
+    pbr_out.resize((size_t) nv * 6);
+    t2pbr::sample_sparse_trilinear(pbr.data(), M, 6, pbr_coords.data(),
+                                   query.data(), nv, pbr_out.data(), weights.data());
+    for (int v = 0; v < nv; ++v) {
+        float * d = pbr_out.data() + (size_t) v * 6;
+        if (weights[(size_t) v] <= 1e-6f) {
+            d[0] = d[1] = d[2] = 0.5f;
+            d[3] = 0.0f; d[4] = 0.5f; d[5] = 1.0f;
+        } else {
+            for (int c = 0; c < 6; ++c) d[c] = std::max(0.0f, std::min(1.0f, d[c]));
+        }
+    }
+
+    // An opaque material can legitimately be white, metallic, or rough, but a
+    // decoder result with essentially every one of the six channels pinned to
+    // one is a collapsed latent, not a usable texture. Never silently persist
+    // that as a successful textured generation again.
+    if (t2pbr::is_collapsed_saturated(pbr_out.data(), nv)) {
+        pbr_out.clear();
+        e = "texture decoder produced a collapsed saturated material";
+        return false;
+    }
+    return true;
+}
+
+} // namespace
+
+extern "C" {
+
+int t2_abi_version(void) { return T2_CAPI_ABI_VERSION; }
+
+t2_pipeline * t2_pipeline_load(const char * dino_gguf,
+                               const char * ss_flow_gguf,
+                               const char * ss_dec_gguf,
+                               const char * slat_flow_gguf,
+                               const char * slat_hr_flow_gguf,
+                               const char * shape_dec_gguf,
+                               const char * shape_enc_gguf,
+                               const char * tex_dec_gguf,
+                               const char * tex_flow_gguf,
+                               const char * tex_flow_hr_gguf,
+                               int flags,
+                               char * err, int err_len) {
+    std::string e;
+    auto * p = new t2_pipeline();
+    p->flags = flags;
+    p->dino = trellis2_dino_load(dino_gguf, true, &e);
+    if (!p->dino) { copy_err(err, err_len, "dino: " + e); t2_pipeline_free(p); return nullptr; }
+    // Free VRAM before the flow DiTs are loaded == the VRAM reclaimable by
+    // freeing them again at decode time. Drives the shape-decoder placement.
+    const size_t free_pre_flows = trellis2_gpu_free_vram();
+    p->flow = trellis2_ss_flow_load(ss_flow_gguf, true, &e);
+    if (!p->flow) { copy_err(err, err_len, "ss_flow: " + e); t2_pipeline_free(p); return nullptr; }
+    // The SS occupancy decoder uses a genuine dense CONV_3D, for which ggml has
+    // no CUDA kernel, so it stays on the CPU (it is only ~3 s / 4 % anyway).
+    p->dec = trellis2_ss_dec_load(ss_dec_gguf, true, &e, "cpu");
+    if (!p->dec) { copy_err(err, err_len, "ss_dec: " + e); t2_pipeline_free(p); return nullptr; }
+
+    auto present = [](const char * s) { return s && s[0]; };
+
+    if (present(slat_flow_gguf) && present(shape_dec_gguf)) {
+        p->slat = trellis2_slat_flow_load(slat_flow_gguf, true, &e);
+        if (!p->slat) { copy_err(err, err_len, "slat_flow: " + e); t2_pipeline_free(p); return nullptr; }
+        const bool will_cascade = present(slat_hr_flow_gguf);
+
+        // Remember the flow-DiT gguf paths so a GPU decode can free them for VRAM
+        // and reload them next generate (ensure_decode_vram / reload_flows).
+        p->ss_flow_path = ss_flow_gguf ? ss_flow_gguf : "";
+        p->slat_path    = slat_flow_gguf;
+        p->slat_hr_path = will_cascade ? slat_hr_flow_gguf : "";
+
+        // Auto-place the shape (FlexiDualGrid VAE) decoder — the biggest fine-path
+        // stage (~44 s CPU / 59 %). Its mask-based submanifold conv runs ~20x
+        // faster on the GPU (~2 s), but the decode's transient buffers need the
+        // flow DiTs' VRAM freed first (done per-request in ensure_decode_vram).
+        // Put it on the GPU when the card can hold that decode once the flows are
+        // freed — i.e. free_pre_flows covers the tier's decode peak plus the
+        // decoder weights (~1 GB) and a margin. TRELLIS2_SHAPE_DEC_{GPU,CPU}
+        // force it. On the CPU (no GPU) or too small a card it stays on the CPU,
+        // so there is never a mid-generation OOM.
+        bool sd_gpu;
+        if      (std::getenv("TRELLIS2_SHAPE_DEC_CPU")) sd_gpu = false;
+        else if (std::getenv("TRELLIS2_SHAPE_DEC_GPU")) sd_gpu = free_pre_flows > 0;
+        else if (free_pre_flows == 0)                   sd_gpu = false;   // no GPU
+        else {
+            const size_t margin = (size_t) 3 << 29;   // ~1.5 GB (weights + slack)
+            sd_gpu = free_pre_flows >= decode_vram_peak(will_cascade ? T2_PIPE_1024
+                                                                     : T2_PIPE_512) + margin;
+        }
+        p->shapedec = trellis2_shape_dec_load(shape_dec_gguf, true, &e, sd_gpu ? nullptr : "cpu");
+        if (!p->shapedec && sd_gpu) {   // unexpected GPU load OOM — fall back to CPU
+            sd_gpu = false;
+            p->shapedec = trellis2_shape_dec_load(shape_dec_gguf, true, &e, "cpu");
+        }
+        if (!p->shapedec) { copy_err(err, err_len, "shape_dec: " + e); t2_pipeline_free(p); return nullptr; }
+        p->shapedec_gpu = sd_gpu;
+        p->fine = true;
+
+        // The 1024 model is optional; when present the cascade path is enabled
+        // and reuses p->shapedec for both the upsample and the 1024^3 decode.
+        if (will_cascade) {
+            p->slat_hr = trellis2_slat_flow_load(slat_hr_flow_gguf, true, &e);
+            if (!p->slat_hr) { copy_err(err, err_len, "slat_hr_flow: " + e); t2_pipeline_free(p); return nullptr; }
+            p->cascade = true;
+        }
+
+        // PBR texturing: enabled when the shape encoder, texture decoder, and
+        // (at least the 512) texture flow are present. The tex models are loaded
+        // lazily per-generate (run_texture_stage), so only their paths are kept.
+        if (present(shape_enc_gguf) && present(tex_dec_gguf) && present(tex_flow_gguf)) {
+            std::string ve;
+            trellis2_shape_enc_model * te = trellis2_shape_enc_load(shape_enc_gguf, false, &ve);
+            if (!te) { copy_err(err, err_len, "shape_enc: " + ve); t2_pipeline_free(p); return nullptr; }
+            trellis2_shape_enc_free(te);
+            trellis2_shape_dec_model * td = trellis2_tex_dec_load(tex_dec_gguf, false, &ve);
+            if (!td) { copy_err(err, err_len, "tex_dec: " + ve); t2_pipeline_free(p); return nullptr; }
+            if (trellis2_shape_dec_hparams_of(td).out_channels != 6) {
+                trellis2_shape_dec_free(td);
+                copy_err(err, err_len, "tex_dec: expected 6 output channels");
+                t2_pipeline_free(p); return nullptr;
+            }
+            trellis2_shape_dec_free(td);
+            trellis2_slat_flow_model * tf = trellis2_slat_flow_load(tex_flow_gguf, false, &ve);
+            if (!tf) { copy_err(err, err_len, "tex_flow: " + ve); t2_pipeline_free(p); return nullptr; }
+            if (trellis2_slat_flow_hparams_of(tf).concat_cond_channels != 32) {
+                trellis2_slat_flow_free(tf);
+                copy_err(err, err_len, "tex_flow: expected 32 concat-conditioning channels");
+                t2_pipeline_free(p); return nullptr;
+            }
+            trellis2_slat_flow_free(tf);
+            if (present(tex_flow_hr_gguf)) {
+                tf = trellis2_slat_flow_load(tex_flow_hr_gguf, false, &ve);
+                if (!tf) { copy_err(err, err_len, "tex_flow_hr: " + ve); t2_pipeline_free(p); return nullptr; }
+                if (trellis2_slat_flow_hparams_of(tf).concat_cond_channels != 32) {
+                    trellis2_slat_flow_free(tf);
+                    copy_err(err, err_len, "tex_flow_hr: expected 32 concat-conditioning channels");
+                    t2_pipeline_free(p); return nullptr;
+                }
+                trellis2_slat_flow_free(tf);
+            }
+            p->shapeenc_path   = shape_enc_gguf;
+            p->texdec_path     = tex_dec_gguf;
+            p->texflow_path    = tex_flow_gguf;
+            p->texflow_hr_path = present(tex_flow_hr_gguf) ? tex_flow_hr_gguf : "";
+            p->texture = true;
+        }
+    }
+
+    p->backend = trellis2_ss_flow_backend_name(p->flow);
+    return p;
+}
+
+int t2_pipeline_caps(t2_pipeline * p) {
+    if (!p) return 0;
+    int c = T2_CAP_COARSE;
+    if (p->fine)    c |= T2_CAP_512;
+    if (p->cascade) c |= T2_CAP_1024;
+    if (p->texture) c |= T2_CAP_TEXTURE;
+    return c;
+}
+
+int t2_pipeline_is_fine(t2_pipeline * p) { return p && (p->fine || p->cascade) ? 1 : 0; }
+
+void t2_pipeline_free(t2_pipeline * p) {
+    if (!p) return;
+    trellis2_dino_free(p->dino);
+    trellis2_ss_flow_free(p->flow);
+    trellis2_ss_dec_free(p->dec);
+    trellis2_slat_flow_free(p->slat);
+    trellis2_slat_flow_free(p->slat_hr);
+    trellis2_shape_dec_free(p->shapedec);
+    delete p;
+}
+
+const char * t2_pipeline_backend(t2_pipeline * p) {
+    return p ? p->backend.c_str() : "none";
+}
+
+static int preprocess_image_bytes_mode(const void * image_bytes, int image_len,
+                                       int out_size, unsigned char * out_rgb,
+                                       int background_mode,
+                                       char * err, int err_len) {
+    if (!image_bytes || image_len <= 0 || out_size <= 0 || !out_rgb) {
+        copy_err(err, err_len, "invalid arguments");
+        return 1;
+    }
+    // Reject absurd dimensions before decoding (upload DoS / decompression
+    // bombs): 16 MPixel is far beyond anything useful at a 512^2 target.
+    int w = 0, h = 0, comp = 0;
+    if (!stbi_info_from_memory((const stbi_uc *) image_bytes, image_len, &w, &h, &comp)) {
+        copy_err(err, err_len, std::string("image probe failed: ") + stbi_failure_reason());
+        return 1;
+    }
+    if (w <= 0 || h <= 0 || (int64_t) w * h > (int64_t) 16 * 1024 * 1024) {
+        copy_err(err, err_len, "image dimensions out of range");
+        return 1;
+    }
+    unsigned char * px = stbi_load_from_memory(
+        (const stbi_uc *) image_bytes, image_len, &w, &h, &comp, 4);
+    if (!px) {
+        copy_err(err, err_len, std::string("image decode failed: ") + stbi_failure_reason());
+        return 1;
+    }
+
+    // stb supplies opaque alpha for inputs without it and preserves alpha for
+    // grayscale+alpha, RGBA, and transparent palette images. Turn an otherwise
+    // opaque border-connected near-black/near-white background into alpha before
+    // the reference alpha-bbox crop; meaningful existing masks are trusted.
+    if (background_mode < T2_BACKGROUND_AUTO || background_mode > T2_BACKGROUND_WHITE) {
+        stbi_image_free(px);
+        copy_err(err, err_len, "invalid background mode");
+        return 1;
+    }
+    trellis2_remove_solid_background_rgba(px, w, h, background_mode);
+
+    std::string e;
+    std::vector<uint8_t> rgb;
+    const bool ok = trellis2_preprocess_rgba(px, w, h, out_size, rgb, &e);
+    stbi_image_free(px);
+    if (!ok) {
+        copy_err(err, err_len, "preprocess failed: " + e);
+        return 1;
+    }
+    std::memcpy(out_rgb, rgb.data(), rgb.size());
+    return 0;
+}
+
+int t2_preprocess_image_bytes(const void * image_bytes, int image_len,
+                              int out_size, unsigned char * out_rgb,
+                              char * err, int err_len) {
+    return preprocess_image_bytes_mode(image_bytes, image_len, out_size, out_rgb,
+                                       T2_BACKGROUND_AUTO, err, err_len);
+}
+
+t2_mesh_result * t2_generate(t2_pipeline * p,
+                             const void * image_bytes, int image_len,
+                             int pipeline_type, int background_mode,
+                             uint64_t seed, int steps, float guidance, int texture_steps,
+                             t2_progress_fn progress, void * user,
+                             t2_preview_fn preview, void * preview_user,
+                             char * err, int err_len) {
+    if (!p) { copy_err(err, err_len, "null pipeline"); return nullptr; }
+    std::string e;
+
+    // Reload any flow DiT a previous GPU decode freed for VRAM (usually a no-op).
+    if (!reload_flows(p, e)) {
+        copy_err(err, err_len, "reload flow models: " + e);
+        return nullptr;
+    }
+
+    // Resolve the requested path to what is actually loaded.
+    int pt = pipeline_type;
+    if (pt == T2_PIPE_AUTO) {
+        pt = p->cascade ? T2_PIPE_1024 : (p->fine ? T2_PIPE_512 : T2_PIPE_COARSE);
+    }
+    if (pt == T2_PIPE_1024 && !p->cascade) pt = p->fine ? T2_PIPE_512 : T2_PIPE_COARSE;
+    if (pt == T2_PIPE_512  && !p->fine)    pt = T2_PIPE_COARSE;
+
+    // Intermediate shape-SLAT keyframes (opt-in via T2_KEYFRAMES = per-stage
+    // count): capture a few x_0 estimates during the shape flow and replay them
+    // as coarse meshes after the final decode. Only when the host takes previews.
+    int keyframes = 0;
+    if (preview) {
+        if (const char * kv = std::getenv("T2_KEYFRAMES")) keyframes = std::atoi(kv);
+        keyframes = keyframes < 0 ? 0 : (keyframes > 8 ? 8 : keyframes);
+    }
+
+    const int S = 512;
+
+    if (progress) progress(user, T2_STAGE_PREPROCESS, 0, 0);
+    std::vector<unsigned char> rgb((size_t) S * S * 3);
+    char perr[256] = {0};
+    if (preprocess_image_bytes_mode(image_bytes, image_len, S, rgb.data(),
+                                    background_mode, perr, sizeof(perr))) {
+        copy_err(err, err_len, perr);
+        return nullptr;
+    }
+
+    if (progress) progress(user, T2_STAGE_DINO, 0, 0);
+    trellis2_dino_cond cond;   // 512-res conditioning (SS + LR flow)
+    if (!trellis2_dino_encode_rgb(p->dino, rgb.data(), S, cond, &e)) {
+        copy_err(err, err_len, "dino encode: " + e);
+        return nullptr;
+    }
+
+    const trellis2_ss_flow_hparams & fhp = trellis2_ss_flow_hparams_of(p->flow);
+    if (cond.channels() != fhp.cond_channels) {
+        copy_err(err, err_len, "cond/flow channel mismatch");
+        return nullptr;
+    }
+
+    // SS-decoder geometry (also the occupancy scratch reused by the live
+    // previews and the settled decode below).
+    const trellis2_ss_dec_hparams & dechp = trellis2_ss_dec_hparams_of(p->dec);
+    const int Rout = dechp.res_out();   // 64
+    std::vector<float> occ((size_t) dechp.out_channels * Rout * Rout * Rout);
+
+    trellis2_ss_sampler_params sp;
+    if (steps > 0)       sp.steps = steps;
+    if (guidance >= 0)   sp.guidance_strength = guidance;
+    sp.seed    = seed;
+    sp.verbose = false;
+    struct cb_ctx { t2_progress_fn fn; void * user; int stage; } cbc{progress, user, T2_STAGE_SS_FLOW};
+    if (progress) {
+        progress(user, T2_STAGE_SS_FLOW, 0, sp.steps);
+        sp.progress = [](void * u, int step, int total) {
+            auto * c = (cb_ctx *) u;
+            c->fn(c->user, c->stage, step, total);
+        };
+        sp.progress_user = &cbc;
+    }
+    // Live per-step previews: decode each step's x_0 estimate into 64^3
+    // occupancy and stream it as voxels (stride-gated; the last step is left to
+    // the settled SS_DEC checkpoint below). `pctx`/`occ` outlive the sampler.
+    ss_preview_ctx pctx;
+    if (preview) {
+        pctx = ss_preview_ctx{preview, preview_user, p->dec, Rout, preview_stride(sp.steps), &occ};
+        sp.preview = [](void * u, int step, int total, const float * latent, int /*n*/) {
+            auto * c = (ss_preview_ctx *) u;
+            if (step % c->stride != 0 || step == total) return;
+            std::string de;
+            if (!trellis2_ss_dec_decode(c->dec, latent, c->occ->data(), &de)) return;
+            std::vector<int32_t> cells;
+            collect_occupied(c->occ->data(), c->res, cells);
+            emit_voxels(c->fn, c->user, T2_STAGE_SS_FLOW, step, total, c->res, cells);
+        };
+        sp.preview_user = &pctx;
+    }
+
+    const int R = fhp.resolution;
+    std::vector<float> latent((size_t) fhp.in_channels * R * R * R);
+    if (!trellis2_ss_flow_sample(p->flow, cond.data.data(),
+                                 (int) cond.tokens(), (int) cond.channels(),
+                                 &sp, nullptr, latent.data(), &e)) {
+        copy_err(err, err_len, "ss_flow sample: " + e);
+        return nullptr;
+    }
+
+    if (progress) progress(user, T2_STAGE_SS_DEC, 0, 0);
+    if (!trellis2_ss_dec_decode(p->dec, latent.data(), occ.data(), &e)) {
+        copy_err(err, err_len, "ss_dec decode: " + e);
+        return nullptr;
+    }
+    // Settled-occupancy checkpoint (the clean sparse structure, 64^3 voxels).
+    if (preview) {
+        std::vector<int32_t> cells;
+        collect_occupied(occ.data(), Rout, cells);
+        emit_voxels(preview, preview_user, T2_STAGE_SS_DEC, 0, 0, Rout, cells);
+    }
+
+    auto * r = new t2_mesh_result();
+
+    if (pt == T2_PIPE_COARSE) {
+        // ── coarse path: marching cubes on the 64^3 occupancy ────────────────
+        if (progress) progress(user, T2_STAGE_MESH, 0, 0);
+        mc::Mesh mesh = mc::extract(occ.data(), Rout, Rout, Rout, /*iso*/ 0.0f);
+        if (mesh.verts.empty()) {
+            copy_err(err, err_len, "empty mesh (no occupied voxels at iso 0)");
+            delete r; return nullptr;
+        }
+        const float inv = 1.0f / (float) Rout;
+        for (size_t i = 0; i < mesh.verts.size(); ++i) mesh.verts[i] = mesh.verts[i] * inv - 0.5f;
+        r->verts   = std::move(mesh.verts);
+        r->normals = std::move(mesh.normals);
+        r->tris    = std::move(mesh.tris);
+        return r;
+    }
+
+    // ── fine / cascade: 64^3 occupancy -> 32^3 voxel scaffold ────────────────
+    const trellis2_slat_flow_hparams & shp = trellis2_slat_flow_hparams_of(p->slat);
+    const int ss_res = shp.resolution;   // 32
+    const int ratio = Rout / ss_res;     // 2 (max-pool 64 -> 32)
+    std::vector<int32_t> coords;
+    for (int x = 0; x < ss_res; ++x)
+    for (int y = 0; y < ss_res; ++y)
+    for (int z = 0; z < ss_res; ++z) {
+        bool any = false;
+        for (int dx = 0; dx < ratio && !any; ++dx)
+        for (int dy = 0; dy < ratio && !any; ++dy)
+        for (int dz = 0; dz < ratio && !any; ++dz) {
+            const int xi = x*ratio+dx, yi = y*ratio+dy, zi = z*ratio+dz;
+            const size_t idx = ((size_t) xi * Rout + yi) * Rout + zi;
+            if (occ[idx] > 0.0f) any = true;
+        }
+        if (any) { coords.push_back(x); coords.push_back(y); coords.push_back(z); }
+    }
+    int L = (int) (coords.size() / 3);
+    if (L == 0) { copy_err(err, err_len, "empty voxel scaffold"); delete r; return nullptr; }
+
+    // shape-SLAT sampler params (shared LR + HR)
+    auto make_slp = [&](int stage, uint64_t sd) {
+        trellis2_ss_sampler_params slp;
+        if (steps > 0)     slp.steps = steps;
+        if (guidance >= 0) slp.guidance_strength = guidance;
+        slp.guidance_rescale = 0.5f;
+        slp.rescale_t = 3.0f;
+        slp.seed = sd;
+        slp.verbose = false;
+        if (progress) {
+            progress(user, stage, 0, slp.steps);
+            slp.progress = [](void * u, int step, int total) {
+                auto * c = (cb_ctx *) u;
+                c->fn(c->user, c->stage, step, total);
+            };
+            cbc.stage = stage;
+            slp.progress_user = &cbc;
+        }
+        return slp;
+    };
+
+    kf_capture kf_lr, kf_hr;   // intermediate shape-flow keyframes (opt-in)
+
+    // ── LR shape-SLAT flow (512 model, 512-res cond) ─────────────────────────
+    std::vector<float> slat((size_t) L * shp.in_channels);
+    {
+        trellis2_ss_sampler_params slp = make_slp(T2_STAGE_SLAT_FLOW, seed ^ 0x51a7ULL);
+        if (keyframes > 0) {
+            kf_lr.stage = T2_STAGE_SLAT_FLOW; kf_lr.res_in = ss_res; kf_lr.channels = shp.in_channels;
+            kf_lr.norm_mean = shp.norm_mean; kf_lr.norm_std = shp.norm_std; kf_lr.coords = coords;
+            while ((ss_res << (kf_lr.levels + 1)) <= 128) kf_lr.levels++;   // -> 128^3
+            if (kf_lr.levels < 1) kf_lr.levels = 1;
+            kf_lr.stride = std::max(1, slp.steps / keyframes);
+            slp.preview = kf_capture_cb; slp.preview_user = &kf_lr;
+        }
+        if (!trellis2_slat_flow_sample(p->slat, L, coords.data(),
+                                       cond.data.data(), (int) cond.tokens(), (int) cond.channels(),
+                                       &slp, nullptr, /*denormalize*/ true, slat.data(), &e)) {
+            copy_err(err, err_len, "slat sample: " + e);
+            delete r; return nullptr;
+        }
+    }
+
+    const trellis2_shape_dec_hparams & dhp2 = trellis2_shape_dec_hparams_of(p->shapedec);
+    std::vector<float> dec_feats;      // 7-ch decoder output to mesh
+    std::vector<int32_t> dec_coords;
+    int grid = 0;
+    trellis2_dino_cond cond1024;       // filled by the cascade branch; reused by texturing
+
+    if (pt == T2_PIPE_512) {
+        // ── 512 fine: decode the LR slat directly at grid 512 ────────────────
+        if (progress) progress(user, T2_STAGE_SHAPE_DEC, 0, 0);
+        ensure_decode_vram(p, T2_PIPE_512);   // free the flow DiTs if a GPU decode needs the room
+        if (!trellis2_shape_dec_decode(p->shapedec, slat.data(), L, coords.data(),
+                                       dec_feats, dec_coords, nullptr, &e)) {
+            copy_err(err, err_len, "shape decode: " + e);
+            delete r; return nullptr;
+        }
+        grid = ss_res * dhp2.upscale();   // 32 * 16 = 512
+    } else {
+        // ── 1024 cascade: upsample -> quantize -> HR flow -> decode grid 1024 ─
+        if (progress) progress(user, T2_STAGE_UPSAMPLE, 0, 0);
+        std::vector<int32_t> up_coords;   // 512^3 candidate coords
+        if (!trellis2_shape_dec_upsample(p->shapedec, slat.data(), L, coords.data(),
+                                         /*upsample_times*/ 4, up_coords, &e)) {
+            copy_err(err, err_len, "shape upsample: " + e);
+            delete r; return nullptr;
+        }
+        // quantize (c+0.5)/512*64 and dedup into the 64^3 HR scaffold
+        const int lr_res = ss_res * dhp2.upscale();   // 512
+        const int hr_grid = shp.resolution * 2;       // 64 (HR flow resolution)
+        std::unordered_set<uint64_t> seen;
+        std::vector<int32_t> hr_coords;
+        auto key = [](int32_t a, int32_t b, int32_t c) {
+            return ((uint64_t)(uint32_t)a<<40) | ((uint64_t)(uint32_t)b<<20) | (uint64_t)(uint32_t)c;
+        };
+        for (size_t i = 0; i < up_coords.size(); i += 3) {
+            int32_t qx = (int32_t)((up_coords[i]     + 0.5f) / lr_res * hr_grid);
+            int32_t qy = (int32_t)((up_coords[i + 1] + 0.5f) / lr_res * hr_grid);
+            int32_t qz = (int32_t)((up_coords[i + 2] + 0.5f) / lr_res * hr_grid);
+            if (seen.insert(key(qx, qy, qz)).second) {
+                hr_coords.push_back(qx); hr_coords.push_back(qy); hr_coords.push_back(qz);
+            }
+        }
+        const int Lhr = (int) (hr_coords.size() / 3);
+        if (Lhr == 0) { copy_err(err, err_len, "empty HR scaffold"); delete r; return nullptr; }
+
+        // Sharper 64^3 HR-scaffold checkpoint (the cascade's refined structure).
+        emit_voxels(preview, preview_user, T2_STAGE_UPSAMPLE, 0, 0, hr_grid, hr_coords);
+
+        // 1024-res conditioning (separate preprocess + encode at 1024)
+        std::vector<unsigned char> rgb1024((size_t) 1024 * 1024 * 3);
+        if (preprocess_image_bytes_mode(image_bytes, image_len, 1024, rgb1024.data(),
+                                        background_mode, perr, sizeof(perr))) {
+            copy_err(err, err_len, perr); delete r; return nullptr;
+        }
+        if (!trellis2_dino_encode_rgb(p->dino, rgb1024.data(), 1024, cond1024, &e)) {
+            copy_err(err, err_len, "dino encode 1024: " + e); delete r; return nullptr;
+        }
+
+        // HR shape-SLAT flow (1024 model)
+        const trellis2_slat_flow_hparams & shp_hr = trellis2_slat_flow_hparams_of(p->slat_hr);
+        std::vector<float> hr_slat((size_t) Lhr * shp_hr.in_channels);
+        trellis2_ss_sampler_params slp = make_slp(T2_STAGE_SLAT_FLOW_HR, seed ^ 0x1024ULL);
+        if (keyframes > 0) {
+            kf_hr.stage = T2_STAGE_SLAT_FLOW_HR; kf_hr.res_in = hr_grid; kf_hr.channels = shp_hr.in_channels;
+            kf_hr.norm_mean = shp_hr.norm_mean; kf_hr.norm_std = shp_hr.norm_std; kf_hr.coords = hr_coords;
+            while ((hr_grid << (kf_hr.levels + 1)) <= 128) kf_hr.levels++;   // -> 128^3
+            if (kf_hr.levels < 1) kf_hr.levels = 1;
+            kf_hr.stride = std::max(1, slp.steps / keyframes);
+            slp.preview = kf_capture_cb; slp.preview_user = &kf_hr;
+        }
+        if (!trellis2_slat_flow_sample(p->slat_hr, Lhr, hr_coords.data(),
+                                       cond1024.data.data(), (int) cond1024.tokens(), (int) cond1024.channels(),
+                                       &slp, nullptr, /*denormalize*/ true, hr_slat.data(), &e)) {
+            copy_err(err, err_len, "HR slat sample: " + e);
+            delete r; return nullptr;
+        }
+
+        if (progress) progress(user, T2_STAGE_SHAPE_DEC_HR, 0, 0);
+        ensure_decode_vram(p, T2_PIPE_1024);   // free the flow DiTs (all done) for the 1024³ decode
+        if (!trellis2_shape_dec_decode(p->shapedec, hr_slat.data(), Lhr, hr_coords.data(),
+                                       dec_feats, dec_coords, nullptr, &e)) {
+            copy_err(err, err_len, "HR shape decode: " + e);
+            delete r; return nullptr;
+        }
+        grid = hr_grid * dhp2.upscale();   // 64 * 16 = 1024
+    }
+
+    // ── mesh extraction (shared) ─────────────────────────────────────────────
+    if (progress) progress(user, T2_STAGE_MESH, 0, 0);
+    const int nvox = (int) (dec_coords.size() / 3);
+    fdg::Mesh mesh = fdg::extract(dec_feats.data(), dec_coords.data(), nvox, grid);
+    if (mesh.verts.empty()) {
+        copy_err(err, err_len, "empty mesh (dual grid found no faces)");
+        delete r; return nullptr;
+    }
+    // Clean up the raw dual-grid soup: drop floating specks, then fill the small
+    // boundary holes extract() left. Both only edit triangles (no new vertices),
+    // so the generated material volume can still be sampled at every vertex.
+    fdg::drop_small_components(mesh);
+    fdg::fill_holes(mesh);
+    r->verts   = std::move(mesh.verts);
+    r->tris    = std::move(mesh.tris);
+    r->normals = fdg::vertex_normals(fdg::Mesh{r->verts, r->tris});
+
+    // ── shape-flow keyframe replay ───────────────────────────────────────────
+    // Now is the safe window: the flow DiTs are freed (ensure_decode_vram) and
+    // the shape decoder owns VRAM, before the texture stage loads its models.
+    if (preview && keyframes > 0) {
+        emit_keyframes(p->shapedec, kf_lr, preview, preview_user);
+        emit_keyframes(p->shapedec, kf_hr, preview, preview_user);   // empty for 512
+    }
+
+    // ── PBR texture stage (optional) ─────────────────────────────────────────
+    if (p->texture && pt != T2_PIPE_COARSE) {
+        // Free the (finished) geometry flow DiTs so the ~4 GB of tex models fit
+        // in VRAM; reload_flows() restores them on the next generate.
+        if (trellis2_gpu_free_vram() > 0) {
+            if (p->flow)    { trellis2_ss_flow_free(p->flow);      p->flow    = nullptr; }
+            if (p->slat)    { trellis2_slat_flow_free(p->slat);    p->slat    = nullptr; }
+            if (p->slat_hr) { trellis2_slat_flow_free(p->slat_hr); p->slat_hr = nullptr; }
+        }
+        const trellis2_dino_cond & texcond = (pt == T2_PIPE_1024) ? cond1024 : cond;
+        std::vector<float> pbr;
+        std::string te;
+        if (!run_texture_stage(p, dec_feats, dec_coords, r->verts, grid, pt,
+                               texcond, seed ^ 0x7ec0ULL,
+                               texture_steps, progress, user, pbr, te)) {
+            copy_err(err, err_len, "texture: " + te);
+            delete r; return nullptr;
+        }
+        r->pbr = std::move(pbr);
+    }
+    return r;
+}
+
+int t2_mesh_n_verts(const t2_mesh_result * r) { return r ? (int) (r->verts.size() / 3) : 0; }
+int t2_mesh_n_tris (const t2_mesh_result * r) { return r ? (int) (r->tris.size()  / 3) : 0; }
+const float * t2_mesh_verts  (const t2_mesh_result * r) { return r ? r->verts.data()   : nullptr; }
+const float * t2_mesh_normals(const t2_mesh_result * r) { return r ? r->normals.data() : nullptr; }
+const int *   t2_mesh_tris   (const t2_mesh_result * r) { return r ? r->tris.data()    : nullptr; }
+int t2_mesh_has_pbr(const t2_mesh_result * r) { return (r && !r->pbr.empty()) ? 1 : 0; }
+const float * t2_mesh_pbr(const t2_mesh_result * r) { return (r && !r->pbr.empty()) ? r->pbr.data() : nullptr; }
+void t2_mesh_free(t2_mesh_result * r) { delete r; }
+
+t2_mesh_result * t2_prepare_mesh(const float * verts, int n_verts,
+                                 const int * tris, int n_tris,
+                                 const float * pbr,
+                                 int component_filter,
+                                 char * err, int err_len) {
+    if (!verts || !tris || n_verts <= 0 || n_tris <= 0) {
+        copy_err(err, err_len, "empty mesh"); return nullptr;
+    }
+    if (component_filter < 0 || component_filter > 2) {
+        copy_err(err, err_len, "bad component filter"); return nullptr;
+    }
+    t2glb::MeshExportOptions opt;
+    opt.components = (t2glb::ComponentFilter) component_filter;
+    t2glb::PreparedMesh prepared;
+    std::string e;
+    if (!t2glb::prepare_mesh(verts, n_verts, (const int32_t *) tris, n_tris,
+                             pbr, opt, prepared, e)) {
+        copy_err(err, err_len, e); return nullptr;
+    }
+    auto * r = new t2_mesh_result();
+    r->verts = std::move(prepared.verts);
+    r->normals = std::move(prepared.normals);
+    r->tris.assign(prepared.tris.begin(), prepared.tris.end());
+    r->pbr = std::move(prepared.pbr);
+    return r;
+}
+
+uint8_t * t2_bake_glb(const float * verts, int n_verts, const int * tris, int n_tris,
+                      const float * pbr, int texture_size, int component_filter,
+                      int * out_len, char * err, int err_len) {
+    if (out_len) *out_len = 0;
+    if (!verts || !tris || n_verts <= 0 || n_tris <= 0) {
+        copy_err(err, err_len, "empty mesh"); return nullptr;
+    }
+    t2glb::MeshExportOptions opt;
+    if (texture_size > 0) opt.texture_size = texture_size;
+    if (component_filter < 0 || component_filter > 2) {
+        copy_err(err, err_len, "bad component filter"); return nullptr;
+    }
+    opt.components = (t2glb::ComponentFilter) component_filter;
+    std::vector<uint8_t> glb;
+    std::string e;
+    if (!t2glb::mesh_to_glb(verts, n_verts, tris, n_tris, pbr, opt, glb, e)) {
+        copy_err(err, err_len, e); return nullptr;
+    }
+    uint8_t * buf = (uint8_t *) std::malloc(glb.size());
+    if (!buf) { copy_err(err, err_len, "out of memory"); return nullptr; }
+    std::memcpy(buf, glb.data(), glb.size());
+    if (out_len) *out_len = (int) glb.size();
+    return buf;
+}
+
+void t2_free_buffer(uint8_t * buf) { std::free(buf); }
+
+} // extern "C"
diff --git a/trellis2_capi.h b/trellis2_capi.h
new file mode 100644
index 0000000..a689316
--- /dev/null
+++ b/trellis2_capi.h
@@ -0,0 +1,193 @@
+/*
+** trellis2_capi.h — flat C ABI for embedding trellis2 in non-C++ hosts
+** (the Go demo server dlopens libtrellis2.so and binds these by name).
+**
+** ABI version bumps whenever any signature or struct layout here changes.
+*/
+#pragma once
+
+#include <stdint.h>
+
+#ifdef TRELLIS2_SHARED
+#    if defined(_WIN32) && !defined(__MINGW32__)
+#        ifdef TRELLIS2_BUILD
+#            define TRELLIS2_CAPI __declspec(dllexport)
+#        else
+#            define TRELLIS2_CAPI __declspec(dllimport)
+#        endif
+#    else
+#        define TRELLIS2_CAPI __attribute__ ((visibility ("default")))
+#    endif
+#else
+#    define TRELLIS2_CAPI
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define T2_CAPI_ABI_VERSION 9
+
+TRELLIS2_CAPI int t2_abi_version(void);
+
+/* Pipeline stages reported by the progress callback. */
+enum t2_stage {
+    T2_STAGE_PREPROCESS   = 0,  /* image decode + crop/premultiply/resize */
+    T2_STAGE_DINO         = 1,  /* conditioning encoder                   */
+    T2_STAGE_SS_FLOW      = 2,  /* sparse-structure flow sampling (steps) */
+    T2_STAGE_SS_DEC       = 3,  /* occupancy decoder -> voxel scaffold    */
+    T2_STAGE_SLAT_FLOW    = 4,  /* shape-SLAT flow sampling (steps)       */
+    T2_STAGE_SHAPE_DEC    = 5,  /* shape decoder -> dual-grid fields      */
+    T2_STAGE_MESH         = 6,  /* mesh extraction                        */
+    T2_STAGE_UPSAMPLE     = 7,  /* cascade: LR slat -> HR voxel scaffold  */
+    T2_STAGE_SLAT_FLOW_HR = 8,  /* cascade: 1024 shape-SLAT flow (steps)  */
+    T2_STAGE_SHAPE_DEC_HR = 9,  /* cascade: 1024^3 shape decoder          */
+    T2_STAGE_TEXTURE      = 10  /* PBR texture: flow + guided decode      */
+};
+
+/* Pipeline type for t2_generate. */
+enum t2_pipeline_type {
+    T2_PIPE_AUTO    = 0,  /* cascade if available, else 512 fine, else coarse */
+    T2_PIPE_COARSE  = 1,  /* 64^3 occupancy -> marching cubes preview        */
+    T2_PIPE_512     = 2,  /* 512 fine dual-grid                              */
+    T2_PIPE_1024    = 3   /* 1024 cascade                                    */
+};
+
+/* Solid-background handling before the alpha-bbox crop. */
+enum t2_background_mode {
+    T2_BACKGROUND_AUTO  = 0, /* detect border-connected near-black/near-white */
+    T2_BACKGROUND_KEEP  = 1, /* preserve the decoded alpha exactly             */
+    T2_BACKGROUND_BLACK = 2, /* force removal of border-connected near-black   */
+    T2_BACKGROUND_WHITE = 3  /* force removal of border-connected near-white   */
+};
+
+/* Capability bits reported by t2_pipeline_caps (loaded qualities/features). */
+enum t2_caps {
+    T2_CAP_COARSE = 1,
+    T2_CAP_512    = 2,
+    T2_CAP_1024   = 4,
+    T2_CAP_TEXTURE = 8
+};
+
+/* Load-time flags for t2_pipeline_load. */
+enum t2_load_flags {
+    T2_LOAD_LOW_VRAM = 1   /* reserved: load DiTs on demand (follow-on)     */
+};
+
+/* step/total are meaningful for T2_STAGE_SS_FLOW; other stages send 0/0 at
+** entry. Called from the generating thread. */
+typedef void (*t2_progress_fn)(void * user, int stage, int step, int total);
+
+/* Optional live intermediate-preview callback. During generation the host
+** receives self-describing geometry blobs (currently "T2VOX01": a voxel set —
+** magic[8], u32 res, u32 nvox, u16[3*nvox] coords in [0,res)) for the current
+** stage, so a viewer can show the shape emerging in 3D. `data` is valid only
+** during the call (copy it). Fires on the generating thread. NULL disables it.
+** See t2_generate. */
+typedef void (*t2_preview_fn)(void * user, int stage, int step, int total,
+                              const void * data, int len);
+
+typedef struct t2_pipeline    t2_pipeline;
+typedef struct t2_mesh_result t2_mesh_result;
+
+/* Load the pipeline models. Optional models (pass NULL/"" to omit) select the
+** available qualities:
+**   - slat_flow_gguf + shape_dec_gguf present  -> 512 fine dual-grid
+**   - + slat_hr_flow_gguf present               -> 1024 cascade (reuses shape_dec)
+**   - shape_enc_gguf + tex_dec_gguf + tex_flow_gguf -> PBR texturing
+**   - neither pair                              -> coarse marching-cubes preview
+** `flags` is a bitmask of t2_load_flags (0 for standard resident loading).
+** On failure returns NULL and, if err != NULL, writes a reason into err. */
+TRELLIS2_CAPI t2_pipeline * t2_pipeline_load(const char * dino_gguf,
+                                             const char * ss_flow_gguf,
+                                             const char * ss_dec_gguf,
+                                             const char * slat_flow_gguf,
+                                             const char * slat_hr_flow_gguf,
+                                             const char * shape_dec_gguf,
+                                             /* PBR texturing (optional; NULL/"" to disable). The tex
+                                             ** models are loaded lazily per-generate, not held resident.
+                                             ** The validated generation path uses shape_enc_gguf to
+                                             ** re-encode the decoded dual grid before texture flow. */
+                                             const char * shape_enc_gguf,
+                                             const char * tex_dec_gguf,
+                                             const char * tex_flow_gguf,
+                                             const char * tex_flow_hr_gguf,
+                                             int flags,
+                                             char * err, int err_len);
+
+/* Bitmask of t2_caps: which mesh qualities/features this pipeline can produce. */
+TRELLIS2_CAPI int t2_pipeline_caps(t2_pipeline * p);
+/* Back-compat: 1 if any fine (512/1024) path is available, else 0. */
+TRELLIS2_CAPI int t2_pipeline_is_fine(t2_pipeline * p);
+TRELLIS2_CAPI void          t2_pipeline_free(t2_pipeline * p);
+TRELLIS2_CAPI const char *  t2_pipeline_backend(t2_pipeline * p);
+
+/* image bytes (PNG/JPEG/...; anything stb_image decodes) -> triangle mesh.
+** pipeline_type is a t2_pipeline_type (T2_PIPE_AUTO picks the best available).
+** background_mode is a t2_background_mode (normally T2_BACKGROUND_AUTO).
+** steps <= 0, guidance < 0, and texture_steps <= 0 select the pipeline defaults
+** (12 / 7.5 / 12 respectively).
+** `preview` (may be NULL) streams live intermediate 3D previews as the sparse
+** structure emerges; `preview_user` is passed back to it. The T2_PREVIEW_STRIDE
+** env var (default: ~4 previews across the SS steps) tunes the per-step cadence.
+** NOT thread-safe per pipeline: serialize calls on one t2_pipeline. */
+TRELLIS2_CAPI t2_mesh_result * t2_generate(t2_pipeline * p,
+                                           const void * image_bytes, int image_len,
+                                           int pipeline_type, int background_mode,
+                                           uint64_t seed, int steps, float guidance,
+                                           int texture_steps,
+                                           t2_progress_fn progress, void * user,
+                                           t2_preview_fn preview, void * preview_user,
+                                           char * err, int err_len);
+
+/* Mesh accessors. Vertices are in a centered unit cube ([-0.5, 0.5]^3, same
+** axes as the voxel grid); normals are per-vertex unit vectors. Buffers stay
+** valid until t2_mesh_free. */
+TRELLIS2_CAPI int           t2_mesh_n_verts(const t2_mesh_result * r);
+TRELLIS2_CAPI int           t2_mesh_n_tris (const t2_mesh_result * r);
+TRELLIS2_CAPI const float * t2_mesh_verts  (const t2_mesh_result * r); /* 3*n_verts   */
+TRELLIS2_CAPI const float * t2_mesh_normals(const t2_mesh_result * r); /* 3*n_verts   */
+TRELLIS2_CAPI const int *   t2_mesh_tris   (const t2_mesh_result * r); /* 3*n_tris    */
+/* Per-vertex PBR (6*n_verts: base_color rgb, metallic, roughness, alpha), or NULL when
+** the mesh is untextured. t2_mesh_has_pbr reports availability. */
+TRELLIS2_CAPI int           t2_mesh_has_pbr(const t2_mesh_result * r);
+TRELLIS2_CAPI const float * t2_mesh_pbr    (const t2_mesh_result * r); /* 6*n_verts   */
+TRELLIS2_CAPI void          t2_mesh_free   (t2_mesh_result * r);
+
+/* Prepare the exact component-cleaned geometry used for export so hosts can preview it.
+** component_filter: 0 removes only tiny islands; 1 keeps the largest connected
+** component; 2 keeps all components. The returned mesh owns copied PBR and is
+** freed with t2_mesh_free. */
+TRELLIS2_CAPI t2_mesh_result * t2_prepare_mesh(const float * verts, int n_verts,
+                                               const int * tris, int n_tris,
+                                               const float * pbr,
+                                               int component_filter,
+                                               char * err, int err_len);
+
+/* Bake a mesh into a portable UV-atlas-textured GLB (glTF 2.0 binary): optional
+** component cleanup -> UV unwrap -> per-texel PBR bake (from the dense
+** per-vertex attributes) -> gutter inpaint -> glTF. All CPU, no CUDA.
+**   verts  3*n_verts, tris  3*n_tris, pbr  6*n_verts (base_color rgb, metallic,
+**   roughness, alpha) or NULL for an untextured grey bake.
+**   texture_size  square atlas resolution hint (e.g. 2048; <=0 -> default).
+**   component_filter  0 remove tiny islands, 1 largest only, 2 keep all.
+** Operates on raw arrays so hosts can bake straight from their own buffers.
+** On success returns a malloc'd GLB buffer (free with t2_free_buffer) and writes
+** its length to *out_len; on failure returns NULL with a reason in err. */
+TRELLIS2_CAPI uint8_t * t2_bake_glb(const float * verts, int n_verts,
+                                    const int * tris, int n_tris,
+                                    const float * pbr,
+                                    int texture_size, int component_filter,
+                                    int * out_len, char * err, int err_len);
+TRELLIS2_CAPI void      t2_free_buffer(uint8_t * buf);
+
+/* Image decode + TRELLIS.2 preprocessing only (no models). out_rgb must hold
+** out_size*out_size*3 bytes. Returns 0 on success, nonzero on failure (reason
+** in err). This is the untrusted-input surface targeted by the fuzzers. */
+TRELLIS2_CAPI int t2_preprocess_image_bytes(const void * image_bytes, int image_len,
+                                            int out_size, unsigned char * out_rgb,
+                                            char * err, int err_len);
+
+#ifdef __cplusplus
+}
+#endif