> ## Documentation Index
> Fetch the complete documentation index at: https://avala.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Основные концепции

> Разберитесь в фундаментальных концепциях платформы Avala

На этой странице рассматриваются базовые элементы платформы Avala: визуализация, аннотация, наборы данных, проекты, задачи, организации, метки, контроль качества и последовательности. Понимание этих концепций поможет вам проектировать эффективные рабочие процессы с данными для Physical AI.

## Визуализация

Avala предоставляет GPU-ускоренную визуализацию сенсорных данных прямо в браузере. Эти концепции применимы ко всем функциям визуализации.

### Просмотрщики

Avala включает специализированные просмотрщики для различных типов данных. **Мультисенсорный просмотрщик** работает с записями MCAP и ROS с синхронным воспроизведением всех сенсорных потоков. **3D-просмотрщик облаков точек** рендерит данные LiDAR с шестью режимами визуализации. **Просмотрщик Gaussian Splat** рендерит фотореалистичные 3D-реконструкции сцен с использованием WebGPU.

### Панели

Мультисенсорный просмотрщик организует данные в **панели** — независимые окна визуализации для различных потоков данных. Avala поддерживает восемь типов панелей:

| Тип панели         | Описание                                  |
| ------------------ | ----------------------------------------- |
| Изображение        | Кадры камер и потоки изображений          |
| 3D / Облако точек  | Сканы LiDAR и 3D-геометрия                |
| График             | Временные ряды и числовые сигналы         |
| Сырые сообщения    | Декодированные данные сообщений           |
| Лог                | Текстовые потоки логов                    |
| Карта              | Географическое положение и траектории     |
| Датчик             | Числовые показания в реальном времени     |
| Переходы состояний | Дискретные изменения состояний во времени |

Топики автоматически назначаются панелям на основе их схемы.

### Макеты

Многооконные макеты располагают панели в настраиваемой сетке. **Компоновщик макетов** автоматически строит оптимальные расположения на основе топиков в ваших данных, или вы можете настроить макет вручную, перетаскивая, изменяя размер и переупорядочивая панели.

### Таймлайны

Все панели в просмотрщике используют **синхронизированный таймлайн**. Перемещайтесь покадрово, переходите к конкретным временным меткам или воспроизводите записи с настраиваемой скоростью. Таймлайн синхронизирует все сенсорные потоки независимо от их индивидуальной частоты захвата.

### Сенсорные потоки

Записи MCAP содержат множество **сенсорных потоков** (топиков). Каждый топик несёт определённый тип данных — изображения, облака точек, показания IMU, координаты GPS — с собственной частотой. Avala синхронизирует все потоки по временным меткам, так что вы видите полную картину сенсоров в любой момент времени.

### Режимы визуализации

Данные облаков точек могут быть окрашены с использованием шести режимов:

| Режим                | Описание                                              |
| -------------------- | ----------------------------------------------------- |
| Нейтральный          | Единый однородный цвет                                |
| Интенсивность        | Окраска по силе отражённого сигнала                   |
| Радуга               | Временная или последовательная окраска                |
| Метка                | Окраска по семантическому классу                      |
| Паноптический        | Окраска по идентификатору экземпляра                  |
| Проекция изображения | Текстурирование проецированными изображениями с камер |

<Info>
  Режимы визуализации применяются к 3D-просмотрщику облаков точек и работают как с отдельными наборами данных LiDAR, так и с потоками облаков точек внутри записей MCAP.
</Info>

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

**Набор данных** — это коллекция элементов данных (изображений, видеокадров, облаков точек или мультисенсорных записей), которые служат исходным материалом для визуализации и аннотации.

### Свойства набора данных

| Свойство     | Описание                                                                 |
| ------------ | ------------------------------------------------------------------------ |
| `name`       | Человекочитаемое имя                                                     |
| `slug`       | URL-совместимый идентификатор (уникальный в пространстве имён владельца) |
| `data_type`  | Тип данных: `image`, `video`, `lidar`, `mcap`, `image_3d`, `splat`       |
| `visibility` | `public` или `private`                                                   |
| `owner`      | Пользователь или организация — владелец набора данных                    |
| `item_count` | Общее количество элементов данных в наборе                               |

### Элементы данных

Каждый набор данных содержит **элементы** — отдельные образцы данных:

* **Наборы изображений** — Каждый элемент — один файл изображения.
* **Наборы видео** — Элементы — видеокадры, сгруппированные в последовательности.
* **Наборы LiDAR** — Элементы — отдельные сканы облаков точек.
* **Наборы MCAP** — Элементы содержат синхронизированные мультисенсорные кадры (камера + LiDAR + IMU).

### Последовательности

**Последовательности** группируют связанные элементы для временных или многокадровых данных:

* Видеокадры из одной записи
* Сканы LiDAR из непрерывной сессии вождения
* Синхронизированные захваты нескольких камер в последовательные моменты времени

