TwoFootBot-isaaclab/README.md

197 lines
7.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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` 对应的策略回放视频:
<video src="png/model_55399.mp4" controls width="800">
当前浏览器不支持内嵌视频,请<a href="png/model_55399.mp4">打开或下载回放视频</a>。
</video>
视频文件也可以直接[打开或下载](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)。