OpenParable
Skip to content
← Back to skills

Usd Articulation

Development
usd-articulation

Usd Articulation is an Agent Skill for development published in the isaac-sim/IsaacSim repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Validate and build multi-arm robot articulations in USD for Isaac Sim 6 / Lab. Covers programmatic assembly (chassis + arms + `FixedJoint`s), `ArticulationRootAPI` placement, the modern Isaac Robot Schema overlay (`IsaacRobotAPI`, `IsaacLinkAPI`, `IsaacJointAPI`, `IsaacSiteAPI`, `IsaacNamedPose`, `KinematicChain`), `PopulateRobotSchemaFromArticulation` for retrofitting existing USDs, flatten-before-deploy, and the validation checklist (articulation roots, joint connections, robot-schema integrity, floating arms). Use when creating multi-limb robots in USD, retrofitting an existing articulation with the Robot Schema, debugging "floating arms" or disconnected geometry, or flattening articulations for deployment to Isaac Lab.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/isaac-sim/IsaacSim/blob/HEAD/skills/usd-articulation/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/usd-articulation, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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)
SchemaApplied toRole
IsaacRobotAPI (Classes.ROBOT_API)robot rootrobot_type, ordered link/joint relations, named-pose container
IsaacLinkAPI (Classes.LINK_API)each rigid linkmass/visual aux for tools that walk the chain
IsaacJointAPI (Classes.JOINT_API)each jointsemantic joint metadata
IsaacSiteAPI (Classes.SITE_API)grasp / mount / reference framesnamed frames for IK targets, mounts, sensors
IsaacNamedPose (Classes.NAMED_POSE)pose container primsstored joint configurations (see manipulation-ik)
Classes.SURFACE_GRIPPERend-effector siteauthor surface gripper via CreateSurfaceGripper
Classes.ATTACHMENT_POINT_APIsite or linkattachment points used by accessory tooling

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

SymptomCauseFix
Arms render but floatNo FixedJoint to chassisadd FixedJoint
Multiple articulation rootsArm USD has its own rootRemoveAPI(UsdPhysics.ArticulationRootAPI) from arms
Training works but arms independentSeparate articulation treessingle root + FixedJoints
RobotPoser.solve_ik() errors outmissing IsaacRobotAPI / link relationsApplyRobotAPI + PopulateRobotSchemaFromArticulation
Importer applied IsaacReferencePointAPIolder assetre-import with current Isaac Sim, or migrate to IsaacSiteAPI (deprecation warning)
robot_type attribute value rejectedtypo or stale tokenpick from get_allowed_tokens(Attributes.ROBOT_TYPE)