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

В этом руководстве описаны различные способы представления действий робота в LeRobot, их взаимосвязь и случаи, когда следует использовать каждый из них.

## Совместное пространство и пространство исполнительного органа

Прежде чем обсуждать представления действий, полезно понять два координатных пространства, в которых действия могут существовать.

### Совместное пространство

Действия в пространстве суставов напрямую задают целевые позиции для каждого привода. Для манипулятора с 6 степенями свободы и захватом действие в пространстве суставов может выглядеть так:

```
action = [shoulder_pan: 45.0, shoulder_lift: -20.0, elbow: -30.0, wrist_pitch: 10.0, wrist_roll: 0.0, wrist_yaw: 5.0, gripper: 0.8]
```

Совместное пространство (joint space) используется по умолчанию в LeRobot. Оно простое, не требует модели кинематики и напрямую отображается в команды для двигателей. Большинство начальных конфигураций (SO-100, Koch) используют действия в совместном пространстве.

### Пространство исполнительного органа (EE)

Действия в пространстве конечного эффектора задают желаемое положение и ориентацию наконечника инструмента робота (захвата) в декартовых координатах:

```
action = [x: 0.25, y: -0.10, z: 0.15, wx: 0.0, wy: 0.0, wz: 0.1, gripper: 0.8]
```

EE space is more intuitive for tasks like pick-and-place because it directly describes where the gripper should go, but it requires a kinematics model (URDF) to convert between EE poses and joint angles.

### Преобразование между пространствами

LeRobot предоставляет шаги процессора для преобразования между пространством суставов и пространством исполнительного органа с использованием прямой и обратной кинематики. Они построены на базе `RobotKinematics`, который загружает модель URDF вашего робота.

```python
from lerobot.model.kinematics import RobotKinematics
from lerobot.robots.so_follower.robot_kinematic_processor import (
    ForwardKinematicsJointsToEE,
    InverseKinematicsEEToJoints,
)

kinematics = RobotKinematics(
    urdf_path="./SO101/so101_new_calib.urdf",
    target_frame_name="gripper_frame_link",
    joint_names=["shoulder", "elbow", "wrist_pitch", "wrist_roll", "wrist_yaw"],
)

# Joints → EE (for observations: "where is my gripper?")
fk_step = ForwardKinematicsJointsToEE(kinematics=kinematics, motor_names=[...])

# EE → Joints (for actions: "move my gripper here")
ik_step = InverseKinematicsEEToJoints(kinematics=kinematics, motor_names=[...])
```

