企业官网建设流程全解析

ManiSkill 控制器与动作空间完全指南：从 PD 关节控制到末端执行器位姿 IK 控制

【免费下载链接】ManiSkillManipulation Skill Framework, an open source GPU parallelized robotics simulator and benchmark项目地址: https://gitcode.com/GitHub_Trending/ma/ManiSkill

控制器（Controller）是 ManiSkill 中连接策略（Policy）与机器人本体的核心接口：每当你对环境执行step并给出一个动作（action），该动作会被送往当前选中的控制器，由它转换为送往机器人的控制信号。本文以 controllers.md 为骨架，结合 controllers 模块源码 与 Panda 机器人配置，系统讲解 ManiSkill 内置的各类控制器、动作空间的构成方式、末端执行器控制器的坐标系原理，以及 Panda 机器人上全部控制模式的数学定义。读完本文，你将掌握如何为任务选择控制器、理解每个控制器的动作维度与含义，并能在自定义机器人上正确配置控制器。

控制器在 ManiSkill 中的定位

ManiSkill 中所有机器人（无论 CPU 仿真还是 GPU 仿真）在最底层都是通过**关节位置（joint position）或关节速度（joint velocity）**两种方式被控制的——即指定每个关节"应该到哪"或"应该多快"。控制器位于用户/策略与这一底层控制之间，将高层、更符合直觉的动作翻译成底层信号。

例如arm_pd_ee_delta_pose控制器接收的是末端执行器的相对位姿增量，通过逆运动学（IK）把输入动作换算成各关节的目标位置，再由机器人的PD 控制器驱动电机趋向目标。理解控制器需要记住三个关键事实：

• 控制器定义了任务的动作空间：选择哪种控制器，直接决定策略输出的动作维度与物理含义；
• 同一机器人可为不同关节组配置不同控制器：最终动作空间是所有控制器动作空间的拼接（concatenation）；
• 单个机器人可以有多套控制器组合：例如 Panda 机器人内置了 11 种控制模式，可在创建环境时通过control_mode参数切换。

需要说明的是：文档中曾注释提到，虽然基于 IK 的pd_ee_delta_pose类控制器在强化学习训练中可能采样效率更高，但此类控制器在 GPU 仿真中的运行开销较大，可能拖慢 RL 训练速度，选择控制器时需要权衡训练效率与仿真开销。

动作空间如何拼接：DictController 与 CombinedController

从源码看，控制器的装配发生在 BaseAgent.set_control_mode：当_controller_configs中某个控制模式的值是一个dict（例如 Panda 的pd_ee_delta_pose=dict(arm=..., gripper=...)）时，会构造 CombinedController。它是 DictController 的扁平化视图：

• DictController为每个子控制器保留独立的spaces.Dict动作空间；
• CombinedController通过flatten_action_spaces将所有子控制器动作空间拼接成一个spaces.Box，并通过action_mapping记录每个子控制器在扁平向量中的起止索引（to_action_dict/from_action_dict用于两种表示的相互转换）。

因此 Panda 的pd_ee_delta_pose模式实际动作维度为3（平移增量）+ 3（旋转增量）+ 1（夹爪目标位置）= 7维，而pd_joint_pos模式为7（关节位置）+ 1（夹爪）= 8维。

内置控制器总览

所有控制器的配置类都从 ControllerConfig 派生，可在 controllers/init.py 中看到完整的导出清单。下面逐一介绍。

Passive（被动控制器）

from mani_skill.agents.controllers import PassiveControllerConfig

Passive 控制器让指定关节不接受任何动作控制。它不产生动作空间维度（动作空间为空），只负责按配置设置关节的阻尼、力限与摩擦等驱动属性。源码中 PassiveController 的set_action与before_simulation_step均为空实现，sets_target_qpos与sets_target_qvel均为False。

