Demonstrations

Demonstrations#

Each benchmark task has 60 successful human VR demonstrations. They are published as the Hugging Face dataset SWIRL-Lab/bigym-g1-native60, one LeRobot v3 folder per task, with frames stored as lossless PNG.

Getting the demonstrations#

env.get_demos(n) downloads the task’s folder on first use. bigym-download fetches ahead of time:

uv run bigym-download --list                  # tasks the dataset provides
uv run bigym-download --all                   # every task
uv run bigym-download --task move_plate pick_box
uv run bigym-download --all --local-dir bigym-data   # into a folder instead of the cache

Both share the Hugging Face cache and its variables (HF_HOME, HF_TOKEN, HF_HUB_OFFLINE=1). BIGYM_DATASET_REPO and BIGYM_DATASET_REVISION select another repository or pin a revision.

Watching them#

uv run bigym-view opens a browser viewer for the dataset. --task move_plate opens that task first, and --demo-dir bigym-data opens a downloaded folder.

Loading them#

env.get_demos() checks the dataset against the env and decodes it:

  • On a make env it returns lists of ExtendedTimeStep with the env’s own frame stacking.

  • On a make_gym env it returns gymnasium-shaped trajectories: obs[i] --action[i]--> obs[i + 1].

It raises an error when the task has no published demonstrations or the dataset does not match the env. The FAQ covers both.

bigym.loco.demos.dataset.load_episodes(task_dir) is the reader underneath. It reads the LeRobot folder with pyarrow and Pillow, without installing lerobot. Row t holds the observation at step t with the action, reward and discount of the transition that produced it, and row 0 is the reset row.

How an episode ends#

Each episode ends on the step where the official env latches success, cut from a recording made with the collector’s longer 3.0 s hold.

Formats#

The collector writes one npz file per episode. Loading one needs only numpy:

from bigym.loco.demos import load_episode, validate_episode

episode = load_episode(path)
violations = validate_episode(episode)   # empty when valid

  • bigym-view --demo-dir reads both formats. get_demos() and load_episodes read LeRobot folders only.

  • Video-mode LeRobot exports are for viewing. The training loader rejects them because the codec is lossy.

  • Every step stores the full simulator state (full_qpos, full_qvel), so a batch can be re-rendered at another resolution, such as 224×224 for a VLA.

  • Every episode stores its engage snapshot for exact replay.

  • In the parquet files, frame k holds observation k and the action executed from it.

Converting and re-rendering#

Both commands need the lerobot extra (see Installation). bigym-export-lerobot converts an npz batch to LeRobot v3:

uv run bigym-export-lerobot --demo-dir <npz batch> \
    --repo-id <hf-user>/<dataset> --root <output dir>

bigym-rerender-lerobot takes the same arguments plus --size, re-renders the cameras (224×224 by default) and writes a LeRobot dataset:

uv run bigym-rerender-lerobot --demo-dir <npz batch> \
    --repo-id <hf-user>/<dataset>-224 --root <output dir>

Batch metadata#

Each batch’s metadata.json stores the configuration it was collected in under env_config, and EnvConfig.from_metadata(metadata) reads it back. That configuration holds the collector’s episode cap, which is longer than the benchmark budget (see Episode budgets).

Every task at once#

scripts/demo_grid.py plays one demonstration of every published task in a single looping viser scene, for screenshots and recordings:

MUJOCO_GL=egl uv run python scripts/demo_grid.py
MUJOCO_GL=egl uv run python scripts/demo_grid.py --tasks move_plate,pick_box --columns 2
MUJOCO_GL=egl uv run python scripts/demo_grid.py --record grid.mp4 --record-size 1920x1080
MUJOCO_GL=egl uv run python scripts/demo_grid.py --screenshot grid.png --frame 400

--help lists the other options. --export-states FILE.npz saves the chosen episodes’ states, and --states FILE.npz builds the grid from that file without the dataset.