redmo is ok
This commit is contained in:
parent
d962687b9d
commit
b3add27910
259
README.md
259
README.md
|
|
@ -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:
|
||||
以下图片展示了机器人在仿真中的模型和结构设计:
|
||||
|
||||
| 仿真模型 | 机器人结构示意 |
|
||||
| --- | --- |
|
||||
|  |  |
|
||||
|
||||
`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 \
|
||||
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 ../TwoFootBot/logs/rsl_rl/cartpole_direct/2026-10-27_14-26-38/model_28000.pt
|
||||
--checkpoint CanGoModel/model_55399.pt
|
||||
```
|
||||
|
||||
Isaac Lab 3.0 takes the checkpoint path directly; the old `--resume` and `--load_run` options are no longer used.
|
||||
请确保 `--task` 与检查点训练所用任务一致;示例检查点对应 v2,训练任务信息也可在 `CanGoModel/run.json` 中查看。
|
||||
|
||||
## 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"
|
||||
```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 # 锁定的依赖版本
|
||||
```
|
||||
|
||||
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.
|
||||
## 开发与测试
|
||||
|
||||
## Development
|
||||
|
||||
Run the registration test and code-quality checks through the project environment:
|
||||
运行任务注册测试:
|
||||
|
||||
```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 |
Binary file not shown.
Loading…
Reference in New Issue