Последовательности обеспечивают покадровую навигацию, трекинг объектов между кадрами и временную согласованность аннотаций.

Рабочий процесс статуса последовательности:

```
uploading → processing → ready → failed
```

## Проекты

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

### Компоненты проекта

```
Project
├── Datasets (источники данных)
├── Task Type (метод аннотации)
├── Label Config (классы объектов, атрибуты)
├── Quality Control (этапы рецензирования, консенсус)
└── Tasks (отдельные единицы работы)
```

### Типы задач

Проекты настраиваются с одним из следующих типов задач:

| Тип задачи              | Значение API             | Описание                                                                          |
| ----------------------- | ------------------------ | --------------------------------------------------------------------------------- |
| Аннотация изображений   | `image-annotation`       | 2D-аннотация одиночных изображений (рамки, полигоны, сегментация, ключевые точки) |
| Аннотация видео         | `video-annotation`       | Покадровая аннотация с трекингом объектов между кадрами                           |
| Аннотация облаков точек | `point-cloud-annotation` | 3D-аннотация сканов LiDAR (кубоиды, сегментация)                                  |
| Объекты в облаках точек | `point-cloud-objects`    | Аннотация объектов в последовательностях 3D-облаков точек                         |

### Статус проекта

| Статус             | Описание                       |
| ------------------ | ------------------------------ |
| `pending-approval` | Ожидает одобрения для начала   |
| `active`           | Принимает работу по аннотации  |
| `paused`           | Временно приостановлен         |
| `canceled`         | Окончательно остановлен        |
| `archived`         | Завершён и архивирован         |
| `completed`        | Все задачи аннотации завершены |

## Задачи

**Задача** — это отдельная единица работы в рамках проекта. Каждая задача представляет работу по аннотации, которую должен выполнить один аннотатор на одном или нескольких элементах данных.

### Жизненный цикл задачи

Задачи проходят через следующие состояния:

```
pending → assigned → in_progress → submitted → under_review → approved
                                                             → rejected → rework
```

| Статус         | Описание                                    |
| -------------- | ------------------------------------------- |
| `pending`      | Создана, но ещё не назначена аннотатору     |
| `assigned`     | Назначена аннотатору, ожидает начала работы |
| `in_progress`  | Аннотатор активно работает над задачей      |
| `submitted`    | Аннотатор отправил работу на рецензирование |
| `under_review` | Рецензент проверяет отправленные аннотации  |
| `approved`     | Аннотации приняты — задача завершена        |
| `rejected`     | Аннотации не прошли рецензию                |
| `rework`       | Возвращена аннотатору для исправлений       |

### Результаты

Когда аннотатор завершает задачу, он отправляет **результат**, содержащий:

* Данные аннотации (ограничивающие рамки, полигоны, кубоиды, маски сегментации и т.д.)
* Метаданные (затраченное время, версии инструментов)

Результаты проходят рецензию контроля качества перед окончательным принятием.

## Организации

**Организация** объединяет пользователей и ресурсы для командной работы.

### Структура организации

```
Organization
├── Members (пользователи с ролями)
├── Datasets (общие данные)
├── Projects (общие рабочие процессы)
└── Settings (биллинг, API-ключи, разрешения)
```

### Роли участников

| Роль     | Возможности                                                |
| -------- | ---------------------------------------------------------- |
| `owner`  | Полный контроль — биллинг, настройки, удаление организации |
| `admin`  | Управление участниками, создание и настройка ресурсов      |
| `member` | Доступ к общим ресурсам, выполнение работы по аннотации    |

## Метки и таксономия

### Конфигурация меток

Проекты определяют **конфигурацию меток** — набор предопределённых классов объектов, которые аннотаторы присваивают аннотациям:

```json theme={null}
{
  "labels": [
    { "name": "car", "color": "#FF0000" },
    { "name": "pedestrian", "color": "#00FF00" },
    { "name": "cyclist", "color": "#0000FF" }
  ]
}
```

### Классификация

Для более сложных таксономий проекты могут включать **конфигурации классификации**, определяющие:

* **Атрибуты** — Свойства вроде цвета, уровня перекрытия или обрезки, которые аннотаторы присваивают каждому объекту.
* **Иерархические категории** — Вложенные структуры классов (например, Транспортное средство > Автомобиль > Седан).
* **Условные атрибуты** — Атрибуты, которые отображаются только для определённых классов объектов.

## Типы аннотаций

Avala поддерживает следующие типы аннотаций, каждый из которых предназначен для конкретных задач разметки:

