Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

19.7 KB
Raw Blame
"""
Unit tests for the pure glTF pipeline in garment_glb.py: no GPU, no network,
no GCP. Runs as a Docker build gate (see Dockerfile) and locally:

    python3 workers/garment-forge/test_garment_glb.py

Covers, in pipeline order:
  - bone-name canonicalization (the Mixamo-scope port),
  - slot placement math (scale + translation into the slot box),
  - scene composition (garment + reference body, names preserved, textures
    survive the trimesh round-trip),
  - garment extraction from a rigged composite (body stripped, buffer
    repacked, joints canonicalized, garment texture kept),
  - skin statistics / coverage / occludes derivation,
  - all 6 manifest validation rules, each failing for its own reason.
"""

from __future__ import annotations

import io
import struct
import sys

import numpy as np
import pygltflib
import trimesh
from PIL import Image

from canonical_bones import canonicalize_bone_name
from garment_glb import (
    GARMENT_PREFIX,
    MIN_BIND_COVERAGE,
    REFBODY_PREFIX,
    SLOT_BOXES,
    SPEC_URI,
    build_manifest,
    compose_scene,
    derive_occludes,
    extract_garment,
    garment_placement,
    sha256_hex,
    skin_stats,
    slugify,
    validate_manifest,
    weighted_bones,
)

PASS = 0


def check(name: str, condition: bool, detail: str = "") -> None:
    global PASS
    if not condition:
        print(f"FAIL  {name}  {detail}")
        sys.exit(1)
    PASS += 1
    print(f"ok    {name}")


# ── fixtures ────────────────────────────────────────────────────────────────

def textured_box_glb() -> bytes:
    """A box with a real baseColorTexture, exported through trimesh."""
    mesh = trimesh.creation.box(extents=(1.0, 2.0, 0.5))
    img = Image.new("RGB", (8, 8), (200, 40, 40))
    uv = np.zeros((len(mesh.vertices), 2), dtype=np.float64)
    mesh.visual = trimesh.visual.TextureVisuals(
        uv=uv, material=trimesh.visual.material.PBRMaterial(baseColorTexture=img))
    scene = trimesh.Scene()
    scene.add_geometry(mesh, node_name="src", geom_name="src")
    return scene.export(file_type="glb")


def plain_body_glb() -> bytes:
    scene = trimesh.Scene()
    scene.add_geometry(trimesh.creation.capsule(radius=0.2, height=1.2),
                       node_name="body", geom_name="body")
    return scene.export(file_type="glb")


def _pack_floats(values) -> bytes:
    return struct.pack(f"<{len(values)}f", *values)


