simready-forge 0.1.0__py3-none-any.whl

simready_forge/poses.py

@@ -0,0 +1,293 @@
+"""The review's joint poses without Isaac Sim: put a USD asset in the poses the Isaac review drives it to (every joint
+at 80 % of the far side of its range, then every two-sided joint at 80 % of the other side), and report where
+colliders of bodies that are not jointed to each other overlap, and how low the asset reaches (the ground is z = 0).
+
+Collision shapes are taken as the convex hull of each collider mesh, as PhysX takes a convexHull approximation; an
+overlap is the least push along a face normal of either hull that separates two hulls (edge-to-edge contacts are not
+tested, so a few overlaps reported may be near misses). Good enough to catch an arm's head in the desk or a lid
+swung into its box before a review.
+"""
+
+import json
+import math
+from pathlib import Path
+
+import numpy as np
+from pxr import Usd, UsdGeom, UsdPhysics
+from scipy.spatial import ConvexHull, QhullError
+
+AXIS = {"X": 0, "Y": 1, "Z": 2}
+TOLERANCE = 0.001  # m: overlaps and dips below the ground smaller than this are contact, not a fault
+EMPTY = 0.02  # an opening counts as open when colliders fill at most 2 % of its box
+NEAR = 0.002  # m: bodies closer than this at rest touch through PhysX's contact offset and prop each other up
+SWEEP = 0.003  # m: how much deeper than at rest two jointed bodies may sit (hinge knuckles interleave at rest)
+
+
+def _quat(q):
+    """A Gf quaternion as a 3x3 rotation acting on column vectors."""
+    w, (x, y, z) = q.GetReal(), q.GetImaginary()
+    return np.array(
+        [
+            [1 - 2 * (y * y + z * z), 2 * (x * y - w * z), 2 * (x * z + w * y)],
+            [2 * (x * y + w * z), 1 - 2 * (x * x + z * z), 2 * (y * z - w * x)],
+            [2 * (x * z - w * y), 2 * (y * z + w * x), 1 - 2 * (x * x + y * y)],
+        ]
+    )
+
+
+def _world(cache, prim):
+    """A prim's world rotation (column vectors) and translation, in metres."""
+    m = np.array(cache.GetLocalToWorldTransform(prim))  # row vectors: p_world = p @ m[:3, :3] + m[3, :3]
+    return m[:3, :3].T, m[3, :3]
+
+
+def _rotation(axis, degrees):
+    """Rodrigues: a rotation of `degrees` about the unit `axis`."""
+    a = axis / np.linalg.norm(axis)
+    k = np.array([[0, -a[2], a[1]], [a[2], 0, -a[0]], [-a[1], a[0], 0]])
+    t = math.radians(degrees)
+    return np.eye(3) + math.sin(t) * k + (1 - math.cos(t)) * k @ k
+
+
+class Joint:
+    """A revolute or prismatic joint read from the stage: its bodies, world anchor and axis at rest, its position at
+    rest in its own coordinate, and the review's targets."""
+
+    def __init__(self, prim, cache):
+        joint = UsdPhysics.Joint(prim)
+        self.name = prim.GetName()
+        self.revolute = prim.IsA("PhysicsRevoluteJoint")
+        b0, b1 = joint.GetBody0Rel().GetTargets(), joint.GetBody1Rel().GetTargets()
+        self.body0, self.body1 = (str(b0[0]) if b0 else None), str(b1[0])
+        stage = prim.GetStage()
+        r0, t0 = _world(cache, stage.GetPrimAtPath(self.body0)) if self.body0 else (np.eye(3), np.zeros(3))
+        r1, t1 = _world(cache, stage.GetPrimAtPath(self.body1))
+        rot0, rot1 = joint.GetLocalRot0Attr().Get(), joint.GetLocalRot1Attr().Get()
+        frame0 = r0 @ (_quat(rot0) if rot0 is not None else np.eye(3))
+        frame1 = r1 @ (_quat(rot1) if rot1 is not None else np.eye(3))
+        pos0 = np.array(joint.GetLocalPos0Attr().Get() or (0, 0, 0), dtype=float)
+        pos1 = np.array(joint.GetLocalPos1Attr().Get() or (0, 0, 0), dtype=float)
+        index = AXIS[prim.GetAttribute("physics:axis").Get()]
+        self.anchor = r0 @ pos0 + t0
+        self.axis = frame0[:, index]
+        relative = frame0.T @ frame1
+        if self.revolute:  # the rest position: frame 1's turn about the axis from frame 0 (a lamp can rest at -37)
+            angle = math.degrees(math.acos(max(-1.0, min(1.0, (np.trace(relative) - 1) / 2))))
+            w = np.array(
+                [relative[2, 1] - relative[1, 2], relative[0, 2] - relative[2, 0], relative[1, 0] - relative[0, 1]]
+            )
+            self.rest = angle if w[index] >= 0 else -angle
+        else:
+            self.rest = float(frame0[:, index] @ ((r1 @ pos1 + t1) - self.anchor))
+        lo, hi = prim.GetAttribute("physics:lowerLimit").Get(), prim.GetAttribute("physics:upperLimit").Get()
+        lo = -math.inf if lo is None else lo
+        hi = math.inf if hi is None else hi
+        free = not (math.isfinite(lo) and math.isfinite(hi)) or max(abs(lo), abs(hi)) > 1e6
+        if free and not self.revolute:
+            self.sides = []  # the review leaves an unlimited slide alone
+            return
+        if free:
+            lo, hi = -90.0, 90.0
+        far, near = (lo, hi) if abs(lo) > abs(hi) else (hi, lo)
+        self.sides = [0.8 * far] + ([0.8 * near] if abs(near) > 0.1 * (hi - lo) else [])
+
+    def motion(self, rotation, translation, target):
+        """The joint's move to `target` once its parent has moved by (rotation, translation), as a rigid transform."""
+        anchor, axis = rotation @ self.anchor + translation, rotation @ self.axis
+        travel = target - self.rest
+        if self.revolute:
+            turn = _rotation(axis, travel)
+            return turn, anchor - turn @ anchor
+        return np.eye(3), axis / np.linalg.norm(axis) * travel
+
+
+def _colliders(stage, cache):
+    """Every collider mesh as (body path, collider name, its points in world stage units at rest)."""
+    found = []
+    for prim in stage.Traverse():
+        if not prim.HasAPI("PhysicsRigidBodyAPI"):
+            continue
+        for child in Usd.PrimRange(prim):
+            if child != prim and child.HasAPI("PhysicsRigidBodyAPI"):
+                continue
+            if child.HasAPI("PhysicsCollisionAPI") and child.IsA("Mesh"):
+                points = np.array(UsdGeom.Mesh(child).GetPointsAttr().Get() or [], dtype=float)
+                if len(points) >= 4:
+                    m = np.array(cache.GetLocalToWorldTransform(child))
+                    found.append((str(prim.GetPath()), child.GetName(), points @ m[:3, :3] + m[3, :3]))
+    return found
+
+
+def _hulls(stage, cache):
+    """Each rigid body's collider hulls, in world stage units at rest."""
+    bodies = {str(p.GetPath()): [] for p in stage.Traverse() if p.HasAPI("PhysicsRigidBodyAPI")}
+    for body, _, points in _colliders(stage, cache):
+        bodies[body].append(points)
+    return bodies
+
+
+def _empty(colliders, box, samples=14):
+    """How much of a box that should stay empty (an opening, a cup's inside) the colliders fill, and which ones."""
+    lo, hi = np.asarray(box[:3], dtype=float), np.asarray(box[3:], dtype=float)
+    axes = [np.linspace(lo[i], hi[i], samples) for i in range(3)]
+    points = np.stack(np.meshgrid(*axes, indexing="ij"), axis=-1).reshape(-1, 3)
+    filled = np.zeros(len(points), bool)
+    by = {}
+    for _, name, hull in colliders:
+        if np.any(hull.max(0) < lo) or np.any(hull.min(0) > hi):
+            continue
+        try:
+            equations = ConvexHull(hull).equations
+        except QhullError:
+            continue
+        inside = np.all(points @ equations[:, :3].T + equations[:, 3] <= 0, axis=1)
+        if inside.any():
+            by[name] = round(float(inside.mean()), 3)
+            filled |= inside
+    worst = sorted(by.items(), key=lambda kv: -kv[1])[:5]
+    return {"filled": round(float(filled.mean()), 3), "by": [{"collider": k, "share": v} for k, v in worst]}
+
+
+def _normals(hull):
+    try:
+        return ConvexHull(hull).equations[:, :3]
+    except QhullError:  # flat or degenerate: no volume to sink into
+        return np.zeros((0, 3))
+
+
+def _depth(a, b):
+    """How far two convex hulls sit in each other: the least overlap of their shadows along any face normal of
+    either (the separating-axis test over face normals); negative, the gap, when some face separates them."""
+    normals = np.vstack([_normals(a), _normals(b)])
+    if not len(normals):
+        return -math.inf
+    pa, pb = a @ normals.T, b @ normals.T
+    overlap = np.minimum(pa.max(0), pb.max(0)) - np.maximum(pa.min(0), pb.min(0))
+    return float(overlap.min())
+
+
+def _depths(moved, margin=0.0):
+    """How deep each pair of bodies' hulls sit in each other (negative: the gap), for every pair whose boxes come
+    within `margin`."""
+    found = {}
+    names = sorted(moved)
+    for i, a in enumerate(names):
+        for b in names[i + 1 :]:
+            depth = -math.inf
+            for ha in moved[a]:
+                for hb in moved[b]:
+                    lo, hi = np.maximum(ha.min(0), hb.min(0)), np.minimum(ha.max(0), hb.max(0))
+                    if np.all(lo <= hi + margin):
+                        depth = max(depth, _depth(ha, hb))
+            if depth > -margin:
+                found[frozenset((a, b))] = depth
+    return found
+
+
+def _overlaps(depths, rest, jointed, tolerance, sweep, scale):
+    """Bodies not jointed to each other that overlap; jointed ones that sit deeper in each other than at rest. PhysX
+    does not collide jointed bodies, so a lid whose limits swing it into its box goes straight through."""
+    found = []
+    for pair, depth in sorted(depths.items(), key=lambda kv: sorted(kv[0])):
+        joined = pair in jointed
+        if (depth - max(rest.get(pair, 0.0), 0.0) > sweep) if joined else (depth > tolerance):
+            entry = {"bodies": sorted(b.rsplit("/", 1)[-1] for b in pair), "depth_mm": round(depth * scale * 1000, 1)}
+            found.append({**entry, "jointed": True} if joined else entry)
+    return found
+
+
+def poses(path, empty=(), chosen=None):
+    """The asset in its rest pose and the review's two combined poses: overlaps and the lowest point of each."""
+    stage = Usd.Stage.Open(str(path))
+    scale = UsdGeom.GetStageMetersPerUnit(stage)
+    cache = UsdGeom.XformCache()
+    tolerance, sweep = TOLERANCE / scale, SWEEP / scale  # everything below is in stage units; the report in mm
+    hulls = _hulls(stage, cache)
+    joints = [
+        Joint(p, cache) for p in stage.Traverse() if p.IsA("PhysicsRevoluteJoint") or p.IsA("PhysicsPrismaticJoint")
+    ]
+    jointed = {frozenset((j.body0, j.body1)) for j in joints if j.body0}
+    children = {}
+    for j in joints:
+        children.setdefault(j.body0, []).append(j)
+    roots = [b for b in hulls if b not in {j.body1 for j in joints}]
+
+    rest_depths = {}
+    rest_low = {b: min((float(h[:, 2].min()) for h in hs), default=math.inf) for b, hs in hulls.items()}
+    floor = min(rest_low.values(), default=0.0)
+    supports = [b for b, z in rest_low.items() if z <= floor + NEAR / scale]
+
+    def pose(targets):
+        moved = {b: (np.eye(3), np.zeros(3)) for b in hulls}
+        todo = list(roots) + ([None] if None in children else [])
+        while todo:
+            parent = todo.pop(0)
+            rotation, translation = moved.get(str(parent), (np.eye(3), np.zeros(3)))  # None: the world
+            for j in children.get(parent, []):
+                target = targets.get(j.name, j.rest)
+                turn, shift = j.motion(rotation, translation, target)
+                moved[j.body1] = (turn @ rotation, turn @ translation + shift)
+                todo.append(j.body1)
+        placed = {b: [h @ moved[b][0].T + moved[b][1] for h in hs] for b, hs in hulls.items()}
+
+        def low(bodies):
+            return min((float(h[:, 2].min()) for b in bodies for h in placed[b]), default=math.inf)
+
+        # a body that stands on the ground at rest is a support: folding it lowers the stance, and the asset settles
+        # onto it; anything else going below the ground (an arm's head into the desk) is a fault
+        free_low, stance_low = low([b for b in placed if b not in supports]), low(supports)
+        lowest = min(free_low, stance_low) if math.isfinite(min(free_low, stance_low)) else 0.0
+        found = {
+            "targets": {k: round(v, 4) for k, v in targets.items()},
+            "overlaps": _overlaps(
+                _depths(placed) if targets else rest_depths, rest_depths, jointed, tolerance, sweep, scale
+            ),
+            "lowest_mm": round(lowest * scale * 1000, 1),
+            "below_ground": bool(math.isfinite(free_low) and free_low < -tolerance),
+        }
+        if math.isfinite(stance_low) and stance_low < -tolerance:
+            found["stance_lowered_mm"] = round(-stance_low * scale * 1000, 1)  # supports folded under: expected
+        return found
+
+    near = NEAR / scale
+    rest_depths.update(_depths({b: hulls[b] for b in hulls}, margin=near))
+    far = {j.name: j.sides[0] for j in joints if j.sides}
+    other = {**far, **{j.name: j.sides[1] for j in joints if len(j.sides) > 1}}
+    report = {"asset": str(path), "rest": pose({}), "far": pose(far)}
+    if other != far:
+        report["other_side"] = pose(other)
+    singles = [(j.name, side) for j in joints for side in j.sides]  # each joint alone: a chain's own working poses
+    checked = [{"joint": name, **pose({name: side})} for name, side in singles]
+    report["single"] = [p for p in checked if p["overlaps"] or p["below_ground"]]
+    report["single_checked"] = len(singles)
+    report["near_at_rest"] = [
+        {"bodies": sorted(b.rsplit("/", 1)[-1] for b in pair), "gap_mm": round(-depth * scale * 1000, 2)}
+        for pair, depth in sorted(rest_depths.items(), key=lambda kv: sorted(kv[0]))
+        if pair not in jointed and -near + 1e-5 / scale < depth <= tolerance  # 2 mm itself is far enough
+    ]
+    every = [p for p in report.values() if isinstance(p, dict)] + report["single"]
+    report["clear"] = all(not p["overlaps"] and not p["below_ground"] for p in every)
+    if chosen:  # joint targets the builder picks: degrees for a hinge, mm for a slide
+        by_name = {j.name: j for j in joints}
+        unknown = sorted(set(chosen) - set(by_name))
+        if unknown:
+            raise ValueError(f"no joint named {unknown}; the joints are {sorted(by_name)}")
+        targets = {k: v if by_name[k].revolute else v * 0.001 / scale for k, v in chosen.items()}
+        report["chosen"] = pose(targets)
+        report["clear"] = report["clear"] and not report["chosen"]["overlaps"] and not report["chosen"]["below_ground"]
+    if empty:  # boxes in mm that should stay empty at rest: openings, cavities
+        colliders = _colliders(stage, cache)
+        to_stage = 0.001 / scale
+        report["empty"] = [{"box_mm": list(b), **_empty(colliders, [x * to_stage for x in b])} for b in empty]
+        report["clear"] = report["clear"] and all(e["filled"] <= EMPTY for e in report["empty"])
+    return report
+
+
+def main(path, out=None, empty=(), chosen=None):
+    report = poses(path, empty, chosen)
+    text = json.dumps(report, indent=1)
+    if out:
+        Path(out).parent.mkdir(parents=True, exist_ok=True)
+        Path(out).write_text(text, encoding="utf-8")
+    print(text)
+    return 0 if report["clear"] else 1