| Тип                      | Описание                                                           | Типы данных        |
| ------------------------ | ------------------------------------------------------------------ | ------------------ |
| **Ограничивающая рамка** | 2D-прямоугольная область вокруг объекта                            | Изображения, Видео |
| **Полигон**              | Произвольная замкнутая форма по границам объекта                   | Изображения, Видео |
| **3D-кубоид**            | 3D-ограничивающий параллелепипед с позицией, размерами и вращением | Облака точек, MCAP |
| **Сегментация**          | Попиксельная маска классификации                                   | Изображения, Видео |
| **Полилиния**            | Открытый путь для полос, границ и краёв                            | Изображения, Видео |
| **Ключевые точки**       | Точки-ориентиры для оценки позы и структуры                        | Изображения, Видео |
| **Классификация**        | Категориальные метки на уровне сцены или объекта                   | Все типы данных    |

## Контроль качества

Avala предоставляет встроенные инструменты обеспечения качества для гарантии точности и согласованности аннотаций.

### Рецензирование

Аннотации проходят **этап рецензирования** перед принятием:

1. Аннотатор отправляет результат.
2. Рецензент проверяет аннотации.
3. Рецензент **принимает** корректную работу или **отклоняет** работу, требующую исправлений.
4. Отклонённые задачи возвращаются аннотатору для доработки.

### Проблемы

**Проблемы аннотации** позволяют рецензентам отмечать конкретные недостатки в отдельных аннотациях:

* Привязка проблемы к конкретному объекту или области сцены.
* Назначение проблем участникам команды для решения.
* Отслеживание статуса проблемы (открыта, решена).

### Метрики

Отслеживайте качество аннотаций с помощью встроенных метрик:

* **Коэффициент принятия** — Процент задач, принятых с первой отправки.
* **Время аннотации** — Среднее время на одну задачу.
* **Согласие между аннотаторами** — Согласованность результатов разных аннотаторов на одних и тех же данных.
* **Частота проблем** — Количество отмеченных проблем на задачу.

### Консенсус

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

<Info>
  Метрики качества помогают определить потребности в обучении и поддерживать единые стандарты аннотации в вашей команде.
</Info>

## Последовательности

**Последовательности** — это упорядоченные коллекции элементов данных, представляющие временные или пространственные прогрессии — видеокадры, обороты LiDAR или мультисенсорные записи.

### Свойства

| Свойство      | Описание                                   |
| ------------- | ------------------------------------------ |
| `name`        | Идентификатор последовательности           |
| `frame_count` | Количество кадров в последовательности     |
| `status`      | Статус обработки последовательности        |
| `data_type`   | Наследуется от родительского набора данных |

### Рабочий процесс статуса

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

```
uploading → processing → ready
                       → failed
```

* **uploading** — Кадры загружаются на платформу.
* **processing** — Кадры валидируются и подготавливаются для аннотации.
* **ready** — Все кадры обработаны и доступны для аннотации.
* **failed** — При обработке произошла ошибка (проверьте статусы отдельных кадров).

## Управление парком

<Info>
  Управление парком находится в предварительном доступе. Описанные функции могут измениться.
</Info>

Возможности управления парком Avala позволяют управлять устройствами, записями и телеметрией роботизированных парков в масштабе.

### Устройства

**Устройство** представляет физического робота, сенсорную установку или вычислительный модуль в вашем парке. Каждое устройство имеет уникальный идентификатор с префиксом `dev_` и отслеживает метаданные — тип, версию прошивки и статус (`online`, `offline`, `maintenance`).

### Записи

Устройства создают **записи** — файлы MCAP, захваченные во время работы. Записи автоматически связываются с исходным устройством и могут фильтроваться по устройству, дате, статусу и тегам.

### События

**События** — это временные метки на записях: ошибки, изменения состояния, аномалии и пользовательские аннотации. События отображаются на таймлайне просмотрщика MCAP и могут быть запрошены по всему парку.

### Правила записи

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

### Оповещения

**Оповещения** уведомляют вашу команду об изменении условий парка. Направляйте оповещения в Slack, email, вебхуки или уведомления в приложении. Оповещения следуют жизненному циклу: `open` → `acknowledged` → `resolved`.

## Следующие шаги

<CardGroup cols={3}>
  <Card title="Типы данных" icon="database" href="/docs/ru/getting-started/data-types">
    Поддерживаемые форматы, возможности визуализации и инструменты аннотации для каждого типа данных.
  </Card>

  <Card title="Аннотация" icon="display" href="/docs/ru/annotation/overview">
    Изучите веб-интерфейс для визуализации, аннотации и управления проектами.
  </Card>

  <Card title="Архитектура" icon="sitemap" href="/docs/ru/getting-started/architecture">
    Как компоненты платформы Avala взаимодействуют друг с другом, включая движок визуализации.
  </Card>

  <Card title="Аутентификация API" icon="key" href="/docs/api-reference/authentication">
    Настройте API-ключи и начните выполнять аутентифицированные запросы.
  </Card>

  <Card title="Панель управления парком" icon="satellite-dish" href="/docs/visualization/fleet/fleet-dashboard">
    Управляйте устройствами, записями и телеметрией вашего парка роботов.
  </Card>
</CardGroup>