企业官网建设流程全解析

XLeRobot ManiSkill 更多场景实战指南：在 ReplicaCAD、AI2THOR、Robocasa 与 OpenCabinetDrawer 环境中运行双臂移动机器人

【免费下载链接】XLeRobotXLeRobot: Practical Dual-Arm Mobile Home Robot for $660项目地址: https://gitcode.com/GitHub_Trending/xl/XLeRobot

本篇指南聚焦 XLeRobot 在 ManiSkill 仿真平台上的场景扩展能力：除了默认的ReplicaCAD_SceneManipulation-v1，你还可以让双臂移动机器人运行在 AI2THOR、Robocasa 厨房台面以及OpenCabinetDrawer-v1等更多环境中。读完本文，你将掌握 XLeRobot 与 ManiSkill 场景系统的对接原理、场景切换方法，以及关节控制、末端执行器控制、Rerun 相机可视化三套演示脚本的完整运行方式。

场景系统：为什么需要"更多场景"

ManiSkill 的任务环境（Environment）与"场景"（Scene）是两个层次的概念：场景决定机器人与之交互的物理世界（墙面、家具、台面、抽屉等静态/半静态物体），而环境（如SceneManipulation-v1）则定义在该世界中放置哪些机器人、如何初始化和如何渲染。XLeRobot 的仿真演示默认使用ReplicaCAD_SceneManipulation-v1——即由 ReplicaCAD 数据集构建的室内场景；当需要验证机器人在不同家居环境中的操作能力（如厨房台面、客厅柜体、抽屉开关），就需要切换到更多场景。

在 simulation/Maniskill 目录中，官方文档明确列出的可用场景如下：

• ReplicaCAD_SceneManipulation-v1（默认）
• AI2THOR 场景
• Robocasa 厨房台面场景
• OpenCabinetDrawer-v1

支持场景总览

说明：场景的具体数据集下载命令与 ReplicaCAD 一致，均通过 ManiSkill 提供的python -m mani_skill.utils.download_asset "<名称>"方式获取；本文不输出外部站点链接，详细清单请查阅 ManiSkill 官方文档中的场景（scenes）章节。

源码视角：场景是如何接入 XLeRobot 的

场景切换能力并非魔法，而是由环境类的可插拔场景构建器机制支撑的。仓库中的 base_env.py 是实现这一机制的核心：

@register_env("SceneManipulation-v1", max_episode_steps=200) class SceneManipulationEnv(BaseEnv): SUPPORTED_ROBOTS = ["panda", "fetch", "xlerobot"] def __init__(self, *args, robot_uids="fetch", scene_builder_cls: Union[str, SceneBuilder] = "ReplicaCAD", build_config_idxs=None, init_config_idxs=None, ...):

关键点有三：

1. scene_builder_cls参数（base_env.py）默认值为"ReplicaCAD"，允许按名称字符串或场景构建器类传入；从该类的 docstring 可以看到，环境明确支持 "any of the AI2THOR SceneBuilders"，Robocasa 场景同样以构建器形式挂载，这正是"更多场景"能在同一套环境逻辑下工作的原因。
2. 环境 ID 的拼装规则：ManiSkill 会把场景名称前缀与已注册的基础环境组合成完整环境 ID，ReplicaCAD_SceneManipulation-v1即ReplicaCAD（场景）＋SceneManipulation-v1（环境）拼接而成。切换场景时，只要把命令行中的-e参数换成对应场景的前缀即可，例如 AI2THOR 场景对应AI2THOR_SceneManipulation-v1这类 ID（可依据上述命名规则推断）。
3. SUPPORTED_ROBOTS（base_env.py）将xlerobot注册为可放置的机器人之一，因此无论切换到哪个场景，都可以用-r "xlerobot"把 XLeRobot 放入场景中。

机器人侧，xlerobot.py 中Xlerobot类通过@register_agent()注册，uid = "xlerobot"（第 28 行），URDF 指向 assets/xlerobot/xlerobot.urdf，并定义了rest关键帧位姿（17 维 qpos，覆盖底座 x/y/旋转、双臂各 5 关节、头部 pan/tilt 与双夹爪）。这意味着机器人是场景无关的——换场景只需要换-e，机器人的 URDF、控制器与传感器配置保持不变。

安装与准备

运行更多场景的前提是完成 ManiSkill 与 XLeRobot 仿真环境的搭建，完整步骤见 getting_started/index.md，这里摘要关键环节：

