yqi19/conflict_experiment_maniskill

ManiSkill 迁移指南（迁移到另一台工作站）

本文档说明如何将 datagen/ManiSkill 下的代码与工作流迁移到另一台工作站环境，并在新机器上完成依赖安装与数据生成流程。

1. 项目简介与目录结构

本仓库中的 ManiSkill 用于数据生成：通过 motion planning 生成 Pick/Pull 等任务的轨迹，replay 成带 RGB 的 H5，再转换为 LeRobot 格式数据集。

主要目录与脚本：

2. 环境要求

• —系统：推荐 Linux + NVIDIA GPU（CPU 仿真可用，渲染与 GPU 仿真需 Linux + NVIDIA）
• —Python：>= 3.9（推荐 3.10）
• —GPU 驱动：需安装 NVIDIA 驱动，且需 Vulkan 支持（用于渲染）
• —磁盘：预留空间给 ~/.maniskill 或 MS_ASSET_DIR 下的资产与 demo

3. 迁移时拷贝什么 / 不拷贝什么

建议拷贝

• —整个 `datagen/ManiSkill/` 目录（或至少包含）：
• —mani_skill/
• —scripts/
• —demo_collection/
• —setup.py
• —demos/（若希望沿用已有 H5，避免重新跑 motion planning）
• —若使用自定义配置或脚本，一并拷贝（如你修改过的 run_collect_and_convert.sh 等）

可不拷贝（在新环境重建即可）

• —lerobot_dataset/：可由 H5 重新运行 convert_maniskill_to_lerobot.py 生成
• —Python 虚拟环境目录：venv/、.venv/、env/ 等
• —缓存与构建产物：*.pyc、__pycache__/、*.egg-info/、build/ 等
• —大型资产：若新环境可联网，ManiSkill 会在首次使用时从 ~/.maniskill 或 MS_ASSET_DIR 自动下载所需资产，无需从旧机器拷贝

可选：资产目录

若新机器网络受限，可将旧机器上的 ManiSkill 资产目录 整份拷贝到新机器，并设置相同路径：

# 旧机器上默认位置
~/.maniskill/

# 或你自定义的 MS_ASSET_DIR，例如
export MS_ASSET_DIR=/path/to/mani_skill_data

在新机器上设置同样的 MS_ASSET_DIR 并指向拷贝过去的目录即可。

4. 新环境安装步骤

4.1 克隆/拷贝代码

将 datagen/ManiSkill 拷贝到新工作站，例如：

# 假设新机器上的工作目录
cd /path/to/your/workspace
# 拷贝整个 ManiSkill 目录（或通过 git 拉取包含 datagen 的仓库）

进入 ManiSkill 根目录（即包含 setup.py 和 mani_skill/ 的目录）：

cd /path/to/your/workspace/datagen/ManiSkill
# 或你实际放置的路径，例如
cd ManiSkill

后续所有命令均在该根目录下执行。

4.2 创建 ManiSkill 主环境（收集 demo + replay）

用于运行 motion planning、replay_trajectory 等，需要安装 ManiSkill 与 PyTorch。

# 创建并激活环境（推荐 Python 3.10）
conda create -n maniskill39 python=3.10 -y
conda activate maniskill39

# 安装 ManiSkill（从当前目录安装，便于开发与脚本路径）
pip install -e .

# 安装与当前 CUDA 匹配的 PyTorch（按需选择版本）
# 例如 CUDA 12.x:
pip install torch

若官方文档推荐使用 pip install mani_skill，也可改用：

pip install --upgrade mani_skill torch

此时应使用官方包，脚本需能从 mani_skill 找到 envs 和 trajectory 等模块（若你改过本地 mani_skill/，则更适合 pip install -e .）。

4.3 安装 Vulkan（渲染必需）

Ubuntu 示例：

sudo apt-get update
sudo apt-get install -y libvulkan1 vulkan-tools
# 验证
vulkaninfo

若使用 NVIDIA GPU，需保证存在 /usr/share/vulkan/icd.d/nvidia_icd.json 等配置，详见 ManiSkill 官方文档 Installation - Vulkan。

4.4 可选：设置资产目录

若希望将资产与 demo 放在固定目录（便于多机一致或备份）：

export MS_ASSET_DIR=/path/to/mani_skill_data
# 建议写入 ~/.bashrc 或 ~/.profile

跳过下载确认提示（非交互式时有用）：

export MS_SKIP_ASSET_DOWNLOAD_PROMPT=1

4.5 验证 ManiSkill 环境

conda activate maniskill39
cd /path/to/ManiSkill

# 简单跑一个 episode
python -m mani_skill.examples.demo_random_action

若无报错且能跑通，说明主环境可用。

5. LeRobot 转换环境（可选，单独环境）

将 H5 转为 LeRobot 数据集时，推荐使用独立环境安装 LeRobot，避免与 ManiSkill 的依赖冲突。此环境不需要安装 ManiSkill，只需能读 H5 和运行 convert_maniskill_to_lerobot.py。

conda create -n lerobot_convert python=3.10 -y
conda activate lerobot_convert
cd /path/to/ManiSkill
pip install -r demo_collection/requirements_lerobot_convert.txt

转换时只需在该环境下执行（见下文「运行流程」）。

6. 运行流程（新环境上复现数据生成）

在 ManiSkill 根目录 下进行。

方式 A：一键收集 + 转 LeRobot

