# TwoFootBot Isaac Lab TwoFootBot 是一个基于 [Isaac Lab](https://github.com/isaac-sim/IsaacLab) 的双足机器人强化学习项目。仓库包含机器人 URDF、Isaac Lab 环境与任务配置、RSL-RL PPO 训练配置、训练检查点,以及批量回放和训练期间自动回放脚本。 完整的机器人3D文件在[TwoFootBot-3D](https://github.com/zhenaiwork/TwoFootBot-3D) ## 项目展示 以下图片展示了机器人在仿真中的模型和结构设计: | 仿真模型 | 机器人结构示意 | | --- | --- | | ![Isaac Lab 中的 TwoFootBot 仿真模型](png/c1c42bc9-b5fc-4253-9366-ba74e0cddc7c.png) | ![TwoFootBot 机器人结构示意图](png/e8c392db-57aa-4a93-9a14-5042769981d1.png) | `model_55399.pt` 对应的策略回放视频: 视频文件也可以直接[打开或下载](png/model_55399.mp4)。原始视频保存在 `CanGoModel/videos/play/model_55399.mp4`,README 展示所用的副本位于 `png/model_55399.mp4`。 ## 功能概览 - 使用 URDF 在 Isaac Lab 中生成 TwoFootBot,并以 8 个腿部关节作为控制对象。 - 使用 Gymnasium 注册 `Template-Twofootbot-mlp-v0` 至 `Template-Twofootbot-mlp-v3` 任务。 - 使用 RSL-RL PPO 配置训练策略。 - 提供 `playall.py`,按训练步数顺序回放运行目录中的检查点,并为尚无视频的检查点录制视频。 - 提供 `autoplay.py`,监视训练运行目录,在检查点写入稳定后自动回放。 - `CanGoModel/` 提供一个 v2 任务训练运行的检查点、策略导出文件和回放视频。 ### 任务版本 | 任务 ID | 主要配置 | 说明 | | --- | --- | --- | | `Template-Twofootbot-mlp-v0` | `Lv0.py` | 基础行走任务;配置注释中的目标速度为约 0.2 m/s。 | | `Template-Twofootbot-mlp-v1` | `Lv1.py` | 在基础任务上加入材质、基座质量和质心随机化,并训练速度跟踪。 | | `Template-Twofootbot-mlp-v2` | `Lv2.py` | 在 v1 基础上增加周期性外力扰动。 | | `Template-Twofootbot-mlp-v3` | `Lv3.py` | 在 v2 基础上增加执行器增益随机化,并增强外力扰动范围。 | 上述任务由 `src/TwoFootBot_isaaclab/tasks/manager_based/twofootbot/` 中的配置定义,并在该目录的 `__init__.py` 中注册。`CanGoModel/run.json` 中记录的任务是 `Template-Twofootbot-mlp-v2`。 ## 环境要求 - Linux x86_64、NVIDIA GPU 及兼容的 NVIDIA 驱动/CUDA 环境。 - Python 3.12。 - [uv](https://docs.astral.sh/uv/getting-started/installation/)。 - Isaac Lab 源码仓库。当前 `pyproject.toml` 通过相对路径引用 Isaac Lab,默认期望目录结构如下: ```text 工作目录/ ├── IsaacLab/ └── TwoFootBot-isaaclab/ ``` 如果 Isaac Lab 位于其他位置,请按实际路径修改 `pyproject.toml` 的 `[tool.uv.sources]`。 ## 安装 在仓库根目录执行: ```bash uv sync --locked --extra isaacsim --extra rsl-rl ``` 此命令安装 Isaac Sim 和 RSL-RL 相关依赖。首次解析依赖时,uv 可能会检查 Isaac Lab 可选依赖中的 Git 仓库;后续在锁文件不变时,`--locked` 会使用 `uv.lock` 中记录的版本。运行其他 Isaac Lab 后端、可视化器或功能时,可按需添加对应的项目 extra;可选项见 `pyproject.toml`。 ## 查看和训练任务 列出已注册的任务: ```bash uv run isaaclab list_envs --show_presets ``` 使用 RSL-RL PPO 训练 v2 任务: ```bash uv run --extra isaacsim --extra rsl-rl isaaclab train \ --rl_library rsl_rl \ --task Template-Twofootbot-mlp-v2 \ --headless ``` 如需训练其他版本,将 `--task` 后的 ID 替换为上表中的任务。训练日志和检查点由 Isaac Lab 写入其运行日志目录;训练运行目录包含 `run.json` 和一个或多个 `.pt` 检查点。 ## 回放检查点 ### 回放单个检查点 使用 Isaac Lab 的 play 命令回放已有检查点: ```bash uv run --extra isaacsim --extra rsl-rl isaaclab play \ --rl_library rsl_rl \ --task Template-Twofootbot-mlp-v2 \ --checkpoint CanGoModel/model_55399.pt ``` 如需录制视频,可添加 `--video` 等选项;`playall.py` 使用 96 个环境并录制 1000 个仿真步。 ### 批量回放一个训练运行 将训练运行目录作为参数传给 `playall.py`。脚本从该目录的 `run.json` 读取任务 ID,按步数顺序回放其中直接存放的 `.pt` 检查点,并将视频写入该运行目录下的 `videos/play/`: ```bash uv run python playall.py CanGoModel ``` 也可以省略目录参数,按提示输入: ```bash uv run python playall.py ``` 默认使用 GPU 0;通过 `--gpu` 指定其他 GPU 或 GPU 列表: ```bash uv run python playall.py CanGoModel --gpu 1 uv run python playall.py CanGoModel --gpu 0,1 ``` 如果对应检查点的视频已经存在,脚本会跳过该检查点。若运行目录缺少有效的 `run.json`,或没有 `.pt` 检查点,脚本会报错。 ### 训练时自动回放新检查点 `autoplay.py` 持续扫描训练运行目录;检查点在连续两次扫描中保持不变后才会启动回放。按 `Ctrl+C` 停止: ```bash uv run python autoplay.py CanGoModel ``` 可调整扫描间隔(秒)和 GPU: ```bash uv run python autoplay.py CanGoModel --interval 5 --gpu 1 ``` 默认扫描间隔为 10 秒、默认 GPU 为 0。已存在回放视频的检查点会被跳过;回放失败的检查点会在后续扫描时重试。 ## 从检查点继续训练 Isaac Lab 3.0 可通过 `--checkpoint` 指定已有模型,不再使用旧版的 `--resume` 和 `--load_run` 参数。例如: ```bash uv run --extra isaacsim --extra rsl-rl isaaclab train \ --rl_library rsl_rl \ --task Template-Twofootbot-mlp-v2 \ --max_iterations 100000 \ --headless \ --checkpoint CanGoModel/model_55399.pt ``` 请确保 `--task` 与检查点训练所用任务一致;示例检查点对应 v2,训练任务信息也可在 `CanGoModel/run.json` 中查看。 ## 仓库结构 ```text TwoFootBot-isaaclab/ ├── bot/2foot/ # ROS 机器人包、URDF、网格和关节配置 ├── CanGoModel/ # 训练运行、检查点、策略导出和原始回放视频 ├── png/ # README 图片及 model_55399.mp4 展示副本 ├── scripts/ # Isaac Lab 任务查看、智能体及 RSL-RL 脚本 ├── src/TwoFootBot_isaaclab/ │ ├── assets/ # 项目资源包 │ └── tasks/manager_based/twofootbot/ # 环境、奖励、终止条件和任务注册 ├── tests/ # 任务注册测试 ├── autoplay.py # 监视新检查点并自动回放 ├── playall.py # 批量回放训练检查点 ├── pyproject.toml # 项目、依赖和任务入口配置 └── uv.lock # 锁定的依赖版本 ``` ## 开发与测试 运行任务注册测试: ```bash uv run pytest ``` 运行全部 pre-commit 检查: ```bash uv run pre-commit run --all-files ``` 需要配置 VS Code 的 Python 环境时,可运行: ```bash uv run --extra isaacsim isaaclab --editor ``` ## 许可 项目许可信息见仓库根目录的 [`LICENSE`](LICENSE)。