simready-forge 0.1.0__py3-none-any.whl

simready_forge/__init__.py

@@ -0,0 +1,14 @@
+"""simready-forge: a prompt or a photo in, an NVIDIA SimReady asset out (OpenUSD with materials, physics and joints)."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .kit import Asset
+from .scan import load_scan
+from .validate import validate
+
+try:
+    __version__ = version("simready-forge")
+except PackageNotFoundError:  # a source tree that was never installed
+    __version__ = "0.0.0"
+
+__all__ = ["Asset", "__version__", "load_scan", "validate"]

simready_forge/cli.py

@@ -0,0 +1,221 @@
+"""The `simready-forge` command: what the plugin's skills and the builder agents run.
+
+simready-forge validate <asset.usda>
+simready-forge review <asset.usda> [--out DIR] [--isaac PYTHON]
+simready-forge trellis txt2img|image <prompt|image> <out_dir> [--effort low|medium|high] [--server URL]
+simready-forge views <mesh.glb> --height N [--units mm] --out views.png
+simready-forge qcode "<object class>" | Q<id> [Q<id> ...]
+simready-forge prefs show|set|reset [--data DIR] [--session ID] [--project DIR] [--scope S] [key=value ...]
+simready-forge cost --session ID --project DIR [--since ISO]
+simready-forge example --show | --build DIR
+simready-forge version
+"""
+
+import argparse
+import json
+import re
+import sys
+import time
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+
+def _wikidata(params, need):
+    url = "https://www.wikidata.org/w/api.php?" + urllib.parse.urlencode(params | {"language": "en", "format": "json"})
+    request = urllib.request.Request(
+        url, headers={"User-Agent": "simready-forge (github.com/serionist/simready-forge)"}
+    )
+    answer = {}
+    for attempt in range(3):  # Wikidata now and then answers a good query without its results: a retry gets them
+        with urllib.request.urlopen(request, timeout=20) as response:  # noqa: S310 (a fixed https URL)
+            answer = json.loads(response.read())
+        if need in answer:
+            return answer
+        time.sleep(2 * (attempt + 1))
+    sys.exit(f"Wikidata answered without {need!r}: {str(answer.get('error', answer))[:300]}")
+
+
+def _qcode(words):
+    """Search for a class, or, given Q-codes, print what each one is: a remembered code is often someone else."""
+    if all(re.fullmatch(r"Q\d+", w) for w in words):
+        entities = _wikidata(
+            {"action": "wbgetentities", "ids": "|".join(words), "props": "labels|descriptions", "languages": "en"},
+            "entities",
+        )["entities"]
+        for qid in words:
+            item = entities.get(qid, {})
+            label = item.get("labels", {}).get("en", {}).get("value", "(no such item)")
+            print(f"{qid:>12}  {label}: {item.get('descriptions', {}).get('en', {}).get('value', '')}")
+        return 0
+    for hit in _wikidata({"action": "wbsearchentities", "search": " ".join(words), "limit": 7}, "search")["search"]:
+        print(f"{hit['id']:>12}  {hit.get('label', '')}: {hit.get('description', '')}")
+    return 0
+
+
+def _prefs(args):
+    from . import prefs
+
+    where = {"data_dir": args.data, "session": args.session, "project": args.project}
+    if args.action == "set":
+        prefs.set_values(prefs.parse(args.pairs), args.scope, **where)
+    elif args.action == "reset":
+        prefs.reset(args.scope, **where)
+    values, source = prefs.resolve(**where)
+    print(json.dumps({"values": values, "source": source, "remembered": prefs.remembered(**where)}, indent=1))
+    return 0
+
+
+def _example(args):
+    from .examples import cabinet
+
+    if args.show:
+        print(Path(cabinet.__file__).read_text(encoding="utf-8"))
+        return 0
+    return 0 if cabinet.build(args.build)["passed"] else 1
+
+
+def main(argv=None):
+    for stream in (sys.stdout, sys.stderr):  # Wikidata labels hold emoji; a Windows console's cp1252 cannot print them
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure:
+            reconfigure(encoding="utf-8", errors="replace")
+    parser = argparse.ArgumentParser(prog="simready-forge", description=(__doc__ or "").split("\n")[0])
+    sub = parser.add_subparsers(dest="command", required=True)
+    p = sub.add_parser("validate", help="NVIDIA's SimReady validator, Robotics-Prop 4.0.0")
+    p.add_argument("asset")
+    p.add_argument("--out")
+    p = sub.add_parser("inspect", help="the asset's bodies, joints, materials and colliders, read from the USD")
+    p.add_argument("asset")
+    p.add_argument("--out")
+    p = sub.add_parser("poses", help="the review's joint poses without Isaac: overlaps and the lowest point")
+    p.add_argument("asset")
+    p.add_argument("--out")
+    p.add_argument(
+        "--empty",
+        nargs=6,
+        type=float,
+        action="append",
+        default=[],
+        metavar=("X0", "Y0", "Z0", "X1", "Y1", "Z1"),
+        help="a box in mm that should stay empty (an opening, a cavity); repeatable",
+    )
+    p.add_argument(
+        "--set",
+        action="append",
+        default=[],
+        metavar="JOINT=VALUE",
+        help="put joints at chosen targets too (degrees, mm for a slide), the rest at rest; repeatable",
+    )
+    p = sub.add_parser("probe", help="Isaac Sim physics probe: settle, tilt, push, lift, load")
+    p.add_argument("asset")
+    p.add_argument("--out")
+    p.add_argument("--isaac", help="Isaac Sim's Python")
+    p.add_argument(
+        "--tests",
+        nargs="+",
+        choices=("settle", "tilt", "push", "lift", "load"),
+        default=(),
+        help="run only these, keeping the others' earlier results",
+    )
+    p = sub.add_parser("review", help="Isaac Sim renders and PhysX checks (a software preview without Isaac Sim)")
+    p.add_argument("asset")
+    p.add_argument("--out")
+    p.add_argument("--isaac", help="Isaac Sim's Python")
+    p = sub.add_parser("trellis", help="local text-to-image and image-to-3D through ComfyUI")
+    p.add_argument("rest", nargs=argparse.REMAINDER)
+    p = sub.add_parser("views", help="front, side and top views of a generated mesh with a grid, to split it")
+    p.add_argument("mesh")
+    p.add_argument("--out", required=True)
+    p.add_argument("--units", default="mm")
+    p.add_argument("--height", type=float)
+    p.add_argument("--longest", type=float)
+    p.add_argument("--turn", type=float, default=0.0, help="degrees about Z, as load_scan(turn=)")
+    p = sub.add_parser("qcode", help="search Wikidata for a class, or check what Q-codes are")
+    p.add_argument("query", nargs="+")
+    p = sub.add_parser("prefs", help="the remembered choices")
+    p.add_argument("action", choices=["show", "set", "reset"])
+    p.add_argument("pairs", nargs="*")
+    p.add_argument("--scope", default="session")
+    p.add_argument("--data")
+    p.add_argument("--session")
+    p.add_argument("--project")
+    p = sub.add_parser("cost", help="tokens and dollars per role from the session transcripts")
+    p.add_argument("--session", required=True)
+    p.add_argument("--project", required=True)
+    p.add_argument("--since")
+    p.add_argument("--out")
+    p = sub.add_parser("example", help="the worked example: a cabinet with a hinged door and a drawer")
+    group = p.add_mutually_exclusive_group(required=True)
+    group.add_argument("--show", action="store_true")
+    group.add_argument("--build")
+    sub.add_parser("version")
+    args = parser.parse_args(argv)
+
+    if args.command == "validate":
+        from .validate import validate
+
+        return 0 if validate(args.asset, args.out)["passed"] else 1
+    if args.command == "inspect":
+        from .readback import inspect
+
+        text = json.dumps(inspect(args.asset), indent=1)
+        if args.out:
+            Path(args.out).parent.mkdir(parents=True, exist_ok=True)
+            Path(args.out).write_text(text, encoding="utf-8")
+        print(text)
+        return 0
+    if args.command == "poses":
+        from .poses import main as poses
+
+        chosen = {k: float(v) for k, v in (item.split("=", 1) for item in args.set)}
+        return poses(args.asset, args.out, args.empty, chosen)
+    if args.command == "probe":
+        from .review import probe
+
+        out = args.out or Path(args.asset).resolve().parent.parent.parent / f"{Path(args.asset).stem}_reports" / "probe"
+        report = probe(args.asset, out, args.isaac, tests=args.tests)
+        print(json.dumps({k: report.get(k) for k in ("passed", "all_passed", "error")}, indent=1))
+        return 0 if report.get("all_passed") else 1
+    if args.command == "review":
+        from .review import review
+
+        out = (
+            args.out or Path(args.asset).resolve().parent.parent.parent / f"{Path(args.asset).stem}_reports" / "review"
+        )
+        report = review(args.asset, out, args.isaac)
+        print(json.dumps(report, indent=1))
+        return 0 if report.get("passed", report.get("renderer") == "software") else 1
+    if args.command == "trellis":
+        from . import trellis
+
+        return trellis.main(args.rest)
+    if args.command == "views":
+        from .scan import load_scan
+
+        load_scan(args.mesh, args.units, height=args.height, longest=args.longest, turn=args.turn).views(args.out)
+        print(args.out)
+        return 0
+    if args.command == "qcode":
+        return _qcode(args.query)
+    if args.command == "prefs":
+        return _prefs(args)
+    if args.command == "cost":
+        from .cost import report
+
+        result = report(args.session, args.project, args.since)
+        text = json.dumps(result, indent=1)
+        if args.out:
+            Path(args.out).write_text(text, encoding="utf-8")
+        print(text)
+        return 0
+    if args.command == "example":
+        return _example(args)
+    from . import __version__
+
+    print(__version__)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

simready_forge/cost.py

@@ -0,0 +1,120 @@
+"""What a run cost: tokens and dollars per role, read from Claude Code's session transcripts at list prices.
+
+Claude Code keeps a session at ~/.claude/projects/<project>/<session>.jsonl and its agents under
+<session>/subagents/. The entry format is internal to Claude Code, so this is best effort and says so. An agent's role
+comes from the marker its brief carries: `[simready-forge role: builder]` and so on.
+"""
+
+import json
+import re
+from datetime import datetime
+from pathlib import Path
+
+# $ per million tokens: input, output, cache read, 5-minute cache write, 1-hour cache write (Anthropic list prices)
+PRICES = {
+    "claude-fable-5-1": (10.0, 50.0, 0.25, 12.5, 20.0),
+    "claude-opus-5-5": (4.0, 20.0, 0.20, 5.0, 8.0),
+    "claude-sonnet-5-5": (2.0, 10.0, 0.20, 2.5, 4.0),
+    "claude-haiku-5-5": (0.10, 0.50, 0.01, 0.125, 0.20),
+}
+ROLE = re.compile(r"\[simready-forge role: ([a-z-]+)\]")
+
+
+def project_folder(project_dir):
+    """Claude Code's folder name for a working directory: every non-alphanumeric character becomes '-'."""
+    return re.sub(r"[^A-Za-z0-9]", "-", str(project_dir))
+
+
+def _stamp(entry):
+    value = entry.get("timestamp")
+    return datetime.fromisoformat(value.replace("Z", "+00:00")) if value else None
+
+
+def _usage(path, since):
+    calls, model, role = {}, None, None
+    for line in Path(path).read_text(encoding="utf-8", errors="replace").splitlines():
+        try:
+            entry = json.loads(line)
+        except ValueError:
+            continue
+        when = _stamp(entry)
+        message = entry.get("message") or {}
+        if role is None and entry.get("type") == "user":
+            content = message.get("content")
+            text = (
+                content
+                if isinstance(content, str)
+                else "".join(b.get("text", "") for b in content or [] if isinstance(b, dict))
+            )
+            found = ROLE.search(text)
+            role = found.group(1) if found else "agent"
+        if since and when and when < since:
+            continue
+        if entry.get("type") == "assistant" and message.get("usage"):
+            calls[message.get("id") or entry.get("uuid")] = message["usage"]
+            model = message.get("model") or model
+    return calls, model, role
+
+
+def _price(calls, model):
+    usage: dict[str, float | None] = {
+        "calls": len(calls),
+        "input": 0,
+        "output": 0,
+        "cache_read": 0,
+        "cache_write_5m": 0,
+        "cache_write_1h": 0,
+    }
+    tokens: dict[str, int] = dict.fromkeys(("input", "output", "cache_read", "cache_write_5m", "cache_write_1h"), 0)
+    for u in calls.values():
+        tokens["input"] += u.get("input_tokens", 0)
+        tokens["output"] += u.get("output_tokens", 0)
+        tokens["cache_read"] += u.get("cache_read_input_tokens", 0)
+        split = u.get("cache_creation") or {}
+        tokens["cache_write_1h"] += split.get("ephemeral_1h_input_tokens", 0)
+        tokens["cache_write_5m"] += (
+            split.get("ephemeral_5m_input_tokens", 0) if split else u.get("cache_creation_input_tokens", 0)
+        )
+    for key, value in tokens.items():
+        usage[key] = value
+    rates = PRICES.get(model or "")
+    usage["usd"] = round(sum(tokens[k] * r for k, r in zip(tokens, rates, strict=True)) / 1e6, 4) if rates else None
+    return usage
+
+
+def report(session, project_dir, since=None, claude_home=None):
+    """Usage per role since a time (ISO), for the session and its agents."""
+    home = Path(claude_home) if claude_home else Path.home() / ".claude"
+    base = home / "projects" / project_folder(project_dir)
+    start = datetime.fromisoformat(since.replace("Z", "+00:00")) if since else None
+    rows = []
+    main = base / f"{session}.jsonl"
+    if main.is_file():
+        calls, model, _ = _usage(main, start)
+        rows.append({"role": "coordinator", "model": model} | _price(calls, model))
+    for path in sorted((base / str(session) / "subagents").glob("agent-*.jsonl")):
+        calls, model, role = _usage(path, start)
+        if calls:
+            rows.append({"role": role, "model": model, "agent": path.stem} | _price(calls, model))
+    totals = {
+        "usd": round(sum(r["usd"] or 0 for r in rows), 4),
+        "unpriced_models": sorted({r["model"] for r in rows if r["usd"] is None and r["model"]}),
+        "tokens": sum(
+            r["input"] + r["output"] + r["cache_read"] + r["cache_write_5m"] + r["cache_write_1h"] for r in rows
+        ),
+    }
+    by_role = {}
+    for r in rows:
+        entry = by_role.setdefault(r["role"], {"usd": 0.0, "calls": 0, "agents": 0})
+        entry["usd"] = round(entry["usd"] + (r["usd"] or 0), 4)
+        entry["calls"] += r["calls"]
+        entry["agents"] += 1
+    return {
+        "session": session,
+        "since": since,
+        "rows": rows,
+        "by_role": by_role,
+        "totals": totals,
+        "basis": "Anthropic list prices per million tokens; read from Claude Code transcripts (internal format, "
+        "best effort)",
+    }