def build_rigged_composite(garment_joint_weights, body_texture: bool = True) -> bytes:
    """A minimal rigged composite the way model-rig would emit it: a mixamorig
    joint chain, one skin, a `garment_0` mesh and a `refbody_0` mesh, both
    skinned, the garment with a real embedded texture.

    garment_joint_weights: list of (joint_index, weight) rows, one per garment
    vertex (3 vertices required), letting tests steer coverage/occludes.
    """
    glb = pygltflib.GLTF2()
    blob = bytearray()

    def append_view(data: bytes, target=None) -> int:
        while len(blob) % 4:
            blob.append(0)
        view = pygltflib.BufferView(buffer=0, byteOffset=len(blob), byteLength=len(data))
        if target is not None:
            view.target = target
        blob.extend(data)
        glb.bufferViews.append(view)
        return len(glb.bufferViews) - 1

    def add_accessor(view, comp, count, typ, mn=None, mx=None) -> int:
        acc = pygltflib.Accessor(bufferView=view, componentType=comp, count=count, type=typ)
        if mn is not None:
            acc.min, acc.max = mn, mx
        glb.accessors.append(acc)
        return len(glb.accessors) - 1

    # Joints: Hips(0) → Spine(1) → LeftArm(2), plus a helper the canonical set
    # lacks (3) to exercise unresolved-mass accounting.
    joint_names = ["mixamorig:Hips", "mixamorig:Spine", "mixamorig:LeftArm",
                   "mixamorig:WeirdHelper"]
    for i, name in enumerate(joint_names):
        glb.nodes.append(pygltflib.Node(name=name, translation=[0, 0.3 * i, 0]))
    glb.nodes[0].children = [1]
    glb.nodes[1].children = [2, 3]

    ibm = np.tile(np.eye(4, dtype=np.float32).T.reshape(-1), (len(joint_names), 1))
    ibm_acc = add_accessor(append_view(ibm.tobytes()), 5126, len(joint_names), "MAT4")
    glb.skins.append(pygltflib.Skin(joints=[0, 1, 2, 3], inverseBindMatrices=ibm_acc,
                                    skeleton=0))

    def add_skinned_mesh(name: str, rows, material=None) -> int:
        pos = np.array([[0, 0, 0], [1, 0, 0], [0, 1, 0]], dtype=np.float32)
        pos_acc = add_accessor(append_view(pos.tobytes(), 34962), 5126, 3, "VEC3",
                               mn=pos.min(axis=0).tolist(), mx=pos.max(axis=0).tolist())
        joints = np.zeros((3, 4), dtype=np.uint8)
        weights = np.zeros((3, 4), dtype=np.float32)
        for vi, (ji, w) in enumerate(rows):
            joints[vi, 0] = ji
            weights[vi, 0] = w
            rest = 1.0 - w
            if rest > 0:
                joints[vi, 1] = 0
                weights[vi, 1] = rest
        j_acc = add_accessor(append_view(joints.tobytes(), 34962), 5121, 3, "VEC4")
        w_acc = add_accessor(append_view(weights.tobytes(), 34962), 5126, 3, "VEC4")
        idx = np.array([0, 1, 2], dtype=np.uint16)
        i_acc = add_accessor(append_view(idx.tobytes(), 34963), 5123, 3, "SCALAR")
        prim = pygltflib.Primitive(
            attributes=pygltflib.Attributes(POSITION=pos_acc, JOINTS_0=j_acc,
                                            WEIGHTS_0=w_acc),
            indices=i_acc, material=material)
        glb.meshes.append(pygltflib.Mesh(name=name, primitives=[prim]))
        node = pygltflib.Node(name=name, mesh=len(glb.meshes) - 1, skin=0)
        glb.nodes.append(node)
        return len(glb.nodes) - 1

    # Garment texture: a real PNG embedded in the buffer.
    png = io.BytesIO()
    Image.new("RGB", (4, 4), (10, 200, 10)).save(png, format="PNG")
    img_view = append_view(png.getvalue())
    glb.images.append(pygltflib.Image(bufferView=img_view, mimeType="image/png"))
    glb.samplers.append(pygltflib.Sampler())
    glb.textures.append(pygltflib.Texture(source=0, sampler=0))
    glb.materials.append(pygltflib.Material(
        name="garment-mat",
        pbrMetallicRoughness=pygltflib.PbrMetallicRoughness(
            baseColorTexture=pygltflib.TextureInfo(index=0))))

    # Body texture: a second PNG that extraction must drop.
    body_mat = None
    if body_texture:
        png2 = io.BytesIO()
        Image.new("RGB", (4, 4), (10, 10, 200)).save(png2, format="PNG")
        img_view2 = append_view(png2.getvalue())
        glb.images.append(pygltflib.Image(bufferView=img_view2, mimeType="image/png"))
        glb.textures.append(pygltflib.Texture(source=1, sampler=0))
        glb.materials.append(pygltflib.Material(
            name="body-mat",
            pbrMetallicRoughness=pygltflib.PbrMetallicRoughness(
                baseColorTexture=pygltflib.TextureInfo(index=1))))
        body_mat = 1

    garment_node = add_skinned_mesh(f"{GARMENT_PREFIX}_0", garment_joint_weights, 0)
    body_node = add_skinned_mesh(f"{REFBODY_PREFIX}_0",
                                 [(0, 1.0), (0, 1.0), (1, 1.0)], body_mat)

    glb.scenes.append(pygltflib.Scene(nodes=[0, garment_node, body_node]))
    glb.scene = 0
    glb.buffers.append(pygltflib.Buffer(byteLength=len(blob)))
    glb.set_binary_blob(bytes(blob))
    out = glb.save_to_bytes()
    return b"".join(out) if isinstance(out, (list, tuple)) else out


# ── canonicalization ────────────────────────────────────────────────────────

