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 には、次の 2 つのレイヤーを適用します。

1. 物理：UsdPhysics.ArticulationRootAPI、UsdPhysics.Joint、UsdPhysics.RigidBodyAPI、PhysxSchema.PhysxArticulationAPI。
2. ロボットスキーマ（usd.schema.isaac.robot_schema）：isaacsim.robot.poser、インポーター、マニピュレーターのサンプル、および「このロボットのリンク／ジョイント／名前付きポーズ」をたどるすべてのツールで使用される、セマンティックオーバーレイです。

ルール：見た目がもっともらしいことは、機械的に正しいことを意味しません。アーティキュレーションしないものは、存在しないも同然です。

利用可能なスクリプト

スクリプト	目的	引数
scripts/apply_robot_schema.py	既存の USD アーティキュレーションに Isaac ロボットスキーマオーバーレイを適用します	script --help を参照
scripts/multi_arm_assembly.py	FixedJoint を使用して、USD 内に複数アームロボットを組み立てます	script --help を参照
scripts/validate_articulation.py	複数アームロボットの USD アーティキュレーション構造を検証します	sys.argv 経由の CLI 引数（script --help を参照）

スクリプトの実行

スキル実行ヘルパーを公開しているエージェントランタイムからは、run_script() でヘルパーを呼び出します。

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

ビルド済みの Isaac Sim ツリーからは、_build/*/release にある ./python.sh（Linux）または python.bat（Windows）で同じファイルを実行するか、シミュレーターを必要としない場合はシェルヘルパーを直接実行します。

複数アームの組み立て（正しいパターン）

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 を 2 回参照する。
• パーツレイヤーで over "Geometry" を使用してアームを追加する。
• 視覚的に存在することが物理的な接続を意味すると考える。

Robot Schema オーバーレイ（Kit 110）

物理レイヤーの上に最新の Isaac Robot Schema を適用します。URDF/MJCF インポーターでは自動的に適用されます。手作業で作成した USD、または後から改修した 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 を参照してください。

スキーマ	適用先	役割
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 または link	アクセサリーツールで使用するアタッチメントポイント

検証チェックリスト

複数のアームを持つロボットを信頼する前に、次の項目を確認してください。

1. シャーシ上に UsdPhysics.ArticulationRootAPI がちょうど 1 つだけあり、それ以外の場所にはないこと。
2. flatten-before-deploy の前に、各最上位の接続サブシステムを固定するシャーシ／ルートブランチの FixedJoint が少なくとも 1 つあること。
3. すべてのジョイントボディが、接続された単一のジョイント階層を通じて、単一のアーティキュレーションルートから到達可能であること。
4. ルートに IsaacRobotAPI があり、robot_type が有効なトークンに設定されていること。
5. ROBOT_LINKS／ROBOT_JOINTS リレーションが設定されていること（未設定の場合は PopulateRobotSchemaFromArticulation を呼び出します）。
6. 各把持フレームに IsaacSiteAPI があること（非推奨の IsaacReferencePointAPI ではないこと）。
7. 4 方向（正面、側面、斜め上、上面）からレンダリングします。
8. 二択の質問（「アームは接続されていますか？ PASS/FAIL」）を使って、ビジョン LLM に送信します。

検証スニペット（単体で実行可能）

$ISAAC_SIM_DIR/python.sh から実行します。ArticulationRootAPI がちょうど 1 つであることを強制し、ジョイントグラフ全体がそのルートにつながっていることを検証します。また、flatten-before-deploy の前にルートブランチの FixedJoint アタッチメントが少なくとも 1 つあることを確認し、Robot Schema の状態を報告します。

validate_articulation(usd_path) — ArticulationRootAPI がちょうど 1 つであることをアサートし、階層の接続性を検証して、ルートに接続された子要素と Robot Schema の状態を出力します。

scripts/validate_articulation.py を参照してください。

アセットで使用しているサブシステムのパスパターンに合わせて拡張してください。二択の目標は、ルートが 1 つ、接続されたアーティキュレーション階層が 1 つ、平坦化前のルートブランチに FixedJoint アンカーが少なくとも 1 つあり、Robot Schema オーバーレイが存在することです。

よくある失敗

症状	原因	修正方法
アームはレンダリングされるが、浮いている	シャーシへの FixedJoint がない	FixedJoint を追加する
アーティキュレーションルートが複数ある	アーム USD に独自のルートがある	アームから RemoveAPI(UsdPhysics.ArticulationRootAPI) を実行する
トレーニングは動作するが、アームが独立している	アーティキュレーションツリーが分かれている	単一のルートと FixedJoint を使用する
RobotPoser.solve_ik() がエラーになる	IsaacRobotAPI／リンクリレーションがない	ApplyRobotAPI と PopulateRobotSchemaFromArticulation を実行する
インポーターが IsaacReferencePointAPI を適用した	古いアセット	現行の Isaac Sim で再インポートするか、IsaacSiteAPI に移行する（非推奨の警告）
robot_type 属性値が拒否される	タイプミスまたは古いトークン	get_allowed_tokens(Attributes.ROBOT_TYPE) から選択する