simready_forge/examples/cabinet.py

@@ -0,0 +1,124 @@
+"""Worked example: a 400 mm oak bedside cabinet with a hinged door and a drawer on runners.
+
+    simready-forge example --show            print this file
+    simready-forge example --build <dir>     build it, export it and validate it
+
+The pattern every build script follows: real dimensions, build123d shapes in the assembled pose, one body per moving
+part, materials with their physics values, joints with limits, then save() and validate().
+"""
+
+import numpy as np
+from build123d import Box, Cylinder, Pos, Rot
+
+from simready_forge import Asset, validate
+
+W, D, H, T = 400, 350, 500, 18  # mm: width (X), depth (Y, front at -Y), height (Z), board thickness
+
+
+def board(x0, x1, y0, y1, z0, z1):
+    return Pos((x0 + x1) / 2, (y0 + y1) / 2, (z0 + z1) / 2) * Box(x1 - x0, y1 - y0, z1 - z0)
+
+
+def knob(x, z):
+    """A round knob on the front face, sticking out toward -Y."""
+    return Pos(x, -D / 2 - T, z) * Rot(90, 0, 0) * (Pos(0, 0, 6) * Cylinder(5, 12) + Pos(0, 0, 16) * Cylinder(12, 8))
+
+
+def wood_texture(size=512, seed=3):
+    """Oak grain along the image's width, tileable both ways: integer frequencies only, so it repeats without seams."""
+    rng = np.random.default_rng(seed)
+    u, v = np.meshgrid(np.arange(size) / size, np.arange(size) / size)
+
+    def wave(amplitude, fu, fv):  # integer frequencies, so every term repeats across the tile
+        return amplitude * np.sin(2 * np.pi * (fu * u + fv * v) + rng.uniform(0, 2 * np.pi))
+
+    # rings: their spacing varies down the board (a third to twice the mean) and they wander gently along it
+    spacing = sum(wave(a, 0, k) / (2 * np.pi * k) for a, k in ((5.0, 1), (3.0, 2), (2.0, 3)))
+    wander = sum(wave(rng.uniform(0.04, 0.1), fu, fv) for fu, fv in ((1, 0), (1, 1), (2, -1), (1, 2), (3, 1)))
+    phase = (12 * v + spacing + wander) % 1.0
+    strength = 0.6 + 0.4 * (0.5 + 0.5 * (wave(1, 0, 5) + wave(1, 0, 7)) / 2)  # some late-wood lines darker
+    late = strength * np.exp(-((np.minimum(phase, 1 - phase) / 0.06) ** 2))
+    # long streaks: noise blurred along the grain by a Gaussian that wraps round, so the edges still meet
+    distance = np.minimum(np.arange(size), size - np.arange(size))
+    kernel = np.fft.fft(np.exp(-0.5 * (distance / 24.0) ** 2))
+    streaks = np.real(np.fft.ifft(np.fft.fft(rng.normal(0, 1, (size, size)), axis=1) * kernel, axis=1))
+    streaks /= streaks.std()
+    g = np.clip(0.72 - 0.38 * late + 0.07 * streaks + 0.03 * rng.normal(0, 1, (size, size)), 0, 1)[..., None]
+    return (np.array([120, 78, 44]) * (1 - g) + np.array([196, 150, 102]) * g).astype(np.uint8)
+
+
+def build(out_dir="simready_assets", formats=("usd", "urdf", "glb")):
+    asset = Asset(
+        "bedside_cabinet",
+        out_dir,
+        label="nightstand",
+        qcode="Q667999",
+        units="mm",
+        category="furniture",
+        description="400 mm oak bedside cabinet: a drawer on runners above a hinged door, steel knobs",
+    )
+    oak = asset.material(
+        "oak",
+        texture=wood_texture(),
+        uv_scale=3.0,
+        lengthwise=True,
+        roughness=0.55,
+        friction=(0.5, 0.4),
+        restitution=0.1,
+        density=700,
+        label="wood",
+        nonvisual=("wood", "clearcoat"),
+    )
+    steel = asset.material(
+        "brushed_steel",
+        color=(0.75, 0.75, 0.77),
+        metallic=1.0,
+        roughness=0.35,
+        friction=(0.4, 0.3),
+        restitution=0.2,
+        density=7850,
+        label="steel",
+        nonvisual=("steel", "none"),
+    )
+
+    # everything that does not move is one body
+    carcass = asset.body("carcass", label="cabinet body")
+    panels = {
+        "left": (-W / 2, -W / 2 + T, -D / 2, D / 2, 0, H),
+        "right": (W / 2 - T, W / 2, -D / 2, D / 2, 0, H),
+        "top": (-W / 2, W / 2, -D / 2, D / 2, H - T, H),
+        "bottom": (-W / 2 + T, W / 2 - T, -D / 2, D / 2, 40, 40 + T),
+        "shelf": (-W / 2 + T, W / 2 - T, -D / 2, D / 2, 330, 330 + T),
+        "back": (-W / 2 + T, W / 2 - T, D / 2 - 8, D / 2, 40, H - T),
+    }
+    for name, dims in panels.items():
+        asset.add(carcass, name, board(*dims), oak, collider="box")
+
+    # the door under the shelf, hinged on its left edge: it opens outward with negative angles about +Z
+    door = asset.body("door")
+    asset.add(
+        door,
+        "panel",
+        board(-W / 2 + T + 1, W / 2 - T - 1, -D / 2 - T, -D / 2, 40 + T + 1, 330 - 1),
+        oak,
+        collider="box",
+    )
+    asset.add(door, "knob", knob(W / 2 - T - 40, 200), steel)
+    asset.revolute("door_hinge", carcass, door, anchor=(-W / 2 + T, -D / 2 - T / 2, 200), axis="Z", limits=(-110, 0))
+
+    # the drawer above the shelf, pulling out toward -Y
+    drawer = asset.body("drawer")
+    z0, z1, x0, x1 = 330 + T + 2, H - T - 2, -W / 2 + T + 2, W / 2 - T - 2
+    sides = {
+        "front": (x0, x1, -D / 2 - T, -D / 2, z0, z1),
+        "floor": (x0, x1, -D / 2, D / 2 - 30, z0, z0 + 8),
+        "side_l": (x0, x0 + 12, -D / 2, D / 2 - 30, z0 + 8, z1 - 20),
+        "side_r": (x1 - 12, x1, -D / 2, D / 2 - 30, z0 + 8, z1 - 20),
+        "rear": (x0, x1, D / 2 - 42, D / 2 - 30, z0 + 8, z1 - 20),
+    }
+    for name, dims in sides.items():
+        asset.add(drawer, name, board(*dims), oak, collider="box")
+    asset.add(drawer, "knob", knob(0, (z0 + z1) / 2), steel)
+    asset.prismatic("drawer_slide", carcass, drawer, anchor=(0, 0, (z0 + z1) / 2), axis="Y", limits=(-250, 0))
+
+    return validate(asset.save(formats=formats))

