manipulation-ik

マニピュレーション IK

目的

微分 IK、スキーマネイティブなポーザーワークフロー、グラスプフレーム、固定ジョイントによる把持、IK と関節空間モーションを組み合わせて、マニピュレーターアームを制御します。

前提条件

• 検証済みのロボットモーションライブラリを使用する場合：source/libraries のビルドが完了しているか、対応するディストリビューションがインストールされていること。
• RobotPoser、ライブアーティキュレーション、把持／接触、またはインタラクティブな作業を行う場合：Isaac Sim がビルド済みであり、isaac-sim-orchestrator のシェル環境を使用すること。

制限事項

• 特に記載がない限り、対象は Isaac Sim 6 / Kit 110 です。
• サポート対象外のエッジケースについて、NVIDIA の公式ドキュメントに代わるものではありません。

トラブルシューティング

エラー／症状	原因	解決策
フレームが黒い、または空になる	ライトがない、または非 RTX のレンダリングモード	ドームライト／キーライトを追加し、RTX／PathTracing の設定を確認してください
ステージの読み込み時または初回レンダリング時に停止する	MDL のコンパイル、またはステージのサイズが大きすぎる	isaac-sim-troubleshooting の切り分け手順に従ってください

ライブラリ経由と Kit 経由

isaacsim.robot_motion.controllers、isaacsim.robot_motion.cumotion、および isaacsim.robot_motion.experimental.motion_generation モジュールは、 source/libraries/isaacsim/robot_motion/ にあるライブラリ所有のモジュールです。検証済みのスタンドアロン動作には、 motion-generation と source/examples/series/motion_generation/ を使用してください。 RobotPoser、ライブの Articulation 制御、接触／把持の統合、UI は Kit 経由で行います。

各パターンでは Isaac Sim のドキュメントとローカルのサンプルファイルを参照しています。埋め込みコードはパターンの概要であり、正式なソースではありません。必ずリンク先のサンプルを読んでください。上流のコードには、インストール済みの Isaac Sim バージョンが反映されています。

利用可能なスクリプト

スクリプト	目的	引数
scripts/differential_ik_sketch.py	ヤコビアンベースのカスタム微分 IK の概念スケッチ	script --help を参照
scripts/robot_poser_example.py	isaacsim.robot.poser を使用したスキーマネイティブな IK + 名前付きポーズのワークフロー	script --help を参照

スクリプトの実行

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

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

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

使用する場面

• 関節アームを制御して、対象への到達、把持、搬送、配置を行う場合。
• IK ベースのエンドエフェクター制御（関節空間制御との比較）を設定する場合。
• 再利用可能なロボットポーズを名前付きポーズとして保存し、後で適用する場合。
• 把持（FixedJoint、SurfaceGripper、接触ベース）を設定する場合。
• フィードバックループでマニピュレーションの成功を検証する場合。

適切な IK スタックの選択

スタック	モジュール	使用する場面
Articulation 上の微分 IK	isaacsim.core.experimental.prims.Articulation + カスタムヤコビアンソルバー	エンドエフェクターを直接制御する特殊な用途。保守されているサンプルラッパーはありません
スキーマネイティブな IK + 名前付きポーズ	isaacsim.robot.poser.RobotPoser（isaacsim.robot.poser.IKSolverRegistry 経由の LM ソルバー）	オフラインでのポーズ作成、永続化された「pick_position」／「approach」ポーズ
障害物を考慮したリアクティブ制御	motion-generation 経由の isaacsim.robot_motion.cumotion.RmpFlowController	動的な障害物回避、リアクティブな軌道
Pinocchio / PINK	isaacsim.robot_motion.pink.PinkIKController	関節制限／タスク階層に対応した、代替となるフル IK スタック
Lula モーション生成	isaacsim.robot_motion.lula + isaacsim.robot_motion.motion_generation	レガシーです。サポートされていますが、新しい作業では上記のいずれかを使用してください（名称変更の対応表）

キットのサンプルファイル

$ISAAC_SIM_DIR/source/standalone_examples/api/isaacsim.robot_motion.examples/manipulation/からの相対パスです。

