usd-articulation

USD 关节结构体 —— 多臂机器人

用途

在部署前，使用 ArticulationRootAPI、固定关节和 Isaac 机器人架构叠加层组装并验证多连杆机器人关节结构体。

前置条件

• 对于独立架构编写：匹配的 OpenUSD 和 isaacsim-robot-schema 库构件。
• 对于实时关节结构体交互、扩展命令或渲染：已构建的 Isaac Sim，以及来自 isaac-sim-orchestrator 的环境。

限制

• 目标为 Isaac Sim 6 / Kit 110，除非某个章节另有说明。
• 不能替代 NVIDIA 官方文档来处理不受支持的边缘情况。

故障排除

错误 / 症状	原因	解决方案
画面全黑或空白	缺少灯光或未使用 RTX 渲染模式	添加穹顶灯 / 主光源；确认 RTX / PathTracing 设置
加载场景或首次渲染时卡住	MDL 编译或场景过大	按照 isaac-sim-troubleshooting 中的隔离步骤操作

架构编写与运行时交互

机器人架构由 source/libraries/isaacsim_usd_schemas/robot/ 生成并打包；使用该发行包通过 OpenUSD 独立应用和验证架构。对于机器人运动架构元数据，请使用单独的 isaacsim.robot_motion.schema 模块。仅导入这些架构包无需 Kit 扩展注册表。

Kit 命令、实时时间轴交互、UI 和渲染仍通过 Kit 路径进行。

机器人 USD 上叠加了两层：

1. 物理：UsdPhysics.ArticulationRootAPI、UsdPhysics.Joint、UsdPhysics.RigidBodyAPI、PhysxSchema.PhysxArticulationAPI。
2. 机器人架构（usd.schema.isaac.robot_schema）：语义叠加层，供 isaacsim.robot.poser、导入器、机械臂示例，以及任何遍历“此机器人的连杆 / 关节 / 命名姿势”的工具使用。

规则：视觉上看起来合理，不代表机械结构正确。如果它不能活动，就等于不存在。

可用脚本

脚本	用途	参数
scripts/apply_robot_schema.py	将 Isaac Robot Schema 叠加层应用到现有关节结构体 USD	参见脚本 --help
scripts/multi_arm_assembly.py	使用 FixedJoints 在 USD 中组装多臂机器人	参见脚本 --help
scripts/validate_articulation.py	验证多臂机器人 USD 关节结构体	通过 sys.argv 传递 CLI 参数（参见脚本 --help）

运行脚本

在提供技能执行辅助函数的 Agent 运行时中，使用 run_script() 调用辅助函数：

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

在已构建的 Isaac Sim 树中，从 _build/*/release 运行同一文件：Linux 使用 ./python.sh，Windows 使用 python.bat；如果 shell 辅助程序不需要模拟器，也可以直接执行。

多臂组装（正确模式）

assemble_multi_arm_robot(stage, chassis_usd, arm_usd, robot_root, arm_offset, chassis_body_path, arm_base_path) — 生成底盘和机械臂，创建 FixedJoint，并从机械臂中移除 ArticulationRootAPI。

参见 scripts/multi_arm_assembly.py。

不起作用的做法

• 通过子层合成两次引用同一个机械臂 USD。
• 使用 over "Geometry" 在部件层中添加机械臂。
• 认为视觉上存在就等于物理上已连接。

Robot Schema 覆盖层（Kit 110）

在物理层之上应用现代 Isaac Robot Schema。URDF/MJCF 导入器会自动执行此操作；对于手动创作或改造的 USD，请手动应用。

apply_robot_schema(stage, robot_prim, link_prims, joint_prims, site_prims, robot_type) — 在根节点上应用 IsaacRobotAPI，在每个链接上应用 IsaacLinkAPI，在每个关节上应用 IsaacJointAPI，在抓取/安装框架上应用 IsaacSiteAPI，然后调用 PopulateRobotSchemaFromArticulation 填充 ROBOT_LINKS/ROBOT_JOINTS。有效的 robot_type 令牌：Default、End Effector、Manipulator、Humanoid、Wheeled、Holonomic、Quadruped、Mobile Manipulators、Aerial。

参见 scripts/apply_robot_schema.py。

Schema	应用于	作用
IsaacRobotAPI（Classes.ROBOT_API）	机器人根节点	robot_type、有序链接/关节关系、命名姿势容器
IsaacLinkAPI（Classes.LINK_API）	每个刚性链接	为遍历运动链的工具提供质量/视觉辅助信息
IsaacJointAPI（Classes.JOINT_API）	每个关节	关节语义元数据
IsaacSiteAPI（Classes.SITE_API）	抓取/安装/参考框架	用于 IK 目标、安装件、传感器的命名框架
IsaacNamedPose（Classes.NAMED_POSE）	姿势容器 prim	存储的关节配置（参见 manipulation-ik）
Classes.SURFACE_GRIPPER	末端执行器 site	通过 CreateSurfaceGripper 创作表面夹爪
Classes.ATTACHMENT_POINT_API	site 或链接	配件工具使用的连接点

验证清单

在信任任何多臂机器人之前：

1. 底盘上恰好有 1 个 UsdPhysics.ArticulationRootAPI，其他位置都没有。
2. 在展平后部署之前，至少有一个底盘/根分支 FixedJoint 用于锚定每个顶层连接的子系统。
3. 每个关节体都能通过一个连通的关节层级从唯一的 articulation 根节点到达。
4. 根节点上存在 IsaacRobotAPI；robot_type 设置为有效令牌。
5. 已填充 ROBOT_LINKS / ROBOT_JOINTS 关系（如果未填充，请调用 PopulateRobotSchemaFromArticulation）。
6. 每个抓取框架都带有 IsaacSiteAPI（而非已弃用的 IsaacReferencePointAPI）。
7. 从四个角度渲染（正面、侧面、3/4 视角、顶部）。
8. 将图像发送给视觉大模型，并提出二元问题（“机械臂已连接？通过/失败”）。

验证代码片段（独立运行）

通过 $ISAAC_SIM_DIR/python.sh 运行。强制要求恰好有一个 ArticulationRootAPI，验证整个关节图与该根节点连通，检查展平后部署前是否至少有一个根分支 FixedJoint 连接，并报告 Robot Schema 状态。

validate_articulation(usd_path) — 断言恰好有 1 个 ArticulationRootAPI，验证层级连通性，并打印根节点连接的子项以及 Robot Schema 状态。

参见 scripts/validate_articulation.py。

根据资产使用的子系统路径模式进行扩展。二元目标：恰好一个根节点、一个连通的关节层级、展平前至少有一个根分支 FixedJoint 锚点，并且存在 Robot Schema 覆盖层。

常见故障

症状	原因	修复方法
机械臂渲染出来但悬空	没有连接到底盘的 FixedJoint	添加 FixedJoint
存在多个 articulation 根节点	机械臂 USD 有自己的根节点	从机械臂中执行 RemoveAPI(UsdPhysics.ArticulationRootAPI)
训练正常但机械臂彼此独立	存在独立的 articulation 树	使用单一根节点 + FixedJoint
RobotPoser.solve_ik() 报错	缺少 IsaacRobotAPI / 链接关系	使用 ApplyRobotAPI + PopulateRobotSchemaFromArticulation
导入器应用了 IsaacReferencePointAPI	资产较旧	使用当前版本的 Isaac Sim 重新导入，或迁移到 IsaacSiteAPI（弃用警告）
robot_type 属性值被拒绝	拼写错误或令牌已过时	从 get_allowed_tokens(Attributes.ROBOT_TYPE) 中选择