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

• Built Isaac Sim ($ISAAC_SIM_DIR or _build/linux-x86_64/release).
• NVIDIA GPU with a current driver (nvidia-smi).
• Shell env contract from isaac-sim-orchestrator: $ISAAC_SIM_DIR, $ISAAC_LAB_DIR, $WORKSPACE_DIR.

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
Extension or import not found	Wrong $ISAAC_SIM_DIR or stale build	Point env vars at _build/linux-x86_64/release or rebuild
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

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)