典型应用是 CartPole 环境：CartPole 任务只允许控制滑块，而摆杆的铰链关节hinge_1被配置为被动控制：

rest = PassiveControllerConfig(["hinge_1"], damping=0, friction=0)

配置参数包括damping（阻尼）、force_limit（力限，默认 1e10）、friction（摩擦，默认 0.0）。

PD Joint Position（PD 关节位置控制）

from mani_skill.agents.controllers import PDJointPosControllerConfig

该控制器通过 PD 控制器，用动作直接设定给定关节的目标关节位置。动作空间维度等于受控关节数，上下界默认为关节限位（也可通过lower/upper覆盖，见 PDJointPosControllerConfig）。核心参数：

从 PDJointPosController.set_action 可看到三种目标计算方式：use_delta=False时 $\bar{q}=a$（绝对目标）；use_delta=True, use_target=False时 $\bar{q}(t)=q(t)+a$；use_delta=True, use_target=True时 $\bar{q}(t)=\bar{q}(t-1)+a$。

PD EE Pos / PD EE Pose（末端执行器位置/位姿控制）

from mani_skill.agents.controllers import PDEEPosControllerConfig from mani_skill.agents.controllers import PDEEPoseControllerConfig

这是 ManiSkill 中最常用的高层控制器，允许直接控制机器人末端执行器（或任意 link）的位置/位姿，而非逐个关节设置。PD EE Pos只控制平移（3 维），PD EE Pose同时控制平移与旋转（6 维）。两者都支持增量（delta）与绝对（非 delta）两种模式，内部在每个环境时间步根据动作计算末端新目标位姿，再通过 IK 求出能实现该位姿的关节动作——配置项的本质就是改变"新目标位姿"的计算方式。配置关键参数见 PDEEPosControllerConfig 与 PDEEPoseControllerConfig：

需要特别注意：PD EE Pose控制器对旋转动作的归一化是按范数裁剪而非逐元素缩放——旋转动作的欧拉角会被限制在单位球内再乘以rot_lower（见 PDEEPoseController._clip_and_scale_action），以避免旋转增量过大导致 IK 失效。另外，从源码注释可以确认，GPU 仿真目前**只支持root_translation（Pos）与root_translation:root_aligned_body_rotation（Pose）**这两种坐标系（见 PDEEPosController._check_gpu_sim_works），使用其他 frame 组合在 GPU 仿真下会触发断言错误。

三个关键坐标系

理解该控制器必须先区分三个相关变换坐标系（见原文档配图 robot-with-frames.png，RGB 轴分别对应 X/Y/Z，其中 Z 轴是 ManiSkill/SAPIEN 中规范的"上下"方向，与其他仿真器不同）：

1. World Frame（世界坐标系）；
2. Root Link Frame（机器人根连杆坐标系）；
3. End Effector / Body Frame（末端执行器/机体坐标系，PD EE 控制器实际支持控制任意 link）。

配图中受控的 body 是一个表示工具中心点（TCP）的虚拟 link，它是真实末端 link 的一个简单偏移，因此 body 坐标系原点位于夹爪两指之间。

增量控制（Delta Control，默认启用）

增量控制由use_delta属性开启（默认True），动作表示末端位姿的增量：平移增量以米为单位，旋转增量以弧度为单位（未归一化时）。控制器对平移和旋转进行解耦控制——平移动作不影响旋转动作，反之亦然，因此 Pose 控制器共 6 维动作（3 平移 + 3 旋转）。

平移与旋转各自有两种坐标系选择，因此共有 4 种 frame 组合，命名规则为<frame>_translation:<frame>_rotation：

# Naming Scheme is <frame>_translation:<frame>_rotation # The following 4 frame combos are possible "body_translation:root_aligned_body_rotation", "root_translation:root_aligned_body_rotation", "body_translation:body_aligned_body_rotation", "root_translation:body_aligned_body_rotation", # This is the default frame combo "root_translation:root_aligned_body_rotation"

