Skip to content

Commit f3e1b78

Browse files
geng-haorangeng-haoran
committed
comprehensive documentation enhancement - tutorials and index pages
1 parent 776c70e commit f3e1b78

24 files changed

Lines changed: 589 additions & 75 deletions

‎docs/source/index.md‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,6 @@
11
# RoboVerse
22

3-
<p align="center">
4-
<img src="./metasim/images/tea.jpg" alt="RoboVerse" style="max-width:100%; height:auto;" />
5-
</p>
3+
![RoboVerse](./metasim/images/tea.jpg)
64

75
<p align="center">
86
<a href="https://roboverseorg.github.io"><img src="https://img.shields.io/badge/project-page-brightgreen" alt="Project Page"></a>

‎docs/source/metasim/developer_guide/tips/index.md‎

Lines changed: 65 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,70 @@
1-
# Tips
1+
# Development Tips
2+
3+
This section contains helpful tips and best practices for working with RoboVerse and its dependencies.
4+
5+
---
6+
7+
## Topics
8+
9+
| Topic | Description |
10+
|-------|-------------|
11+
| [Hugging Face](huggingface) | Managing assets and models via Hugging Face Hub |
12+
| [Git Submodules](git_submodule) | Working with external dependencies as submodules |
13+
| [Git LFS](git_lfs) | Managing large files with Git Large File Storage |
14+
15+
---
16+
17+
## Quick Tips
18+
19+
### Environment Management
20+
21+
```bash
22+
# Create a dedicated conda environment
23+
conda create -n roboverse python=3.10
24+
conda activate roboverse
25+
26+
# Install in development mode
27+
pip install -e ".[dev]"
28+
```
29+
30+
### Debugging Simulations
31+
32+
```python
33+
# Enable verbose logging
34+
import logging
35+
logging.basicConfig(level=logging.DEBUG)
36+
37+
# Run in non-headless mode to visualize
38+
scenario = ScenarioCfg(
39+
robots=["franka"],
40+
simulator="mujoco",
41+
headless=False, # Show GUI for debugging
42+
)
43+
```
44+
45+
### Performance Profiling
46+
47+
```python
48+
import torch
49+
50+
# Enable CUDA profiling
51+
with torch.profiler.profile(
52+
activities=[
53+
torch.profiler.ProfilerActivity.CPU,
54+
torch.profiler.ProfilerActivity.CUDA,
55+
]
56+
) as prof:
57+
for _ in range(100):
58+
handler.simulate()
59+
60+
print(prof.key_averages().table(sort_by="cuda_time_total"))
61+
```
62+
63+
---
64+
265
```{toctree}
366
:titlesonly:
67+
:hidden:
468
569
huggingface
670
git_submodule

‎docs/source/metasim/features/cross_embodiment.md‎

Lines changed: 35 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,44 @@
1-
# Cross Embodiment
1+
# Cross-Embodiment Transfer
22

3-
For parallel gripper on tabletop manipulation, you can specify different robot for the same task. For example, you can specify `iiwa` for `StackCube` task.
3+
Cross-embodiment is a key feature of RoboVerse that enables policies and demonstrations to be transferred across different robot morphologies. This allows you to:
4+
5+
- Train on one robot and deploy on another
6+
- Leverage demonstrations from multiple robot types
7+
- Test generalization across embodiments
8+
9+
---
10+
11+
## Supported Robot Categories
12+
13+
| Category | Robots | Gripper Type |
14+
|----------|--------|--------------|
15+
| **7-DOF Arms** | Franka Panda, KUKA iiwa, Kinova Gen3 | Parallel gripper |
16+
| **6-DOF Arms** | UR5, UR10, xArm6 | Parallel gripper |
17+
| **Mobile Manipulators** | Fetch, Tiago, Stretch | Various |
18+
| **Dexterous Hands** | Allegro, Shadow, LEAP | Multi-finger |
19+
| **Humanoids** | H1, G1, GR1 | Anthropomorphic |
20+
21+
---
22+
23+
## Basic Usage
24+
25+
### Switching Robots for Tasks
26+
27+
For tabletop manipulation tasks with parallel grippers, you can swap robots easily:
428

529
```bash
30+
# Run StackCube with Franka (default)
31+
python scripts/advanced/replay_demo.py --sim=isaaclab --task=StackCube --num_envs=4
32+
33+
# Run the same task with KUKA iiwa
634
python scripts/advanced/replay_demo.py --sim=isaaclab --task=StackCube --num_envs=4 --robot=iiwa
35+
36+
# Run with UR10
37+
python scripts/advanced/replay_demo.py --sim=isaaclab --task=StackCube --num_envs=4 --robot=ur10
738
```
839

40+
---
41+
942
## Retarget between Robots
1043

1144
We provide `src/scripts/retarget_demo.py` to retarget trajectories from one source robot to one or multiple target robots.

‎docs/source/metasim/features/cross_sim.md‎

Lines changed: 117 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,121 @@
1-
# Cross Simulator
2-
## Basic usage
3-
By default, the simulator is set to `isaacsim`. You can change it to other simulators by setting the `sim` argument. Currently, we support:
4-
- `isaacsim`
5-
- `isaacgym`
6-
- `pyrep`
7-
8-
## IsaacGym example
9-
For example, to replay the demo in IsaacGym, you can run:
1+
# Cross-Simulator Support
2+
3+
MetaSim enables you to write code once and run it across multiple physics simulators without modifications. This is one of the core features that makes RoboVerse a unified platform for robot learning.
4+
5+
---
6+
7+
## Supported Simulators
8+
9+
| Simulator | Backend | GPU Parallel | Best Use Case |
10+
|-----------|---------|--------------|---------------|
11+
| `mujoco` | MuJoCo | Via MJX | Fast prototyping, CPU training |
12+
| `mjx` | MuJoCo MJX | Native | Massively parallel RL |
13+
| `isaacsim` | Isaac Sim | Native | High-fidelity sim2real |
14+
| `isaacgym` | Isaac Gym | Native | GPU-accelerated RL |
15+
| `sapien3` | SAPIEN 3 | Native | Manipulation research |
16+
| `sapien2` | SAPIEN 2 | - | Legacy support |
17+
| `genesis` | Genesis | Native | Large-scale training |
18+
| `pybullet` | PyBullet | - | Debugging, education |
19+
20+
---
21+
22+
## Basic Usage
23+
24+
### Switching Simulators
25+
26+
Change the simulator by setting the `simulator` parameter in your scenario:
27+
28+
```python
29+
from metasim.scenario.scenario import ScenarioCfg
30+
31+
# Run with MuJoCo
32+
scenario = ScenarioCfg(
33+
robots=["franka"],
34+
simulator="mujoco", # Change this to switch simulators
35+
num_envs=1,
36+
)
37+
38+
# Or switch to Isaac Sim
39+
scenario = ScenarioCfg(
40+
robots=["franka"],
41+
simulator="isaacsim",
42+
num_envs=1,
43+
)
44+
```
45+
46+
### Command Line Examples
47+
48+
Most scripts support the `--sim` argument to select the simulator:
49+
1050
```bash
51+
# Run with MuJoCo
52+
python scripts/advanced/replay_demo.py --sim=mujoco --task=StackCube
53+
54+
# Run with Isaac Gym
1155
python scripts/advanced/replay_demo.py --sim=isaacgym --task=StackCube
56+
57+
# Run with SAPIEN 3
58+
python scripts/advanced/replay_demo.py --sim=sapien3 --task=PickCube
1259
```
1360

14-
task could also be:
15-
- `PickCube`
16-
- `StackCube`
17-
- `CloseBox`
61+
---
62+
63+
## Considerations
64+
65+
### Feature Parity
66+
67+
Not all features are available across all simulators. Check the [Support Matrix](support_matrix.rst) for detailed compatibility information.
68+
69+
### Performance Differences
70+
71+
| Simulator | Single Env Speed | Parallel Scaling | Rendering Quality |
72+
|-----------|------------------|------------------|-------------------|
73+
| MuJoCo | Fast | Good (via MJX) | Medium |
74+
| Isaac Sim | Medium | Excellent | Excellent (RTX) |
75+
| SAPIEN 3 | Fast | Good | Good |
76+
| Genesis | Fast | Excellent | Good |
77+
78+
### Asset Compatibility
79+
80+
Different simulators may require different asset formats:
81+
82+
| Simulator | Preferred Format |
83+
|-----------|------------------|
84+
| MuJoCo | MJCF (.xml) |
85+
| Isaac Sim | USD (.usd, .usda) |
86+
| SAPIEN | URDF (.urdf) |
87+
| PyBullet | URDF (.urdf) |
88+
89+
MetaSim handles format conversion automatically when possible.
90+
91+
---
92+
93+
## Example: Multi-Simulator Evaluation
94+
95+
Evaluate the same policy across different simulators to test sim2sim transfer:
96+
97+
```python
98+
from metasim.scenario.scenario import ScenarioCfg
99+
from metasim.task.registry import get_task_class
100+
101+
task_cls = get_task_class("StackCube")
102+
103+
simulators = ["mujoco", "sapien3", "isaacsim"]
104+
results = {}
105+
106+
for sim in simulators:
107+
scenario = task_cls.scenario.update(
108+
simulator=sim,
109+
num_envs=10,
110+
headless=True,
111+
)
112+
env = task_cls(scenario=scenario)
113+
114+
# Run evaluation
115+
success_rate = evaluate_policy(env, policy)
116+
results[sim] = success_rate
117+
118+
env.close()
119+
120+
print("Cross-simulator results:", results)
121+
```

‎docs/source/metasim/get_started/advanced/index.md‎

Lines changed: 27 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,34 @@
1-
# Advanced
1+
# Advanced Tutorials
22

3-
We also provide advanced tasks tutorials for using MetaSim:
3+
This section covers advanced topics for users who are comfortable with the basics and want to explore more sophisticated features of MetaSim.
4+
5+
---
6+
7+
## Overview
8+
9+
| Topic | Description | Difficulty |
10+
|-------|-------------|------------|
11+
| [Motion Planning](motion_planning/index) | Plan collision-free trajectories with CuRobo | Intermediate |
12+
| [RL Examples](rl_example/index) | Train RL policies with PPO, TD3, SAC | Intermediate |
13+
| [Imitation Learning](il/index) | Learn from demonstrations | Intermediate |
14+
| [Viser Visualization](viser/usage) | Web-based 3D visualization | Beginner |
15+
| [Object Layout](obj_layout/index) | Procedural scene generation | Advanced |
16+
17+
---
18+
19+
## Prerequisites
20+
21+
Before diving into these tutorials, ensure you have:
22+
23+
- Completed the [Quick Start](../quick_start/index) tutorials
24+
- Understanding of [Core Concepts](../../concept/architecture)
25+
- Installed relevant optional dependencies (e.g., `pip install -e ".[curobo]"` for motion planning)
26+
27+
---
428

529
```{toctree}
630
:titlesonly:
31+
:hidden:
732
833
motion_planning/index
934
rl_example/index

