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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
"""Core-path tests for the segmenter (segment_core.py): pure geometry, no GCS,
no FastAPI, no network. Runs locally and as a Docker build gate:
python3 workers/segment/test_segment_core.py
The performance case is the important one. It pins the 2026-08-11 fix for a
merge pass whose cost grew faster than quadratically: production jobs ran for
2.9 to 4 HOURS and drove repeated 16 GiB OOM kills, because every single merge
rebuilt the whole label-adjacency map and rescanned the full label array. On
this machine the 20 k-face case took 328 s before the fix and well under a
second after it.
"""
from __future__ import annotations
import math
import os
import sys
import time
import numpy as np
import trimesh
# Importable from anywhere, so the documented repo-root invocation works.
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
import segment_core as seg
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
def noisy_sphere(subdivisions: int, amplitude: float = 0.06, seed: int = 7):
"""A sphere with jittered vertices: lots of genuine concave creases, so the
minima rule produces thousands of regions the merge pass has to dissolve."""
mesh = trimesh.creation.icosphere(subdivisions=subdivisions, radius=1.0)
rng = np.random.default_rng(seed)
mesh.vertices = mesh.vertices + rng.normal(0, amplitude, mesh.vertices.shape)
mesh.merge_vertices()
return mesh
def two_boxes():
"""Two physically disjoint shells: the unambiguous connected-component case."""
a = trimesh.creation.box(extents=(1, 1, 1))
b = trimesh.creation.box(extents=(1, 1, 1))
b.apply_translation([5.0, 0, 0])
return trimesh.util.concatenate([a, b])
def partition_of(result) -> list[int]:
return sorted(len(p.mesh.faces) for p in result.parts)
# ── loading ───────────────────────────────────────────────────────────────────
glb = trimesh.creation.box(extents=(1, 2, 3)).export(file_type="glb")
loaded = seg.load_concatenated(glb, ".glb")
check("load_concatenated returns a Trimesh", isinstance(loaded, trimesh.Trimesh))
check("load_concatenated keeps the faces", len(loaded.faces) == 12, str(len(loaded.faces)))
scene = trimesh.Scene()
scene.add_geometry(trimesh.creation.box(extents=(1, 1, 1)), geom_name="a")
scene.add_geometry(two_boxes(), geom_name="b")
merged = seg.load_concatenated(scene.export(file_type="glb"), ".glb")
check("a multi-node scene concatenates to one mesh", isinstance(merged, trimesh.Trimesh))
check("concatenation keeps every face", len(merged.faces) == 36, str(len(merged.faces)))
try:
seg.load_concatenated(trimesh.Trimesh().export(file_type="ply"), ".ply")
check("empty mesh is rejected", False, "no error raised")
except seg.SegmentInputError:
check("empty mesh is rejected", True)
except ValueError:
# trimesh may refuse the empty export first; still a caller-facing refusal.
check("empty mesh is rejected", True)
# ── connected components ──────────────────────────────────────────────────────
result = seg.segment(two_boxes(), method="connected")
check("connected mode finds both shells", len(result.parts) == 2, str(len(result.parts)))
check("connected mode reports source faces", result.source_faces == 24, str(result.source_faces))
check(
"connected mode splits faces evenly",
partition_of(result) == [12, 12],
str(partition_of(result)),
)
# ── crease segmentation ───────────────────────────────────────────────────────
bumpy = noisy_sphere(4)
result = seg.segment(bumpy, method="crease", max_parts=24, min_part_faces=64)
check("crease mode returns parts", len(result.parts) >= 2, str(len(result.parts)))
check("crease mode honours the cap", len(result.parts) <= 24, str(len(result.parts)))
check(
"every face lands in exactly one part",
sum(len(p.mesh.faces) for p in result.parts) == len(bumpy.faces),
f"{sum(len(p.mesh.faces) for p in result.parts)} vs {len(bumpy.faces)}",
)
for cap in (2, 4, 8, 24, 40):
r = seg.segment(noisy_sphere(4), method="crease", max_parts=cap, min_part_faces=16)
check(f"max_parts={cap} is never exceeded", len(r.parts) <= cap, str(len(r.parts)))
# The floor is a merge target, not a guarantee: a part with no neighbour cannot
# be dissolved. What must hold is that no shard survives while it still has a
# neighbour to merge into, which shows up as a single part in the degenerate case.
r = seg.segment(noisy_sphere(4), method="crease", max_parts=64, min_part_faces=100_000)
check("an impossible floor collapses to one part", len(r.parts) == 1, str(len(r.parts)))
# Parts must PARTITION the input: same faces, redistributed. trimesh's split
# patches holes by default, which silently grew a real 17031-face model to 17050
# faces across its parts and made the manifest contradict its own source_faces.
holed = trimesh.creation.box(extents=(1, 1, 1))
holed.update_faces(np.arange(len(holed.faces)) != 0) # punch a hole
holed.remove_unreferenced_vertices()
for mode in ("connected", "crease", "auto"):
r = seg.segment(holed, method=mode, max_parts=24, min_part_faces=4)
total = sum(len(p.mesh.faces) for p in r.parts)
check(
f"{mode} mode invents no faces on an open mesh",
total == len(holed.faces) == r.source_faces,
f"{total} vs {len(holed.faces)} (source_faces={r.source_faces})",
)
# ── determinism ───────────────────────────────────────────────────────────────
a = seg.segment(noisy_sphere(4), method="crease", max_parts=12, min_part_faces=64)
b = seg.segment(noisy_sphere(4), method="crease", max_parts=12, min_part_faces=64)
check(
"the same mesh segments identically twice",
partition_of(a) == partition_of(b),
f"{partition_of(a)} vs {partition_of(b)}",
)
check(
"part names are stable across runs",
[p.name for p in a.parts] == [p.name for p in b.parts],
)
# ── merge-pass policy ─────────────────────────────────────────────────────────
mesh = noisy_sphere(4)
labels = seg._crease_labels(mesh, math.radians(40.0))
check("crease labelling finds many regions", len(np.unique(labels)) > 100, str(len(np.unique(labels))))
capped = seg._merge_small_and_cap(mesh, labels, 64, 10)
check("merge caps the region count", len(np.unique(capped)) <= 10, str(len(np.unique(capped))))
check("merge keeps one label per face", len(capped) == len(mesh.faces))
check(
"merge never invents a region",
len(np.unique(capped)) <= len(np.unique(labels)),
)
sizes = np.bincount(capped.astype(np.int64))
sizes = sizes[sizes > 0]
check("merged regions all carry faces", bool((sizes > 0).all()))
check("merged regions cover the mesh", int(sizes.sum()) == len(mesh.faces))
# ── performance: the regression that caused the outage ────────────────────────
big = noisy_sphere(5)
labels = seg._crease_labels(big, math.radians(40.0))
t0 = time.time()
seg._merge_small_and_cap(big, labels, 64, 24)
merge_s = time.time() - t0
check(
f"20 k-face merge stays fast ({merge_s:.2f}s, was 328s pre-fix)",
merge_s < 30.0,
f"took {merge_s:.1f}s",
)
t0 = time.time()
full = seg.segment(noisy_sphere(6), method="auto", max_parts=24, min_part_faces=64)
full_s = time.time() - t0
check(
f"80 k-face end-to-end segmentation stays fast ({full_s:.2f}s)",
full_s < 120.0,
f"took {full_s:.1f}s",
)
check("the large mesh still yields parts", len(full.parts) >= 1, str(len(full.parts)))
# ── time budget ───────────────────────────────────────────────────────────────
try:
seg.segment(noisy_sphere(6), method="crease", time_budget_s=-1.0)
check("an exhausted budget raises SegmentTimeout", False, "no error raised")
except seg.SegmentTimeout as exc:
check("an exhausted budget raises SegmentTimeout", True)
check("the timeout says how to recover", "max_parts" in str(exc), str(exc))
roomy = seg.segment(two_boxes(), method="connected", time_budget_s=600.0)
check("a roomy budget does not interfere", len(roomy.parts) == 2)
# ── scene + manifest ──────────────────────────────────────────────────────────
result = seg.segment(two_boxes(), method="connected")
scene = seg.build_scene(result.parts)
expected_nodes = {f"part_{p.index:02d}" for p in result.parts}
check(
"scene geometry is named by part id",
set(scene.geometry.keys()) == expected_nodes,
f"{set(scene.geometry.keys())} vs {expected_nodes}",
)
exported = scene.export(file_type="glb")
check("the scene exports to GLB", isinstance(exported, bytes) and len(exported) > 0)
reloaded = trimesh.load(__import__("io").BytesIO(exported), file_type="glb")
check(
"the exported GLB keeps one node per part",
len(reloaded.geometry) == len(result.parts),
str(len(reloaded.geometry)),
)
man = seg.manifest(result)
check("manifest reports the method", man["method"] == "connected")
check("manifest counts the parts", man["part_count"] == len(result.parts))
check("manifest reports source faces", man["source_faces"] == 24)
check("manifest carries a warnings list", isinstance(man["warnings"], list))
for entry in man["parts"]:
for key in (
"id", "name", "region", "face_count", "vertex_count",
"bbox", "centroid", "volume", "color",
):
check(f"manifest part has {key}", key in entry, str(entry))
check("part id is zero padded", entry["id"].startswith("part_"), entry["id"])
check("colour is a hex triplet", len(entry["color"]) == 7 and entry["color"][0] == "#", entry["color"])
check("bbox has both corners", set(entry["bbox"]) == {"min", "max"})
check("centroid is a 3-vector", len(entry["centroid"]) == 3)
check("face_count is positive", entry["face_count"] > 0)
ids = [entry["id"] for entry in man["parts"]]
check("part ids are unique", len(set(ids)) == len(ids), str(ids))
names = [entry["name"] for entry in man["parts"]]
check("part names are unique", len(set(names)) == len(names), str(names))
# The cap warning has to be truthful: present only when something was folded.
capped_result = seg.segment(noisy_sphere(4), method="crease", max_parts=3, min_part_faces=4)
check("a capped run reports at most the cap", len(capped_result.parts) <= 3)
uncapped = seg.segment(two_boxes(), method="connected", max_parts=24)
check("an uncapped run warns about nothing", uncapped.warnings == [], str(uncapped.warnings))
# ── region naming ─────────────────────────────────────────────────────────────
bounds = np.array([[0.0, 0.0, 0.0], [1.0, 1.0, 1.0]])
check("centre is core", seg._region_name(np.array([0.5, 0.5, 0.5]), bounds) == "core")
check("high is top", seg._region_name(np.array([0.5, 0.9, 0.5]), bounds) == "top")
check("low is bottom", seg._region_name(np.array([0.5, 0.1, 0.5]), bounds) == "bottom")
check(
"off-axis picks up a qualifier",
seg._region_name(np.array([0.1, 0.9, 0.5]), bounds) == "top-left",
seg._region_name(np.array([0.1, 0.9, 0.5]), bounds),
)
# A flat mesh has zero span on an axis; that must not divide by zero.
flat = np.array([[0.0, 0.0, 0.0], [1.0, 0.0, 1.0]])
check("a zero-span axis is safe", isinstance(seg._region_name(np.array([0.5, 0.0, 0.5]), flat), str))
check("duplicate regions get numbered", seg._unique_names(["top", "top"]) == ["top-1", "top-2"])
check("a unique region keeps its name", seg._unique_names(["top", "core"]) == ["top", "core"])
# ── meshopt-compressed input ─────────────────────────────────────────────────
# Callers segment avatar URLs, and most three.ws avatars are saved with
# EXT_meshopt_compression, which trimesh cannot read: every segmentation of one
# failed until main._fetch_mesh started transcoding. gltf_meshopt.py owns the
# decode (and has its own suite); this pins that load_concatenated takes what it
# produces.
import shutil # noqa: E402
import subprocess # noqa: E402
import tempfile # noqa: E402
from pathlib import Path # noqa: E402
import gltf_meshopt # noqa: E402
_source = trimesh.creation.icosphere(subdivisions=2)
_plain_glb = trimesh.Scene({"a": _source}).export(file_type="glb")
if shutil.which(gltf_meshopt.GLTFPACK_BIN):
with tempfile.TemporaryDirectory() as _packdir:
_raw = Path(_packdir) / "raw.glb"
_packed = Path(_packdir) / "packed.glb"
_raw.write_bytes(_plain_glb)
subprocess.run(
[gltf_meshopt.GLTFPACK_BIN, "-i", str(_raw), "-o", str(_packed), "-cc"],
capture_output=True,
check=True,
timeout=gltf_meshopt.GLTFPACK_TIMEOUT_S,
)
_packed_bytes = _packed.read_bytes()
try:
seg.load_concatenated(_packed_bytes, ".glb")
_raw_failed = False
except Exception: # noqa: BLE001: the exact trimesh error is not the contract
_raw_failed = True
check("a compressed glb is unreadable without the decode", _raw_failed)
_decoded, _suffix = gltf_meshopt.decode_if_meshopt(_packed_bytes, ".glb")
_mesh = seg.load_concatenated(_decoded, _suffix)
check(
"the segmenter loads a decoded meshopt glb",
len(_mesh.faces) == len(_source.faces),
f"{len(_mesh.faces)} vs {len(_source.faces)}",
)
else:
print("skip meshopt decode section (no gltfpack binary)")
print(f"\nOK {PASS} checks passed")