Skip to content

Commit 04a157f

Browse files
cvolkcvolkhajan
cvolkcvolk
and
hajan
authored
docs: comprehensive README overhaul (#480)
Picks up the work from #461 (hajan:improve-readme), which couldn't pass CI due to a missing NVCR token on the fork. ## Changes - Add pre-alpha status warning banner - Add version/platform/license badges - Add quick-start installation section - Add composability overview table (Scene / Embodiment / Task) - Add usage example (kitchen pick-and-place) - Add project structure tree (including missing `isaaclab_arena_environments/` and `isaaclab_arena_examples/`) - Add version compatibility table (with corrected Isaac Sim 5.0.0 for `release/0.1.1`) - Add ecosystem, contributing, support, and citation sections - Restore "Made with ❤️ by the NVIDIA Robotics Team" footer --------- Signed-off-by: Clemens Volk <cvolk@nvidia.com> Co-authored-by: hajan <spencer.m.huang@gmail.com>
1 parent 9812aec commit 04a157f

File tree

1 file changed

+228
-5
lines changed

1 file changed

+228
-5
lines changed

‎README.md‎

Lines changed: 228 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,239 @@
1-
# Isaac-Lab Arena
1+
<div align="center">
2+
3+
# Isaac Lab Arena
4+
5+
### Composable Environment Creation and Policy Evaluation for Robotics Simulation
6+
7+
[![Pre-Alpha](https://img.shields.io/badge/status-pre--alpha-e8912d.svg)](#%EF%B8%8F-project-status)
8+
[![Version](https://img.shields.io/badge/version-0.1.x-blue.svg)](https://github.com/isaac-sim/IsaacLab-Arena/tree/release/0.1.1)
9+
[![IsaacSim](https://img.shields.io/badge/IsaacSim-5.1.0-silver.svg)](https://docs.isaacsim.omniverse.nvidia.com/latest/index.html)
10+
[![IsaacLab](https://img.shields.io/badge/IsaacLab-2.3.0-silver.svg)](https://github.com/isaac-sim/IsaacLab)
11+
[![Python](https://img.shields.io/badge/python-≥3.10-blue.svg)](https://docs.python.org/3/whatsnew/3.10.html)
12+
[![Linux](https://img.shields.io/badge/platform-linux--64-orange.svg)](https://releases.ubuntu.com/22.04/)
13+
[![License](https://img.shields.io/badge/license-Apache--2.0-yellow.svg)](LICENSE.md)
214

3-
**A scalable environment creation and evaluation framework for robotics simulations built on top of NVIDIA Isaac Lab**
15+
[Documentation](https://isaac-sim.github.io/IsaacLab-Arena/main/index.html) · [NVIDIA Blog Post](https://developer.nvidia.com/blog/simplify-generalist-robot-policy-evaluation-in-simulation-with-nvidia-isaac-lab-arena/) · [Report a Bug](https://github.com/isaac-sim/IsaacLab-Arena/issues) · [Discussions](https://github.com/isaac-sim/IsaacLab-Arena/discussions)
416

517
</div>
618

7-
Isaac-Lab Arena is a comprehensive robotics simulation framework that enhances NVIDIA Isaac Lab by providing a composable, scalable system for creating diverse simulation environments and evaluating robot learning policies. The framework enables researchers and developers to rapidly prototype and test robotic tasks with various robot embodiments, objects, and environments.
19+
---
20+
21+
> [!WARNING]
22+
> **Pre-Alpha Software — Not an Early Access or General Availability Release.**
23+
> Isaac Lab Arena `v0.1.x` is an early code release intended to give the community a practical starting point to experiment, provide feedback, and influence future design direction. APIs are unstable and will change. Features are incomplete. Documentation is evolving. **Do not use this in production.** See [Project Status](#%EF%B8%8F-project-status) for details.
24+
25+
---
26+
27+
## Overview
28+
29+
**Isaac Lab Arena** is an open-source extension to [NVIDIA Isaac Lab](https://github.com/isaac-sim/IsaacLab) that simplifies the creation of large-scale task and environment libraries for robotic policy evaluation. Co-developed with [Lightwheel](https://www.lightwheel.ai/), it provides a composable architecture where environments are assembled on-the-fly from independent, reusable building blocks — eliminating the redundant boilerplate that plagues traditional task library development.
30+
31+
Instead of hand-writing and maintaining a separate configuration for every combination of robot, object, and scenario, Arena lets you **compose** environments from three independent primitives:
32+
33+
| Primitive | Description |
34+
|-----------|-------------|
35+
| **Scene** | The physical environment layout — a collection of objects, furniture, fixtures |
36+
| **Embodiment** | The robot and its observations, actions, sensors, and controllers |
37+
| **Task** | The objective — what the robot should accomplish (pick-and-place, open door, etc.) |
38+
39+
The `ArenaEnvBuilder` composes these primitives into a standard `ManagerBasedRLEnvCfg` that runs natively in Isaac Lab.
40+
41+
## Why Isaac Lab Arena?
42+
43+
With the rise of generalist robot policies (e.g., [GR00T N](https://developer.nvidia.com/isaac/gr00t), [pi0](https://www.physicalintelligence.company/), [SmolVLA](https://huggingface.co/docs/lerobot/smolvla)), there is an urgent need to evaluate these policies across many diverse tasks and environments. Traditional approaches suffer from:
44+
45+
- **Code duplication** — each task variation (different object, different robot) requires a near-copy of the same configuration
46+
- **Maintenance burden** — N robots × M objects × K scenes = an explosion of configs to keep in sync
47+
- **Slow iteration** — researchers spend more time wrangling configs than running experiments
48+
49+
Arena solves this by making environment variation a first-class concept. Swap an object, change a robot, or modify a scene — all without duplicating a single line of task logic.
50+
51+
## Key Features
52+
53+
- **Composable Environments** — Mix and match scenes, embodiments, and tasks independently
54+
- **On-the-fly Assembly** — Environments are built at runtime; no duplicate config files to maintain
55+
- **Asset Registry** — Centralized management of robots, objects, and scenes with affordance annotations
56+
- **Integrated Evaluation** — Built-in metrics and evaluation pipelines for policy benchmarking
57+
- **Teleoperation Support** — Data collection via keyboard, VR, or other input devices
58+
- **GR00T Integration** — First-class support for NVIDIA GR00T N policy training and evaluation
59+
- **LeRobot Hub** — Publish and share environments on the [Hugging Face LeRobot Environment Hub](https://huggingface.co/blog/nvidia/generalist-robotpolicy-eval-isaaclab-arena-lerobot)
60+
61+
## Quick Start
62+
63+
### Prerequisites
64+
65+
- Linux (Ubuntu 22.04+)
66+
- NVIDIA GPU (see [Isaac Sim hardware requirements](https://docs.isaacsim.omniverse.nvidia.com/5.1.0/installation/requirements.html))
67+
- Docker and NVIDIA Container Toolkit
68+
- Git
69+
70+
### Installation
71+
72+
Isaac Lab Arena currently supports **installation from source inside a Docker container**.
73+
74+
```bash
75+
# 1. Clone the repository
76+
git clone git@github.com:isaac-sim/IsaacLab-Arena.git
77+
cd IsaacLab-Arena
78+
git submodule update --init --recursive
79+
80+
# 2. Launch the Docker container
81+
# Base container (recommended for development):
82+
./docker/run_docker.sh
83+
84+
# Or with GR00T dependencies (for policy training/evaluation):
85+
./docker/run_docker.sh -g
86+
87+
# 3. Verify the installation
88+
/isaac-sim/python.sh -m pytest -sv -m "not with_cameras" isaaclab_arena/tests/
89+
```
90+
91+
> **Note:** The Docker script automatically mounts `$HOME/datasets`, `$HOME/models`, and `$HOME/eval` from your host into the container.
92+
93+
For detailed setup instructions (including server-client mode for GR00T), see the [Installation Guide](https://isaac-sim.github.io/IsaacLab-Arena/main/pages/quickstart/installation.html).
94+
95+
## Usage Example
96+
97+
Compose a Franka arm in a kitchen scene with a couple of objects:
98+
99+
```python
100+
from isaaclab_arena.assets.asset_registry import AssetRegistry
101+
from isaaclab_arena.cli.isaaclab_arena_cli import get_isaaclab_arena_cli_parser
102+
from isaaclab_arena.environments.arena_env_builder import ArenaEnvBuilder
103+
from isaaclab_arena.environments.isaaclab_arena_environment import IsaacLabArenaEnvironment
104+
from isaaclab_arena.scene.scene import Scene
105+
106+
asset_registry = AssetRegistry()
107+
108+
# Select building blocks
109+
background = asset_registry.get_asset_by_name("kitchen")()
110+
embodiment = asset_registry.get_asset_by_name("franka")()
111+
cracker_box = asset_registry.get_asset_by_name("cracker_box")()
112+
tomato_soup_can = asset_registry.get_asset_by_name("tomato_soup_can")()
113+
114+
# Compose the environment
115+
scene = Scene(assets=[background, cracker_box, tomato_soup_can])
116+
env_cfg = IsaacLabArenaEnvironment(
117+
name="franka_kitchen_example",
118+
embodiment=embodiment,
119+
scene=scene,
120+
)
121+
122+
args_cli = get_isaaclab_arena_cli_parser().parse_args([])
123+
env_builder = ArenaEnvBuilder(env_cfg, args_cli)
124+
env = env_builder.make_registered()
125+
env.reset()
126+
```
127+
128+
Explore more examples in the [documentation](https://isaac-sim.github.io/IsaacLab-Arena/main/index.html), including:
129+
130+
| Example | Description |
131+
|---------|-------------|
132+
| [G1 Loco-Manipulation](https://isaac-sim.github.io/IsaacLab-Arena/main/pages/example_workflows/locomanipulation/index.html) | Unitree G1 humanoid locomotion + manipulation |
133+
| [GR1 Open Microwave Door](https://isaac-sim.github.io/IsaacLab-Arena/main/pages/example_workflows/static_manipulation/index.html) | GR1 humanoid interacting with articulated objects |
134+
| [GR1 Sequential Pick & Place](https://isaac-sim.github.io/IsaacLab-Arena/main/pages/example_workflows/sequential_static_manipulation/index.html) | Multi-step manipulation with GR1 |
135+
| [Franka Lift Object](https://isaac-sim.github.io/IsaacLab-Arena/main/pages/example_workflows/reinforcement_learning/index.html) | Classic Franka pick-up task |
136+
137+
## Project Structure
138+
139+
```
140+
IsaacLab-Arena/
141+
├── isaaclab_arena/ # Core framework (environments, tasks, scenes, embodiments)
142+
├── isaaclab_arena_environments/ # Concrete environment definitions
143+
├── isaaclab_arena_examples/ # Policy and relation examples
144+
├── isaaclab_arena_g1/ # Unitree G1 humanoid embodiment + examples
145+
├── isaaclab_arena_gr00t/ # GR00T policy integration
146+
├── docker/ # Docker configurations and launch scripts
147+
├── docs/ # Sphinx documentation source
148+
├── osmo/ # Cloud deployment configs (OSMO)
149+
├── submodules/ # Git submodules (Isaac Lab, etc.)
150+
├── setup.py # Package installation
151+
├── CONTRIBUTING.md # Contribution guidelines
152+
└── LICENSE.md # Apache 2.0 license
153+
```
154+
155+
## Version Compatibility
156+
157+
| Isaac Lab Arena | Isaac Lab | Isaac Sim | Python |
158+
|-----------------|-----------|-----------|--------|
159+
| `main` branch | 2.3.2 | 5.1.0 | ≥ 3.10 |
160+
| `release/0.1.1` | 2.3.0 | 5.0.0 | ≥ 3.10 |
161+
162+
## ⚠️ Project Status
163+
164+
Isaac Lab Arena is in **pre-alpha** (`v0.1.x`). This is important to understand:
165+
166+
| What This Means | Details |
167+
|-----------------|---------|
168+
| **Not EA / GA** | This is not an Early Access or General Availability release. It is a very early community code drop. |
169+
| **APIs will break** | Public interfaces are under active development and will change without deprecation warnings. |
170+
| **Features are incomplete** | Core capabilities like natural-language object placement, composite task chaining, RL task setup, and heterogeneous parallel evaluation are planned but not yet implemented. |
171+
| **Docker-only install** | Source installation in a Docker container is the only supported method in `v0.1.x`. |
172+
| **Limited testing** | The `main` branch contains the latest code but may not be fully tested. Use `release/0.1.1` for the most stable experience. |
173+
174+
175+
## Ecosystem
176+
177+
Isaac Lab Arena is part of a growing ecosystem of tools and benchmarks:
178+
179+
- **[Lightwheel RoboCasa Tasks](https://github.com/lightwheel-ai)** — 250+ open-source tasks built on Arena
180+
- **[Lightwheel LIBERO Tasks](https://github.com/lightwheel-ai)** — Adapted LIBERO benchmarks
181+
- **[LeRobot Environment Hub](https://huggingface.co/blog/nvidia/generalist-robotpolicy-eval-isaaclab-arena-lerobot)** — Share and discover Arena environments on Hugging Face
182+
- **[RoboTwin 2.0](https://robotwin-benchmark.github.io/dex-robot/)** — Extended simulation benchmarks using Arena
183+
- **[Isaac Lab Teleop](https://github.com/isaac-sim/IsaacLab)** — Demonstration collection
184+
- **[Isaac Lab Mimic](https://github.com/isaac-sim/IsaacLab)** — Synthetic data generation
185+
186+
## Contributing
187+
188+
We welcome contributions — bug reports, feature suggestions, and code. This is a pre-alpha project, so community input directly shapes the framework's direction.
189+
190+
1. Read the [Contribution Guidelines](CONTRIBUTING.md)
191+
2. Sign off your commits (DCO required — see `CONTRIBUTING.md`)
192+
3. Open a [Pull Request](https://github.com/isaac-sim/IsaacLab-Arena/pulls)
193+
194+
Areas where contributions are especially valuable:
195+
- New task definitions and benchmark suites
196+
- Additional robot embodiments and scene assets
197+
- Sim-to-real validated evaluation methods
198+
- Documentation improvements and tutorials
199+
200+
## Support
201+
202+
- **Questions & Ideas** — [GitHub Discussions](https://github.com/isaac-sim/IsaacLab-Arena/discussions)
203+
- **Bug Reports** — [GitHub Issues](https://github.com/isaac-sim/IsaacLab-Arena/issues)
204+
- **Isaac Sim Questions** — [NVIDIA Forums](https://forums.developer.nvidia.com/c/agx-autonomous-machines/isaac/67)
205+
- **Community Chat** — [Omniverse Discord](https://discord.com/invite/nvidiaomniverse)
206+
207+
## License
208+
209+
Isaac Lab Arena is released under the [Apache 2.0 License](LICENSE.md).
210+
211+
Note that Isaac Lab Arena requires Isaac Sim, which includes components under proprietary licensing terms. See the [Isaac Sim license](https://docs.isaacsim.omniverse.nvidia.com/latest/common/NVIDIA_Omniverse_License_Agreement.html) for details.
212+
213+
## Citation
214+
215+
If you use Isaac Lab Arena in your research, please cite:
216+
217+
```bibtex
218+
@misc{isaaclab-arena2025,
219+
title = {Isaac Lab Arena: Composable Environment Creation and Policy Evaluation for Robotics},
220+
author = {{NVIDIA Isaac Lab Arena Contributors}},
221+
year = {2025},
222+
url = {https://github.com/isaac-sim/IsaacLab-Arena}
223+
}
224+
```
225+
226+
If you use Isaac Lab (the underlying framework), please also cite the [Isaac Lab paper](https://arxiv.org/abs/2511.04831).
227+
228+
## Acknowledgements
229+
230+
Isaac Lab Arena is co-developed with [Lightwheel](https://www.lightwheel.ai/) and builds on [NVIDIA Isaac Lab](https://github.com/isaac-sim/IsaacLab). We thank the Isaac Lab team and the broader robotics community for their foundational work.
8231

9-
To get started with Isaac-Lab Arena, see our [documentation site](https://isaac-sim.github.io/IsaacLab-Arena/main/index.html).
232+
---
10233

11234
<div align="center">
12235

13-
**Isaac-Lab Arena** - Scaling robotic simulation and evaluation for the future
236+
**Isaac Lab Arena** · Pre-Alpha · [Documentation](https://isaac-sim.github.io/IsaacLab-Arena/main/index.html) · [GitHub](https://github.com/isaac-sim/IsaacLab-Arena)
14237

15238
Made with ❤️ by the NVIDIA Robotics Team
16239

0 commit comments

Comments
 (0)