usd-articulation

USD Articulation — Multi-Arm Robots

Purpose

Assemble and validate multi-link robot articulations with ArticulationRootAPI, fixed joints, and Isaac robot schema overlays before deployment.

Prerequisites

• For standalone schema authoring: matching OpenUSD and isaacsim-robot-schema library artifacts.
• For live articulation interaction, extension commands, or rendering: built Isaac Sim and the environment from isaac-sim-orchestrator.

Limitations

• Targets Isaac Sim 6 / Kit 110 unless a section states otherwise.
• Does not replace official NVIDIA documentation for unsupported edge cases.

Troubleshooting

Error / symptom	Cause	Solution
Black or empty frames	Missing lights or non-RTX render mode	Add dome/key light; confirm RTX / PathTracing settings
Hang on stage load or first render	MDL compile or oversized stage	Follow isolation steps in isaac-sim-troubleshooting

Schema authoring versus runtime interaction

The robot schema is generated and packaged from source/libraries/isaacsim_usd_schemas/robot/; use that distribution for standalone schema application and validation with OpenUSD. For robot-motion schema metadata, use the separate isaacsim.robot_motion.schema module. These schema packages do not require a Kit extension registry merely to import.

Kit commands, live timeline interaction, UI, and rendering stay on the Kit route.

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.

Available Scripts

Script	Purpose	Arguments
scripts/apply_robot_schema.py	Apply Isaac Robot Schema overlay to an existing USD articulation	see script --help
scripts/multi_arm_assembly.py	Assemble a multi-arm robot in USD using FixedJoints	see script --help
scripts/validate_articulation.py	Validate multi-arm robot USD articulation structure	CLI args via sys.argv (see script --help)

Running scripts

From agent runtimes that expose skill execution helpers, invoke helpers with run_script():

run_script("scripts/apply_robot_schema.py", args=["--help"])

From a built Isaac Sim tree, run the same file with ./python.sh (Linux) or python.bat (Windows) from _build/*/release, or execute shell helpers directly when they do not require the simulator.

Multi-arm assembly (correct pattern)

assemble_multi_arm_robot(stage, chassis_usd, arm_usd, robot_root, arm_offset, chassis_body_path, arm_base_path) — spawn chassis + arm, create a FixedJoint, remove ArticulationRootAPI from the arm.

See scripts/multi_arm_assembly.py.

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.

apply_robot_schema(stage, robot_prim, link_prims, joint_prims, site_prims, robot_type) — apply IsaacRobotAPI on root, IsaacLinkAPI on each link, IsaacJointAPI on each joint, IsaacSiteAPI on grasp/mount frames, then call PopulateRobotSchemaFromArticulation to fill ROBOT_LINKS/ROBOT_JOINTS. Valid robot_type tokens: Default, End Effector, Manipulator, Humanoid, Wheeled, Holonomic, Quadruped, Mobile Manipulators, Aerial.

See scripts/apply_robot_schema.py.

Schema	Applied to	Role
IsaacRobotAPI (Classes.ROBOT_API)	robot root	robot_type, ordered link/joint relations, named-pose container
IsaacLinkAPI (Classes.LINK_API)	each rigid link	mass/visual aux for tools that walk the chain
IsaacJointAPI (Classes.JOINT_API)	each joint	semantic joint metadata
IsaacSiteAPI (Classes.SITE_API)	grasp / mount / reference frames	named frames for IK targets, mounts, sensors
IsaacNamedPose (Classes.NAMED_POSE)	pose container prims	stored joint configurations (see manipulation-ik)
Classes.SURFACE_GRIPPER	end-effector site	author surface gripper via CreateSurfaceGripper
Classes.ATTACHMENT_POINT_API	site or link	attachment points used by accessory tooling

Validation checklist

Before trusting any multi-arm robot:

1. Exactly 1 UsdPhysics.ArticulationRootAPI on the chassis, nowhere else.
2. At least one chassis/root-branch FixedJoint anchors each top-level attached subsystem before flatten-before-deploy.
3. Every joint body is reachable from the single articulation root through one connected joint hierarchy.
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, verifies the entire joint graph is connected to that root, checks for at least one root-branch FixedJoint attachment before flatten-before-deploy, and reports the Robot Schema state.

validate_articulation(usd_path) — assert exactly 1 ArticulationRootAPI, verify hierarchy connectivity, and print root-attached children plus Robot Schema state.

See scripts/validate_articulation.py.

Extend with whatever subsystem path patterns your asset uses. Binary goal: exactly one root, one connected articulated hierarchy, at least one root-branch FixedJoint anchor before flattening, and the Robot Schema overlay present.

Common failures

Symptom	Cause	Fix
Arms render but float	No FixedJoint to chassis	add FixedJoint
Multiple articulation roots	Arm USD has its own root	RemoveAPI(UsdPhysics.ArticulationRootAPI) from arms
Training works but arms independent	Separate articulation trees	single root + FixedJoints
RobotPoser.solve_ik() errors out	missing IsaacRobotAPI / link relations	ApplyRobotAPI + PopulateRobotSchemaFromArticulation
Importer applied IsaacReferencePointAPI	older asset	re-import with current Isaac Sim, or migrate to IsaacSiteAPI (deprecation warning)
robot_type attribute value rejected	typo or stale token	pick from get_allowed_tokens(Attributes.ROBOT_TYPE)