simready-forge 0.1.0__py3-none-any.whl

simready_forge/isaac_probe.py

@@ -0,0 +1,785 @@
+"""Probe a SimReady asset's physics in Isaac Sim: what a robot or a person would do to it, measured against what the
+asset's own values predict.
+
+    OMNI_KIT_ACCEPT_EULA=YES <isaac sim python> isaac_probe.py <asset.usda> <out_dir> [test ...]
+
+Tests, each from the asset's rest pose on a grid ground (static friction 0.8, dynamic 0.6):
+  tilt    the ground and the asset tilted together, steeper run by run, in four directions: the angle where it
+          first slides or tips, against atan(friction) and atan(support / height of the centre of mass)
+  push    with the part's parent held still, a 10 N fingertip push at each moving part's rim (along a slide), at
+          most at a hand's speed, then let go: whether a hand can move it, whether it stays or springs back, and at
+          its limit how far past it goes and whether the joint holds
+  lift    the main body held by a hand, lifted 30 cm, shaken +-5 cm at 2 Hz, set down: joints that overrun or part
+  settle  10 s at rest: how far anything still creeps after 5 s
+  load    a box a quarter of the asset's mass dropped on its top from 10 cm: it fails only if the asset topples or
+          the simulation blows up
+Writes out_dir/probe.json. Named tests run only those and keep the others' results from an existing probe.json;
+`versions` says which probe version wrote each test. Exit code 0 when every test passes, 1 when one fails, 2 on an
+error.
+"""
+
+import json
+import math
+import sys
+import traceback
+from pathlib import Path
+
+ASSET = str(Path(sys.argv[1]).resolve()).replace("\\", "/")
+OUT = Path(sys.argv[2]).resolve()
+ONLY = sys.argv[3:]
+OUT.mkdir(parents=True, exist_ok=True)
+
+from isaacsim import SimulationApp
+
+app = SimulationApp({"headless": True})
+import numpy as np
+import omni.usd
+from omni.physx import get_physx_interface, get_physx_simulation_interface
+from pxr import Gf, PhysicsSchemaTools, Sdf, Usd, UsdGeom, UsdPhysics
+
+AXIS = {"X": 0, "Y": 1, "Z": 2}
+TESTS = ("settle", "tilt", "push", "lift", "load")
+# 2: recalibrated criteria; 3: the push holds the part's parent; 4: a part standing on the ground is not judged on
+# whether a fingertip moves it; 5: the push keeps to a hand's speed, and masses and centres of mass come from PhysX;
+# 6: the push is a fingertip that sets its force each step to keep to that speed (5's on-off push overshot light parts);
+# 7: the fingertip presses harder while a spring or a stop holds the part back (a one-step boost: too little);
+# 8: it relearns how much a newton moves the part every step (still threw light levers apart, swung a sprung arm);
+# 9: the push is a velocity drive on a second joint, at hand speed and at most 10 N, solved by PhysX itself (it broke
+# the limits of joints outside an articulation); 10: that drive in an articulation, 8's fingertip force outside one;
+# 11: the push passes when the joint survives it (no blow-up, limits and joint hold); operable_by_hand is reported
+VERSION = 11
+HAND_SPEED = 0.3  # m/s: how fast a fingertip moves a part along
+PUSH = 10.0  # N: the most a fingertip pushes with
+HZ = 120  # physics steps per simulated second, stepped by hand with no rendering (as the judge's drop is)
+G = 9.81
+GROUND_STATIC = 0.8
+TOLERANCE = 0.005  # m: movement smaller than this is settling, not sliding
+# label: (the rotation axis, its sign, the downhill direction). +X turned about X lifts +Y; about Y it lowers +X.
+TILTS = {
+    "front down (-Y)": (0, 1.0, (0, -1, 0)),
+    "back down (+Y)": (0, -1.0, (0, 1, 0)),
+    "right down (+X)": (1, 1.0, (1, 0, 0)),
+    "left down (-X)": (1, -1.0, (-1, 0, 0)),
+}
+
+
+def quat_matrix(q):
+    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 setup():
+    ctx = omni.usd.get_context()
+    ctx.new_stage()
+    for _ in range(5):
+        app.update()
+    stage = ctx.get_stage()
+    UsdGeom.SetStageUpAxis(stage, UsdGeom.Tokens.z)
+    UsdGeom.SetStageMetersPerUnit(stage, 1.0)
+    UsdGeom.Xform.Define(stage, "/World")
+    UsdPhysics.Scene.Define(stage, "/World/physicsScene").CreateGravityMagnitudeAttr(G)
+    tilt = UsdGeom.Xform.Define(stage, "/World/Tilt")  # the ground and the asset, tilted together
+    tilt_op = tilt.AddRotateXYZOp()
+    ground = UsdGeom.Mesh.Define(stage, "/World/Tilt/Ground")
+    h = 50.0
+    ground.CreatePointsAttr([(-h, -h, 0), (h, -h, 0), (h, h, 0), (-h, h, 0)])
+    ground.CreateFaceVertexCountsAttr([4])
+    ground.CreateFaceVertexIndicesAttr([0, 1, 2, 3])
+    UsdPhysics.CollisionAPI.Apply(ground.GetPrim())
+    from pxr import UsdShade
+
+    look = UsdShade.Material.Define(stage, "/World/Looks/Ground")
+    grip = UsdPhysics.MaterialAPI.Apply(look.GetPrim())
+    grip.CreateStaticFrictionAttr(GROUND_STATIC)
+    grip.CreateDynamicFrictionAttr(0.6)
+    grip.CreateRestitutionAttr(0.1)
+    UsdShade.MaterialBindingAPI.Apply(ground.GetPrim()).Bind(look, UsdShade.Tokens.weakerThanDescendants, "physics")
+    holder = UsdGeom.Xform.Define(stage, "/World/Tilt/Asset")
+    holder.GetPrim().GetReferences().AddReference(ASSET)
+    for _ in range(10):
+        app.update()
+    box = UsdGeom.BBoxCache(Usd.TimeCode.Default(), [UsdGeom.Tokens.default_, UsdGeom.Tokens.render])
+    rng = box.ComputeWorldBound(holder.GetPrim()).ComputeAlignedRange()
+    lo, hi = rng.GetMin(), rng.GetMax()
+    holder.AddTranslateOp().Set(Gf.Vec3d(-(lo[0] + hi[0]) / 2, -(lo[1] + hi[1]) / 2, 0.001 - lo[2]))
+    for _ in range(10):
+        app.update()
+    return stage, tilt_op
+
+
+def poses(bodies):
+    cache = UsdGeom.XformCache()
+    out = {}
+    for b in bodies:
+        m = cache.GetLocalToWorldTransform(b)
+        out[str(b.GetPath())] = (np.array(m.ExtractRotationMatrix()).T, np.array(m.ExtractTranslation()))
+    return out
+
+
+def turned(r0, r1):
+    """Degrees between two rotations."""
+    return math.degrees(math.acos(max(-1.0, min(1.0, (np.trace(r0.T @ r1) - 1) / 2))))
+
+
+class Joint:
+    """A joint read from the stage: its bodies, axis and anchor in each body's frame, limits, and its position."""
+
+    def __init__(self, prim):
+        j = UsdPhysics.Joint(prim)
+        self.prim, self.name = prim, prim.GetName()
+        self.revolute = prim.IsA(UsdPhysics.RevoluteJoint)
+        self.b0, self.b1 = str(j.GetBody0Rel().GetTargets()[0]), str(j.GetBody1Rel().GetTargets()[0])
+        self.rot0 = quat_matrix(j.GetLocalRot0Attr().Get()) if j.GetLocalRot0Attr().Get() is not None else np.eye(3)
+        self.rot1 = quat_matrix(j.GetLocalRot1Attr().Get()) if j.GetLocalRot1Attr().Get() is not None else np.eye(3)
+        self.pos0 = np.array(j.GetLocalPos0Attr().Get() or (0, 0, 0), dtype=float)
+        self.pos1 = np.array(j.GetLocalPos1Attr().Get() or (0, 0, 0), dtype=float)
+        self.index = AXIS[prim.GetAttribute("physics:axis").Get()]
+        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
+        self.free = not (math.isfinite(lo) and math.isfinite(hi)) or max(abs(lo), abs(hi)) > 1e6
+        self.lo, self.hi = (-90.0, 90.0) if self.free and self.revolute else (lo, hi)
+        self.value = self.last = None
+
+    def frames(self, f):
+        (r0, t0), (r1, t1) = f[self.b0], f[self.b1]
+        return r0 @ self.rot0, r0 @ self.pos0 + t0, r1 @ self.rot1, r1 @ self.pos1 + t1
+
+    def sample(self, f):
+        """The joint coordinate (degrees, or metres), followed in small steps; and the anchors' separation (m)."""
+        frame0, anchor0, frame1, anchor1 = self.frames(f)
+        if self.revolute:
+            rel = frame0.T @ frame1
+            if self.last is None:
+                self.value = self._angle(rel)
+            else:
+                self.value += self._angle(rel @ self.last.T)
+            self.last = rel
+        else:
+            self.value = float(frame0[:, self.index] @ (anchor1 - anchor0))
+        return self.value, float(np.linalg.norm(anchor1 - anchor0) if self.revolute else self._off_axis(f))
+
+    def _angle(self, rotation):
+        angle = math.degrees(math.acos(max(-1.0, min(1.0, (np.trace(rotation) - 1) / 2))))
+        w = np.array(
+            [rotation[2, 1] - rotation[1, 2], rotation[0, 2] - rotation[2, 0], rotation[1, 0] - rotation[0, 1]]
+        )
+        return angle if w[self.index] >= 0 else -angle
+
+    def _off_axis(self, f):
+        frame0, anchor0, _, anchor1 = self.frames(f)
+        d = anchor1 - anchor0
+        axis = frame0[:, self.index]
+        return float(np.linalg.norm(d - (d @ axis) * axis))
+
+    def far(self):
+        """The side of the range a push goes to: the larger one, as the review drives it."""
+        return self.lo if abs(self.lo) > abs(self.hi) else self.hi
+
+    def push_force(self, f, child_point, size):
+        """The world force at the world point that pushes this joint toward its far side with `size` newtons."""
+        frame0, anchor0, _, _ = self.frames(f)
+        axis = frame0[:, self.index]
+        sign = 1.0 if self.far() > 0 else -1.0
+        if not self.revolute:
+            return axis * size * sign
+        arm = child_point - anchor0
+        arm = arm - (arm @ axis) * axis
+        tangent = np.cross(axis, arm)
+        n = np.linalg.norm(tangent)
+        return tangent / n * size * sign if n > 1e-6 else np.zeros(3)
+
+
+class Finger:
+    """A fingertip pushing at a part's rim from outside, for a joint outside any articulation (where a second joint's
+    drive broke the joint's own limits): it learns each step how much a newton speeds the part up and pushes only as
+    hard as hand speed needs, pressing on to PUSH newtons while something holds the part back."""
+
+    def __init__(self):
+        self.point, self.speed, self.pushed, self.gain = None, 0.0, 0.0, None
+
+    def force(self, point, direction):
+        """Newtons to push with this step, given the contact point now and the push's unit direction."""
+        speed = 0.0 if self.point is None else float((point - self.point) @ direction) * HZ
+        previous = self.speed
+        self.point, self.speed = point, speed
+        if self.pushed > 0:
+            observed = max(speed - previous, 0.0) / self.pushed  # m/s per newton over the last step
+            if observed > 0 or self.gain is not None:
+                self.gain = observed if self.gain is None else 0.5 * self.gain + 0.5 * observed
+        if self.gain is None:  # nothing has moved yet: press harder, from 0.1 N up
+            wanted = 0.1 if self.pushed == 0 else 2 * self.pushed
+        else:
+            wanted = (HAND_SPEED - speed) / max(self.gain, 1e-9)
+        self.pushed = float(np.clip(wanted, 0.0, PUSH))
+        return self.pushed
+
+
+class Probe:
+    def __init__(self, stage, tilt_op):
+        self.stage, self.tilt_op = stage, tilt_op
+        root = stage.GetPrimAtPath("/World/Tilt/Asset")
+        self.bodies = [p for p in Usd.PrimRange(root) if p.HasAPI(UsdPhysics.RigidBodyAPI)]
+        self.joints = [
+            Joint(p) for p in Usd.PrimRange(root) if p.IsA(UsdPhysics.RevoluteJoint) or p.IsA(UsdPhysics.PrismaticJoint)
+        ]
+        self.physx = get_physx_simulation_interface()
+        self.stage_id = omni.usd.get_context().get_stage_id()
+        self.articulated = any(p.HasAPI(UsdPhysics.ArticulationRootAPI) for p in Usd.PrimRange(root))
+        self.rest = poses(self.bodies)
+        self.inertial = self._inertial()  # PhysX's own: authored, or from the colliders where the asset leaves it out
+        authored = {str(b.GetPath()): UsdPhysics.MassAPI(b).GetMassAttr().Get() or 0.0 for b in self.bodies}
+        self.mass = {k: self.inertial[k][0] if k in self.inertial else m for k, m in authored.items()}
+        children = {j.b1 for j in self.joints}
+        roots = [str(b.GetPath()) for b in self.bodies if str(b.GetPath()) not in children]
+        self.root = max(roots, key=lambda b: self.mass[b]) if roots else None  # the main body: heaviest root
+        self.loose = len(roots) > 1  # a pile or a set of parts not jointed into one tree
+        self.box = (
+            UsdGeom.BBoxCache(Usd.TimeCode.Default(), [UsdGeom.Tokens.default_, UsdGeom.Tokens.render])
+            .ComputeWorldBound(root)
+            .ComputeAlignedRange()
+        )
+
+    # -------------------------------------------------------------- running
+    def run(self, seconds, each=None, bodies=None):
+        """Simulate from the stage as it stands for `seconds`; each(step, poses) may apply forces or move things."""
+        physx = get_physx_interface()
+        tracked = bodies or self.bodies
+        physx.start_simulation()
+        t, dt = 0.0, 1.0 / HZ
+        for step in range(int(seconds * HZ)):
+            if each is not None:
+                each(step, poses(tracked))
+            physx.update_simulation(dt, t)
+            t += dt
+            physx.update_transformations(False, True, True, False)
+        return poses(tracked)
+
+    def reset(self):
+        """Back to the rest pose: the simulation restores the transforms it started from."""
+        get_physx_interface().reset_simulation()
+
+    def _hold(self, body, at):
+        """A kinematic hand fixed to `body` at the world point `at`, keeping the body in its rest pose until the hand
+        moves. Returns the hand's translate op."""
+        r, t = self.rest[body]
+        hand = UsdGeom.Xform.Define(self.stage, "/World/Hand")
+        op = hand.AddTranslateOp()
+        op.Set(Gf.Vec3d(*[float(x) for x in at]))
+        UsdPhysics.RigidBodyAPI.Apply(hand.GetPrim()).CreateKinematicEnabledAttr(True)
+        UsdPhysics.MassAPI.Apply(hand.GetPrim()).CreateMassAttr(1.0)
+        fixed = UsdPhysics.FixedJoint.Define(self.stage, "/World/HandJoint")
+        fixed.CreateBody0Rel().SetTargets([hand.GetPath()])
+        fixed.CreateBody1Rel().SetTargets([Sdf.Path(body)])
+        fixed.CreateLocalPos0Attr(Gf.Vec3f(0, 0, 0))
+        fixed.CreateLocalPos1Attr(Gf.Vec3f(*[float(x) for x in r.T @ (np.asarray(at) - t)]))
+        # the hand is world-aligned, so the body's side of the joint undoes its rest rotation (a Gf matrix is the
+        # transpose of these column-vector ones, so r as a Gf matrix is r.T here)
+        q = Gf.Matrix4d(Gf.Matrix3d(*r.flatten().tolist()), Gf.Vec3d(0, 0, 0)).ExtractRotation().GetQuat()
+        fixed.CreateLocalRot1Attr(Gf.Quatf(float(q.GetReal()), Gf.Vec3f(*[float(x) for x in q.GetImaginary()])))
+        fixed.CreateExcludeFromArticulationAttr(True)
+        for _ in range(3):
+            app.update()
+        return op
+
+    def _let_go(self):
+        for path in ("/World/Finger", "/World/HandJoint", "/World/Hand"):
+            self.stage.RemovePrim(path)
+        for _ in range(3):
+            app.update()
+
+    def force(self, body, force, point):
+        self.physx.apply_force_at_pos(
+            self.stage_id,
+            PhysicsSchemaTools.sdfPathToInt(Sdf.Path(body)),
+            Gf.Vec3f(*[float(x) for x in force]),
+            Gf.Vec3f(*[float(x) for x in point]),
+            "Force",
+        )
+
+    @staticmethod
+    def finite(f):
+        return all(np.isfinite(r).all() and np.isfinite(t).all() for r, t in f.values())
+
+    # -------------------------------------------------------------- what the asset's values predict
+    def _inertial(self):
+        """Each body's mass and centre of mass (in its own frame) as PhysX computes them: {path: (kg, centre)}. An
+        asset that leaves them out (a density, or nothing) gets them from its colliders, so the predictions below hold
+        for every pipeline's assets alike."""
+        from omni.physx import get_physx_property_query_interface
+        from omni.physx.bindings._physx import PhysxPropertyQueryMode, PhysxPropertyQueryResult
+
+        out = {}
+        for b in self.bodies:
+            path = str(b.GetPath())
+
+            def report(info, path=path):
+                if info.result == PhysxPropertyQueryResult.VALID:
+                    out[path] = (float(info.mass), np.array(list(info.center_of_mass), dtype=float))
+
+            get_physx_property_query_interface().query_prim(
+                stage_id=self.stage_id,
+                prim_id=PhysicsSchemaTools.sdfPathToInt(b.GetPath()),
+                query_mode=PhysxPropertyQueryMode.QUERY_RIGID_BODY_WITH_COLLIDERS,
+                timeout_ms=30000,
+                rigid_body_fn=report,
+            )
+        for _ in range(200):  # collider cooking can finish a few updates later
+            if len(out) == len(self.bodies):
+                break
+            app.update()
+        return out
+
+    def centre_of_mass(self):
+        total, moment = 0.0, np.zeros(3)
+        cache = UsdGeom.XformCache()
+        for b in self.bodies:
+            m = self.mass[str(b.GetPath())]
+            com = UsdPhysics.MassAPI(b).GetCenterOfMassAttr().Get()
+            local = np.array(com, dtype=float) if com is not None and abs(com[0]) < 1e6 else np.zeros(3)
+            if str(b.GetPath()) in self.inertial:
+                local = self.inertial[str(b.GetPath())][1]
+            world = np.array(cache.GetLocalToWorldTransform(b).Transform(Gf.Vec3d(*local)))
+            total, moment = total + m, moment + m * world
+        return moment / total if total else None
+
+    def support(self):
+        """Collider points within 4 mm of the lowest collider point at rest (the visual meshes may sit above or below
+        the colliders), and the least static friction among their materials."""
+        cache = UsdGeom.XformCache()
+        points, friction = [], []
+        floor = self._lowest_collider(cache)
+        for b in self.bodies:
+            for c in Usd.PrimRange(b):
+                if not (c.HasAPI(UsdPhysics.CollisionAPI) and c.IsA(UsdGeom.Mesh)):
+                    continue
+                pts = np.array(UsdGeom.Mesh(c).GetPointsAttr().Get() or [], dtype=float)
+                if not len(pts):
+                    continue
+                m = np.array(cache.GetLocalToWorldTransform(c))
+                world = pts @ m[:3, :3] + m[3, :3]
+                low = world[world[:, 2] < floor + 0.004]
+                if len(low):
+                    points.append(low)
+                    from pxr import UsdShade
+
+                    mat = UsdShade.MaterialBindingAPI(c).ComputeBoundMaterial("physics")[0]
+                    value = mat.GetPrim().GetAttribute("physics:staticFriction").Get() if mat else None
+                    friction.append(0.5 if value is None else float(value))
+        return (np.vstack(points) if points else np.zeros((0, 3))), (min(friction) if friction else 0.5)
+
+    def _standing(self):
+        """The bodies whose colliders come within 4 mm of the lowest point at rest: what the asset stands on."""
+        cache = UsdGeom.XformCache()
+        floor = self._lowest_collider(cache)
+        return {str(b.GetPath()) for b in self.bodies if self._lowest_collider(cache, [b]) < floor + 0.004}
+
+    def _lowest_collider(self, cache, bodies=None):
+        lows = []
+        for b in bodies or self.bodies:
+            for c in Usd.PrimRange(b):
+                if c.HasAPI(UsdPhysics.CollisionAPI) and c.IsA(UsdGeom.Mesh):
+                    pts = np.array(UsdGeom.Mesh(c).GetPointsAttr().Get() or [], dtype=float)
+                    if len(pts):
+                        m = np.array(cache.GetLocalToWorldTransform(c))
+                        lows.append(float((pts @ m[:3, :3] + m[3, :3])[:, 2].min()))
+        return min(lows) if lows else (0.0 if bodies is None else math.inf)
+
+    def blown(self, f):
+        """NaN, or any body flung further than ten times the asset's size: the simulation blew up."""
+        if not self.finite(f):
+            return True
+        reach = 10.0 * max(float((self.box.GetMax() - self.box.GetMin()).GetLength()), 0.1)
+        return any(np.linalg.norm(f[k][1] - self.rest[k][1]) > reach for k in f if k in self.rest)
+
+    # -------------------------------------------------------------- tests
+    def tilt(self):
+        """Ground and asset tilted together, steeper run by run (a binary search over 0-45 degrees) in four directions:
+        the angle where the main body (or, for a loose set, any body) first slides or tips, against what its friction
+        and its centre of mass over its support predict, and the angle where a part first moves on its own joint."""
+        com = self.centre_of_mass()
+        support, friction = self.support()
+        mu = (friction + GROUND_STATIC) / 2  # PhysX averages two materials' friction by default
+        slide = math.degrees(math.atan(mu))
+        out = {
+            "friction_expected": round(mu, 3),
+            "slide_expected_deg": round(slide, 1),
+            "mass_from": "physx" if len(self.inertial) == len(self.bodies) else "authored",
+        }
+        for label, (axis, sign, downhill) in TILTS.items():
+            down = np.array(downhill, dtype=float)
+            tip = None
+            if com is not None and len(support):
+                reach = float((support @ down).max() - com @ down)  # from the centre of mass to the edge it tips over
+                tip = math.degrees(math.atan2(max(reach, 0.0), max(float(com[2]), 1e-6)))
+            lo_deg, hi_deg, first, part_from = 0.0, 45.0, None, None
+            for _ in range(6):
+                angle = (lo_deg + hi_deg) / 2
+                kind, part = self._tilted(axis, sign, angle)
+                if part and (part_from is None or angle < part_from):
+                    part_from = angle
+                if kind:
+                    hi_deg, first = angle, kind
+                else:
+                    lo_deg = angle
+            out[label] = {
+                "moves_at_deg": round(hi_deg, 1) if first else None,
+                "how": first or "holds to 45",
+                "tip_expected_deg": None if tip is None else round(tip, 1),
+                "a_part_moves_from_deg": None if part_from is None else round(part_from, 1),
+            }
+        rows = [v for v in out.values() if isinstance(v, dict)]
+        predicted = min([slide] + [v["tip_expected_deg"] for v in rows if v["tip_expected_deg"] is not None])
+        moved = [v["moves_at_deg"] for v in rows if v["moves_at_deg"] is not None]
+        out["first_move_deg"] = min(moved) if moved else None
+        out["predicted_first_deg"] = round(predicted, 1)
+        # a pass: the asset does not give way more than 5 degrees before its own values say it should
+        out["passed"] = bool(self.loose or not moved or min(moved) >= predicted - 5.0)
+        return out
+
+    def _tilted(self, axis, sign, angle):
+        """Run 1.5 s on ground tilted `angle` degrees. Returns (None, 'slides', 'tips', 'rolls' or 'explodes' for the
+        asset as a whole) and whether a part moved on its own joint."""
+        rot = [0.0, 0.0, 0.0]
+        rot[axis] = angle * sign
+        self.tilt_op.Set(Gf.Vec3f(*rot))
+        for _ in range(2):
+            app.update()
+        start = poses(self.bodies)
+        end = self.run(1.5)
+        self.reset()
+        self.tilt_op.Set(Gf.Vec3f(0, 0, 0))
+        if not self.finite(end):
+            return "explodes", False
+        judged = list(end) if self.loose or self.root is None else [self.root]
+        shift = max(np.linalg.norm(end[k][1] - start[k][1]) for k in judged)
+        spin = max(turned(start[k][0], end[k][0]) for k in judged)
+        part = False
+        if not self.loose and self.root is not None:
+            r = self.root
+            part = any(
+                np.linalg.norm((end[k][1] - end[r][1]) - (start[k][1] - start[r][1])) > TOLERANCE for k in end if k != r
+            )
+        if spin > 10 and shift > TOLERANCE:
+            return ("rolls" if self.loose else "tips"), part
+        if shift > TOLERANCE:
+            return "slides", part
+        return None, part
+
+    def push(self):
+        """With the joint's parent body held still (a hand on the base), a fingertip pushes the moving part toward its
+        far side at a hand's speed with at most 10 N at its rim (along a slide) for 1.5 s, then lets go for 1.5 s (a
+        drive on a second joint in an articulation, a force at the rim outside one; `pushed_by` says which):
+        whether a hand can move it, whether it stays or springs back, and, where it reaches its limit, how far past the
+        limit it goes and whether the joint holds together. Unheld, the push shoved or spun whole light assets across
+        the ground. A part that stands on the ground (an A-frame's leg, a stand) is not judged on whether a fingertip
+        moves it: the asset's weight holds it, and a person lifts the asset first."""
+        results = {}
+        standing = self._standing()
+        below = {}  # each body's descendants through the joints
+        for j in self.joints:
+            below.setdefault(j.b0, set()).add(j.b1)
+
+        def subtree(body):
+            out, todo = set(), [body]
+            while todo:
+                b = todo.pop()
+                if b not in out:
+                    out.add(b)
+                    todo.extend(below.get(b, ()))
+            return out
+
+        for j in self.joints:
+            gauge = Joint(j.prim)
+            trace, gaps = [], []
+            self._hold(j.b0, self.rest[j.b0][1])
+            rim = self._rim(j)
+            # in an articulation a second joint's drive pushes (PhysX solves it, stable for a 5 g lever); outside one
+            # that drive broke the joint's own limits, so a fingertip force pushes from outside instead
+            inside = self.articulated and not UsdPhysics.Joint(j.prim).GetExcludeFromArticulationAttr().Get()
+            drive = self._pusher(j, rim) if inside else None
+            finger = Finger()
+
+            def each(step, f, j=j, gauge=gauge, trace=trace, gaps=gaps, drive=drive, finger=finger, rim=rim):
+                value, gap = gauge.sample(f)
+                trace.append(value)
+                gaps.append(gap)
+                if drive is not None:
+                    if step == int(1.5 * HZ):  # let go
+                        drive.GetMaxForceAttr().Set(0.0)
+                        drive.GetDampingAttr().Set(0.0)
+                        drive.GetTargetVelocityAttr().Set(0.0)
+                elif step < 1.5 * HZ:
+                    r1, t1 = f[j.b1]
+                    point = r1 @ rim + t1
+                    direction = j.push_force(f, point, 1.0)
+                    self.force(j.b1, direction * finger.force(point, direction), point)
+
+            end = self.run(3.0, each)
+            self.reset()
+            self._let_go()
+            span = j.hi - j.lo
+            rest = trace[0] if trace else 0.0
+            pushed = max(trace[: int(1.5 * HZ)], key=lambda v: abs(v - rest)) if trace else rest
+            final = trace[-1] if trace else rest
+            moved = abs(pushed - rest)
+            kept = abs(final - rest) / max(moved, 1e-9)
+            limit = j.far()
+            overrun = (
+                0.0
+                if j.free
+                else max((abs(v) - abs(limit) for v in trace if np.sign(v) == np.sign(limit)), default=0.0)
+            )
+            noticeable = 15.0 if j.revolute else 0.015  # degrees, or metres: a hand sees it move
+            blown = self.blown(end)
+            stands = bool(subtree(j.b1) & standing)
+            operable = stands or j.free or moved >= min(0.2 * span, noticeable) or overrun >= -0.02 * span
+            holds = max(overrun, 0.0) <= 0.05 * span + (1.0 if j.revolute else 0.001)
+            # an anchor gap already there at rest is the authoring's, not the push's
+            apart = max(gaps, default=0.0) - (gaps[0] if gaps else 0.0)
+            together = apart < 0.005
+            results[j.name] = {
+                "moved": round(moved, 4),
+                "moved_units": "deg" if j.revolute else "m",
+                "travel_of_range": round(moved / span, 3) if span else None,
+                "after_release": "stays" if kept > 0.8 else "springs back" if kept < 0.2 else "partly back",
+                "overrun_of_range": round(max(overrun, 0.0) / span, 3) if span and not j.free else 0.0,
+                "separation_mm": round(apart * 1000, 2),
+                "anchor_gap_at_rest_mm": round((gaps[0] if gaps else 0.0) * 1000, 2),
+                "blew_up": bool(blown),
+                "operable_by_hand": None if stands else bool(operable),  # None: it stands on the ground
+                "pushed_by": "a drive (in an articulation)" if inside else "a force at the rim (no articulation)",
+                # passes when the joint survives a hand's push; whether a hand moves it is reported, not judged: a
+                # screw cap with drag or a sprung lamp arm rightly resists a fingertip, a stiff drawer does not
+                "passed": bool(not blown and holds and together),
+            }
+        return results
+
+    def _pusher(self, j, rim):
+        """A hand pushing the joint's child toward its far side at a hand's speed, with at most PUSH newtons at the rim:
+        a second joint on the same frames, outside the articulation, free but for a velocity drive on the tested axis,
+        which PhysX solves with the rest of the step. Forces set from outside step by step threw a 6 g lever apart or
+        set a sprung arm swinging. Returns the drive, to let go."""
+        source = UsdPhysics.Joint(j.prim)
+        joint = UsdPhysics.Joint.Define(self.stage, "/World/Finger")
+        joint.CreateBody0Rel().SetTargets([Sdf.Path(j.b0)])
+        joint.CreateBody1Rel().SetTargets([Sdf.Path(j.b1)])
+        for read, write in (
+            (source.GetLocalPos0Attr, joint.CreateLocalPos0Attr),
+            (source.GetLocalRot0Attr, joint.CreateLocalRot0Attr),
+            (source.GetLocalPos1Attr, joint.CreateLocalPos1Attr),
+            (source.GetLocalRot1Attr, joint.CreateLocalRot1Attr),
+        ):
+            if read().Get() is not None:
+                write(read().Get())
+        joint.CreateExcludeFromArticulationAttr(True)
+        joint.CreateCollisionEnabledAttr(False)
+        frame0, anchor0, _, _ = j.frames(self.rest)
+        r1, t1 = self.rest[j.b1]
+        arm = r1 @ rim + t1 - anchor0
+        axis = frame0[:, j.index]
+        reach = max(float(np.linalg.norm(arm - (arm @ axis) * axis)), 0.005) if j.revolute else 1.0
+        speed = math.degrees(HAND_SPEED / reach) if j.revolute else HAND_SPEED  # deg/s, or m/s
+        cap = PUSH * reach  # N*m at the rim's reach, or N along a slide
+        drive = UsdPhysics.DriveAPI.Apply(joint.GetPrim(), ("rot" if j.revolute else "trans") + "XYZ"[j.index])
+        drive.CreateTypeAttr("force")
+        drive.CreateStiffnessAttr(0.0)
+        drive.CreateDampingAttr(cap / (0.1 * speed))  # the whole push once the part lags a tenth of hand speed
+        drive.CreateTargetVelocityAttr((1.0 if j.far() > 0 else -1.0) * speed)
+        drive.CreateMaxForceAttr(cap)
+        for _ in range(3):
+            app.update()
+        return drive
+
+    def _rim(self, j):
+        """A point on the child, in its own frame, far from the joint axis: where a fingertip would push."""
+        child = self.stage.GetPrimAtPath(j.b1)
+        cache = UsdGeom.XformCache()
+        r1, t1 = self.rest[j.b1]
+        pts = []
+        for c in Usd.PrimRange(child):
+            if c.HasAPI(UsdPhysics.CollisionAPI) and c.IsA(UsdGeom.Mesh):
+                p = np.array(UsdGeom.Mesh(c).GetPointsAttr().Get() or [], dtype=float)
+                if len(p):
+                    m = np.array(cache.GetLocalToWorldTransform(c))
+                    pts.append(p @ m[:3, :3] + m[3, :3])
+        if not pts:
+            return np.zeros(3)
+        world = np.vstack(pts)
+        frame0, anchor0, _, _ = j.frames(self.rest)
+        axis = frame0[:, j.index]
+        if j.revolute:
+            arm = world - anchor0
+            arm = arm - np.outer(arm @ axis, axis)
+            point = world[int(np.argmax(np.linalg.norm(arm, axis=1)))] * 0.6 + world.mean(0) * 0.4  # in from the edge
+        else:
+            point = world.mean(0)
+        return r1.T @ (point - t1)
+
+    def lift(self):
+        """The main body held by a kinematic hand at its top: lifted 30 cm in 1 s, shaken +-5 cm at 2 Hz for 2 s, set
+        down in 1 s, held 1 s."""
+        if self.root is None:
+            return {"skipped": "no main body"}
+        lo, hi = self.box.GetMin(), self.box.GetMax()
+        grasp = np.array([(lo[0] + hi[0]) / 2, (lo[1] + hi[1]) / 2, hi[2]])
+        hand_op = self._hold(self.root, grasp)
+        gauges = [Joint(j.prim) for j in self.joints]
+        worst = {"overrun": 0.0, "gap": 0.0}
+
+        def path(step):
+            t = step / HZ
+            if t < 1.0:
+                return np.array([0, 0, 0.3 * t])
+            if t < 3.0:
+                return np.array([0.05 * math.sin(2 * math.pi * 2 * (t - 1.0)), 0, 0.3])
+            if t < 4.0:
+                return np.array([0, 0, 0.3 * (4.0 - t)])
+            return np.zeros(3)
+
+        def each(step, f):
+            hand_op.Set(Gf.Vec3d(*(grasp + path(step))))
+            for g in gauges:
+                value, gap = g.sample(f)
+                span = g.hi - g.lo
+                over = max(g.lo - value, value - g.hi, 0.0)
+                worst["overrun"] = max(worst["overrun"], over / span if span and not g.free else 0.0)
+                worst["gap"] = max(worst["gap"], gap)
+
+        end = self.run(5.0, each)
+        self.reset()
+        self._let_go()
+        fell = []
+        if self.loose:
+            fell = [k.rsplit("/", 1)[-1] for k in end if k != self.root]
+        ok = self.finite(end) and worst["overrun"] <= 0.1 and worst["gap"] < 0.005
+        return {
+            "held_body": self.root.rsplit("/", 1)[-1],
+            "joint_overrun_of_range": round(worst["overrun"], 3),
+            "joint_separation_mm": round(worst["gap"] * 1000, 2),
+            "nan": not self.finite(end),
+            "loose_bodies_left_behind": len(fell),
+            "passed": bool(ok),
+        }
+
+    def settle(self):
+        """10 s at rest with the asset's own drives: how far anything moves between 5 s and 10 s."""
+        marks = {}
+
+        def each(step, f):
+            if step == 5 * HZ:
+                marks["mid"] = f
+
+        end = self.run(10.0, each)
+        self.reset()
+        mid = marks.get("mid", end)
+        creep = max((np.linalg.norm(end[k][1] - mid[k][1]) for k in end), default=0.0)
+        moved = max((np.linalg.norm(end[k][1] - self.rest[k][1]) for k in end), default=0.0)
+        return {
+            "creep_after_5s_mm": round(float(creep) * 1000, 2),
+            "moved_from_pose_mm": round(float(moved) * 1000, 1),
+            "nan": not self.finite(end),
+            "passed": bool(self.finite(end) and creep < 0.002),
+        }
+
+    def load(self):
+        """A box a quarter of the asset's mass (50 g to 2 kg) dropped on the middle of its top from 10 cm."""
+        lo, hi = self.box.GetMin(), self.box.GetMax()
+        size = float(np.clip(0.3 * min(hi[0] - lo[0], hi[1] - lo[1]), 0.03, 0.2))
+        mass = float(np.clip(0.25 * sum(self.mass.values()), 0.05, 2.0))
+        top = float(hi[2])
+        cube = UsdGeom.Cube.Define(self.stage, "/World/Load")
+        cube.CreateSizeAttr(size)
+        cube.AddTranslateOp().Set(Gf.Vec3d((lo[0] + hi[0]) / 2, (lo[1] + hi[1]) / 2, top + 0.1 + size / 2))
+        UsdPhysics.RigidBodyAPI.Apply(cube.GetPrim())
+        UsdPhysics.CollisionAPI.Apply(cube.GetPrim())
+        UsdPhysics.MassAPI.Apply(cube.GetPrim()).CreateMassAttr(mass)
+        for _ in range(3):
+            app.update()
+        load_body = self.stage.GetPrimAtPath("/World/Load")
+        end = self.run(3.0, bodies=[*self.bodies, load_body])
+        self.reset()
+        self.stage.RemovePrim("/World/Load")
+        for _ in range(3):
+            app.update()
+        t = end["/World/Load"][1]
+        bottom = t[2] - size / 2
+        inside = lo[0] <= t[0] <= hi[0] and lo[1] <= t[1] <= hi[1]
+        if not np.isfinite(t).all():
+            where = "explodes"
+        elif bottom >= top - 0.25 * (top - lo[2]) - 0.01 and inside:
+            where = "rests on it"
+        elif inside and bottom < top - 0.25 * (top - lo[2]):
+            where = "sinks into it"
+        else:
+            where = "slides off"
+        asset_end = {k: v for k, v in end.items() if k != "/World/Load"}
+        moved = max((np.linalg.norm(asset_end[k][1] - self.rest[k][1]) for k in asset_end), default=0.0)
+        toppled = self.root is not None and turned(self.rest[self.root][0], asset_end[self.root][0]) > 30
+        return {
+            "box_kg": round(mass, 3),
+            "box_mm": round(size * 1000),
+            "box": where,  # "sinks into it" is fine for an open shoe or a cup: information, not a fault
+            "asset_moved_mm": round(float(moved) * 1000, 1),
+            "asset_toppled": bool(toppled),
+            "passed": bool(where != "explodes" and not self.blown(asset_end) and not toppled),
+        }
+
+
+def main():
+    unknown = sorted(set(ONLY) - set(TESTS))
+    if unknown:
+        raise ValueError(f"no test named {unknown}; the tests are {TESTS}")
+    stage, tilt_op = setup()
+    probe = Probe(stage, tilt_op)
+    earlier = OUT / "probe.json"
+    old = json.loads(earlier.read_text(encoding="utf-8")) if ONLY and earlier.is_file() else {}
+    report = {
+        "asset": ASSET,
+        "bodies": len(probe.bodies),
+        "joints": len(probe.joints),
+        "loose": probe.loose,
+    }
+    run = [t for t in TESTS if t in ONLY] if ONLY else list(TESTS)
+    versions = old.get("versions") or {t: old.get("version") for t in TESTS if t in old}
+    for name in TESTS:
+        if name not in run and name in old:
+            report[name] = old[name]
+    for name in run:
+        versions[name] = VERSION
+        try:
+            report[name] = getattr(probe, name)()
+        except Exception as error:  # noqa: BLE001  one test's failure must not hide the others' results
+            report[name] = {"error": f"{type(error).__name__}: {error}", "passed": False}
+            traceback.print_exc()
+            probe.reset()
+
+    def passed(result):
+        if isinstance(result, dict) and "passed" in result:
+            return result["passed"]
+        if isinstance(result, dict):
+            return all(passed(v) for v in result.values() if isinstance(v, dict))
+        return True
+
+    report["versions"] = {t: versions.get(t) for t in TESTS}
+    report["version"] = min((v for v in report["versions"].values() if v is not None), default=VERSION)
+    report["passed"] = {name: passed(report[name]) for name in TESTS if name in report}
+    report["all_passed"] = all(report["passed"].values())
+    (OUT / "probe.json").write_text(json.dumps(report, indent=1, default=float), encoding="utf-8")
+    print("PROBE " + json.dumps(report["passed"]))
+    return report["all_passed"]
+
+
+try:
+    code = 0 if main() else 1
+except Exception:  # noqa: BLE001  Kit swallows uncaught exceptions and exits 0
+    traceback.print_exc()
+    code = 2
+app.close()
+sys.exit(code)