平移（Translation）：用户给出 X、Y、Z 三个方向的位移增量。两种平移坐标系为 root frame（根坐标系方向）与 body frame（机体坐标系方向），由compute_target_pose中的实现可见（PDEEPosController.compute_target_pose）：root_translation下新目标位置为delta_pose * prev_ee_pose_at_base，body_translation下为prev_ee_pose_at_base * delta_pose。对应的动画演示视频位于 docs/source/_static/videos/controllers/（root_translation.mp4、body_translation.mp4）。

旋转（Rotation）：用户给出 X、Y、Z 三个轴的旋转增量（弧度），内部按XYZ 欧拉角处理并转换为四元数，再由 IK 换算为关节动作。ManiSkill 实现两种最直观、也最贴合真实机器人的旋转模式（"A aligned B"表示"取 A 的方向、B 的位置"）：

• root_aligned_body_rotation：四元数计算为delta_pose.q * prev_ee_pose_at_base.q；
• body_aligned_body_rotation：四元数计算为prev_ee_pose_at_base.q * delta_pose.q。

两者的四元数乘法顺序差异正是方向来源的差别（见 PDEEPoseController.compute_target_pose）。演示视频为 root_aligned_body_rotation.mp4 与 body_aligned_body_rotation.mp4。

非增量控制（Non Delta Control）

当use_delta=False时启用。动作必须直接给出一个 3D 目标位置与旋转（XYZ 欧拉角），并使用默认 frameroot_translation:root_aligned_body_rotation。这种控制方式更接近运动规划：策略指定目标位姿，控制器通过 IK 求出尽量逼近该位姿的关节动作。Panda 的pd_ee_pose模式即此配置（pos_lower=-2.0, pos_upper=2.0, use_delta=False, normalize_action=False，见 panda.py）。

其他控制器

除上述外，controllers/init.py 还导出：

• PDJointVelController/PDJointVelControllerConfig：只控制目标关节速度，刚度 $K_p$ 置 0，动作直接作为速度目标下发（见 pd_joint_vel.py）；
• PDJointPosVelController/PDJointPosVelControllerConfig：同时控制位置与速度，动作维度为受控关节数的 2 倍（前一半位置、后一半速度，见 pd_joint_pos_vel.py）；
• PDJointPosMimicController/PDJointPosMimicControllerConfig：模拟（mimic）关节控制器，通过q_mimic = q_controlling * multiplier + offset让从动关节跟随主动关节，用于模拟真实机器人夹爪的联动（见 pd_joint_pos.py）；
• PDBaseVelController/PDBaseForwardVelController：移动底盘速度控制。

深入案例：Franka Emika Panda 机器人的全部控制模式

下面以 Panda（即 Franka Emika Panda，7 自由度机械臂 + 2 指夹爪）为例，用公式精确说明各控制器在仿真中的行为。Panda 以两指之间的工具中心点（TCP）作为末端执行器，所有 "pd" 控制器都把输入动作转换为内置 PD 控制器的目标关节位置 $\bar{q}$（及速度）。除arm_pd_joint_pos与arm_pd_joint_pos_vel外，所有控制器都使用归一化动作空间[-1, 1]。

术语约定

• fixed joint：不可控关节，自由度为 0；
• $q$（qpos）：可控关节位置；$\dot{q}$（qvel）：可控关节速度；
• $\bar{q}$：驱动关节的电机目标位置；$\bar{\dot{q}}$：目标关节速度；
• PD 控制器：控制回路 $F(t) = K_p (\bar{q}(t) - q(t)) + K_d (\bar{\dot{q}}(t) - \dot{q}(t))$，其中 $K_p$（刚度 stiffness）与 $K_d$（阻尼 damping）为超参数，$F(t)$ 为电机力；
• 增强 PD 控制器：被动力（如重力）可通过禁用重力来补偿（计算重力项较慢且非必需）；
• $a$：控制器输入动作，即策略输出。

