ManiSkill 数据采集指南基于运动规划与遥操作生成示范轨迹【免费下载链接】ManiSkillManipulation Skill Framework, an open source GPU parallelized robotics simulator and benchmark项目地址: https://gitcode.com/GitHub_Trending/ma/ManiSkillManiSkill 提供了一套完整的演示数据demonstration data采集工具链既可以用编程式的运动规划motion planning方案自动生成轨迹也可以借助鼠标点击拖拽等遥操作teleoperation系统人工采集。本文以官方文档 data_collection/index.md 为骨架结合仓库中的实际示例代码、RecordEpisode封装器源码与 HDF5 轨迹格式说明系统讲解如何采集、保存并读取示范轨迹。读完本文你将掌握运行 Panda 运动规划求解器、使用点击拖拽遥操作采集数据、理解RecordEpisode的录制原理以及如何加载 .h5 轨迹文件用于模仿学习。数据采集总览两条主线与一个统一入口ManiSkill 的数据采集围绕动作来源展开主要有两条路径运动规划Motion Planning借助开源库 mplib安装 ManiSkill 时会一并安装无需额外安装由程序化的求解器自动规划机械臂轨迹。适合抓取、放置、插入等可分解为接近—抓取—移动—释放序列的任务其局限在于通常需要工程师手工编写和调优求解逻辑且无法处理高动态任务如抛掷物体。遥操作Teleoperation通过人机交互界面由人类操作员控制机械臂末端执行器逐段生成示范。目前官方提供的是点击拖拽clickdrag系统支持鼠标和键盘社区项目还提供了 VR 遥操作方案。无论数据来源如何采集到的轨迹最终都会统一经过RecordEpisode封装器落盘为 .h5 数据文件同时生成同名的 JSON 元数据这一点在源码 mani_skill/utils/wrappers/record.py 中体现得非常清晰RecordEpisode是gym.Wrapper的子类其 docstring 明确说明Record trajectories or videos for episodes并详细描述了 HDF5 与 JSON 的存储结构。采集完成后这些 .h5 文件可以用 datasets/index.md 介绍的方式加载使用——包括下载官方演示数据集、重放replay轨迹、以及构建 PyTorch Dataset 用于模仿学习基线训练。运动规划采集以 Panda 机械臂为例内置求解器与运行方式仓库在mani_skill/examples/motionplanning/panda/目录下为 Panda 机械臂提供了多个任务的现成求解方案。从 run.py 中的MP_SOLUTIONS字典可以看到目前支持的任务DrawTriangle-v1、PickCube-v1、StackCube-v1、PegInsertionSide-v1、PlugCharger-v1、PlaceSphere-v1、PushCube-v1、PullCubeTool-v1、LiftPegUpright-v1、PullCube-v1、DrawSVG-v1、StackPyramid-v1每个任务对应solutions/目录下的一个求解脚本例如 pick_cube.py、stack_cube.py 等。运行运动规划采集的基本命令如下轨迹数据默认保存到demos/motionplanning/env_id# 无头模式运行只保存视频 python -m mani_skill.examples.motionplanning.panda.run -e PickCube-v1 --save-video # 打开 GUI 实时可视化求解过程 python -m mani_skill.examples.motionplanning.panda.run -e StackCube-v1 --vis # 查看帮助菜单同时列出哪些任务已有现成求解方案 python -m mani_skill.examples.motionplanning.panda.run -hrun.py中parse_args定义的主要命令行参数如下均来自源码 run.py参数默认值说明-e, --env-idPickCube-v1要运行运动规划求解器的环境 ID可选值即上表所列任务-o, --obs-modenone观测模式。通常保持none因为观测不必在采集时存储之后可通过mani_skill.trajectory.replay_trajectory脚本重放补充-n, --num-traj10要生成的轨迹条数--only-count-successFalse若开启则持续生成直到获得num_traj条成功轨迹且只保存成功的轨迹/视频-b, --sim-backendauto仿真后端可选auto、cpu、gpu--render-modergb_array可选sensors或rgb_array仅影响保存的视频内容--visFalse是否打开 GUI 实时可视化--save-videoFalse是否在本地保存视频--traj-name时间戳生成的轨迹 .h5 文件名--shaderdefault渲染着色器default速度最快rt为光线追踪可生成照片级真实感渲染rt-fast为更快但质量略低的光追渲染--record-dirdemos录制轨迹的保存根目录--num-procs1用于并行重放轨迹的进程数基于 CPU 多进程目前仅 CPU 仿真后端支持_main函数中还展示了与RecordEpisode的配合方式创建环境后用RecordEpisode包装并传入source_typemotionplanning、source_descofficial motion planning solution from ManiSkill contributors即可在求解器逐步执行动作的同时录制轨迹。一个求解器的执行流程PickCube-v1 拆解运动规划求解的本质是将任务分解为一系列简单的 pick、place 与移动操作。官方文档以 PickCube-v1 为例给出了四步分解将夹爪移动到红色立方体正上方并旋转夹爪使其与立方体朝向一致下移夹爪使两指包围立方体闭合夹爪将夹爪移动到目标位置上方使夹爪的工具中心点tool center point, TCP落在目标位置。源码 pick_cube.py 将这一过程实现为四个阶段Reach接近通过get_actor_obb(env.cube)获取立方体的有向包围盒OBB再用compute_grasp_info_by_obb结合approaching接近方向[0,0,-1]与target_closing计算抓取位姿grasp_pose最后用planner.move_to_pose_with_screw(reach_pose)运动到抓取点上方 5cm 处grasp_pose * sapien.Pose([0, 0, -0.05])Grasp抓取move_to_pose_with_screw(grasp_pose)到达抓取位姿后调用planner.close_gripper()闭合夹爪Move to goal pose移动到目标以env.goal_site.pose.sp.p为位置、保持抓取时的姿态四元数构造goal_pose再次运动规划到达。move_to_pose_with_screw在底层使用 mplib 的规划器生成关节路径随后由TwoFingerGripperMotionPlanningSolver.follow_path见 motionplanner.py逐帧执行每个时间步把规划结果position中的关节目标与夹爪状态拼成动作向量送入env.step(action)。夹爪开合由open_gripper/close_gripper实现其动作构造逻辑在pd_joint_pos控制模式下为np.hstack([qpos, gripper_state])。可扩展性说明运动规划求解器被设计为可复用的基类体系从源码结构看base_motionplanner/motionplanner.py 提供基础求解器two_finger_gripper/motionplanner.py 的TwoFingerGripperMotionPlanningSolver在两指夹爪层面封装开合动作与路径跟随panda/motionplanner.py 的PandaArmMotionPlanningSolver针对 Panda 设置MOVE_GROUP panda_hand_tcp并定义夹爪开合值OPEN 1、CLOSED -1。官方文档说明示例代码为 Panda 编写但可以修改适配其他机械臂。仓库中还提供了其他机器人的运动规划示例例如mani_skill/examples/motionplanning/so100/、mani_skill/examples/motionplanning/xarm6/可作为适配参考。遥操作采集点击拖拽系统系统定位与使用方式官方文档将点击拖拽ClickDrag系统的特点总结为硬件要求显示器、鼠标、键盘易用性生成细粒度演示极其容易局限仅适用于两指夹爪的非高动态任务如抓取立方体抛掷立方体这类任务无法完成。启动命令需先安装带 GUI 交互的环境python -m mani_skill.examples.teleoperation.interactive_panda -e StackCube-v1脚本 interactive_panda.py 使用tyro定义参数支持-e/--env-id默认PickCube-v1、-r/--robot-uid默认panda也支持panda_stick、--record-dir默认demos、--save-video等。它默认以pd_joint_pos控制模式创建环境并用RecordEpisode包装写入source_typeteleoperation。交互方式与键盘指令操作流程基于 SAPSEN 查看器viewer的 TransformWindow 插件你可以像拖拽 gizmo 一样把机械臂末端即虚拟的幽灵Panda 手臂拖到任意位置与姿态。源码中solve函数完整定义了键盘指令按键功能h打印帮助菜单说明所有键盘命令g切换夹爪开/合仅对带夹爪的机器人如panda有效n通过运动规划执行当前目标位姿让机器人移动到幽灵手臂指示的位置c结束当前 episode保存轨迹并进入新 episodeq退出脚本保存所有轨迹若开启--save-video则随后生成视频u/j将末端抓手沿 z 轴向上/向下微移 1cm方向键将末端抓手沿对应方向微移 1cm官方文档还补充说明按n执行运动规划时每次都会打印当前任务是否已解决的信息。interactive_panda.py中执行前会先做dry_runTrue的预规划若规划失败返回-1会打印 Plan failed若规划路径过长len(result[position]) 150则提示 Generated motion plan was too long. Try a closer sub-goal引导用户选择更近的子目标。数据保存位置为demos/teleop/env_id先保存轨迹.h5 .json退出时若开启了--save-video脚本会用trajectory_utils.dict_to_list_of_dicts读取env_states、set_state_dict恢复初始状态后重放轨迹生成视频。如果你想跳过视频生成可直接按CTRLC中断脚本。VR 遥操作方案官方文档提到仓库本身暂不计划内置 VR 遥操作工具出于复杂度和单功能依赖的考虑但推荐了社区项目ImVR基于 ALVR 的本地连接 VR 遥操作系统Maniskill Quest Teleop基于 WebXR 的遥操作工具。相关内容可参考文档 teleoperation.md。一切数据的中枢RecordEpisode 封装器RecordEpisode是数据采集的核心基础设施两条采集路径最终都通过它落盘。它同时支持 CPU 与 GPU 并行仿真下的录制源码注释说明该实现为兼顾两者与部分重置而略显复杂。关键构造参数结合源码 record.py主要参数如下参数默认值说明output_dir必填输出目录save_trajectory或save_video为真时自动创建save_trajectoryTrue是否保存轨迹 .h5 与 .jsontrajectory_name时间戳轨迹文件名不带扩展名不传则用%Y%m%d_%H%M%Ssave_videoTrue是否保存视频info_on_videoFalse是否把 reward、action 等信息写到视频帧上首帧一般是第一次 reset 的画面save_on_resetTruereset 时是否自动保存上一条轨迹及视频。注意GPU 并行环境必须设置max_steps_per_video为固定值因为部分重置会让视频切分产生歧义save_video_triggerNone回调函数输入已累计的环境步数返回是否开始录制该时间步max_steps_per_videoNone单个视频最多容纳的步数达到后强制刷盘flush并重置步数计数器。源码中 GPU 环境num_envs 1开启视频时对此有断言强制clean_on_closeTrue关闭时是否清理轨迹重命名为连续编号traj_0、traj_1...并删除空动作轨迹elapsed_steps 0record_rewardTrue是否在轨迹中记录 rewardrecord_env_stateTrue是否记录环境状态若状态字典不一致会自动禁用并告警video_fps30生成视频的帧率render_substepsFalse是否按物理子步渲染更流畅但更慢avoid_overwriting_videoFalse为真时自动迭代视频名避免覆盖已有文件适合续训场景source_type/source_descNone数据来源类别与描述官方数据集的source_type通常为human、motionplanning或rl使用建议源码 docstring 明确说明RecordEpisode一般应作为最外层包装器尤其在叠加了修改观测的观测包装器时只有向量环境接口包装器可以放在它之后。录制原理从 Step 缓冲到 flushRecordEpisode内部用Step数据结构record.py缓冲轨迹数据包含state、observation、action、reward、terminated、truncated、done、success、fail以及env_episode_ptr记录每个子环境当前 episode 的起始指针用于 GPU 并行环境的部分重置。录制流程可归纳为reset时构造首帧Stepterminated/truncated固定为True表示 episode 起点写入last_reset_kwargs供后续reset_kwargs元数据使用每次step把新的 state/obs/action/reward/terminated/truncated/doneterminated | truncated以及可选 success/fail 追加进缓冲调用flush_trajectory默认在 reset 或 close 时触发时按env_episode_ptr切片写出到 h5py grouptraj_{episode_id}观测数据若为字典如多相机用recursive_add_to_h5py递归写入子 group其中rgb、depth、seg使用 gzipcompression_opts5压缩其余数据不压缩flush_video把累积的渲染帧通过images_to_video写成 mp4close时若clean_on_closeTrue调用clean_trajectories将轨迹重编号并删除空轨迹随后写回 JSON。值得注意的是flush_trajectory会从动作序列中剔除首帧 dummy 数据slice(start_ptr 1, end_ptr)并在episode_info中记录episode_id、episode_seed、control_mode、elapsed_steps与可选的成功/失败标记。轨迹数据格式HDF5 与 JSON采集产出的 .h5 文件配合同名 .json 元数据使用。官方文档 demos.md 对格式有权威定义RecordEpisode的实现与其完全对应。JSON 元数据每个 JSON 文件包含env_infoDict任务/环境信息用于初始化任务env_idstr任务 IDmax_episode_stepsint最大 episode 步数env_kwargsDict初始化任务的关键字参数重建环境的关键。episodesList[Dict])episode 信息列表source_typeOptional[str]数据来源类别如motionplanning、teleoperation、rl、humansource_descOptional[str]数据生成方式的长描述另外源码中还会写入commit_info见 record.py记录生成数据时的代码提交信息便于复现。episode 信息元素包含episode_idint索引 episode 的唯一 IDreset_kwargsDict重置任务的关键字参数复现轨迹的关键control_modestr该 episode 使用的控制模式elapsed_stepsint轨迹长度infoDictepisode 结束时环境返回的 infoGPU 并行仿真下还会额外写入success/fail字段。仅凭元数据即可复现任务场景env gym.make(env_info[env_id], **env_info[env_kwargs]) episode env_info[episodes][0] # 取第一条 env.reset(**episode[reset_kwargs])需要注意如果轨迹是在 GPU 仿真中采集的其随机化不仅依赖 seed 还依赖并行环境数量。为确保起始状态一致应使用轨迹中保存的第一个环境状态env_states通过set_state_dict恢复。HDF5 轨迹数据每个 .h5 数据集包含多条轨迹键名为traj_{episode_id}如traj_0。每条轨迹是一个h5py.Group含以下数据集字段形状类型说明actions[T, A]np.float32动作序列T 为转移步数terminated[T]np.bool_各时间步是否终止truncated[T]np.bool_各时间步是否截断env_states[T1, D]np.float32环境状态序列可通过env.set_state_dict恢复状态但未必足够完整复现轨迹success可选[T]np.bool_各时间步是否成功任务定义 success 时存在fail可选[T]np.bool_各时间步是否处于失败态任务定义 fail 时存在obs可选[T1, D]视 obs_mode 而定观测序列env_states以字典形式存储观测在字典 obs_mode 下同理结构形如env_state env.get_state_dict() env_state { actors: { actor_id: [...numpy_actor_state...], ... }, articulations: { articulation_id: [...numpy_articulation_state...], ... } } 在轨迹文件中env_states保持同样结构但每个叶子值变为随时间变化的序列。实际使用中更常见的是对env_states或观测做切片import mani_skill.trajectory.utils as trajectory_utils env_states trajectory_utils.dict_to_list_of_dicts(env_states) # 现在 env_states[i] 等价于时间步 i 时 env.get_state_dict() 返回的数据 i 10 env_state_i trajectory_utils.index_dict(env_states, i) # 现在 env_state_i 等价于时间步 i 时 env.get_state_dict() 返回的数据文件命名约定演示数据集文件命名形如trajectory.{obs_mode}.{control_mode}.{sim_backend}.h5并伴随同名 JSON。除非另行说明trajectory.h5是trajectory.none.pd_joint_pos.physx_cpu.h5的简写表示由pd_joint_pos控制器、none观测模式空观测、CPU 仿真生成。务必检查同名 JSON 确认实际使用的控制器因为可能存在其他控制器生成的演示。加载轨迹数据PyTorch Dataset 实践官方在 trajectory/datasets.py 提供了一套可直接使用的 PyTorch Dataset 示例文档 demos.md 中完整粘贴了代码。核心要点ManiSkillTrajectoryDataset构造函数参数dataset_file.h5 路径会自动推断同名 .json、load_count加载条数-1表示全部加载进内存、success_only是否只加载最终成功的轨迹、device数据存放设备None时保持 numpy内部用load_h5_data递归把 h5 数据读入内存观测中的np.uint16会被转换为np.int32便于直接转成 torch 张量官方注释说明 uint16 是用于节省磁盘与内存空间的读取观测时会排除最后一条观测slice(eps_len)因为大多数学习流程不使用它通过common.index_dict_array/common.append_dict_array处理字典形式的观测拼接若指定device动作、观测、终止/截断标记等会通过sapien_utils.to_tensor迁移到目标设备。该 Dataset 返回的样本为字典含obs、action、terminated、truncated以及可选的reward、success、fail。下载与重放官方演示数据集除自行采集外ManiSkill 还提供命令行工具直接下载官方演示数据集托管于 Hugging Face按任务 ID 区分# 下载指定任务的演示数据集 python -m mani_skill.utils.download_demo ${ENV_ID} # 不带参数运行会打印所有可用数据集 python -m mani_skill.utils.download_demo # 下载全部数据集可能非常慢 python -m mani_skill.utils.download_demo all演示数据集通常以最小格式存储例如不存观测改存环境状态以压缩体积。如需为轨迹补充视觉观测、录制视频等可使用 replay.md 介绍的重放工具。若想本地自行生成官方格式的压缩数据集仓库在scripts/data_generation/目录下保存了数据集生成脚本进行模仿学习基准评测的用户则应参考 setup.md 中关于重放压缩数据集用于训练评测的说明。小结ManiSkill 的数据采集体系可以用一句话概括运动规划与遥操作负责产生动作RecordEpisode负责忠实记录。前者覆盖了可编程化分解的任务12 个 Panda 现成求解器后者提供了人类介入的细粒度控制点击拖拽 键盘指令而两者产出的 .h5 .json 轨迹格式完全统一可直接用于数据集下载、轨迹重放、PyTorch Dataset 构建乃至下游模仿学习训练。理解RecordEpisode的缓冲、flush 与清理机制是排查数据采集问题如 GPU 并行环境下的视频切分、状态字典一致性的关键所在。【免费下载链接】ManiSkillManipulation Skill Framework, an open source GPU parallelized robotics simulator and benchmark项目地址: https://gitcode.com/GitHub_Trending/ma/ManiSkill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考