check("mixamorig namespace strips", canonicalize_bone_name("mixamorig:LeftArm") == "LeftArm")
check("numbered namespace strips", canonicalize_bone_name("mixamorig1:Spine2") == "Spine2")
check("glued mixamo prefix strips", canonicalize_bone_name("mixamorigRightFoot") == "RightFoot")
check("canonical passes through", canonicalize_bone_name("LeftHandIndex2") == "LeftHandIndex2")
check("separators normalize", canonicalize_bone_name("left_fore_arm") == "LeftForeArm")
check("non-humanoid rejects", canonicalize_bone_name("tentacle_tip") is None)

# ── placement ───────────────────────────────────────────────────────────────

box_glb = textured_box_glb()
loaded = trimesh.load(io.BytesIO(box_glb), file_type="glb", process=False)
meshes = [g.copy() for g in loaded.geometry.values()]
placement = garment_placement(meshes, "top")
placed = meshes[0].copy()
placed.apply_transform(placement)
top = SLOT_BOXES["top"]
height = placed.bounds[1][1] - placed.bounds[0][1]
center_y = (placed.bounds[1][1] + placed.bounds[0][1]) / 2
check("placement fits slot height", abs(height - top["size"][1]) < 1e-6, f"height={height}")
check("placement centers on slot", abs(center_y - top["center"][1]) < 1e-6, f"cy={center_y}")

# Footwear is depth-fit: a pair whose shoes nearly touch must size by foot
# length, not by the (meaningless) pair width. Two 0.1-wide boxes 0.02 apart,
# each 0.5 long in z: after placement the pair depth equals the slot's z size
# regardless of the tiny pair width.
shoe_l = trimesh.creation.box(extents=(0.1, 0.1, 0.5))
shoe_l.apply_translation((-0.06, 0.0, 0.0))
shoe_r = trimesh.creation.box(extents=(0.1, 0.1, 0.5))
shoe_r.apply_translation((0.06, 0.0, 0.0))
foot_place = garment_placement([shoe_l, shoe_r], "footwear")
pair = [m.copy() for m in (shoe_l, shoe_r)]
for m in pair:
    m.apply_transform(foot_place)
lo = np.min([m.bounds[0] for m in pair], axis=0)
hi = np.max([m.bounds[1] for m in pair], axis=0)
foot_box = SLOT_BOXES["footwear"]
check("footwear fits by depth", abs((hi[2] - lo[2]) - foot_box["size"][2]) < 1e-6,
      f"depth={hi[2] - lo[2]}")
check("footwear pair stays narrow (no width blow-up)", (hi[0] - lo[0]) < 0.30,
      f"width={hi[0] - lo[0]}")

# snap_pair_to_feet: each shoe lands centered on its foot; a single component
# (one shoe, fused sandals) is left alone.
from garment_glb import FOOT_CENTERS_X, snap_pair_to_feet  # noqa: E402
snapped = snap_pair_to_feet([m.copy() for m in pair])
sn_left = [c for c in snapped if c.centroid[0] < 0]
sn_right = [c for c in snapped if c.centroid[0] >= 0]
lx = (min(c.bounds[0][0] for c in sn_left) + max(c.bounds[1][0] for c in sn_left)) / 2
rx = (min(c.bounds[0][0] for c in sn_right) + max(c.bounds[1][0] for c in sn_right)) / 2
check("left shoe snaps to left foot", abs(lx - FOOT_CENTERS_X[0]) < 1e-6, f"lx={lx}")
check("right shoe snaps to right foot", abs(rx - FOOT_CENTERS_X[1]) < 1e-6, f"rx={rx}")
single = trimesh.creation.box(extents=(0.1, 0.1, 0.3))
check("single component is not snapped",
      snap_pair_to_feet([single.copy()])[0].centroid[0] == single.centroid[0])

# Hair anchors its TOP to the crown, so length hangs down the back instead of
# floating above the head, and a wildly out-of-proportion mesh is REFUSED
# rather than published. Both reproduce the live 2026-07-27 defect: a
# "long straight black hair" mesh that came out 1.43 m deep and reached 36 cm
# above the crown (gait p95 53 cm off the body).
from garment_glb import assert_plausible_extents  # noqa: E402

hair_box = SLOT_BOXES["hair"]
crown = hair_box["center"][1] + hair_box["size"][1] / 2

long_hair = trimesh.creation.box(extents=(0.30, 0.60, 0.20))
hp = garment_placement([long_hair], "hair")
placed_hair = long_hair.copy()
placed_hair.apply_transform(hp)
check("hair top anchors to the crown",
      abs(placed_hair.bounds[1][1] - crown) < 1e-6, f"top={placed_hair.bounds[1][1]}")
