Milestones 6+8: albedo/material/AO baking + ORM pack, LODs, collision, pivot, scale

Milestone 6 — Stage 2G-2I (stage2_bake_albedo.py, stage2_bake_ao.py):
- bake_albedo(): vertex-colour albedo to UV atlas via nvdiffrast + trimesh proximity
- bake_material(): metallic/roughness maps; reads mesh metadata attrs from TRELLIS.2
GLB, falls back to dielectric defaults (met=0, rough=0.5)
- bake_ao(): hemisphere ray casting via trimesh RayMesh; 16/64/256 rays per quality
preset; uses nvdiffrast only for UV rasterization, CPU for actual ray tests

Milestone 8 — Stage 2K-2O (stage2_finalize.py):
- pack_orm(): AO→R, Roughness→G, Metallic→B for UE5
- generate_lods(): LOD0/1/2 via PyMeshLab quadric at 100%/50%/25%
- generate_collision(): CoACD convex decomposition (convex_hull fallback)
- set_pivot(): bottom_center / geometric_center pivot correction
- validate_scale(): rescale to real-world height in cm (UE5 units)

app.py: wire all stages into run_post_process; only SDXL inpaint (M7) is a stub
requirements.txt: add coacd==1.0.4

app.py

@@ -156,25 +156,89 @@ def run_post_process(
         except Exception as e:
             log.append(f"⚠️ Normal bake error: {e}")
 
-    # Later milestones — stubs with informative messages
-    pending = []
-    if do_albedo:      pending.append("Albedo bake (M6)")
-    if do_material:    pending.append("Material bake (M6)")
-    if do_ao:          pending.append("AO bake (M6)")
-    if do_inpaint:     pending.append("SDXL inpaint (M7)")
-    if do_lods:        pending.append("LOD generation (M8)")
-    if do_collision:   pending.append("Collision (M8)")
-    if pending:
-        log.append(f"\n🚧 **Not yet implemented:** {', '.join(pending)}")
+    st = workspace.get_state()
+    hp = st.high_poly_glb
+    lo = st.unwrapped_glb or current_glb
+
+    if do_albedo:
+        try:
+            from src.stages.stage2_bake_albedo import bake_albedo
+            if not hp or not hp.exists():
+                log.append("⚠️ Albedo bake: no high-poly. Generate first.")
+            else:
+                _, msg = bake_albedo(hp, lo, map_size=2048)
+                log.append(f"✅ {msg}")
+        except Exception as e:
+            log.append(f"⚠️ Albedo bake error: {e}")
+
+    if do_material:
+        try:
+            from src.stages.stage2_bake_albedo import bake_material
+            if not hp or not hp.exists():
+                log.append("⚠️ Material bake: no high-poly. Generate first.")
+            else:
+                _, _, msg = bake_material(hp, lo, map_size=2048)
+                log.append(f"✅ {msg}")
+        except Exception as e:
+            log.append(f"⚠️ Material bake error: {e}")
+
+    if do_ao:
+        try:
+            from src.stages.stage2_bake_ao import bake_ao
+            _, msg = bake_ao(current_glb, lo, map_size=2048, quality=ao_quality)
+            log.append(f"✅ {msg}")
+        except Exception as e:
+            log.append(f"⚠️ AO bake error: {e}")
+
+    # Pack ORM if we have the component maps
+    st2 = workspace.get_state()
+    if do_albedo or do_material or do_ao:
+        try:
+            from src.stages.stage2_finalize import pack_orm
+            _, msg = pack_orm(st2.ao_png, st2.roughness_png, st2.metallic_png)
+            log.append(f"✅ {msg}")
+        except Exception as e:
+            log.append(f"⚠️ ORM pack error: {e}")
+
+    if do_lods:
+        try:
+            from src.stages.stage2_finalize import generate_lods
+            lod_src = st2.final_glb or st2.low_poly_glb or current_glb
+            _, msg = generate_lods(lod_src)
+            log.append(f"✅ {msg}")
+        except Exception as e:
+            log.append(f"⚠️ LOD error: {e}")
+
+    if do_collision:
+        try:
+            from src.stages.stage2_finalize import generate_collision
+            col_src = st2.low_poly_glb or current_glb
+            _, msg = generate_collision(col_src)
+            log.append(f"✅ {msg}")
+        except Exception as e:
+            log.append(f"⚠️ Collision error: {e}")
+
+    # Pivot + scale (always run if we have a final mesh)
+    try:
+        from src.stages.stage2_finalize import set_pivot, validate_scale
+        piv_src = st2.low_poly_glb or current_glb
+        piv_src, msg = set_pivot(piv_src, pivot)
+        log.append(f"✅ {msg}")
+        _, msg = validate_scale(piv_src, float(scale_m))
+        log.append(f"✅ {msg}")
+    except Exception as e:
+        log.append(f"⚠️ Pivot/scale error: {e}")
+
+    if do_inpaint:
+        log.append("🚧 SDXL inpaint — Milestone 7 (not yet implemented)")
 
     if not log:
         return "No processing steps selected."
 
     final = workspace.get_state()
-    out = final.low_poly_glb or final.cleaned_glb or final.repaired_glb
+    out = final.final_glb or final.low_poly_glb or final.cleaned_glb or final.repaired_glb
     if out and out.exists():
-        fc = final.face_count
-        log.append(f"\n**Output:** `{out.name}`" + (f" · {fc:,} faces" if fc else ""))
+        log.append(f"\n**Output:** `{out.name}`")
 
     return "\n".join(log)
 

requirements.txt

@@ -40,7 +40,7 @@ scipy               # normal map dilation
 # ===== Milestone 5: Stage 2F Normal Baking =====
 nvdiffrast          # PyPI version — compiles against installed CUDA at runtime
 
-# coacd==1.0.4  — Milestone 8
+coacd==1.0.4  # Milestone 8 collision
 
 # ===== Milestone 4: Stage 2 GPU baking =====
 # nvdiffrast      (install from PyPI — compatible with current torch)

src/stages/stage2_bake_albedo.py

@@ -0,0 +1,204 @@
+"""
+Stage 2G — Albedo bake and Stage 2H — Material (metallic/roughness) bake.
+
+Both follow the same nvdiffrast UV-rasterize + high-poly proximity pattern as
+the normal baker, but sample colour/material attributes instead of normals.
+
+The TRELLIS.2 GLB returned by gradio_client already encodes PBR attributes as
+vertex colours (or material attributes).  We read them from the high-poly mesh
+and bake them to UV textures on the low-poly.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+import spaces
+
+from src import workspace
+from src.workspace import CURRENT
+
+
+def _ensure_tex_dir() -> Path:
+    d = CURRENT / "textures"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _dilate(img: np.ndarray, mask: np.ndarray, n: int = 8) -> np.ndarray:
+    from scipy.ndimage import binary_dilation, convolve
+
+    result = img.astype(np.float32)
+    valid = mask.astype(bool)
+    kernel = np.array([[0, 1, 0], [1, 0, 1], [0, 1, 0]], dtype=np.float32)
+
+    for _ in range(n):
+        expanded = binary_dilation(valid)
+        border = expanded & ~valid
+        if not border.any():
+            break
+        for c in range(result.shape[2]):
+            w = convolve(result[:, :, c] * valid, kernel)
+            wn = convolve(valid.astype(np.float32), kernel)
+            result[:, :, c] = np.where(border, np.where(wn > 0, w / wn, 0), result[:, :, c])
+        valid = expanded
+
+    return result.clip(0, 255).astype(np.uint8)
+
+
+@spaces.GPU(duration=60)
+def bake_albedo(
+    high_poly_path: Path,
+    unwrapped_glb_path: Path,
+    map_size: int = 2048,
+) -> tuple[Path, str]:
+    """
+    Bake vertex-colour albedo from the high-poly to the low-poly UV atlas.
+    Falls back to a neutral grey if the high-poly has no vertex colours.
+    """
+    import torch
+    import trimesh
+    import nvdiffrast.torch as dr
+    from PIL import Image
+
+    device = torch.device("cuda")
+    ctx = dr.RasterizeCudaContext()
+
+    hi = trimesh.load(str(high_poly_path), force="mesh")
+    lo = trimesh.load(str(unwrapped_glb_path), force="mesh")
+
+    if not isinstance(lo.visual, trimesh.visual.TextureVisuals) or lo.visual.uv is None:
+        raise ValueError("Low-poly has no UV coordinates — run UV unwrap first.")
+
+    uvs = np.array(lo.visual.uv, dtype=np.float32)
+    lo_v = np.array(lo.vertices, dtype=np.float32)
+    lo_f = np.array(lo.faces, dtype=np.int32)
+
+    # Get high-poly vertex colours (albedo)
+    if hasattr(hi.visual, "vertex_colors") and hi.visual.vertex_colors is not None:
+        hi_colors = np.array(hi.visual.vertex_colors, dtype=np.float32)[:, :3] / 255.0
+    else:
+        # No vertex colours — use neutral grey
+        hi_colors = np.full((len(hi.vertices), 3), 0.5, dtype=np.float32)
+
+    pos_clip = np.zeros((len(uvs), 4), dtype=np.float32)
+    pos_clip[:, 0] = uvs[:, 0] * 2.0 - 1.0
+    pos_clip[:, 1] = (1.0 - uvs[:, 1]) * 2.0 - 1.0
+    pos_clip[:, 3] = 1.0
+
+    v_clip = torch.tensor(pos_clip, device=device).unsqueeze(0)
+    faces_t = torch.tensor(lo_f, device=device, dtype=torch.int32)
+    lo_v_t = torch.tensor(lo_v, device=device).unsqueeze(0)
+
+    rast, _ = dr.rasterize(ctx, v_clip, faces_t, resolution=[map_size, map_size])
+    world_pos, _ = dr.interpolate(lo_v_t, rast, faces_t)
+
+    mask = (rast[..., 3] > 0).squeeze(0).cpu().numpy()
+    wp = world_pos.squeeze(0).cpu().numpy()
+
+    ys, xs = np.where(mask)
+    prox = trimesh.proximity.ProximityQuery(hi)
+    _, _, tri_ids = prox.on_surface(wp[ys, xs])
+
+    # Interpolate vertex colours at face centroids (simple approximation)
+    face_verts = hi.faces[tri_ids]
+    albedo_vals = hi_colors[face_verts].mean(axis=1)  # [P, 3]
+
+    albedo_map = np.full((map_size, map_size, 3), 127, dtype=np.uint8)
+    packed = np.clip(albedo_vals * 255, 0, 255).astype(np.uint8)
+    albedo_map[ys, xs] = packed
+    albedo_map = _dilate(albedo_map, mask)
+
+    tex_dir = _ensure_tex_dir()
+    out_path = tex_dir / "albedo.png"
+    Image.fromarray(albedo_map).save(str(out_path))
+
+    state = workspace.get_state()
+    state.albedo_png = out_path
+
+    return out_path, f"Albedo baked: {map_size}×{map_size}"
+
+
+@spaces.GPU(duration=60)
+def bake_material(
+    high_poly_path: Path,
+    unwrapped_glb_path: Path,
+    map_size: int = 2048,
+) -> tuple[Path, Path, str]:
+    """
+    Bake metallic and roughness maps from high-poly vertex attributes.
+    Returns (metallic_path, roughness_path, message).
+    """
+    import torch
+    import trimesh
+    import nvdiffrast.torch as dr
+    from PIL import Image
+
+    device = torch.device("cuda")
+    ctx = dr.RasterizeCudaContext()
+
+    hi = trimesh.load(str(high_poly_path), force="mesh")
+    lo = trimesh.load(str(unwrapped_glb_path), force="mesh")
+
+    if not isinstance(lo.visual, trimesh.visual.TextureVisuals) or lo.visual.uv is None:
+        raise ValueError("Low-poly has no UV coordinates — run UV unwrap first.")
+
+    uvs = np.array(lo.visual.uv, dtype=np.float32)
+    lo_v = np.array(lo.vertices, dtype=np.float32)
+    lo_f = np.array(lo.faces, dtype=np.int32)
+
+    # Check for PBR attributes in high-poly metadata
+    # TRELLIS.2 stores metallic/roughness as vertex attributes in custom extras
+    # Fallback: metallic=0 (dielectric), roughness=0.5
+    hi_metallic = np.zeros(len(hi.vertices), dtype=np.float32)
+    hi_roughness = np.full(len(hi.vertices), 0.5, dtype=np.float32)
+
+    if hasattr(hi, "metadata") and hi.metadata:
+        m = hi.metadata.get("metallic")
+        r = hi.metadata.get("roughness")
+        if m is not None:
+            hi_metallic = np.array(m, dtype=np.float32)
+        if r is not None:
+            hi_roughness = np.array(r, dtype=np.float32)
+
+    pos_clip = np.zeros((len(uvs), 4), dtype=np.float32)
+    pos_clip[:, 0] = uvs[:, 0] * 2.0 - 1.0
+    pos_clip[:, 1] = (1.0 - uvs[:, 1]) * 2.0 - 1.0
+    pos_clip[:, 3] = 1.0
+
+    v_clip = torch.tensor(pos_clip, device=device).unsqueeze(0)
+    faces_t = torch.tensor(lo_f, device=device, dtype=torch.int32)
+    lo_v_t = torch.tensor(lo_v, device=device).unsqueeze(0)
+
+    rast, _ = dr.rasterize(ctx, v_clip, faces_t, resolution=[map_size, map_size])
+    world_pos, _ = dr.interpolate(lo_v_t, rast, faces_t)
+
+    mask = (rast[..., 3] > 0).squeeze(0).cpu().numpy()
+    wp = world_pos.squeeze(0).cpu().numpy()
+
+    ys, xs = np.where(mask)
+    prox = trimesh.proximity.ProximityQuery(hi)
+    _, _, tri_ids = prox.on_surface(wp[ys, xs])
+
+    face_verts = hi.faces[tri_ids]
+    met_vals = hi_metallic[face_verts].mean(axis=1)
+    rou_vals = hi_roughness[face_verts].mean(axis=1)
+
+    tex_dir = _ensure_tex_dir()
+
+    def _save_grey(vals: np.ndarray, path: Path) -> None:
+        img = np.full((map_size, map_size), 127, dtype=np.uint8)
+        img[ys, xs] = np.clip(vals * 255, 0, 255).astype(np.uint8)
+        img = _dilate(img[:, :, None], mask)[:, :, 0]
+        Image.fromarray(img).save(str(path))
+
+    met_path = tex_dir / "metallic.png"
+    rou_path = tex_dir / "roughness.png"
+    _save_grey(met_vals, met_path)
+    _save_grey(rou_vals, rou_path)
+
+    state = workspace.get_state()
+    state.metallic_png = met_path
+    state.roughness_png = rou_path
+
+    return met_path, rou_path, f"Material maps baked: {map_size}×{map_size}"

src/stages/stage2_bake_ao.py

@@ -0,0 +1,159 @@
+"""
+Stage 2I — Ambient Occlusion bake.
+
+Casts hemisphere rays from each UV-covered pixel's world position along the
+surface normal.  Occlusion is estimated by counting how many rays hit the mesh
+within a configurable radius (using trimesh's ray intersection).
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+import spaces
+
+from src import workspace
+from src.workspace import CURRENT
+
+
+def _dilate(img: np.ndarray, mask: np.ndarray, n: int = 8) -> np.ndarray:
+    from scipy.ndimage import binary_dilation, convolve
+
+    result = img.astype(np.float32)
+    valid = mask.astype(bool)
+    kernel = np.array([[0, 1, 0], [1, 0, 1], [0, 1, 0]], dtype=np.float32)
+
+    for _ in range(n):
+        expanded = binary_dilation(valid)
+        border = expanded & ~valid
+        if not border.any():
+            break
+        for c in range(result.shape[2]):
+            w = convolve(result[:, :, c] * valid, kernel)
+            wn = convolve(valid.astype(np.float32), kernel)
+            result[:, :, c] = np.where(border, np.where(wn > 0, w / wn, 0), result[:, :, c])
+        valid = expanded
+
+    return result.clip(0, 255).astype(np.uint8)
+
+
+def _hemisphere_rays(normal: np.ndarray, n_rays: int, rng: np.random.Generator):
+    """Generate n_rays directions distributed over the hemisphere around normal."""
+    # Random cosine-weighted hemisphere samples
+    u1 = rng.random(n_rays)
+    u2 = rng.random(n_rays)
+    r = np.sqrt(u1)
+    theta = 2 * np.pi * u2
+    x = r * np.cos(theta)
+    y = r * np.sin(theta)
+    z = np.sqrt(np.maximum(0.0, 1.0 - u1))
+    local_dirs = np.stack([x, y, z], axis=1)  # hemisphere in Z-up frame
+
+    # Build orthonormal basis from normal
+    up = np.array([0.0, 1.0, 0.0])
+    if abs(np.dot(normal, up)) > 0.99:
+        up = np.array([1.0, 0.0, 0.0])
+    T = np.cross(up, normal)
+    T /= np.linalg.norm(T)
+    B = np.cross(normal, T)
+    return local_dirs @ np.stack([T, B, normal]).T  # [n_rays, 3]
+
+
+@spaces.GPU(duration=120)
+def bake_ao(
+    mesh_path: Path,
+    unwrapped_glb_path: Path,
+    map_size: int = 2048,
+    quality: str = "Standard",  # "Fast" | "Standard" | "High"
+) -> tuple[Path, str]:
+    """Bake AO by hemisphere ray casting on the CPU (trimesh RayMesh intersector)."""
+    import torch
+    import trimesh
+    import nvdiffrast.torch as dr
+    from PIL import Image
+
+    n_rays_map = {"Fast": 16, "Standard": 64, "High": 256}
+    n_rays = n_rays_map.get(quality, 64)
+    max_dist = 0.5  # AO search radius (in mesh units)
+
+    device = torch.device("cuda")
+    ctx = dr.RasterizeCudaContext()
+
+    # Use the unwrapped mesh for both source positions and AO scene
+    scene_mesh = trimesh.load(str(mesh_path), force="mesh")
+    lo = trimesh.load(str(unwrapped_glb_path), force="mesh")
+
+    if not isinstance(lo.visual, trimesh.visual.TextureVisuals) or lo.visual.uv is None:
+        raise ValueError("Low-poly has no UV coordinates — run UV unwrap first.")
+
+    uvs = np.array(lo.visual.uv, dtype=np.float32)
+    lo_v = np.array(lo.vertices, dtype=np.float32)
+    lo_f = np.array(lo.faces, dtype=np.int32)
+    lo_n = np.array(lo.vertex_normals, dtype=np.float32)
+
+    pos_clip = np.zeros((len(uvs), 4), dtype=np.float32)
+    pos_clip[:, 0] = uvs[:, 0] * 2.0 - 1.0
+    pos_clip[:, 1] = (1.0 - uvs[:, 1]) * 2.0 - 1.0
+    pos_clip[:, 3] = 1.0
+
+    v_clip = torch.tensor(pos_clip, device=device).unsqueeze(0)
+    faces_t = torch.tensor(lo_f, device=device, dtype=torch.int32)
+    lo_v_t = torch.tensor(lo_v, device=device).unsqueeze(0)
+    lo_n_t = torch.tensor(lo_n, device=device).unsqueeze(0)
+
+    rast, _ = dr.rasterize(ctx, v_clip, faces_t, resolution=[map_size, map_size])
+    world_pos, _ = dr.interpolate(lo_v_t, rast, faces_t)
+    world_nrm, _ = dr.interpolate(lo_n_t, rast, faces_t)
+
+    mask = (rast[..., 3] > 0).squeeze(0).cpu().numpy()
+    wp = world_pos.squeeze(0).cpu().numpy()
+    wn = world_nrm.squeeze(0).cpu().numpy()
+
+    ys, xs = np.where(mask)
+    if len(ys) == 0:
+        raise ValueError("No UV-covered pixels.")
+
+    pts = wp[ys, xs]          # [P, 3]
+    nrms = wn[ys, xs]         # [P, 3]
+    norms = np.linalg.norm(nrms, axis=1, keepdims=True)
+    nrms = nrms / np.where(norms < 1e-8, 1.0, norms)
+
+    # CPU ray casting via trimesh (GPU not needed for rays)
+    ray_mesh = trimesh.ray.ray_pyembree.RayMeshIntersector(scene_mesh) \
+        if trimesh.ray.has_embree else trimesh.ray.ray_triangle.RayMeshIntersector(scene_mesh)
+
+    rng = np.random.default_rng(seed=42)
+    occlusion = np.zeros(len(pts), dtype=np.float32)
+
+    # Process in batches to avoid OOM
+    batch = 512
+    eps = 1e-4
+    for i in range(0, len(pts), batch):
+        p_batch = pts[i:i + batch]
+        n_batch = nrms[i:i + batch]
+
+        # Generate rays for all points in batch
+        dirs_list = [_hemisphere_rays(n_batch[j], n_rays, rng) for j in range(len(p_batch))]
+        all_dirs = np.concatenate(dirs_list, axis=0)
+        all_origins = np.repeat(p_batch + n_batch * eps, n_rays, axis=0)
+
+        hits = ray_mesh.intersects_any(all_origins, all_dirs)
+        # Reshape and average
+        hit_mat = hits.reshape(len(p_batch), n_rays)
+        occlusion[i:i + batch] = hit_mat.mean(axis=1)
+
+    ao_vals = 1.0 - occlusion  # 1 = fully lit, 0 = fully occluded
+
+    ao_map = np.full((map_size, map_size, 1), 255, dtype=np.uint8)
+    ao_map[ys, xs, 0] = np.clip(ao_vals * 255, 0, 255).astype(np.uint8)
+    ao_map = _dilate(ao_map, mask)
+
+    tex_dir = CURRENT / "textures"
+    tex_dir.mkdir(parents=True, exist_ok=True)
+    out_path = tex_dir / "ao.png"
+    Image.fromarray(ao_map[:, :, 0]).save(str(out_path))
+
+    state = workspace.get_state()
+    state.ao_png = out_path
+
+    return out_path, f"AO baked ({quality}, {n_rays} rays): {map_size}×{map_size}"

src/stages/stage2_finalize.py

@@ -0,0 +1,196 @@
+"""
+Stage 2K–2O — Finalization: ORM channel pack, LODs, collision, pivot, scale.
+All CPU-side, no GPU required.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+
+from src import workspace
+from src.workspace import CURRENT, CURRENT_LODS
+
+
+# ---------------------------------------------------------------------------
+# 2K  ORM channel packing
+# ---------------------------------------------------------------------------
+
+def pack_orm(ao_path: Path | None, roughness_path: Path | None, metallic_path: Path | None) -> tuple[Path, str]:
+    """Pack AO(R), Roughness(G), Metallic(B) → ORM texture for UE5."""
+    from PIL import Image
+
+    def _load_grey(p: Path | None, size: int) -> np.ndarray:
+        if p and p.exists():
+            img = Image.open(p).convert("L")
+            return np.array(img)
+        return np.full((size, size), 255, dtype=np.uint8)
+
+    # Determine output size from whichever map exists
+    size = 2048
+    for p in (ao_path, roughness_path, metallic_path):
+        if p and p.exists():
+            img = Image.open(p)
+            size = max(img.size)
+            break
+
+    r = _load_grey(ao_path, size)        # AO → Red
+    g = _load_grey(roughness_path, size) # Roughness → Green
+    b = _load_grey(metallic_path, size)  # Metallic → Blue
+
+    orm = np.stack([r, g, b], axis=2)
+    out_path = CURRENT / "textures" / "orm.png"
+    Image.fromarray(orm).save(str(out_path))
+
+    state = workspace.get_state()
+    state.orm_png = out_path
+
+    return out_path, "ORM packed (AO→R, Roughness→G, Metallic→B)"
+
+
+# ---------------------------------------------------------------------------
+# 2L  LOD generation
+# ---------------------------------------------------------------------------
+
+def generate_lods(input_glb: Path, lod_ratios: tuple = (1.0, 0.5, 0.25)) -> tuple[list[Path], str]:
+    """
+    Generate LOD0/LOD1/LOD2 via PyMeshLab quadric decimation.
+    lod_ratios: face-count multipliers relative to input (1.0 = full).
+    """
+    import trimesh
+    import pymeshlab
+    import tempfile
+
+    mesh = trimesh.load(str(input_glb), force="mesh")
+    base_faces = len(mesh.faces)
+
+    with tempfile.NamedTemporaryFile(suffix=".ply", delete=False) as tmp:
+        ply_in = tmp.name
+    mesh.export(ply_in)
+
+    CURRENT_LODS.mkdir(parents=True, exist_ok=True)
+
+    lod_paths = []
+    for idx, ratio in enumerate(lod_ratios):
+        target = max(100, int(base_faces * ratio))
+
+        if ratio == 1.0:
+            out = CURRENT_LODS / f"LOD{idx}.glb"
+            mesh.export(str(out))
+        else:
+            ms = pymeshlab.MeshSet()
+            ms.load_new_mesh(ply_in)
+            ms.apply_filter(
+                "meshing_decimation_quadric_edge_collapse",
+                targetfacenum=target,
+                preservenormal=True,
+                preservetopology=True,
+                autoclean=True,
+            )
+            with tempfile.NamedTemporaryFile(suffix=".ply", delete=False) as tmp:
+                ply_out = tmp.name
+            ms.save_current_mesh(ply_out)
+            lod_mesh = trimesh.load(ply_out, force="mesh")
+            out = CURRENT_LODS / f"LOD{idx}.glb"
+            lod_mesh.export(str(out))
+
+        lod_paths.append(out)
+
+    state = workspace.get_state()
+    state.lod_glbs = lod_paths
+
+    counts = [int(base_faces * r) for r in lod_ratios]
+    return lod_paths, f"LODs: {' / '.join(str(c) for c in counts)} faces"
+
+
+# ---------------------------------------------------------------------------
+# 2M  Collision mesh (CoACD)
+# ---------------------------------------------------------------------------
+
+def generate_collision(input_glb: Path) -> tuple[Path, str]:
+    """Generate convex decomposition collision mesh via CoACD."""
+    import trimesh
+
+    try:
+        import coacd
+        mesh = trimesh.load(str(input_glb), force="mesh")
+        m = coacd.Mesh(mesh.vertices, mesh.faces)
+        parts = coacd.run_coacd(m)
+        hulls = [trimesh.Trimesh(p[0], p[1]) for p in parts]
+        collision = trimesh.util.concatenate(hulls)
+    except ImportError:
+        # Fallback: single convex hull
+        mesh = trimesh.load(str(input_glb), force="mesh")
+        collision = mesh.convex_hull
+
+    out_path = CURRENT / "collision.glb"
+    collision.export(str(out_path))
+
+    state = workspace.get_state()
+    state.collision_glb = out_path
+
+    return out_path, f"Collision: {len(collision.faces):,} faces"
+
+
+# ---------------------------------------------------------------------------
+# 2N  Pivot correction
+# ---------------------------------------------------------------------------
+
+def set_pivot(input_glb: Path, mode: str = "bottom_center") -> tuple[Path, str]:
+    """Shift mesh so the pivot is at the origin."""
+    import trimesh
+
+    mesh = trimesh.load(str(input_glb), force="mesh")
+    bounds = mesh.bounds  # [[min_x, min_y, min_z], [max_x, max_y, max_z]]
+    center = (bounds[0] + bounds[1]) / 2.0
+
+    if mode == "bottom_center":
+        offset = np.array([center[0], bounds[0][1], center[2]])
+    elif mode == "geometric_center":
+        offset = center
+    else:
+        offset = np.zeros(3)
+
+    mesh.apply_translation(-offset)
+
+    out_path = CURRENT / "pivoted.glb"
+    mesh.export(str(out_path))
+
+    state = workspace.get_state()
+    state.final_glb = out_path
+
+    return out_path, f"Pivot set to {mode}"
+
+
+# ---------------------------------------------------------------------------
+# 2O  Scale validation (UE5: cm units)
+# ---------------------------------------------------------------------------
+
+def validate_scale(input_glb: Path, real_height_m: float = 1.8) -> tuple[Path, str]:
+    """
+    Scale the mesh so its bounding-box height equals real_height_m in metres.
+    For UE5 export, 1 unit = 1 cm, so height_m * 100 = height in UE5 units.
+    """
+    import trimesh
+
+    mesh = trimesh.load(str(input_glb), force="mesh")
+    bounds = mesh.bounds
+    current_height = bounds[1][1] - bounds[0][1]
+
+    if current_height < 1e-6:
+        return input_glb, "Scale: mesh has zero height, skipped"
+
+    # Target height in cm (UE5 units)
+    target_cm = real_height_m * 100.0
+    scale_factor = target_cm / current_height
+
+    mesh.apply_scale(scale_factor)
+
+    out_path = CURRENT / "scaled.glb"
+    mesh.export(str(out_path))
+
+    state = workspace.get_state()
+    state.final_glb = out_path
+
+    new_h = current_height * scale_factor
+    return out_path, f"Scale: {new_h:.1f} cm ({real_height_m} m) for UE5"