‎docs/source/metasim/get_started/quick_start/0_static_scene.md‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,19 @@
1-
# 0. Static Scene
2-
In this tutorial, we will show you how to use MetaSim to simulate a static scene.
1+
# Tutorial 0: Static Scene
32

4-
## Common Usage
3+
**Objective**: Learn how to load and visualize a basic simulation scene with objects.
4+
5+
**What you'll learn**:
6+
- How to create a `ScenarioCfg` with objects
7+
- How to launch a handler and render a scene
8+
- Different object types available in MetaSim
9+
10+
**Prerequisites**: [Installation](../installation) completed
11+
12+
**Estimated time**: 15 minutes
13+
14+
---
15+
16+
## Running the Tutorial
517

618
```bash
719
python get_started/0_static_scene.py --sim <simulator>

‎docs/source/metasim/get_started/quick_start/10_mount_camera.md‎

Lines changed: 16 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,19 @@
1-
# 10. Adding Camera
2-
In this tutorial, we demonstrate how to add and mount cameras in MetaSim.
3-
--sim <simulator>
4-
## Common Usage
1+
# Tutorial 10: Mount Camera
2+
3+
**Objective**: Learn how to add and mount cameras to robots and objects for visual observations.
4+
5+
**What you'll learn**:
6+
- Adding third-person view cameras
7+
- Mounting ego-centric cameras on robot links
8+
- Configuring camera resolution and intrinsics
9+
10+
**Prerequisites**: Completed [Tutorial 9: Config-Based Task](9_cfg_task)
11+
12+
**Estimated time**: 20 minutes
13+
14+
---
15+
16+
## Running the Tutorial
517

618
```bash
719
python get_started/10_mount_camera.py --sim <simulator>

‎docs/source/metasim/get_started/quick_start/12_domain_randomization.md‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,20 @@
1-
# 12. Domain Randomization
1+
# Tutorial 12: Domain Randomization
22

3-
This tutorial shows how to use domain randomization during trajectory replay. We'll go from simple material changes to full scene randomization with lighting and camera variations - basically everything you need for robust sim-to-real transfer.
3+
**Objective**: Learn how to apply domain randomization for robust sim-to-real transfer.
4+
5+
**What you'll learn**:
6+
- Scene randomization (geometry, materials, USD assets)
7+
- Lighting randomization (intensity, color temperature)
8+
- Camera randomization (position, orientation, FOV)
9+
- Multi-level randomization strategies
10+
11+
**Prerequisites**: Completed [Tutorial 10: Mount Camera](10_mount_camera)
12+
13+
**Estimated time**: 30 minutes
14+
15+
---
16+
17+
This tutorial shows how to use domain randomization during trajectory replay. We'll go from simple material changes to full scene randomization with lighting and camera variations.
418

519
## Quick Start
620

0 commit comments

Comments
 (0)