simready_forge/prefs.py

@@ -0,0 +1,105 @@
+"""Remembered choices: the plugin's intake asks once and remembers for a session, a project or always.
+
+The file is preferences.json in the plugin's data folder (the make skill passes ${CLAUDE_PLUGIN_DATA}), else
+~/.simready-forge. A session's or a project's value wins over the always value, which wins over the defaults.
+"""
+
+import json
+from pathlib import Path
+
+DEFAULTS = {
+    "mode": "standard",  # quick | standard | max
+    "builder_model": "sonnet",  # sonnet | opus | haiku | fable | inherit
+    "builder_effort": "inherit",  # low | medium | high | xhigh | max | inherit
+    "critic_model": "opus",
+    "critics": "auto",  # none | <rounds> | auto
+    "max_rounds": 4,
+    "geometry": "auto",  # auto | cad | mesh | hybrid
+    "trellis_effort": "medium",  # low | medium | high
+    "formats": ["usd", "urdf", "glb"],
+    "articulation": "all",  # all | main | static
+    "materials": "textured",  # flat | textured | photo
+    "license": "Proprietary",
+    "out_dir": "simready_assets",
+    "isaac_python": None,
+    "comfyui_url": "http://127.0.0.1:8188",
+}
+SCOPES = ("session", "project", "always")
+
+
+def _file(data_dir=None):
+    folder = Path(data_dir) if data_dir else Path.home() / ".simready-forge"
+    folder.mkdir(parents=True, exist_ok=True)
+    return folder / "preferences.json"
+
+
+def _load(data_dir=None):
+    path = _file(data_dir)
+    return (
+        json.loads(path.read_text(encoding="utf-8")) if path.is_file() else {"always": {}, "project": {}, "session": {}}
+    )
+
+
+def resolve(data_dir=None, session=None, project=None):
+    """The effective choices, and where each came from."""
+    store = _load(data_dir)
+    values, source = dict(DEFAULTS), dict.fromkeys(DEFAULTS, "default")
+    layers = [
+        ("always", store.get("always", {})),
+        ("project", store.get("project", {}).get(str(project), {})),
+        ("session", store.get("session", {}).get(str(session), {})),
+    ]
+    for scope, layer in layers:
+        for key, value in layer.items():
+            values[key], source[key] = value, scope
+    return values, source
+
+
+def remembered(data_dir=None, session=None, project=None):
+    """True when anything beyond the defaults applies to this session or project (the intake can be skipped)."""
+    _, source = resolve(data_dir, session, project)
+    return any(scope != "default" for scope in source.values())
+
+
+def set_values(values, scope, data_dir=None, session=None, project=None):
+    if scope not in SCOPES:
+        raise ValueError(f"scope must be one of {SCOPES}")
+    unknown = set(values) - set(DEFAULTS)
+    if unknown:
+        raise ValueError(f"unknown preferences {sorted(unknown)}; known: {sorted(DEFAULTS)}")
+    store = _load(data_dir)
+    if scope == "always":
+        store.setdefault("always", {}).update(values)
+    else:
+        key = str(session if scope == "session" else project)
+        if key == "None":
+            raise ValueError(f"scope {scope} needs --{scope}")
+        store.setdefault(scope, {}).setdefault(key, {}).update(values)
+    _file(data_dir).write_text(json.dumps(store, indent=1), encoding="utf-8")
+
+
+def reset(scope, data_dir=None, session=None, project=None):
+    store = _load(data_dir)
+    if scope == "always":
+        store["always"] = {}
+    else:
+        store.get(scope, {}).pop(str(session if scope == "session" else project), None)
+    _file(data_dir).write_text(json.dumps(store, indent=1), encoding="utf-8")
+
+
+def parse(pairs):
+    """key=value strings into typed values: numbers, true/false/none, and comma lists for formats."""
+    out = {}
+    for pair in pairs:
+        key, _, raw = pair.partition("=")
+        value: object = raw
+        if raw.lower() in ("none", "null"):
+            value = None
+        elif raw.lower() in ("true", "false"):
+            value = raw.lower() == "true"
+        elif raw.isdigit():
+            value = int(raw)
+        elif key == "formats":
+            value = [f.strip() for f in raw.split(",") if f.strip()]
+        out[key.strip()] = value
+    return out

