usd-articulation

USD Articulation — Multi-Arm Robots

Two layers stack on a robot USD:

1. Physics: UsdPhysics.ArticulationRootAPI, UsdPhysics.Joint, UsdPhysics.RigidBodyAPI, PhysxSchema.PhysxArticulationAPI.
2. Robot Schema (usd.schema.isaac.robot_schema): semantic overlay used by isaacsim.robot.poser, the importers, manipulators examples, and any tool that walks "this robot's links / joints / named poses".

Rule: visual plausibility is not mechanical correctness. If it doesn't articulate, it doesn't exist.

Multi-arm assembly (correct pattern)

from pxr import Usd, UsdGeom, UsdPhysics, Sdf, Gf

# Spawn chassis
chassis = stage.DefinePrim("/World/Robot", "Xform")
chassis.GetReferences().AddReference(CHASSIS_USD)

# Spawn arms as children
left = stage.DefinePrim("/World/Robot/LeftArm", "Xform")
left.GetReferences().AddReference(ARM_USD)
UsdGeom.Xformable(left).AddTranslateOp().Set(Gf.Vec3d(0.0, 0.6, 0.5))

# REQUIRED: FixedJoint connecting arm to chassis
joint = UsdPhysics.FixedJoint.Define(stage, "/World/Robot/LeftArmAttachment")
joint.CreateBody0Rel().SetTargets([Sdf.Path("/World/Robot/.../Chassis")])
joint.CreateBody1Rel().SetTargets([Sdf.Path("/World/Robot/LeftArm/.../BaseMount")])

# REQUIRED: Remove ArticulationRootAPI from arm (only chassis keeps it)
arm_prim = stage.GetPrimAtPath("/World/Robot/LeftArm/...")
arm_prim.RemoveAPI(UsdPhysics.ArticulationRootAPI)

What does not work

• Referencing the same arm USD twice via sublayer composition.
• Using over "Geometry" to add arms in a parts layer.
• Assuming visual presence equals physical attachment.

Robot Schema overlay (Kit 110)

Apply the modern Isaac Robot Schema on top of the physics layer. The URDF/MJCF importers do this automatically; for hand-authored or retrofitted USDs apply it manually.

from pxr import Usd
from usd.schema.isaac.robot_schema import (
    Classes, Attributes,
    ApplyRobotAPI, ApplyLinkAPI, ApplyJointAPI, ApplySiteAPI,
    CreateNamedPose, CreateSurfaceGripper,
    PopulateRobotSchemaFromArticulation, GenerateRobotLinkTree, GetAllNamedPoses,
)

stage = Usd.Stage.Open("/path/robot.usd")
robot_prim = stage.GetPrimAtPath("/World/Robot")

# IsaacRobotAPI on the root: stores robot_type, ordered link/joint relations.
ApplyRobotAPI(robot_prim)
robot_prim.GetAttribute(Attributes.ROBOT_TYPE).Set("Mobile Manipulators")
# Or pick from get_allowed_tokens(Attributes.ROBOT_TYPE) — tokens include:
#   Default, End Effector, Manipulator, Humanoid,
#   Wheeled, Holonomic, Quadruped, Mobile Manipulators, Aerial.

# IsaacLinkAPI on each rigid link; IsaacJointAPI on each joint.
for link in (link_prims):  # walk articulated links
    ApplyLinkAPI(link)
for joint in (joint_prims):
    ApplyJointAPI(joint)

# IsaacSiteAPI on grasp / mount / reference frames (replaces deprecated
# IsaacReferencePointAPI).
ApplySiteAPI(grasp_frame_prim)

# One-shot retrofit: populate ordered link/joint graph from an existing
# Articulation (uses physics traversal to fill ROBOT_LINKS / ROBOT_JOINTS).
PopulateRobotSchemaFromArticulation(stage, robot_prim)

Validation checklist

Before trusting any multi-arm robot:

1. Exactly 1 UsdPhysics.ArticulationRootAPI on the chassis, nowhere else.
2. FixedJoints connect each arm BaseMount to the chassis.
3. Joint count matches: N arm joints per arm + chassis joints.
4. IsaacRobotAPI present on the root; robot_type set to a valid token.
5. ROBOT_LINKS / ROBOT_JOINTS relations populated (call PopulateRobotSchemaFromArticulation if not).
6. Each grasp frame carries IsaacSiteAPI (not deprecated IsaacReferencePointAPI).
7. Render from four angles (front, side, 3/4, top).
8. Send to a vision LLM with a binary question ("Arms attached? PASS/FAIL").

Validation snippet (self-contained)

Run via $ISAAC_SIM_DIR/python.sh. Enforces exactly one ArticulationRootAPI, prints joints and connected bodies, flags arms whose BaseMount is not bound to the chassis via a FixedJoint, and reports the Robot Schema state.

import sys
from pxr import Usd, UsdPhysics, Sdf
from usd.schema.isaac.robot_schema import Classes, Attributes, GetAllNamedPoses

stage = Usd.Stage.Open(sys.argv[1])

art_roots = [p.GetPath() for p in stage.Traverse() if p.HasAPI(UsdPhysics.ArticulationRootAPI)]
print(f"ArticulationRootAPI count: {len(art_roots)} -- {art_roots}")
assert len(art_roots) == 1, "must be exactly 1 articulation root"

joints = [p for p in stage.Traverse() if p.IsA(UsdPhysics.Joint)]
chassis_paths = {str(art_roots[0])}
attached_arms = set()
for j in joints:
    j_api = UsdPhysics.Joint(j)
    b0 = j_api.GetBody0Rel().GetTargets()
    b1 = j_api.GetBody1Rel().GetTargets()
    if j.IsA(UsdPhysics.FixedJoint) and any(str(t).startswith(p) for t in b0 for p in chassis_paths):
        attached_arms.update(str(t) for t in b1)
print(f"Joints: {len(joints)} | FixedJoint-attached children: {sorted(attached_arms)}")

# Robot Schema overlay
robots = [p for p in stage.Traverse() if p.HasAPI(Classes.ROBOT_API)]
print(f"IsaacRobotAPI count: {len(robots)}")
for r in robots:
    rt = r.GetAttribute(Attributes.ROBOT_TYPE).Get()
    poses = GetAllNamedPoses(stage, r)
    print(f"  {r.GetPath()}: robot_type={rt!r}  named_poses={list(poses)}")

Extend with whatever arm/leg path patterns your asset uses. Binary goal: exactly one root, every limb connected to the chassis via a FixedJoint or articulated joint chain, and the Robot Schema overlay present.

Common failures