トピック	パス
ターゲット追従	follow_target.py
ピック＆プレース	pick_place.py
積み重ね	stacking.py
複数のタスク	multiple_tasks.py

共通の実装は source/extensions/isaacsim.robot_motion.examples/isaacsim/robot_motion/examples/manipulation/ （ManipulationScenario、ロボット構成、コントローラー、インタラクティブなタスクバックエンド）にあります。

レガシー／非推奨のサンプルは$ISAAC_SIM_DIR/source/standalone_examples/deprecated/api/isaacsim.robot.manipulators/にあります。

移行： 保守されているマニピュレーションのサンプルにはisaacsim.robot_motion.examplesを使用してください。

ドキュメントの参照先

トピック	URL
ピック＆プレースのチュートリアル	https://docs.isaacsim.omniverse.nvidia.com/latest/robot_setup_tutorials/tutorial_pickplace_example.html
マニピュレーターのセットアップ（インポート／組み立て）	https://docs.isaacsim.omniverse.nvidia.com/latest/robot_setup_tutorials/tutorial_import_assemble_manipulator.html
物理の基礎（ジョイント、スキーマ）	https://docs.isaacsim.omniverse.nvidia.com/latest/physics/simulation_fundamentals.html
Python スクリプトのインデックス	https://docs.isaacsim.omniverse.nvidia.com/latest/python_scripting/index.html

差動IKのパターン（最新のArticulation）

概念的なソルバーは、次の処理を行います。

1. ヤコビ行列を取得します：self.get_jacobian_matrices()（形状には固定ベースのロボットでも仮想ベースが含まれます。必ずベースの自由度より後の部分をスライスしてください）。
2. 現在のEEポーズから目標までの6自由度のポーズ誤差を計算します。
3. 選択したソルバーを適用して、誤差を関節変位に変換します：
   • damped-least-squares：dq = J^T (J J^T + lambda^2 I)^-1 . error（デフォルト）。
   • pseudoinverse、transpose、singular-value-decompositionも使用できます。
4. set_dof_position_targets(current + dq, dof_indices=arm_dofs)で目標を設定します。

differential_ik_step(arm, end_effector, end_effector_link_index, target_pos, target_quat, arm_dofs, method, damping, scale) — ヤコビ行列を計算し、IKの関節変位を解き、set_dof_position_targetsで適用します。これは概念的なパターンです。本番環境での制御には、保守されているRMPflowのサンプルを使用してください。

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

調整（まず控えめな設定から始め、安定したら値を大きくします）：

パラメーター	控えめ	中程度	積極的
damping	0.1	0.05	0.01
1ステップあたりのmax_delta	0.02 rad	0.05 rad	0.10 rad
ドライブのstiffness	200	400	800

積極的な設定では、ペイロードの下でPhysXが発散することがあります。

ハイブリッドIK＋関節空間（6自由度未満のアーム）

劣駆動アームでは、純粋な差動IKは次の状況で失敗します。

• ペイロードを運びながら大きく横方向に移動する場合。
• 運動学的特異点に近い構成。
• 関節制限を越えて動かす場合。

パターン：精密な動作（接近、下降、最終配置）にはIKを使い、長距離の搬送（持ち上げ、横移動、下降）には関節空間補間を使います。順序立てた例については、保守されているマニピュレーションコントローラーを参照してください。

スキーマネイティブIK＋名前付きポーズ（RobotPoser）

ポーズの作成、永続化、再生にはisaacsim.robot.poserを使用します。これは運動学チェーンとIKの実装を管理し、ロボット上のIsaacNamedPoseプリムに名前付きポーズのデータを保存します。

solve_and_store_pose(stage, robot_prim, start_prim, end_prim, target_pos, target_orient, pose_name) — スキーマを検証し、IKを解き、関節に適用して、名前付きポーズとして保存します。再生と永続化にはapply_stored_pose／export_all_posesを使用します。

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

FK／DOF目標の適用に使えるスタンドアロンヘルパー（RobotPoserは不要）：