См. [`examples/so100_to_so100_EE/`](https://github.com/huggingface/lerobot/tree/main/examples/so100_to_so100_EE) для полного рабочего примера записи, воспроизведения и оценки с действиями в пространстве EE на манипуляторе SO-100.

## Абсолютные, относительные и дельта-действия

Независимо от того, работаете ли вы в пространстве суставов или в пространстве конечного эффектора, значения действий можно выразить тремя различными способами. Терминология следует [UMI (Chi et al., 2024)](https://arxiv.org/abs/2402.10329).

### Абсолютные действия (по умолчанию в LeRobot)

Каждое действие указывает целевую позицию напрямую.

**Пример** (совместное пространство, фрагмент из 4):

```
current_state = [45.0, -30.0, 10.0]

action_chunk = [
    [46.0, -29.0, 11.0],   # go to 46, -29, 11
    [47.5, -27.0, 12.0],   # go to 47.5, -27, 12
    [49.0, -25.0, 13.5],   # go to 49, -25, 13.5
    [50.0, -24.0, 15.0],   # go to 50, -24, 15
]
```

Каждое значение представляет собой целевую позицию в системе координат робота. Подход простой и прямой, но требует согласованной глобальной системы координат. Это значение по умолчанию в LeRobot.

### Относительные действия (используются в OpenPI / pi0)

Каждое действие в чанке представляет собой смещение от **текущего состояния на момент предсказания**. Все действия в чанке имеют общую точку отсчёта:

```
current_state = [45.0, -30.0, 10.0]

relative_chunk = [
    [1.0,  1.0, 1.0],   # +1 from current → target 46, -29, 11
    [2.5,  3.0, 2.0],   # +2.5 from current → target 47.5, -27, 12
    [4.0,  5.0, 3.5],   # +4 from current → target 49, -25, 13.5
    [5.0,  6.0, 5.0],   # +5 from current → target 50, -24, 15
]
```

Преобразование выполняется просто: `relative = absolute - current_state`. Чтобы восстановить абсолютное значение: `absolute = relative + current_state`.

**Зачем использовать относительные действия?** Модель обучается предсказывать смещения, центрированные вокруг нуля, что упрощает нормализацию и обеспечивает более стабильное обучение. Поскольку каждый фрагмент ссылается на одно и то же текущее состояние, накопление ошибок между фрагментами отсутствует.

### Delta Actions (последовательные различия)

Каждое действие представляет собой смещение от **предыдущего действия** (или от текущего состояния на первом шаге):

```
current_state = [45.0, -30.0, 10.0]

delta_chunk = [
    [1.0,  1.0, 1.0],   # current → 46, -29, 11
    [1.5,  2.0, 1.0],   # previous action → 47.5, -27, 12
    [1.5,  2.0, 1.5],   # previous action → 49, -25, 13.5
    [1.0,  1.0, 1.5],   # previous action → 50, -24, 15
]
```

Здесь каждый шаг является относительным по отношению к предыдущему. Чтобы восстановить абсолютные позиции, необходимо сложить все предыдущие дельты, что означает накопление ошибок со временем. UMI прямо выступает против такого представления по этой причине.

### Визуальное сравнение

Рисунок ниже (на основе рисунка из [UMI, Chi et al., 2024](https://arxiv.org/abs/2402.10329)) иллюстрирует ключевое различие. При использовании **относительной траектории** каждое действие в блоке отсылает к одной и той же исходной точке (текущему состоянию), поэтому новый шаг вывода чисто сбрасывает опорную точку. При использовании **дельты** каждое действие зависит от предыдущего, из-за чего ошибки накапливаются. **Абсолютные** действия требуют согласованной глобальной системы координат.

<img
  src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lerobot/action_representations_umi.png"
  alt="Relative Trajectory as Action Representation (UMI, Chi et al., 2024)"
  width="85%"
/>

## Использование относительных действий в LeRobot

LeRobot предоставляет `RelativeActionsProcessorStep` для преобразования между абсолютными и относительными действиями внутри конвейера процессора. Именно так pi0, pi0.5 и pi0_fast поддерживают относительные действия.

> **Примечание:** Все модели pi (pi0, pi0.5, pi0*fast) применяют относительное преобразование \_before* нормализации (`relative → normalize`), поэтому нормализатор всегда получает дельта (относительные) значения. Это означает, что **статистика относительных действий требуется** для всех них при обучении с `use_relative_actions=true`. В pi0_fast `RelativeActionsProcessorStep` изменяет только действие — наблюдение состояния не меняется — поэтому `NormalizerProcessorStep` по-прежнему выполняется перед токенизатором состояния, и токенизатор продолжает получать нормализованное состояние, как и ожидалось.

### Как это работает

Во время **обучения** (предобработки) действия преобразуются из абсолютных в относительные до того, как модель их увидит:

```
raw absolute action → RelativeActionsProcessorStep → normalize → model
```

Во время **инференса** (постобработки) предсказания модели преобразуются обратно в абсолютные значения перед отправкой роботу:

```
model output → unnormalize → AbsoluteActionsProcessorStep → robot
```

`AbsoluteActionsProcessorStep` считывает текущее состояние из кэша своего связанного `RelativeActionsProcessorStep`, поэтому эти два шага должны быть соединены (это выполняется автоматически фабрикой политики).

### Включение относительных действий для семейства pi (pi0, pi0.5, pi0_fast)

**Шаг 1**: Предварительно вычислите статистику относительных действий для вашего набора данных:

```bash
lerobot-edit-dataset \
    --repo_id your_dataset \
    --new_repo_id your_dataset \
    --operation.type recompute_stats \
    --operation.overwrite true \
    --operation.relative_action true \
    --operation.chunk_size 50 \
    --operation.relative_exclude_joints "['gripper']"
```

**Шаг 2**: Обучение с включенными относительными действиями:

```bash
lerobot-train \
    --dataset.repo_id=your_dataset \
    --policy.type=pi0 \
    --policy.use_relative_actions=true \
    --policy.relative_exclude_joints='["gripper"]'
```

Параметр `relative_exclude_joints` указывает на суставы, которые должны оставаться в абсолютном пространстве. Например, команды захвата обычно являются бинарными (открыть/закрыть) и не выигрывают от относительного кодирования.

Для конфигураций политики, в которых определён `action_feature_names`, функция `make_policy` заполняет этот список из метаданных `names` признака действия в наборе данных. Имена могут представлять собой плоскую последовательность или словарь, значения которого являются списками или кортежами. Например, `{"arm": ["shoulder", "elbow"], "hand": ["gripper"]}` превращается в `["shoulder", "elbow", "gripper"]`, а не в ключи групп. Порядок вставки групп и порядок внутри групп сохраняются, поэтому имена следует объявлять в том же порядке, что и вектор действия. Устаревшие сопоставления «имя–индекс» сохраняют поведение, основанное на порядке ключей.

### Сочетание относительных действий с RTC

[RTC](https://arxiv.org/abs/2506.07339) выполняет инференс политики с высокой частотой и отправляет действия роботу по мере их предсказания, а не ожидая формирования полного чанка. Относительные действия и RTC полностью совместимы: поскольку каждый чанк в относительном режиме ссылается на **один и тот же** текущий статус (зафиксированный в начале инференса), каждое предсказанное действие в чанке остаётся валидным смещением, даже если робот уже переместился. Специальная обработка не требуется — `RelativeActionsProcessorStep` кэширует статус один раз на каждый вызов инференса, а `AbsoluteActionsProcessorStep` применяет его ко всем действиям в потоковом выводе.

### Сочетание относительных действий с пространством EE

Относительные действия работают как в пространстве суставов, так и в пространстве конечного эффектора. Например, если ваш набор данных хранит действия конечного эффектора, относительное кодирование преобразует их в смещения от текущей позы конечного эффектора:

```
current_ee_state = [x: 0.25, y: -0.10, z: 0.15, gripper: 0.8]

absolute_ee_chunk = [
    [0.26, -0.09, 0.16, 0.8],
    [0.28, -0.07, 0.18, 0.8],
]

relative_ee_chunk = [
    [0.01,  0.01, 0.01, 0.0],   # offset from current EE pose
    [0.03,  0.03, 0.03, 0.0],   # offset from current EE pose
]
```

## Сводка конвейера обработки

Ниже показано, как комбинируются различные процессоры. Каждая стрелка обозначает шаг процессора, и их можно объединять в цепочку в `RobotProcessorPipeline` или `PolicyProcessorPipeline`:

```
                    ┌─────────────────────────────────────────┐
   Action Space     │   Joint Space  ←──IK──→  EE Space      │
                    │   ForwardKinematicsJointsToEE           │
                    │   InverseKinematicsEEToJoints           │
                    └─────────────────────────────────────────┘

                    ┌─────────────────────────────────────────┐
   Representation   │   Absolute  ←────→  Relative            │
                    │   RelativeActionsProcessorStep (pre)    │
                    │   AbsoluteActionsProcessorStep (post)   │
                    └─────────────────────────────────────────┘

                    ┌─────────────────────────────────────────┐
   Normalization    │   Raw  ←────→  Normalized               │
                    │   NormalizerProcessorStep (pre)         │
                    │   UnnormalizerProcessorStep (post)      │
                    └─────────────────────────────────────────┘
```

A typical training preprocessor might chain: `raw absolute joint actions → relative → normalize`. A typical inference postprocessor: `unnormalize → absolute → (optionally IK to joints)`.

## Ссылки

- [Universal Manipulation Interface (UMI)](https://arxiv.org/abs/2402.10329) — Chi et al., 2024. Определяет представление действия в виде относительной траектории и сравнивает его с абсолютными и дельта-действиями.
- [Введение в процессоры](./introduction_processors) — как работают конвейеры процессоров в LeRobot.
- [`examples/so100_to_so100_EE/`](https://github.com/huggingface/lerobot/tree/main/examples/so100_to_so100_EE) — Полный пример записи и оценки с действиями в пространстве EE.