下文以机械臂控制器名称代指"机械臂控制器 + 夹爪控制器"的组合（当前只有一种夹爪控制器），例如pd_joint_delta_pos即arm_pd_joint_delta_pos+gripper_pd_joint_pos。这些配置在 Panda._controller_configs 中逐一定义。

机械臂控制器（7 维基座）

其中基于末端执行器的控制器在 PDEEPosController.set_action 中的完整流程为：预处理动作 → 记录起始 qpos → 计算（或直接使用）目标位姿 → 调用 Kinematics.compute_ik 求解目标 qpos → 若interpolate=True则按_sim_steps线性插值，否则直接下发驱动目标。IK 求解器基于pytorch_kinematics，支持levenberg_marquardt与pseudo_inverse两种求解策略，并会自动沿运动学链裁剪出从根到ee_link的有效关节链（kinematics.py）。

夹爪控制器（可选）

• gripper_pd_joint_pos（1 维）：强制两个夹爪手指具有相同的目标位置，等效于"mimic"（联动）关节。在 Panda 配置中通过PDJointPosMimicControllerConfig实现：mimic={"panda_finger_joint2": {"joint": "panda_finger_joint1"}}，即panda_finger_joint2跟随panda_finger_joint1（panda.py），并设置lower=-0.01（技巧：保证抓取薄物体时仍有夹持力）、upper=0.04。

如何在任务中指定与查看控制器

控制器通过环境/Agent 的control_mode参数指定。例如：

import mani_skill.envs env = gym.make("PickCube-v1", control_mode="pd_ee_delta_pose")

从源码看，control_mode会传入 BaseAgent.init，经set_control_mode校验并实例化对应控制器（base_agent.py），创建后调用set_drive_property写入各关节的刚度/阻尼/力限等驱动属性；balance_passive_force为True时还会通过禁用连杆重力来补偿被动力。action_space属性会随当前控制模式动态返回对应的动作空间。

ManiSkill 内置的 demo_manual_control.py 与 demo_manual_control_continuous.py 均通过--control_mode命令行参数让用户切换控制模式进行手动操控演示；GPU 仿真基准脚本 同样暴露了control_mode参数用于对比不同控制器下的仿真吞吐。特定任务也可固定控制模式，例如数字孪生任务 so100_arm/grasp_cube.py 直接使用control_mode="pd_joint_target_delta_pos"。

控制器选择建议

综合文档与源码，选择控制器的核心依据是任务类型与训练管线：

• RL / 模仿学习初体验：优先pd_ee_delta_pose/pd_ee_delta_pos，末端执行器空间的动作更直观、采样效率通常更高；注意 GPU 仿真下仅支持 root frame 组合，且 IK 求解会带来额外开销；
• 运动规划 / 精确位姿控制：使用pd_joint_pos（绝对关节目标，目标速度恒 0）或pd_ee_pose（use_delta=False的绝对位姿模式）；
• 需要速度控制的底层应用：选择pd_joint_vel或pd_joint_pos_vel（14 维位置+速度）；
• 关节级精细控制：pd_joint_delta_pos系列（增量、可叠加use_target）适合需要维持目标记忆的场景；
• 夹爪联动：统一使用gripper_pd_joint_pos（mimic），保证两指同步。

自定义机器人时，只需在 Agent 子类的_controller_configs属性中返回{控制模式名: {子控制器名: ControllerConfig, ...}}的字典（可参考 Panda 与 BaseAgent 默认配置），ManiSkill 会自动完成动作空间拼接、驱动属性设置与动作分发，从而为任意机器人快速搭建一套完整、可切换的控制器/动作空间体系。

【免费下载链接】ManiSkillManipulation Skill Framework, an open source GPU parallelized robotics simulator and benchmark项目地址: https://gitcode.com/GitHub_Trending/ma/ManiSkill