# LIBERO-plus

  The commands below run the simulator locally. To keep its dependencies away from your policy's, serve it instead with `lerobot-env-server --config_path=docker/sim/configs/libero_plus.yaml --sim.task= --docker=true`, where `` is the command's `--env.task`, and add `--env.server.endpoint=tcp/127.0.0.1:7448` to the command. A server runs the task it was started with (see [Simulation: local or served](./simulation)).

LIBERO-plus adalah **benchmark ketangguhan** untuk model Vision-Language-Action (VLA) yang dibangun di atas [LIBERO](./libero). Benchmark ini secara sistematis menguji kebijakan (policies) dengan menerapkan **tujuh dimensi perturbasi independen** pada set tugas LIBERO asli, sehingga mengungkap mode kegagalan yang terlewat oleh benchmark standar.

- Paper: [Analisis Robustness Mendalam pada Model Vision-Language-Action](https://arxiv.org/abs/2510.13626)
- GitHub: [sylvestf/LIBERO-plus](https://github.com/sylvestf/LIBERO-plus)
- Dataset: [lerobot/libero_plus](https://huggingface.co/datasets/lerobot/libero_plus)

![An overview of the LIBERO-plus benchmark perturbation dimensions](https://github.com/sylvestf/LIBERO-plus/raw/main/static/images/libero-plus.jpg)

## Dimensi perturbasi

LIBERO-plus membuat ~10 000 varian tugas dengan mengganggu setiap tugas LIBERO asli di sepanjang sumbu-sumbu berikut:

| Dimensi             | Apa yang berubah                                          |
| --------------------- | ----------------------------------------------------- |
| Tata letak objek        | Posisi target, keberadaan objek pengganggu      |
| Sudut pandang kamera     | Posisi, orientasi, dan bidang pandang kamera           |
| Kondisi awal robot  | Pose awal manipulator                                |
| Instruksi bahasa | Deskripsi tugas yang ditulis ulang oleh LLM (parafrase / sinonim) |
| Kondisi pencahayaan      | Intensitas, arah, warna, bayangan                   |
| Tekstur latar belakang   | Permukaan adegan dan penampakan objek                   |
| Derau sensor          | Distorsi fotometrik dan degradasi gambar         |

## Kumpulan tugas yang tersedia

LIBERO-plus mengganggu 40 tugas asli dalam suite Spatial, Object, Goal, dan Long. Setiap tugas yang terdaftar dalam keempat suite ini adalah varian yang terganggu, bukan salah satu dari tugas aslinya. Fork ini juga mempertahankan 90 tugas yang tidak terganggu dalam LIBERO-90.

| Suite          | Nama CLI         | Tugas asli | Tugas terdaftar | Langkah maksimum | Deskripsi                                       |
| -------------- | ---------------- | -------------- | ---------------- | --------- | ------------------------------------------------- |
| LIBERO-Spatial | `libero_spatial` | 10             | 2,402            | 280       | Tugas yang memerlukan penalaran tentang relasi spasial |
| LIBERO-Object  | `libero_object`  | 10             | 2,518            | 280       | Tugas yang berfokus pada manipulasi berbagai objek  |
| LIBERO-Goal    | `libero_goal`    | 10             | 2,591            | 300       | Tugas dengan kondisi tujuan yang memiliki target berubah      |
| LIBERO-90      | `libero_90`      | 90             | 90               | 400       | Tugas LIBERO jangka pendek yang tidak terganggu            |
| LIBERO-Long    | `libero_10`      | 10             | 2,519            | 520       | Tugas jangka panjang dari koleksi LIBERO-100 |

Jumlah ini berasal dari [task registry](https://github.com/sylvestf/LIBERO-plus/blob/4976dc30028e805ff8094b55501d532c48fec182/libero/libero/benchmark/libero_suite_task_map.py) upstream. Keempat suite yang terganggu berisi total **10.030 varian task**; LIBERO-90 tidak termasuk dalam jumlah tersebut. Jumlah dan indeks task bergantung pada revisi fork yang terinstal.

  Menginstal LIBERO-plus **menggantikan** LIBERO biasa — proses ini akan menghapus `hf-libero` sehingga `import libero` mengarah ke fork LIBERO-plus. Anda tidak dapat menginstal keduanya secara bersamaan. Untuk kembali ke LIBERO biasa, hapus fork tersebut dan instal ulang dengan `pip install -e ".[libero]"`.

## Instalasi

### Dependensi sistem (hanya Linux)

```bash
sudo apt install libexpat1 libfontconfig1-dev libmagickwand-dev
```

### Paket Python

```bash
pip install -e ".[libero]" "robosuite==1.4.1" bddl easydict mujoco wand scikit-image gym
git clone https://github.com/sylvestf/LIBERO-plus.git
cd LIBERO-plus && pip install --no-deps -e .
pip uninstall -y hf-libero  # so `import libero` resolves to the fork
```

LIBERO-plus diinstal dari fork GitHub-nya, bukan dari extra pyproject — fork ini dikirim sebagai namespace package yang tidak dapat ditangani oleh pip, sehingga harus dikloning dan ditambahkan ke `PYTHONPATH`. Lihat tahap `libero_plus_native` di `docker/Dockerfile.sim` untuk instalasi yang resmi. MuJoCo diperlukan, sehingga hanya Linux yang didukung.

Atur backend rendering MuJoCo sebelum menjalankan evaluasi:

```bash
export MUJOCO_GL=egl   # headless / HPC / cloud
```

### Unduh aset LIBERO-plus

LIBERO-plus menyertakan paket aset yang diperluasnya secara terpisah. Unduh `assets.zip` dari [dataset Hugging Face](https://huggingface.co/datasets/Sylvest/LIBERO-plus/tree/main) dan ekstrak ke direktori paket LIBERO-plus:

```bash
# After installing the package, find where it was installed:
python -c "import libero; print(libero.__file__)"
# Then extract assets.zip into <package_root>/libero/assets/
```

## Evaluasi

### Evaluasi lokal bawaan

Evaluasi setiap varian yang terdaftar di keempat suite yang telah diperturbasi, menggunakan satu episode per varian seperti yang direkomendasikan oleh [panduan evaluasi upstream](https://github.com/sylvestf/LIBERO-plus#-evaluation):

```bash
lerobot-eval \
  --policy.path="your-policy-id" \
  --env.type=libero_plus \
  --env.task=libero_spatial,libero_object,libero_goal,libero_10 \
  --eval.batch_size=1 \
  --eval.n_episodes=1 \
  --env.max_parallel_tasks=1
```

Ini menjalankan **10.030 episode** untuk registry di atas. Dengan `--eval.n_episodes=10`, perintah yang sama menjalankan **100.300 episode**, bukan 400.

### Uji asap

Sebelum meluncurkan evaluasi penuh, periksa pengaturan Anda dengan satu varian terdaftar dan satu episode:

```bash
lerobot-eval \
  --policy.path="your-policy-id" \
  --env.type=libero_plus \
  --env.task=libero_spatial \
  --env.task_ids='[0]' \
  --eval.batch_size=1 \
  --eval.n_episodes=1
```

Ini adalah pemeriksaan konfigurasi, bukan evaluasi ketangguhan yang representatif.

### Evaluasi satu suite

Evaluasi pada satu suite LIBERO-plus:

```bash
lerobot-eval \
  --policy.path="your-policy-id" \
  --env.type=libero_plus \
  --env.task=libero_spatial \
  --eval.batch_size=1 \
  --eval.n_episodes=1
```

- `--env.task` memilih suite (`libero_spatial`, `libero_object`, dll.).
- `--env.task_ids` membatasi pada indeks tugas yang terdaftar (`[0]`, `[1,2,3]`, dll.), yang mengidentifikasi varian dalam empat suite yang terganggu. Abaikan untuk menjalankan semua tugas yang terdaftar. Saat mengevaluasi beberapa suite, daftar indeks yang sama diterapkan secara independen ke setiap suite.
- `--eval.batch_size` mengontrol berapa banyak lingkungan yang berjalan secara paralel.
- `--eval.n_episodes` mengatur jumlah episode yang dijalankan untuk setiap tugas yang terdaftar. Meningkatkannya akan mengulang evaluasi dari varian yang dipilih; hal ini tidak memilih varian berbeda tambahan.

### Evaluasi multi-suite

Bandingkan kinerja kebijakan di beberapa suite sekaligus dengan meneruskan daftar yang dipisahkan koma:

```bash
lerobot-eval \
  --policy.path="your-policy-id" \
  --env.type=libero_plus \
  --env.task=libero_spatial,libero_object \
  --eval.batch_size=1 \
  --eval.n_episodes=1
```

### Mode kontrol

LIBERO-plus mendukung dua mode kontrol — `relative` (default) dan `absolute`. Berbagai checkpoint VLA dilatih dengan parameterisasi aksi yang berbeda, jadi pastikan mode tersebut sesuai dengan kebijakan Anda:

```bash
--env.control_mode=relative   # or "absolute"
```

### Atur ulang kinerja

Secara default, LeRobot mempertahankan perilaku hard-reset dari LIBERO. Dengan initial states yang tetap diaktifkan, Anda dapat memilih soft reset untuk melewati proses membangun ulang model simulator dan renderer di setiap episode:

```bash
--env.init_states=true --env.hard_reset=false
```

Soft reset lebih cepat tetapi tidak identik secara bit dengan hard reset setelah langkah penstabilan lingkungan, sehingga pengamatan kamera dan hasil kebijakan mungkin sedikit berbeda. Gunakan hard reset saat mereproduksi hasil benchmark.

### Input dan output kebijakan

**Observasi:**

- `observation.state` — fitur proprioseptif 8-dimensi (posisi eef, orientasi axis-angle, qpos gripper)
- `observation.images.image` — tampilan kamera utama (`agentview_image`), HWC uint8
- `observation.images.image2` — tampilan kamera pergelangan tangan (`robot0_eye_in_hand_image`), HWC uint8

**Aksi:**

- Kontrol kontinu dalam `Box(-1, 1, shape=(7,))` — delta ujung-efektor 6D + gripper 1D

### Beban kerja evaluasi dan reproduktibilitas

Jumlah total episode evaluasi adalah **jumlah tugas terdaftar yang dipilih di semua suite × `--eval.n_episodes`**. Sebagai contoh, semua varian Spatial dengan satu episode masing-masing menghasilkan 2.402 episode; memilih `--env.task_ids='[0,1,2]'` di Spatial dan Object dengan satu episode masing-masing menghasilkan enam episode.

Perhitungan 400 episode (40 tugas asli × 10 episode) berlaku untuk LIBERO vanilla, bukan evaluasi LIBERO-plus penuh. Untuk LIBERO-plus, mulailah dengan satu episode per varian yang terdaftar. Episode berulang dari suatu varian tidak setara dengan pengambilan sampel varian yang berbeda dari tugas asli.

Untuk subset kustom, gunakan [task classification](https://github.com/sylvestf/LIBERO-plus/blob/4976dc30028e805ff8094b55501d532c48fec182/libero/libero/benchmark/task_classification.json) dari fork untuk mengidentifikasi kategori perturbasi dan tingkat kesulitan. Jangan berasumsi bahwa setiap tugas asli memiliki sepuluh varian yang berbeda di setiap kategori perturbasi. Catat revisi fork, nama suite yang dipilih dan indeks tugas, episode per varian, seed, serta pengaturan reset saat melaporkan hasil. Untuk membandingkan dengan hasil yang telah dipublikasikan, ikuti protokol sampling dan agregasi benchmark, bukan menganggap subset arbitrer sebagai ekuivalen.

## Pelatihan

### Dataset

Dataset pelatihan dalam format LeRobot untuk LIBERO-plus tersedia di:

- [lerobot/libero_plus](https://huggingface.co/datasets/lerobot/libero_plus)

### Perintah pelatihan contoh

```bash
lerobot-train \
    --policy.type=smolvla \
    --policy.repo_id=${HF_USER}/smolvla_libero_plus \
    --policy.load_vlm_weights=true \
    --dataset.repo_id=lerobot/libero_plus \
    --env.type=libero_plus \
    --env.task=libero_spatial \
    --output_dir=./outputs/ \
    --steps=100000 \
    --batch_size=4 \
    --eval.batch_size=1 \
    --eval.n_episodes=1 \
    --env_eval_freq=1000
```

## Hubungan dengan LIBERO

LIBERO-plus adalah ekstensi drop-in dari LIBERO:

- Antarmuka gym Python yang sama (`LiberoEnv`) dan observasi kanonik
- Nama kamera dan format observasi/aksi yang sama
- Nama suite tugas yang sama
- Diinstal di bawah nama paket Python `libero` yang sama (repo GitHub berbeda)

Untuk menggunakan benchmark LIBERO asli, lihat [LIBERO](./libero) dan gunakan `--env.type=libero`.