redmo is ok

This commit is contained in:
zhenai 2026-11-09 17:50:00 +08:00
parent d962687b9d
commit b3add27910
4 changed files with 142 additions and 121 deletions

263
README.md
View File

@ -1,175 +1,196 @@
# TwoFootBot-isaaclab
# TwoFootBot Isaac Lab
An Isaac Lab 3.0 project containing the migrated TwoFootBot locomotion tasks and robot description.
TwoFootBot 是一个基于 [Isaac Lab](https://github.com/isaac-sim/IsaacLab) 的双足机器人强化学习项目。仓库包含机器人 URDF、Isaac Lab 环境与任务配置、RSL-RL PPO 训练配置、训练检查点,以及批量回放和训练期间自动回放脚本。
完整的机器人3D文件在[TwoFootBot-3D](https://github.com/zhenaiwork/TwoFootBot-3D)
## Installation
## 项目展示
Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then create the project environment with the
Isaac Sim and RSL-RL extras used for training:
以下图片展示了机器人在仿真中的模型和结构设计:
| 仿真模型 | 机器人结构示意 |
| --- | --- |
| ![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
```
This project's `pyproject.toml` uses editable relative paths to an Isaac Lab source checkout. Update
`[tool.uv.sources]` if either directory moves.
此命令安装 Isaac Sim 和 RSL-RL 相关依赖。首次解析依赖时,uv 可能会检查 Isaac Lab 可选依赖中的 Git 仓库;后续在锁文件不变时,`--locked` 会使用 `uv.lock` 中记录的版本。运行其他 Isaac Lab 后端、可视化器或功能时,可按需添加对应的项目 extra;可选项见 `pyproject.toml`。
The first dependency resolution creates `uv.lock` and may inspect Git dependencies declared by other optional Isaac Lab
extras, even if those extras are not selected for installation. Once the lock file exists, `--locked` reuses it and
installs only the selected extras.
## 查看和训练任务
The project forwards every optional extra declared by the Isaac Lab package used to create it, including physics,
rendering, visualizer, RL, teleoperation, and development features. Inspect `pyproject.toml` for the complete list and
pass each required extra to `uv run`:
```bash
# Standalone OV PhysX
uv run --extra ovphysx isaaclab random_agent --task <TASK_NAME> physics=ovphysx
# Isaac Sim with PhysX and RTX rendering
uv run --extra isaacsim isaaclab random_agent --task <TASK_NAME> physics=isaacsim_physx
# Isaac Sim with the Rerun visualizer
uv run --extra isaacsim --extra rerun isaaclab random_agent --task <TASK_NAME> --viz rerun
```
The `all` extra forwards Isaac Lab's `all` selection. The `ov` extra installs both the `ovphysx` and `ovrtx` runtimes;
you can also select either independently. Commit `pyproject.toml` and `uv.lock` so collaborators use the same
environment.
## Run the tasks
List the migrated tasks from the project root:
列出已注册的任务:
```bash
uv run isaaclab list_envs --show_presets
```
The MLP training tasks are `Template-Twofootbot-mlp-v0` and `Template-Twofootbot-mlp-v1`.
Use Isaac Lab's unified trainer:
使用 RSL-RL PPO 训练 v2 任务:
```bash
uv run --extra isaacsim --extra rsl-rl isaaclab train --rl_library rsl_rl \
--task Template-Twofootbot-mlp-v1 --headless
uv run --extra isaacsim --extra rsl-rl isaaclab train \
--rl_library rsl_rl \
--task Template-Twofootbot-mlp-v2 \
--headless
```
The robot's URDF and ROS package are in `bot/2foot`.
如需训练其他版本,将 `--task` 后的 ID 替换为上表中的任务。训练日志和检查点由 Isaac Lab 写入其运行日志目录;训练运行目录包含 `run.json` 和一个或多个 `.pt` 检查点。
## Play all checkpoints in a run
## 回放检查点
From the project root, provide a training run directory to play each `.pt` checkpoint in step order. If the directory is
omitted, the script prompts for it:
### 回放单个检查点
使用 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 logs/rsl_rl/cartpole_direct/<RUN_DIRECTORY>
# or
uv run python playall.py
```
The task is read from the run directory's `run.json`; each checkpoint is played with 96 environments and a 500-step
video. Videos are saved in the run's `videos/play` directory using the checkpoint name. Existing videos are skipped,
so rerunning the script only plays checkpoints that do not yet have a video. The script reports an error if `run.json`
is missing, invalid, or does not contain a non-empty `task`.
To keep watching a run while training and automatically play newly saved checkpoints, use `autoplay.py`:
默认使用 GPU 0;通过 `--gpu` 指定其他 GPU 或 GPU 列表:
```bash
uv run python autoplay.py logs/rsl_rl/cartpole_direct/<RUN_DIRECTORY>
# Adjust the scan interval if needed; default is 10 seconds.
uv run python autoplay.py logs/rsl_rl/cartpole_direct/<RUN_DIRECTORY> --interval 5
# Select GPU 1 instead of the default GPU 0.
uv run python autoplay.py logs/rsl_rl/cartpole_direct/<RUN_DIRECTORY> --gpu 1
uv run python playall.py CanGoModel --gpu 1
uv run python playall.py CanGoModel --gpu 0,1
```
The watcher waits for a checkpoint file to remain unchanged across scans before playing it, skips checkpoints that
already have a video, and can be stopped with `Ctrl+C`. `--gpu` sets `CUDA_VISIBLE_DEVICES` for the playback process;
it accepts one GPU index (for example `1`) or a comma-separated list (for example `0,1`). The same option is available
in `playall.py`.
如果对应检查点的视频已经存在,脚本会跳过该检查点。若运行目录缺少有效的 `run.json`,或没有 `.pt` 检查点,脚本会报错。
## Resume an existing run
### 训练时自动回放新检查点
The original project logs are intentionally not copied. Resume directly from its checkpoint while running from this
project root:
`autoplay.py` 持续扫描训练运行目录;检查点在连续两次扫描中保持不变后才会启动回放。按 `Ctrl+C` 停止:
```bash
CUDA_VISIBLE_DEVICES=0 uv run --extra isaacsim --extra rsl-rl isaaclab train --rl_library rsl_rl \
--task Template-Twofootbot-mlp-v1 \
--max_iterations 100000 \
--headless \
--checkpoint ../TwoFootBot/logs/rsl_rl/cartpole_direct/2026-10-27_14-26-38/model_28000.pt
uv run python autoplay.py CanGoModel
```
Isaac Lab 3.0 takes the checkpoint path directly; the old `--resume` and `--load_run` options are no longer used.
可调整扫描间隔(秒)和 GPU:
## Project structure
Migrated task configurations and Gymnasium registrations are under
`src/TwoFootBot_isaaclab/tasks/manager_based/twofootbot`. Importing the project's `isaaclab.tasks` entry point registers
the preserved `Template-Twofootbot-mlp-v0` and `Template-Twofootbot-mlp-v1` task IDs.
## Project assets
Keep project-owned USD files and related data under `src/TwoFootBot_isaaclab/assets/data`. The asset module exposes a
stable path that works from an editable checkout and an installed wheel:
```python
from TwoFootBot_isaaclab.assets import TWOFOOTBOT_ISAACLAB_ASSETS_DIR
robot_usd_path = TWOFOOTBOT_ISAACLAB_ASSETS_DIR / "robots" / "my_robot.usd"
```bash
uv run python autoplay.py CanGoModel --interval 5 --gpu 1
```
Keep asset configuration in the `TwoFootBot_isaaclab.assets` package and pass `str(robot_usd_path)` to configuration fields that
expect a string. USD files are configured for Git LFS by the project's `.gitattributes`; install Git LFS before adding
large binary assets.
默认扫描间隔为 10 秒、默认 GPU 为 0。已存在回放视频的检查点会被跳过;回放失败的检查点会在后续扫描时重试。
## Development
## 从检查点继续训练
Run the registration test and code-quality checks through the project environment:
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
```
The test helpers under `source/isaaclab_tasks/test` in the Isaac Lab repository are not part of the installed
`isaaclab_tasks` package. Keep test fixtures in this project and use public Isaac Lab APIs. If you copy
`env_test_utils.py`, it becomes vendored code whose upstream changes you must track.
To configure VS Code or Cursor, run the `setup_python_env` task or invoke its command directly:
```bash
uv run isaaclab --editor
```
The setup command selects the active interpreter and writes a git-ignored `pyrightconfig.json`. The resulting
configuration inherits the project's checked-in Pyright settings and adds the Isaac Sim extensions, project `src` root,
and any Isaac Lab packages discovered in the active Python environment. This supports both Pylance in VS Code and
basedpyright in Cursor.
In VS Code, use Pylance and select the interpreter that ran the setup command. In Cursor, install the
[basedpyright extension](https://marketplace.visualstudio.com/items?itemName=detachhead.basedpyright) instead of
Pylance, select the same interpreter, and reload the window. Both language servers read `pyrightconfig.json`.
When using the `isaacsim` extra, include it while generating the editor configuration so the command can discover the
Isaac Sim installation:
需要配置 VS Code 的 Python 环境时,可运行:
```bash
uv run --extra isaacsim isaaclab --editor
```
For an Isaac Sim binaries installation that is not available in the project environment, provide its path explicitly:
## 许可
```bash
# Linux
uv run isaaclab --editor --isaac_path <isaac-sim-path>
# Windows
uv run isaaclab --editor --isaac_path <isaac-sim-path>
```
## Troubleshooting
If Pylance or basedpyright cannot resolve modules, confirm that the selected interpreter matches the one used to run the
setup command, then reload the editor window. To add a missing extension or reduce indexing memory, edit the `extraPaths`
array in the root `pyrightconfig.json`; remove simulator extension directories that the project does not use.
项目许可信息见仓库根目录的 [`LICENSE`](LICENSE)。

Binary file not shown.

After

Width:  |  Height:  |  Size: 96 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 162 KiB

BIN
png/model_55399.mp4 Normal file

Binary file not shown.