conda activate maniskill39
cd /path/to/ManiSkill
bash demo_collection/run_collect_and_convert.sh

该脚本会依次： 1）motion planning 生成轨迹并写入 demos/...； 2）replay 成带 RGB 的 H5； 3）调用 convert_maniskill_to_lerobot.py 生成 LeRobot 数据集到 ./lerobot_dataset（或脚本内配置的 OUTPUT_DIR）。

方式 B：分步执行

Step 1：收集 motion planning 轨迹

conda activate maniskill39
cd /path/to/ManiSkill

python scripts/run_verb_color_shape_motion_planning.py \
  --verb pick --color blue --shape cube --traj-name trajectory \
  --obj-xy-range -0.1 0.1 -0.1 0.1 --only-count-success -n 100

python scripts/run_verb_color_shape_motion_planning.py \
  --verb pull --color red --shape cube --traj-name trajectory \
  --obj-xy-range -0.1 0.1 -0.1 0.1 --only-count-success -n 100

Step 2：Replay 为带 RGB 的 H5

python -m mani_skill.trajectory.replay_trajectory \
  --traj-path demos/PickCubeColor-v1/motionplanning/trajectory.h5 \
  --save-traj --save-traj-name pick_cube_blue_rgb --obs-mode rgb

python -m mani_skill.trajectory.replay_trajectory \
  --traj-path demos/PullCubeColor-v1/motionplanning/trajectory.h5 \
  --save-traj --save-traj-name pull_cube_red_rgb --obs-mode rgb

Step 3：转换为 LeRobot 数据集

使用 ManiSkill 环境或 LeRobot 专用环境均可（推荐 LeRobot 环境）：

# 若使用 lerobot_convert 环境
conda activate lerobot_convert
cd /path/to/ManiSkill

python demo_collection/convert_maniskill_to_lerobot.py \
  --output-dir ./lerobot_dataset \
  --task-map '{"pick_cube_blue_rgb":"Pick blue cube","pull_cube_red_rgb":"Pull red cube"}'

若已用 run_collect_and_convert.sh 生成过 H5，也可只在新机器上拷贝 demos/ 后单独执行 Step 3。

7. 路径与配置注意点

• —所有脚本设计为在 ManiSkill 仓库根目录 运行（即 setup.py 所在目录）；run_collect_and_convert.sh、collect_demo.sh、convert_demo.sh 中已包含 cd 到脚本所在父目录的逻辑。
• —convert_maniskill_to_lerobot.py 默认从当前仓库下的 demos/PickCubeColor-v1/motionplanning/pick_cube_blue_rgb.h5 与 demos/PullCubeColor-v1/motionplanning/pull_cube_red_rgb.h5 读取；若你改了 --save-traj-name 或目录，需同步修改 --task-map 及脚本内路径。
• —轨迹与数据集输出目录可在脚本中修改（如 run_collect_and_convert.sh 的 OUTPUT_DIR、replay 的 --save-traj-name 等）。

8. 常见问题

• —Vulkan / 渲染相关报错
• —确保已安装 libvulkan1 与 NVIDIA Vulkan ICD；详见官方 Installation - Vulkan。
• —无头服务器可尝试 --render-backend cpu 或 -b cpu（若脚本支持），部分功能可能受限。

• —mplib 等库 segfault
• —可尝试使用 CPU 后端：在 motion planning 脚本中加 -b cpu --render-backend cpu（参见 run_verb_color_shape_motion_planning.py 注释）。

• —找不到 `mani_skill` 或 env 未注册
• —确认在 ManiSkill 根目录执行，且已 pip install -e . 或已把根目录加入 PYTHONPATH。
• —确认已 import mani_skill.envs（或脚本中已有对 env 的注册）。

• —LeRobot 转换报错
• —使用 demo_collection/requirements_lerobot_convert.txt 单独建环境，避免与 ManiSkill 的 numpy/torch 等版本冲突。
• —确认 H5 路径与 --task-map 中的 key（如 pick_cube_blue_rgb、pull_cube_red_rgb）与 replay 时使用的 --save-traj-name 一致。

• —资产下载慢或失败
• —设置 MS_ASSET_DIR 后，可从旧机器拷贝整个 ~/.maniskill（或你的 MS_ASSET_DIR）到新机器同一路径。
• —或设置 MS_SKIP_ASSET_DOWNLOAD_PROMPT=1 在无交互时避免卡在下载确认。

9. 简要检查清单（迁移后在新机器自检）

• —[ ] 已拷贝 datagen/ManiSkill（至少 mani_skill/、scripts/、demo_collection/、setup.py）
• —[ ] Python 3.9+（推荐 3.10）、conda/venv 已创建并激活
• —[ ] pip install -e . 或 pip install mani_skill + pip install torch
• —[ ] Vulkan 已安装且 vulkaninfo 正常
• —[ ] （可选）MS_ASSET_DIR、MS_SKIP_ASSET_DOWNLOAD_PROMPT 已按需设置
• —[ ] python -m mani_skill.examples.demo_random_action 能跑通
• —[ ] 需要 LeRobot 时：已用 requirements_lerobot_convert.txt 建独立环境并成功运行 convert_maniskill_to_lerobot.py

按上述步骤即可在另一台工作站上复现 ManiSkill 数据生成与 LeRobot 转换流程。若你使用 Docker，可参考仓库内或官方 Docker 文档 在镜像中安装相同依赖后再执行上述命令。