from isaacsim.robot.poser import apply_joint_state, apply_joint_state_anchored
apply_joint_state(stage, robot_prim, joint_values)          # FK off-sim / DOF targets when playing
apply_joint_state_anchored(stage, robot_prim, joint_values, # keep anchor at world pose
                           anchor_prim=base_link_prim)

IKソルバーはisaacsim.robot.poser.IKSolverRegistryを介してプラグイン可能です。付属のLMソルバー（isaacsim.robot.poser.lm_ik）がデフォルトです。

障害物を考慮したモーションコントローラー

cuMotion および RMPflow コントローラーのセットアップ（ワールドへのバインド、 RobotState、制御ループのタイミング、リセットの順序、対応ロボットの設定、 障害物の同期を含む）には、motion-generation を使用してください。このスキルでは、 このスタックを使うべき状況を判断し、マニピュレーションと把持の部分を検証するだけです。 ドキュメントに記載されたローダーを使用してください。コントローラー設定を手動で構築しないでください。

把持フレームの検出（最初に実行）

ほとんどのアセットには把持フレームが付属していません。IK の前に、次の手順を実行してください。

1. グリッパーの USD を調べ、指を閉じたときの中心にあるフレームを探します。
2. 存在しない場合は、グリッパーリンクの子 Xform を追加し、把持中心に配置します。IsaacSiteAPI（robot_schema の ApplySiteAPI）を設定し、後続のツールで認識できるようにします。
3. そのサイトを IK のターゲットとして使用します。目標ポーズは、把持したときにオブジェクトの中心が位置する場所であり、グリッパー本体の位置ではありません。

把持

FixedJoint（補助ありの剛体把持のみ）

パターンの出典：保守されているインタラクティブな pick_place_task.py と UsdPhysics.FixedJoint。接触した瞬間に、グリッパーからオブジェクトへの相対変換を必ず計算してください。オフセットをハードコードしないでください。オフセットをハードコードすると、高い剛性によって PhysX のスナップや爆発が発生します。

自由に動く剛体に対する摩擦のみの平行把持は不安定です。持ち上げると保持できても、搬送時の加速度で滑ることがあります。タスクで補助ありの把持が許可されている場合は、グリップ力や摩擦の調整よりも FixedJoint を優先してください。接触時にアタッチし、グリッパーは見た目上閉じた状態を保ち、リリース時にジョイントを削除して、オブジェクトが重力で落ち着くようにします。

厳密な接触のみのタスクでは、オブジェクトはグリッパーの衝突力／接触力によって移動しなければなりません。成功させるための手段として、FixedJoint、D6 ジョイント、アタッチメント、ポーズ追従、オブジェクトのポーズ書き込み、キネマティックな保持、ダイナミクスの無効化、リリース後の安定化を使用しないでください。

SurfaceGripper（UR10 の例で使用する真空／磁気グリッパー）

パターンの出典：manipulation/ur10_palletizing.py（DirectSurfaceGripper）。

from isaacsim.robot.surface_gripper import _surface_gripper as surface_gripper

iface = surface_gripper.acquire_surface_gripper_interface()
gripper_path = f"{end_effector_path}/SurfaceGripper"
iface.close_gripper(gripper_path)   # attach
iface.open_gripper(gripper_path)    # release
status = iface.get_gripper_status(gripper_path)  # GripperStatus.{Open,Closed}

usd.schema.isaac.robot_schema.CreateSurfaceGripper を使ってロボット上に作成します。

把持データセットのワークフロー

把持データセットの生成については、isaacsim.replicator.grasping（GraspingManager、GraspPhase）および source/standalone_examples/api/isaacsim.replicator.grasping/grasping_workflow_sdg.py を参照してください。

把持の検証（フィードバックループ）

操作デモを実行または記録する前に、対象物を検証してください。把持、引き寄せ、配置、押し出し、または把持したと主張する対象物は、物理シミュレーションに基づいている必要があります。具体的には、剛体またはアーティキュレーションの状態、コリジョン形状、タスクに適した質量／慣性、および実行時の姿勢読み戻し（物理ビューまたは prim API）が必要です。プローブやデバッグにはビジュアルのみのメッシュを使用できますが、最終結果で成功したと主張する対象物は、物理シミュレーションに基づいている必要があります。