# 1. 创建 conda 环境（建议 Python 3.11） conda create -y -n lerobot python=3.11 conda activate lerobot # 2. 安装 ManiSkill pip install mani-skill # 3. 下载 ReplicaCAD 场景数据集 python -m mani_skill.utils.download_asset "ReplicaCAD" # 4. 安装交互与可视化依赖 pip install pygame pip install rerun-sdk

随后将仓库simulation/Maniskill下的内容放入 conda 环境中 ManiSkill 包对应目录（agents/robots、assets/robots、envs/scenes、examples），并在agents/robots/__init__.py中注册 XLeRobot。若数据集下载失败，也可通过官方提供的备份渠道获取后手动放置到~/.maniskill/data/scene_datasets/replica_cad_dataset。

安装完成后，可用随机动作命令验证环境是否就绪：

python -m mani_skill.examples.demo_random_action -e "ReplicaCAD_SceneManipulation-v1" \ --render-mode="human" --shader="rt-fast"

提示：如果你的电脑不支持光线追踪渲染，请把--shader="rt-fast"改为"default"以获得更快的渲染；反过来，追求照片级真实感时可从"default"切换到"rt-fast"（更慢但更真实）。

运行演示：在不同场景中控制 XLeRobot

以下所有演示命令均在 ManiSkill 包根目录执行（即把示例脚本放入examples/后以-m mani_skill.examples.*方式运行）。切换场景时，只需修改-e参数；若目标场景需要特定数据集，请先完成对应资产下载。

关节控制

python -m mani_skill.examples.demo_ctrl_action -e "ReplicaCAD_SceneManipulation-v1" \ -r "xlerobot" --render-mode="human" --shader="default" -c "pd_joint_delta_pos_dual_arm"

该脚本对应 demo_ctrl_action.py，使用 pygame 弹出控制面板：W/S控制底座前进后退，A/D控制转向，7/8/9/0/-与H/J/K/L/;等键逐关节增减双臂目标位置，F/G切换两个夹爪开合，R将目标重置为当前值。脚本内置 50 步预热阶段（warmup），预热期间动作强制归零，之后按比例控制器（P 控制）输出关节速度。

末端执行器控制（双臂 / 单臂）

原始双臂版本：

python -m mani_skill.examples.demo_ctrl_action_ee_keyboard -e "ReplicaCAD_SceneManipulation-v1" \ -r "xlerobot" --render-mode="human" --shader="default" -c "pd_joint_delta_pos_dual_arm"

单臂版本：

python -m mani_skill.examples.demo_ctrl_action_ee_keyboard_single -e "ReplicaCAD_SceneManipulation-v1" \ -r "xlerobot_single" --render-mode="human" --shader="default" -c "pd_joint_delta_pos"

对应源码 demo_ctrl_action_ee_keyboard.py 与 demo_ctrl_action_ee_keyboard_single.py。双臂版本的核心是末端执行器（EE）坐标控制：脚本内置了两连杆逆运动学求解器inverse_kinematics(x, y, l1=0.1159, l2=0.1350)（大臂/小臂长度分别约 0.1159 m 与 0.1350 m），按键盘改变 EE 目标坐标后实时解算肩、肘关节角，实现"控制末端而非关节"的操作体验。双臂键盘布局如下：

控制面板会实时显示 17 维关节角度（底座、双臂、夹爪、头部）与目标值、EE 坐标及动作速度，便于观察 P 控制的跟踪效果。脚本对不同关节配置了差异化的比例增益（demo_ctrl_action.py）：底座转向增益 0.5、夹爪 0.04 以保持平滑，头部与臂关节为 1.0，这保证了多自由度同时运动时的稳定性。

通过 Rerun 进行相机可视化

python -m mani_skill.examples.demo_ctrl_action_ee_cam_rerun -e "ReplicaCAD_SceneManipulation-v1" \ -r "xlerobot" --render-mode="human" --shader="default" -c "pd_joint_delta_pos_dual_arm"

对应 demo_ctrl_action_ee_cam_rerun.py。该脚本通过 Rerun SDK（pip install rerun-sdk）实时可视化机器人携带的相机数据。XLeRobot 的相机配置定义在 xlerobot.py 的_sensor_configs中：一颗 256×256 的头部主相机（head_camera_link，用于工作区全局观察）与两颗 128×128 的手腕相机（分别挂在Right_Arm_Camera、Left_Arm_Camera上，用于精细操作）。脚本提供--use-rerun、--show-cameras、--debug-cameras参数，可控制是否启用 Rerun、是否展示相机画面及是否输出调试信息——这对于采集仿真数据、验证视觉感知链路非常有用。

演示脚本通用命令行参数

