176 lines
7.1 KiB
Markdown
176 lines
7.1 KiB
Markdown
# TwoFootBot-isaaclab
|
|
|
|
An Isaac Lab 3.0 project containing the migrated TwoFootBot locomotion tasks and robot description.
|
|
|
|
|
|
## 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:
|
|
|
|
```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.
|
|
|
|
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:
|
|
|
|
```bash
|
|
uv run --extra isaacsim --extra rsl-rl isaaclab train --rl_library rsl_rl \
|
|
--task Template-Twofootbot-mlp-v1 --headless
|
|
```
|
|
|
|
The robot's URDF and ROS package are in `bot/2foot`.
|
|
|
|
## 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:
|
|
|
|
```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`:
|
|
|
|
```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
|
|
```
|
|
|
|
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`.
|
|
|
|
## Resume an existing run
|
|
|
|
The original project logs are intentionally not copied. Resume directly from its checkpoint while running from this
|
|
project root:
|
|
|
|
```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
|
|
```
|
|
|
|
Isaac Lab 3.0 takes the checkpoint path directly; the old `--resume` and `--load_run` options are no longer used.
|
|
|
|
## 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"
|
|
```
|
|
|
|
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
|
|
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:
|
|
|
|
```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.
|