simready_forge/preview.py

@@ -0,0 +1,74 @@
+"""Software previews (matplotlib, no GPU): the package thumbnail and a multi-view sheet when Isaac Sim is absent."""
+
+import io
+from typing import TYPE_CHECKING, cast
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from mpl_toolkits.mplot3d import Axes3D
+
+LIGHT = np.array([0.35, -0.55, 0.75]) / np.linalg.norm([0.35, -0.55, 0.75])
+
+
+def _polys(meshes, cap=80000):
+    polys, colours = [], []
+    for points, tris, rgb, opacity in meshes:
+        corners = points[tris]
+        normal = np.cross(corners[:, 1] - corners[:, 0], corners[:, 2] - corners[:, 0])
+        normal /= np.linalg.norm(normal, axis=1, keepdims=True) + 1e-12
+        shade = 0.3 + 0.7 * np.clip(normal @ LIGHT, 0, 1)
+        rgba = np.empty((len(tris), 4))
+        rgba[:, :3] = np.clip(np.array(rgb)[None, :3] * shade[:, None], 0, 1)
+        rgba[:, 3] = max(opacity, 0.35)
+        polys.append(corners)
+        colours.append(rgba)
+    polys, colours = np.concatenate(polys), np.concatenate(colours)
+    if len(polys) > cap:  # keep previews fast on dense scans
+        pick = np.random.default_rng(0).choice(len(polys), cap, replace=False)
+        polys, colours = polys[pick], colours[pick]
+    return polys, colours
+
+
+def _render(polys, colours, elevation, azimuth, pixels):
+    import matplotlib
+
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+    from mpl_toolkits.mplot3d.art3d import Poly3DCollection
+    from PIL import Image
+
+    lo, hi = polys.reshape(-1, 3).min(0), polys.reshape(-1, 3).max(0)
+    centre, half = (lo + hi) / 2, (hi - lo).max() / 2 * 0.82
+    fig = plt.figure(figsize=(4, 4), dpi=128)
+    ax = cast("Axes3D", fig.add_axes((0, 0, 1, 1), projection="3d"))
+    ax.set_axis_off()
+    ax.view_init(elev=elevation, azim=azimuth)
+    # edges in the face colour hide the seams matplotlib leaves between triangles
+    ax.add_collection3d(Poly3DCollection(polys, facecolors=colours, edgecolors=colours, linewidths=0.3))
+    for setter, c in zip((ax.set_xlim, ax.set_ylim, ax.set_zlim), centre, strict=True):
+        setter(c - half, c + half)
+    ax.set_box_aspect((1, 1, 1))
+    buffer = io.BytesIO()
+    fig.savefig(buffer, format="png", facecolor=(0.92, 0.92, 0.93))
+    plt.close(fig)
+    return Image.open(buffer).convert("RGB").resize((pixels, pixels), Image.Resampling.LANCZOS)
+
+
+def thumbnail(meshes, path, size=256):
+    """The package's 256x256 thumbnail. meshes = [(points, tris, rgb, opacity)]."""
+    polys, colours = _polys(meshes)
+    _render(polys, colours, 24, -58, size).save(path)
+
+
+def sheet(meshes, path):
+    """Front, three-quarter, side and top previews side by side, for a review without Isaac Sim."""
+    from PIL import Image
+
+    polys, colours = _polys(meshes)
+    views = [(8, -90), (24, -58), (8, 0), (75, -90)]
+    canvas = Image.new("RGB", (4 * 320, 320), (22, 24, 28))
+    for i, (elevation, azimuth) in enumerate(views):
+        canvas.paste(_render(polys, colours, elevation, azimuth, 320), (i * 320, 0))
+    canvas.save(path)
+    return path