所有演示脚本基于tyro解析参数（见各脚本的Args数据类），常用参数如下：

控制模式说明

XLeRobot 的控制模式在 xlerobot.py 的_controller_configs中注册，常见的包括：

• pd_joint_delta_pos_dual_arm：双臂关节增量位置控制（本文演示默认使用），每臂各 5 个关节 + 夹爪 + 底座速度控制；
• pd_joint_pos_dual_arm：双臂绝对位置控制；
• pd_joint_delta_pos/pd_joint_pos：单臂模式，配合-r "xlerobot_single"使用；
• 更多变体（pd_joint_vel、pd_joint_delta_pos_vel、pd_joint_delta_pos_stiff_body等）可查看控制器配置字典。

控制参数（刚度/阻尼/力限）在 xlerobot.py 中定义：双臂关节刚度2e4、阻尼1e2、力限 250；夹爪刚度 50、阻尼1e2、力限 2.8；头部电机刚度1e4。这些参数与 URDF 中的关节定义一一对应，是仿真手感与 sim2real 迁移的基础。

在更多场景中运行：切换方法与注意点

结合上文的环境 ID 拼装规则，将演示命令中的-e替换即可：

# 示例：切换到 OpenCabinetDrawer-v1 任务环境 python -m mani_skill.examples.demo_ctrl_action -e "OpenCabinetDrawer-v1" \ -r "xlerobot" --render-mode="human" --shader="default" -c "pd_joint_delta_pos_dual_arm"

OpenCabinetDrawer-v1_rt_thumb_first.png 展示了该任务环境的仿真渲染效果，可供运行前直观参考：

几点注意事项：

1. 机器人初始位姿：不同场景的家具布局差异较大，若机器人出生点与柜体/台面过远或发生穿模，需调整场景构建器中的机器人初始位姿（robot_initial_pose，见 base_env.py）。
2. 新机器人注册：按官方文档说明，对于新的机器人 ID，需要先将它们添加到 ReplicaCAD 场景构建器中（修改utils/scene_builder/replicacad/scenebuilder.py）才能正常生成初始位姿。
3. 数据集依赖：AI2THOR、Robocasa 等场景依赖各自的数据集，首次运行前务必完成对应download_asset，否则场景加载会失败。

自定义硬件与场景适配

如果使用不同硬件版本的 XLeRobot（例如更换了 URDF 或关节数量变化），可从以下两点入手适配（见英文版 simdemos 文档）：

1. 修改 URDF 路径：在agents/robots对应的机器人类中，将urdf_path指向assets/下你自己的 URDF 文件。仓库中 xlerobot.py 即采用f"{PACKAGE_ASSET_DIR}/robots/xlerobot/xlerobot.urdf"的方式引用资产。
2. 调整 qpos 维度：根据你的硬件配置调整qpos的大小。XLeRobot 默认是 17 维（底座 3 + 双臂 10 + 头部 2 + 夹爪 2），若更换硬件导致关节数变化，需要同步修改关键帧定义（xlerobot.py）以及演示脚本中get_mapped_joints的关节映射关系。

常见问题排查

根据官方文档与源码，运行演示时可能遇到以下问题：

• link 名称不匹配：若报错提示找不到某个 link，请定位到报错脚本，将代码中引用的 link 名称改为 URDF 中实际定义的名称（例如Fixed_Jaw、Moving_Jaw及对应的_2后缀双臂版本，见 xlerobot.py）。
• 碰撞检测误报：如果机器人初始状态与场景物体发生异常碰撞，可定位到脚本，注释掉避碰（avoid collision）列表中冲突的物体项后再试。

延伸阅读

• 完整安装与数据下载流程：getting_started/index.md
• 场景环境实现：simulation/Maniskill/envs/scenes/base_env.py
• XLeRobot 机器人代理（URDF、控制器、相机）：simulation/Maniskill/agents/xlerobot/xlerobot.py
• 机器人模型与网格资产：simulation/Maniskill/assets/xlerobot
• 关节控制演示：demo_ctrl_action.py
• 双臂末端控制演示：demo_ctrl_action_ee_keyboard.py
• 单臂末端控制演示：demo_ctrl_action_ee_keyboard_single.py
• Rerun 相机可视化：demo_ctrl_action_ee_cam_rerun.py
• VR 遥操作教程（Meta Quest3）：getting_started/vr_sim.md

【免费下载链接】XLeRobotXLeRobot: Practical Dual-Arm Mobile Home Robot for $660项目地址: https://gitcode.com/GitHub_Trending/xl/XLeRobot