実行後、以下の3つのゲートでツールの姿勢だけでなく、対象物の状態を順に検証し、最初の失敗で停止してください。

ゲート	必要な証拠	失敗時の対応
把持／接触	対象物を指で囲んでいること。対象物が把持フレームから約 2 cm 以内にあること	把持フレームのオフセットまたは IK ターゲットを調整する
持ち上げ／保持	対象物が支持面から離れ、計測した時間にわたりリフトしきい値より上で保持されること。XY のドリフトが制限内であること。速度が収束すること	グリッパーが作動していない、または把持オフセットが不適切（補助ありの場合：FixedJoint がない、または不適切）
配置／解放	グリッパーが開き、対象物が支持面上で約 5 cm 以内に収束すること。最終姿勢／速度がしきい値を満たすこと。以前に配置した対象物も引き続き条件を満たすこと	搬送軌道が目標を外れている

• 成功はツールの姿勢ではなく、対象物の姿勢／向きで測定します。ツールが収束していても、対象物が滑ったり、飛び出したり、高い位置に残ったりすることがあります。滑らかな動きは必要ですが、それだけでは十分ではありません。
• 配置フェーズのゲートでは、エンドエフェクターの収束だけでなく、解放後の対象物の姿勢を使用してください。
• 意図的な待機または収束フェーズでない限り、動作フェーズのタイムアウトは失敗として扱ってください。
• 複数対象物の場合、後続のアプローチ、配置、後退のたびに、すでに配置した対象物の範囲を再検証してください。
• 最新の実行からの視覚的な証拠を必須とします。ロボット、対象物、支持面、把持／接触領域、マーカーが映った固定カメラの動画またはスクリーンショットを用意してください。
• 厳密な接触のみを要求するタスクは、接触力だけで成功させる必要があります（上記のとおり、FixedJoint などの補助は使用しないでください）。ゲートに失敗した場合は、数値と視覚の証拠を添えて報告してください。結果を成功に見せるために、隠れた姿勢補助を決して追加しないでください。

ルール

1. まずローカルの例を読んでください。このスキルで説明するのはパターンであり、構文ではありません。
2. IK の前に、必ず把持フレーム（IsaacSiteAPI）を作成するか、特定してください。
3. IK ゲインは控えめな値から始め、安定性を確認してから上げてください。
4. URDF インポーターは PhysxArticulationAPI を自動的に適用します。アーティキュレーションを手動で作成する場合は、ベースリンクに適用してください。
5. SimulationApp を直接使用する場合、スタンドアロンスクリプトは isaaclab.sh -p ではなく $ISAAC_SIM_DIR/python.sh で実行してください。
6. ヤコビアンの列の配置は、固定ベースのロボットでは [仮想ベース DOF | 実 DOF] です。必ず仮想ベースの分をスライスして除いてください。
7. 再利用可能な姿勢は store_named_pose で保存してください。セッションごとに IK を最初から解き直さないでください。
8. ライブラリの診断には isaacsim.common.logging.Logger を、Kit アダプターでは carb.log_* を使用してください。print() は意図した結果の出力に限って使用してください。証拠アーティファクトを書き出しても、診断ログの代わりにはなりません。
9. 各フェーズで視覚的に検証してください。滑らかな動きは、操作の成功を意味しません。
10. DOF が 6 未満のアームでは、ハイブリッド IK と関節空間制御を実用的なデフォルトとしてください。

教訓（2026-04-08）

• SO-101（5 DOF）：純粋な DLS IK は局所的な動作では収束します（誤差約 0.008 m）が、負荷がかかった状態で横方向に搬送すると発散します。ハイブリッド制御が必要です。
• ハードコードしたオフセットと高い剛性を使った FixedJoint は、PhysX の急なスナップと爆発を引き起こします。把持時にオフセットを計算してください。
• ヤコビアンの仮想ベースのオフセットは見落としやすく、IK が気付かれないまま機能しなくなります。必ずベースの分をスライスして除いてください。