simready_forge/readback.py

@@ -0,0 +1,177 @@
+"""What a USD asset holds, read from the stage itself: units, metadata, size, rigid bodies with their mass and
+colliders, joints with their frames, limits and drives, and materials with their visual, physics and sensor values.
+No mesh data: a claim about the asset can be checked against this instead of megabytes of points."""
+
+import json
+from pathlib import Path
+
+from pxr import Usd, UsdGeom, UsdPhysics, UsdShade
+
+DRIVES = ("angular", "linear", "transX", "transY", "transZ", "rotX", "rotY", "rotZ")
+SHADER_INPUTS = ("diffuseColor", "metallic", "roughness", "opacity", "ior", "emissiveColor")
+
+
+def _plain(value):
+    """A USD value as JSON: vectors and quaternions as lists, assets as paths, numbers rounded."""
+    if value is None:
+        return None
+    if isinstance(value, bool | int | str):
+        return value
+    if isinstance(value, float):
+        return round(value, 6)
+    if hasattr(value, "path"):  # Sdf.AssetPath
+        return value.path
+    if hasattr(value, "GetReal"):  # Gf.Quat
+        return [_plain(value.GetReal()), *[_plain(x) for x in value.GetImaginary()]]
+    try:
+        return [_plain(x) for x in value]
+    except TypeError:
+        return str(value)
+
+
+def _attributes(prim, names):
+    found = {}
+    for name in names:
+        attr = prim.GetAttribute(name)
+        if attr and attr.HasAuthoredValue():
+            found[name.split(":")[-1]] = _plain(attr.Get())
+    return found
+
+
+def _labels(prim):
+    return {a.GetName(): _plain(a.Get()) for a in prim.GetAttributes() if a.GetName().startswith("semantics:")}
+
+
+def _body(stage, prim, cache):
+    meshes, triangles, colliders = 0, 0, []
+    for child in Usd.PrimRange(prim):
+        if child != prim and child.HasAPI("PhysicsRigidBodyAPI"):
+            continue  # a nested body is listed on its own
+        if not child.IsA("Mesh"):
+            continue
+        counts = UsdGeom.Mesh(child).GetFaceVertexCountsAttr().Get() or []
+        if child.HasAPI("PhysicsCollisionAPI"):
+            approximation = UsdPhysics.MeshCollisionAPI(child).GetApproximationAttr().Get()
+            binding = UsdShade.MaterialBindingAPI(child).ComputeBoundMaterial("physics")[0]
+            colliders.append(
+                {
+                    "path": str(child.GetPath()),
+                    "approximation": approximation or "none",
+                    "points": len(UsdGeom.Mesh(child).GetPointsAttr().Get() or []),
+                    "purpose": UsdGeom.Imageable(child).ComputePurpose(),
+                    "physics_material": str(binding.GetPath()) if binding else None,
+                }
+            )
+        else:
+            meshes += 1
+            triangles += sum(max(0, int(c) - 2) for c in counts)
+    for child in Usd.PrimRange(prim):  # analytic colliders (cubes, spheres, capsules) count too
+        if child.HasAPI("PhysicsCollisionAPI") and not child.IsA("Mesh"):
+            colliders.append({"path": str(child.GetPath()), "approximation": child.GetTypeName()})
+    mass = UsdPhysics.MassAPI(prim)
+    world = cache.GetLocalToWorldTransform(prim).ExtractTranslation()
+    return {
+        "path": str(prim.GetPath()),
+        "mass": _plain(mass.GetMassAttr().Get()) if prim.HasAPI("PhysicsMassAPI") else None,
+        "density": _plain(mass.GetDensityAttr().Get()) if prim.HasAPI("PhysicsMassAPI") else None,
+        "centre_of_mass": _attributes(prim, ["physics:centerOfMass"]).get("centerOfMass"),
+        "position": _plain(world),
+        "visual_meshes": meshes,
+        "triangles": triangles,
+        "colliders": colliders,
+        "labels": _labels(prim),
+        "articulation_root": prim.HasAPI("PhysicsArticulationRootAPI"),
+    }
+
+
+def _joint(prim):
+    joint = UsdPhysics.Joint(prim)
+    found: dict[str, object] = {
+        "path": str(prim.GetPath()),
+        "type": prim.GetTypeName(),
+        "body0": [str(t) for t in joint.GetBody0Rel().GetTargets()],
+        "body1": [str(t) for t in joint.GetBody1Rel().GetTargets()],
+        **_attributes(
+            prim,
+            [
+                "physics:axis",
+                "physics:localPos0",
+                "physics:localPos1",
+                "physics:localRot0",
+                "physics:localRot1",
+                "physics:lowerLimit",
+                "physics:upperLimit",
+                "physics:collisionEnabled",
+                "physics:jointEnabled",
+            ],
+        ),
+        "labels": _labels(prim),
+    }
+    drives = {}
+    for kind in DRIVES:
+        if f"PhysicsDriveAPI:{kind}" in prim.GetAppliedSchemas():
+            names = ["type", "stiffness", "damping", "targetPosition", "targetVelocity", "maxForce"]
+            drives[kind] = _attributes(prim, [f"drive:{kind}:physics:{n}" for n in names])
+    if drives:
+        found["drives"] = drives
+    return found
+
+
+def _material(prim):
+    material = UsdShade.Material(prim)
+    found: dict[str, object] = {"path": str(prim.GetPath())}
+    for context in ("", "mdl"):  # a UsdPreviewSurface, else an MDL shader such as OmniPBR
+        surface = material.ComputeSurfaceSource(context)[0]
+        if surface:
+            break
+    if surface:
+        shader = surface.GetPrim()
+        found["shader"] = _plain(
+            shader.GetAttribute("info:id").Get() or shader.GetAttribute("info:mdl:sourceAsset:subIdentifier").Get()
+        )
+        names = [i.GetBaseName() for i in surface.GetInputs()]
+        for name in [n for n in SHADER_INPUTS if n in names] + [n for n in names if n not in SHADER_INPUTS]:
+            value = surface.GetInput(name)
+            source = value.GetConnectedSources()[0]
+            if source:
+                upstream = source[0].source.GetPrim()
+                found[name] = {"texture": _plain(upstream.GetAttribute("inputs:file").Get()) or str(upstream.GetPath())}
+            elif value.Get() is not None:
+                found[name] = _plain(value.Get())
+    if prim.HasAPI("PhysicsMaterialAPI"):
+        found["physics"] = _attributes(
+            prim,
+            ["physics:staticFriction", "physics:dynamicFriction", "physics:restitution", "physics:density"],
+        )
+    sensor = {a.GetName(): _plain(a.Get()) for a in prim.GetAttributes() if "nonvisual" in a.GetName()}
+    if sensor:
+        found["nonvisual"] = sensor
+    return found
+
+
+def inspect(path):
+    """The asset's structure as a dict (see the module's docstring)."""
+    stage = Usd.Stage.Open(str(path))
+    cache = UsdGeom.XformCache()
+    box = (
+        UsdGeom.BBoxCache(Usd.TimeCode.Default(), [UsdGeom.Tokens.default_, UsdGeom.Tokens.render])
+        .ComputeWorldBound(stage.GetPseudoRoot())
+        .ComputeAlignedRange()
+    )
+    default = stage.GetDefaultPrim()
+    layer = stage.GetRootLayer().customLayerData or {}
+    prims = list(stage.Traverse())
+    return {
+        "asset": str(Path(path)),
+        "default_prim": str(default.GetPath()) if default else None,
+        "meters_per_unit": UsdGeom.GetStageMetersPerUnit(stage),
+        "up_axis": UsdGeom.GetStageUpAxis(stage),
+        "kilograms_per_unit": UsdPhysics.GetStageKilogramsPerUnit(stage),
+        "size": _plain(box.GetSize()) if not box.IsEmpty() else None,
+        "metadata": json.loads(json.dumps(layer.get("SimReady_Metadata", {}), default=str)),
+        "labels": _labels(default) if default else {},
+        "articulation_roots": [str(p.GetPath()) for p in prims if p.HasAPI("PhysicsArticulationRootAPI")],
+        "bodies": [_body(stage, p, cache) for p in prims if p.HasAPI("PhysicsRigidBodyAPI")],
+        "joints": [_joint(p) for p in prims if p.IsA("PhysicsJoint")],
+        "materials": [_material(p) for p in prims if p.IsA("Material")],
+    }