check("hair length hangs below the crown",
      placed_hair.bounds[0][1] < crown, f"bottom={placed_hair.bounds[0][1]}")
check("in-envelope hair is accepted",
      assert_plausible_extents([long_hair], "hair", hp) is not None)

# The real defect: width-fit is satisfied exactly, but depth is ~5x its
# envelope, so the mesh must be refused with the measurement.
runaway = trimesh.creation.box(extents=(0.30, 0.90, 1.45))
runaway_place = garment_placement([runaway], "hair")
try:
    assert_plausible_extents([runaway], "hair", runaway_place)
    check("runaway hair is refused", False, "no exception raised")
except ValueError as exc:
    check("runaway hair is refused", "out of proportion" in str(exc))
    check("refusal names the offending axis and number",
          "z=" in str(exc) and "max" in str(exc), str(exc)[:90])

# Headwear is contain-fit: a cap with a deep brim (depth 2x width) must be
# bounded by the box on EVERY axis, so depth becomes the limiting dimension
# and the width scales down with it instead of blowing the brim past the face.
cap = trimesh.creation.box(extents=(1.0, 0.9, 2.0))
head_place = garment_placement([cap], "headwear")
placed_cap = cap.copy()
placed_cap.apply_transform(head_place)
head_box = SLOT_BOXES["headwear"]
cap_ext = placed_cap.bounds[1] - placed_cap.bounds[0]
check("headwear contained on depth", abs(cap_ext[2] - head_box["size"][2]) < 1e-6,
      f"depth={cap_ext[2]}")
check("headwear width shrinks with depth", cap_ext[0] <= head_box["size"][0] + 1e-9,
      f"width={cap_ext[0]}")

# ── composition ─────────────────────────────────────────────────────────────

composite = compose_scene(box_glb, plain_body_glb(), "top")
comp_glb = pygltflib.GLTF2.load_from_bytes(composite)
names = sorted(m.name or "" for m in comp_glb.meshes)
check("composite keeps both parts",
      any(n.startswith(GARMENT_PREFIX) for n in names)
      and any(n.startswith(REFBODY_PREFIX) for n in names), str(names))
check("composite garment textured", len(comp_glb.images) >= 1)

# ── extraction ──────────────────────────────────────────────────────────────

# Garment weighted: Spine 100%, Spine 80%/Hips 20%, LeftArm 100%.
rigged = build_rigged_composite([(1, 1.0), (1, 0.8), (2, 1.0)])
garment_only = extract_garment(rigged)
out = pygltflib.GLTF2.load_from_bytes(garment_only)

check("extraction drops body mesh",
      [m.name for m in out.meshes] == [f"{GARMENT_PREFIX}_0"],
      str([m.name for m in out.meshes]))
check("extraction keeps the skin", len(out.skins) == 1)
check("extraction drops body texture", len(out.images) == 1 and len(out.materials) == 1,
      f"images={len(out.images)} materials={len(out.materials)}")
check("extraction shrinks the buffer", len(garment_only) < len(rigged))
joint_names = [out.nodes[j].name for j in out.skins[0].joints]
check("joints canonicalized", joint_names[:3] == ["Hips", "Spine", "LeftArm"],
      str(joint_names))
check("unmappable joint keeps its name", joint_names[3] == "mixamorig:WeirdHelper")
kept_png = None
for img in out.images:
    view = out.bufferViews[img.bufferView]
    blob = out.binary_blob()
    kept_png = bytes(blob[view.byteOffset:view.byteOffset + view.byteLength])
check("kept texture is the garment's",
      kept_png is not None and Image.open(io.BytesIO(kept_png)).getpixel((0, 0))[1] > 150)

# ── stats / coverage / occludes ─────────────────────────────────────────────

stats = skin_stats(garment_only)
check("full coverage when all joints resolve", abs(stats["coverage"] - 1.0) < 1e-9,
      f"coverage={stats['coverage']}")
