# RoboMME

  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/robomme.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)).

[RoboMME](https://robomme.github.io) — это бенчмарк манипуляций с расширенной памятью, созданный на базе ManiSkill (SAPIEN). Он оценивает способность робота удерживать и использовать информацию в течение эпизода — подсчёт, постоянство объектов, ссылки и имитация.

- **16 задач** в 4 наборах навыков по работе с памятью
- **1600 демонстраций обучения** (по 100 на задачу, 50 для валидации, 50 для тестирования)
- **Набор данных**: [`lerobot/robomme`](https://huggingface.co/datasets/lerobot/robomme) — LeRobot v3.0, 768K кадров при 10 fps
- **Симулятор**: ManiSkill / SAPIEN, манипулятор Panda, только Linux

![RoboMME benchmark tasks overview](/static-proxy?url=https%3A%2F%2Fcdn-thumbnails.huggingface.co%2Fsocial-thumbnails%2Fpapers%2F2603.04639%2Fgradient.png)

## Задачи

| Suite                             | Задачи                                                         |
| --------------------------------- | ------------------------------------------------------------- |
| **Подсчёт** (временная память)    | BinFill, PickXtimes, SwingXtimes, StopCube                    |
| **Постоянство** (пространственная память)   | VideoUnmask, VideoUnmaskSwap, ButtonUnmask, ButtonUnmaskSwap  |
| **Справочник** (память объектов)     | PickHighlight, VideoRepick, VideoPlaceButton, VideoPlaceOrder |
| **Имитация** (процедурная память) | MoveCube, InsertPeg, PatternLock, RouteStick                  |

## Установка

> RoboMME требует **Linux** (ManiSkill/SAPIEN использует рендеринг Vulkan). Рекомендуется использовать Docker для изоляции конфликтов зависимостей.

### Native (Linux)

```bash
uv pip install --override <(printf 'gymnasium==0.29.1\nnumpy==1.26.4\n') \
  -e '.[smolvla,av-dep]' \
  'robomme @ git+https://github.com/RoboMME/robomme_benchmark.git@main'
```

> **Примечание о зависимостях**: `mani-skill` (подтягивается `robomme`) фиксирует `gymnasium==0.29.1` и `numpy<2.0.0`, что конфликтует с базовой зависимостью lerobot `numpy>=2.0.0`. Именно поэтому `robomme` не является pyproject extra — используйте установку с переопределением, описанную выше, или подход с Docker, описанный ниже, чтобы полностью избежать конфликтов.

### Docker (рекомендуется)

Запустите RoboMME в собственном образе симулятора, чтобы его фиксированные версии `numpy`/`gymnasium` никогда не пересекались с версиями, используемыми политикой:

```bash
lerobot-env-server --config_path=docker/sim/configs/robomme.yaml --docker=true
```

Затем выполните оценку с помощью `--env.type=robomme --env.server.endpoint=tcp/127.0.0.1:7448` (см. [Симуляция: локальная или серверная](./simulation)).

## Запуск оценки

### Default (одна задача, один эпизод)

```bash
lerobot-eval \
    --policy.path=<your_policy_repo> \
    --env.type=robomme \
    --env.task=PickXtimes \
    --env.dataset_split=test \
    --env.task_ids=[0] \
    --eval.batch_size=1 \
    --eval.n_episodes=1
```

### Оценка по нескольким задачам

Оцените несколько задач за один запуск, разделяя имена задач запятыми. Используйте `task_ids`, чтобы управлять тем, какие эпизоды оцениваются для каждой задачи. Рекомендуется: 50 эпизодов на задачу для тестовой выборки.

```bash
lerobot-eval \
    --policy.path=<your_policy_repo> \
    --env.type=robomme \
    --env.task=PickXtimes,BinFill,StopCube,MoveCube,InsertPeg \
    --env.dataset_split=test \
    --env.task_ids=[0,1,2,3,4,5,6,7,8,9] \
    --eval.batch_size=1 \
    --eval.n_episodes=50
```

### Ключевые параметры CLI для `env.type=robomme`

| Параметр               | По умолчанию       | Описание                                        |
| -------------------- | ------------- | -------------------------------------------------- |
| `env.task`           | `PickXtimes`  | Любое из 16 названий задач выше (через запятую)   |
| `env.dataset_split`  | `test`        | `train`, `val` или `test`                          |
| `env.action_space`   | `joint_angle` | `joint_angle` (8-мерный) или `ee_pose` (7-мерный)             |
| `env.episode_length` | `300`         | Максимальное количество шагов на эпизод                              |
| `env.task_ids`       | `null`        | Список индексов эпизодов для оценки (null = `[0]`) |

## Набор данных

Набор данных [`lerobot/robomme`](https://huggingface.co/datasets/lerobot/robomme) представлен в формате **LeRobot v3.0** и может быть загружен напрямую:

```python
from lerobot.datasets.lerobot_dataset import LeRobotDataset

dataset = LeRobotDataset("lerobot/robomme")
```

### Особенности набора данных

| Возможность            | Форма         | Описание                     |
| ------------------ | ------------- | ------------------------------- |
| `image`            | (256, 256, 3) | RGB-камера спереди                |
| `wrist_image`      | (256, 256, 3) | Камера на запястье RGB                |
| `actions`          | (8,)          | Углы сочленений + захват          |
| `state`            | (8,)          | Положения суставов + состояние захвата |
| `simple_subgoal`   | str           | Аннотация на высокоуровневом языке  |
| `grounded_subgoal` | str           | Аннотация языка с опорой на контекст    |
| `episode_index`    | int           | Идентификатор эпизода                      |
| `frame_index`      | int           | Кадр в эпизоде            |

### Выравнивание ключей признаков (обучение)

Обёртка env предоставляет доступ к своим камерам по пути `pixels/<camera_name>`, имена которых задаются параметрами `RoboMMEEnvConfig.front_camera_name` и `RoboMMEEnvConfig.wrist_camera_name` (по умолчанию `camera1` и `camera2`). Политика получает их как `observation.images.camera1` и `observation.images.camera2`, а состояние (`agent_pos`) — как `observation.state`.

Сырые столбцы набора данных не совпадают с ключами этой политики, поэтому при дообучении передайте `--rename_map`:

```bash
--rename_map='{"image": "observation.images.camera1", "wrist_image": "observation.images.camera2", "state": "observation.state", "actions": "action"}'
```

Переопределите `--env.front_camera_name` / `--env.wrist_camera_name`, если вы обучаете модель с использованием других ключей, чтобы наблюдения при оценке соответствовали ключам, на которых обучалась политика.

## Пространства действий

| Тип          | Размерность | Описание                                               |
| ------------- | --- | --------------------------------------------------------- |
| `joint_angle` | 8   | 7 углов сочленений + 1 захват (−1 закрыт, +1 открыт, абсолютное значение) |
| `ee_pose`     | 7   | xyz + roll/pitch/yaw + захват                            |

Устанавливается через `--env.action_space=joint_angle` (по умолчанию) или `--env.action_space=ee_pose`.

## Примечания по платформе

- **Только Linux**: ManiSkill требует SAPIEN/Vulkan. macOS и Windows не поддерживаются.
- **Рекомендуется GPU**: рендеринг возможен на CPU, но медленный; CUDA + Vulkan обеспечивают полную скорость.
- **конфликт gymnasium / numpy**: см. примечание об установке выше. Образ Docker обрабатывает это автоматически.
- **Вилка ManiSkill**: `robomme` зависит от конкретной вилки ManiSkill (`YinpeiDai/ManiSkill`), которая автоматически подключается через пакет `robomme`.