manipulation-ik

操作 IK

用途

通过微分 IK、原生 Schema 的姿态器工作流、抓取坐标系、固定关节抓取，以及混合 IK 与关节空间运动来控制机械臂。

前置条件

• 使用已验证的机器人运动库路线：完成 source/libraries 构建，或安装匹配的发行版本。
• 使用 RobotPoser、实时关节控制、抓取／接触或交互式工作：构建 Isaac Sim，并使用 isaac-sim-orchestrator 中的 shell 环境。

限制

• 目标版本为 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	基于自定义 Jacobian 的微分 IK 概念示意	参见脚本 --help
scripts/robot_poser_example.py	使用 isaacsim.robot.poser 的原生 Schema IK + 命名姿态工作流	参见脚本 --help

运行脚本

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

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

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

适用场景

• 控制关节臂到达目标、抓取、搬运和放置物体。
• 设置基于 IK 的末端执行器控制（而非关节空间控制）。
• 将可复用的机器人姿态保存为命名姿态，以便稍后应用。
• 设置抓取（FixedJoint、SurfaceGripper、基于接触的抓取）。
• 通过反馈循环验证操作是否成功。

选择合适的 IK 技术栈

技术栈	模块	适用场景
在 Articulation 上进行微分 IK	isaacsim.core.experimental.prims.Articulation + 自定义 Jacobian 求解器	专用的直接末端执行器控制；没有受维护的示例封装
原生 Schema 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	旧版；仍受支持，但新项目建议使用上述方案之一（重命名对照表）

Kit 示例文件

相对于 $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. 计算当前末端执行器位姿到目标位姿的 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
每步的 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 prim 存储在机器人上。

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)

可通过 isaacsim.robot.poser.IKSolverRegistry 插拔 IK 求解器；捆绑的 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）。仅用于探测和调试的网格可以只有视觉效果，但最终结果中声称已操作的物体必须由物理状态支撑。

执行后，请在以下三个关卡依次验证物体状态（而不只是工具位姿），在首个失败处停止：

关卡	所需证据	失败处理
抓取/接触	手指环绕物体；物体位于抓取坐标系约 2 cm 范围内	调整抓取坐标系偏移量或 IK 目标
抬升/保持	物体离开支撑面，并在测量时间窗口内保持在抬升阈值以上；XY 漂移受限；速度趋于稳定	夹爪未啮合；抓取偏移量错误（辅助方式：缺少或配置错误的 FixedJoint）
放置/释放	夹爪打开；物体在支撑面上约 5 cm 范围内稳定下来；最终位姿/速度满足阈值；先前放置的物体仍通过验证	运输轨迹未到达目标

• 成功与否应根据物体位姿/朝向衡量，而不是工具位姿：工具可能已收敛，但物体仍会滑落、弹飞或悬在高处。平滑运动是必要条件，但并不足以证明操作成功。
• 放置阶段关卡应使用释放后的物体位姿，而不只是末端执行器的收敛状态。
• 除非某个阶段是有意停留或等待稳定，否则应将运动阶段超时视为失败。
• 多物体任务：每次后续接近、放置和撤离之后，都要重新验证已放置物体组成的前缀序列。
• 必须提供最新一次运行的视觉证据：固定机位视频或截图，展示机器人、物体、支撑面、抓取/接触区域和标记。
• 纯接触任务必须仅靠接触力成功（不得使用 FixedJoint 或其他辅助方式，见上文）。如果某个关卡失败，应提供数值和视觉证据并报告失败；绝不可添加隐藏的位姿辅助来伪装成功结果。

规则

1. 先阅读本地示例；本技能介绍的是模式，而不是语法。
2. IK 之前务必创建或确定抓取坐标系（IsaacSiteAPI）。
3. 从保守的 IK 增益开始；确认稳定后再提高。
4. URDF 导入器会自动应用 PhysxArticulationAPI；如果手动创建关节结构，需在基座连杆上应用该 API。
5. 直接使用 SimulationApp 时，运行独立脚本应使用 $ISAAC_SIM_DIR/python.sh，而不是 isaaclab.sh -p。
6. 雅可比矩阵的列布局为：固定基座机器人使用 [虚拟基座自由度 | 实际自由度]。务必跳过虚拟基座部分。
7. 使用 store_named_pose 存储可复用位姿；不要每次会话都从头重新求解 IK。
8. 库诊断使用 isaacsim.common.logging.Logger，Kit 适配器中使用 carb.log_*。仅在有意输出结果时使用 print()；写入证据文件不能替代诊断日志记录。
9. 在每个阶段进行视觉验证。运动平滑不等于操作成功。
10. 对于自由度少于 6 的机械臂，混合式 IK + 关节空间控制是实用的默认方案。

经验总结（2026-04-08）

• SO-101，5 自由度：纯 DLS IK 对局部移动可收敛（误差约为 0.008 m），但在负载下进行横向运输时会发散。必须采用混合方式。
• 使用硬编码偏移量和高刚度的 FixedJoint 会导致 PhysX 突跳并引发爆炸。在抓取时计算偏移量。
• 雅可比矩阵的虚拟基座偏移容易被忽略，导致 IK 静默失效。务必跳过基座部分。