occ = derive_occludes(stats["bone_mass"], stats["total_mass"])
check("occludes torso from Spine mass", "torso" in occ, str(occ))
check("occludes upperArms from LeftArm mass", "upperArms" in occ, str(occ))
# The synthetic's Hips mass is 0.2 of one vertex = 6.7% of total garment
# weight — a waistband graze. Under the evidence threshold (10%) a graze must
# NOT hide the pelvis; that exact over-declaration amputated the avatar's
# lower body with the first live-seeded shirt.
check("6.7% hip graze does not occlude hips", "hips" not in occ, str(occ))
check("no phantom regions", all(r in ("torso", "upperArms") for r in occ), str(occ))
# Slot plausibility clamp: evidence alone is not enough. The same weight
# spread on a footwear-slot garment must not hide torso or hips, and a shirt
# whose waistband carries a trace of Hips mass must not amputate the legs.
occ_clamped = derive_occludes(stats["bone_mass"], stats["total_mass"], slot="footwear")
check("slot clamp: footwear cannot occlude torso/hips", occ_clamped == [], str(occ_clamped))
occ_top = derive_occludes(stats["bone_mass"], stats["total_mass"], slot="top")
check("slot clamp: top keeps its evidenced regions", occ_top == occ, f"{occ_top} vs {occ}")
trace = {"Spine": 0.97, "Hips": 0.03}
occ_trace = derive_occludes(trace, 1.0, slot="top")
check("3% hip graze does not hide the pelvis", occ_trace == ["torso"], str(occ_trace))
# scalp is categorically un-occludable: it resolves to the Head bone, and
# Head-bone culling cannot separate scalp from face. A cap or hairstyle whose
# weight sits 100% on Head must still declare occludes=[] or the avatar loses
# its face at attach time.
head_only = {"Head": 1.0}
check("headwear on Head occludes nothing",
      derive_occludes(head_only, 1.0, slot="headwear") == [],
      str(derive_occludes(head_only, 1.0, slot="headwear")))
check("hair on Head occludes nothing",
      derive_occludes(head_only, 1.0, slot="hair") == [],
      str(derive_occludes(head_only, 1.0, slot="hair")))
bones = weighted_bones(stats["bone_mass"], stats["total_mass"])
check("rig.bones in canonical order", bones == ["Hips", "Spine", "LeftArm"], str(bones))

# Low coverage: 70% of weight on the helper joint that cannot canonicalize.
low = extract_garment(build_rigged_composite([(3, 0.7), (3, 0.7), (3, 0.7)]))
low_stats = skin_stats(low)
check("unresolved joints lower coverage", low_stats["coverage"] < MIN_BIND_COVERAGE,
      f"coverage={low_stats['coverage']}")

# ── manifest validation ─────────────────────────────────────────────────────

manifest = build_manifest(
    garment_id="test-shirt-abc123", name="Test shirt", slot="top", version=1,
    model_uri="https://storage.googleapis.com/bucket/garments/top/test/v1/garment.glb",
    glb_bytes=garment_only, triangle_count=stats["triangle_count"],
    bones=bones, occludes=occ, prompt="test shirt", mesh_model="hunyuan3d-2.1",
    thumb_uri="https://storage.googleapis.com/bucket/garments/top/test/v1/thumb.webp")
verdict = validate_manifest(manifest, garment_only)
check("valid manifest passes all 6 rules", verdict["ok"], str(verdict["failures"]))
check("manifest pins the spec URI", manifest["spec"] == SPEC_URI)

bad = dict(manifest, spec="https://example.com/other-spec")
check("rule 1 rejects unknown spec", not validate_manifest(bad, garment_only)["ok"])
bad = dict(manifest, slot="cape")
check("rule 2 rejects unknown slot", not validate_manifest(bad, garment_only)["ok"])
bad = dict(manifest, occludes=["torso", "tail"])
check("rule 3 rejects unknown region", not validate_manifest(bad, garment_only)["ok"])
bad = dict(manifest, model=dict(manifest["model"], sha256="0" * 64))
check("rule 4 rejects a hash mismatch", not validate_manifest(bad, garment_only)["ok"])
low_manifest = dict(manifest, model=dict(manifest["model"], sha256=sha256_hex(low)))
check("rule 5 rejects low coverage", not validate_manifest(low_manifest, low)["ok"])
bad = dict(manifest, license="CC-BY-NC-4.0")
check("rule 6 rejects non-commercial license", not validate_manifest(bad, garment_only)["ok"])

# ── slug ────────────────────────────────────────────────────────────────────

check("slugify", slugify("A White Oxford Shirt, long sleeves!") == "a-white-oxford-shirt-long")

print(f"\nall {PASS} checks passed")