simready_forge/export.py

@@ -0,0 +1,170 @@
+"""Exports of a saved asset: URDF (links, inertia, joints, OBJ visuals, STL hull colliders) and GLB (PBR)."""
+
+import math
+import shutil
+from pathlib import Path
+from typing import cast
+from xml.sax.saxutils import quoteattr
+
+import numpy as np
+
+INERTIA = (("ixx", 0, 0), ("ixy", 0, 1), ("ixz", 0, 2), ("iyy", 1, 1), ("iyz", 1, 2), ("izz", 2, 2))
+AXIS_VECTORS = {"X": "1 0 0", "Y": "0 1 0", "Z": "0 0 1"}
+
+
+def _fmt(values):
+    return " ".join(f"{float(v):.9g}" for v in values)
+
+
+def _damping(joint):
+    """URDF damping is per radian for a hinge (N*m*s/rad); the kit's, like UsdPhysics', is per degree."""
+    damping = joint["drive"]["damping"]
+    return damping * math.degrees(1.0) if joint["kind"] == "revolute" else damping
+
+
+def trees(model):
+    """The joint trees: [(root body, [(joint, parent, child), ...])]. A body with no joints is a tree of its own."""
+    children = {j["body1"].name for j in model["joints"]}
+    out = []
+    for root in [b["name"] for b in model["bodies"] if b["name"] not in children]:
+        edges, frontier = [], [root]
+        while frontier:
+            parent = frontier.pop(0)
+            for j in model["joints"]:
+                if j["body0"].name == parent:
+                    edges.append((j, parent, j["body1"].name))
+                    frontier.append(j["body1"].name)
+        out.append((root, edges))
+    return out
+
+
+def inertia(body):
+    """The body's centre of mass and inertia tensor about it, from its collider hulls scaled to its mass."""
+    import trimesh
+
+    hulls = [trimesh.Trimesh(v, f) for part in body["parts"] for v, f in part["hulls"]]
+    if not hulls:
+        hulls = [trimesh.Trimesh(part["points"], part["tris"]).convex_hull for part in body["parts"]]
+    merged = cast(trimesh.Trimesh, trimesh.util.concatenate(hulls))
+    if merged.volume <= 0:
+        merged = merged.convex_hull
+    merged.density = body["mass"] / merged.volume
+    return np.asarray(merged.center_mass), np.asarray(merged.moment_inertia)
+
+
+def urdf(model, folder, warnings):
+    """One URDF per joint tree; a link's frame sits at the anchor of the joint that carries it, as URDF expects."""
+    import trimesh
+
+    folder = Path(folder)
+    if folder.exists():
+        shutil.rmtree(folder)
+    (folder / "meshes").mkdir(parents=True)
+    bodies = {b["name"]: b for b in model["bodies"]}
+    forest = trees(model)
+    if len(forest) > 1:
+        warnings.append(f"URDF: {len(forest)} separate trees (loose bodies) written as {len(forest)} files")
+    files = []
+    for index, (root, edges) in enumerate(forest):
+        name = model["name"] if len(forest) == 1 else f"{model['name']}_{index}"
+        frame = {root: bodies[root]["origin"]}
+        for j, _, child in edges:
+            frame[child] = j["anchor"]
+        lines = [f"<robot name={quoteattr(name)}>"]
+        for link in [root] + [child for _, _, child in edges]:
+            body = bodies[link]
+            shift = body["origin"] - frame[link]  # body-local points -> link frame
+            com, tensor = inertia(body)
+            lines += [
+                f"  <link name={quoteattr(link)}>",
+                "    <inertial>",
+                f'      <origin xyz="{_fmt(com + shift)}" rpy="0 0 0"/>',
+                f'      <mass value="{body["mass"]:.6g}"/>',
+                "      <inertia " + " ".join(f'{k}="{tensor[i, j]:.9g}"' for k, i, j in INERTIA) + "/>",
+                "    </inertial>",
+            ]
+            for part in body["parts"]:
+                m = part["material"]
+                if part.get("visible", True):  # an invisible part is a collider only
+                    obj = folder / "meshes" / f"{link}_{part['name']}.obj"
+                    trimesh.Trimesh(part["points"] + shift, part["tris"], process=False).export(obj)
+                    rgba = (*[float(c) for c in m.color[:3]], float(m.opacity))
+                    lines += [
+                        "    <visual>",
+                        f'      <geometry><mesh filename="meshes/{obj.name}"/></geometry>',
+                        f'      <material name={quoteattr(m.name)}><color rgba="{_fmt(rgba)}"/></material>',
+                        "    </visual>",
+                    ]
+                for k, (v, f) in enumerate(part["hulls"]):
+                    stl = folder / "meshes" / f"{link}_{part['name']}_collider{k}.stl"
+                    trimesh.Trimesh(v + shift, f, process=False).export(stl)
+                    lines.append(
+                        f'    <collision><geometry><mesh filename="meshes/{stl.name}"/></geometry></collision>'
+                    )
+            lines.append("  </link>")
+        for j, parent, child in edges:
+            lo, hi = j["limits"]
+            if j["kind"] == "revolute":
+                lo, hi = math.radians(lo), math.radians(hi)
+            free = not (math.isfinite(lo) and math.isfinite(hi))  # a free spin is URDF's continuous joint
+            limit = (
+                '    <limit effort="100" velocity="2"/>'
+                if free
+                else (f'    <limit lower="{lo:.9g}" upper="{hi:.9g}" effort="100" velocity="2"/>')
+            )
+            lines += [
+                f'  <joint name={quoteattr(j["name"])} type="{"continuous" if free else j["kind"]}">',
+                f"    <parent link={quoteattr(parent)}/>",
+                f"    <child link={quoteattr(child)}/>",
+                f'    <origin xyz="{_fmt(j["anchor"] - frame[parent])}" rpy="0 0 0"/>',
+                f'    <axis xyz="{AXIS_VECTORS[j["axis"]]}"/>',
+                limit,
+                f'    <dynamics damping="{_damping(j):.6g}" friction="0"/>',
+                "  </joint>",
+            ]
+        lines.append("</robot>")
+        path = folder / f"{name}.urdf"
+        path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+        files.append(path)
+    return files
+
+
+def glb(model, path):
+    """A GLB of the rest pose with PBR materials: base colour textures where the material has one."""
+    import trimesh
+    from PIL import Image
+    from trimesh.visual import TextureVisuals
+    from trimesh.visual.material import PBRMaterial
+
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    scene = trimesh.Scene()
+    materials = {}
+    for body in model["bodies"]:
+        for part in [p for p in body["parts"] if p.get("visible", True)]:
+            m = part["material"]
+            if m.name not in materials:
+                image = Image.open(m.files["base_color"]).convert("RGB") if "base_color" in m.files else None
+                factor = (
+                    None if image is not None else [*(np.array(m.color[:3]) * 255).astype(int), int(255 * m.opacity)]
+                )
+                materials[m.name] = PBRMaterial(
+                    name=m.name,
+                    baseColorFactor=factor,
+                    baseColorTexture=image,
+                    metallicFactor=float(m.metallic),
+                    roughnessFactor=float(m.roughness),
+                    alphaMode="BLEND" if m.opacity < 1 else "OPAQUE",
+                )
+            # one vertex per triangle corner, so the face-varying UVs survive as glTF vertex UVs
+            corners = (part["points"] + body["origin"])[part["tris"]].reshape(-1, 3)
+            faces = np.arange(len(corners)).reshape(-1, 3)
+            visual = TextureVisuals(uv=np.asarray(part["uv"]), material=materials[m.name])
+            mesh = trimesh.Trimesh(corners, faces, visual=visual, process=False)
+            scene.add_geometry(
+                mesh, node_name=f"{body['name']}/{part['name']}", geom_name=f"{body['name']}_{part['name']}"
+            )
+    # glTF is Y-up: turn the Z-up asset so viewers show it standing
+    scene.apply_transform(trimesh.transformations.rotation_matrix(-math.pi / 2, [1, 0, 0]))
+    scene.export(path)
+    return path