TwoFootBot-isaaclab/README.md

161 lines
6.3 KiB
Markdown
Raw Normal View History

2026-11-02 05:56:55 +00:00
# TwoFootBot-isaaclab
2026-10-28 04:04:05 +00:00
2026-11-02 05:56:55 +00:00
An Isaac Lab 3.0 project containing the migrated TwoFootBot locomotion tasks and robot description.
2026-10-28 04:04:05 +00:00
## Installation
2026-11-02 05:56:55 +00:00
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:
2026-10-28 04:04:05 +00:00
```bash
2026-11-02 05:56:55 +00:00
uv sync --locked --extra isaacsim --extra rsl-rl
2026-10-28 04:04:05 +00:00
```
This project's `pyproject.toml` uses editable relative paths to an Isaac Lab source checkout. Update
`[tool.uv.sources]` if either directory moves.
2026-11-02 05:56:55 +00:00
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.
2026-10-28 04:04:05 +00:00
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
2026-11-02 05:56:55 +00:00
List the migrated tasks from the project root:
2026-10-28 04:04:05 +00:00
```bash
uv run isaaclab list_envs --show_presets
```
2026-11-02 05:56:55 +00:00
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`.
## 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.
2026-10-28 04:04:05 +00:00
## Project structure
2026-11-02 05:56:55 +00:00
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.
2026-10-28 04:04:05 +00:00
## 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.