MAI/docs/RUNBOOK_RU.md

# RUNBOOK: запуск и эксплуатация

## 1. Назначение

Этот документ нужен, чтобы новый человек мог:

- понять, что делает проект;
- подготовить окружение;
- запустить проект локально;
- запустить проект в Docker;
- выбрать источник видео;
- выбрать backend выдачи команд;
- включить испытательный UDP-протокол.

## 2. Что делает проект

Проект решает задачу сопровождения цели в видеопотоке. Базовая схема такая:

1. Видео поступает из файла, камеры, RTSP или UDP.
2. `YOLO` ищет объект.
3. `ByteTrack` ведет ID трека.
4. `Kalman` и `KLT` сглаживают движение и удерживают цель при кратких провалах детекции.
5. `guidance.py` строит экранную точку наведения и управляющие команды.
6. `autopilot_bridge.py` отправляет команды наружу.

## 3. Минимальные требования

### Для локального запуска

- Windows 10/11 или Linux
- Python 3.12
- NVIDIA GPU для быстрого режима
- установленный CUDA-совместимый `torch`
- модель `best.pt` в корне проекта

### Для Docker

- Docker Engine или Docker Desktop
- для GPU: NVIDIA драйвер на хосте
- для GPU: NVIDIA Container Toolkit

## 4. Структура запуска

Проект не запускается через CLI-параметры. Есть два способа настройки:

### Вариант 1. Прямое редактирование файлов

- `config.py`
- `config_intercept.py`

Этот вариант проще для локальной разработки.

### Вариант 2. Переменные окружения

Используется для:

- Docker
- запуска из shell без правки файлов

Поддерживаемые env-переменные описаны в [CONFIG_REFERENCE_RU.md](CONFIG_REFERENCE_RU.md).

## 5. Локальный запуск на Windows

### 5.1. Создание окружения

Пример:

```powershell
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
```

### 5.2. Установка зависимостей

CPU/GPU-зависимости проекта не сведены в отдельный локальный `requirements.txt`, поэтому ставятся вручную.

Пример для CUDA 12.8:

```powershell
python -m pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128
python -m pip install -r requirements-docker.txt
```

Если нужен `MSP`, нужен `pyserial`.

Если нужен `MAVLink`, нужен `pymavlink`.

Они уже входят в `requirements-docker.txt`.

### 5.3. Проверка модели

Убедитесь, что файл:

```text
best.pt
```

находится в корне проекта и `MODEL_PATH` указывает на него.

### 5.4. Выбор источника

В `config.py` настройте `SOURCE`.

Примеры:

```python
SOURCE = 0
SOURCE = "rtsp://192.168.1.10:8554/live"
SOURCE = "udp://@0.0.0.0:5600"
SOURCE = r"C:\videos\sample.mp4"
```

### 5.5. Выбор backend команд

В `config_intercept.py` настройте:

```python
AUTOPILOT_BACKEND = "json"
```

Доступные значения:

- `json`
- `mavlink`
- `msp`
- `proto_udp`

### 5.6. Запуск

```powershell
python main.py
```

## 6. Локальный запуск на Linux

Пример:

```bash
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128
python3 -m pip install -r requirements-docker.txt
python3 main.py
```

Для USB-камеры обычно используется:

```python
CAP_BACKEND = cv2.CAP_V4L2
SOURCE = 0
```

## 7. Запуск без правки `config.py` через env

### Windows PowerShell

```powershell
$env:FPV_SOURCE = "0"
$env:FPV_MODEL_PATH = "D:\PycharmProjects\YOLOTrain\BYTETRACK\TEST\fpv_tracker_optimized\best.pt"
$env:FPV_AUTOPILOT_BACKEND = "proto_udp"
$env:FPV_PROTO_UDP_ENABLE = "1"
$env:FPV_PROTO_UDP_HOST = "192.168.1.50"
$env:FPV_PROTO_UDP_PORT = "5005"
python main.py
```

### Linux bash

```bash
export FPV_SOURCE=0
export FPV_MODEL_PATH=/path/to/best.pt
export FPV_AUTOPILOT_BACKEND=proto_udp
export FPV_PROTO_UDP_ENABLE=1
export FPV_PROTO_UDP_HOST=192.168.1.50
export FPV_PROTO_UDP_PORT=5005
python3 main.py
```

## 8. Docker-запуск

### 8.1. Что уже упаковано

Образ включает:

- Python 3
- CUDA runtime
- `torch`
- `torchvision`
- `ultralytics`
- `opencv`
- `pymavlink`
- `pyserial`
- код проекта
- `best.pt`

### 8.2. Сборка

```bash
docker compose build
```

После сборки интернет для старта контейнера не нужен.

### 8.3. Запуск

```bash
docker compose up
```

### 8.4. Изменение режима запуска

Проще всего править `environment` в `docker-compose.yml`.

Ключевые параметры:

- `FPV_SOURCE`
- `FPV_AUTOPILOT_BACKEND`
- `FPV_PROTO_UDP_ENABLE`
- `FPV_PROTO_UDP_HOST`
- `FPV_PROTO_UDP_PORT`
- `FPV_SHOW_OUTPUT`
- `FPV_SAVE_INFER_VIDEO`

### 8.5. Примеры

#### Камера

```yaml
FPV_SOURCE: "0"
```

#### RTSP

```yaml
FPV_SOURCE: "rtsp://192.168.1.10:8554/live"
```

#### UDP-видео

```yaml
FPV_SOURCE: "udp://@0.0.0.0:5600"
```

#### Видео-файл внутри контейнера

Смонтируйте каталог с видео и укажите:

```yaml
FPV_SOURCE: "/data/input/test.mp4"
```

## 9. Важные замечания по Docker и камере

### Linux

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

```yaml
devices:
  - /dev/video0:/dev/video0
```

### Windows Docker Desktop

Обычная webcam часто недоступна напрямую Linux-контейнеру. На Windows лучше использовать:

- RTSP-источник
- UDP-источник
- внешний capture-источник, доступный как сеть

## 10. Выбор backend выдачи команд

### `json`

Самый простой режим.

Что делает:

- записывает текущее управляющее состояние в `autopilot_cmd.json`

Когда использовать:

- отладка
- интеграция с внешним процессом через файл

### `mavlink`

Что делает:

- отправляет команды по MAVLink

Что нужно:

- доступный endpoint
- `pymavlink`

### `msp`

Что делает:

- отправляет RC-команды по MSP

Что нужно:

- COM-порт или `/dev/ttyUSB0`
- `pyserial`

### `proto_udp`

Что делает:

- отправляет бинарный UDP-пакет по вашему испытательному протоколу

Подробности: [PROTOCOL_UDP_RU.md](PROTOCOL_UDP_RU.md)

## 11. Какие файлы появляются после запуска

- `out_infer_*.mp4` — видео с отрисовкой
- `track_log_*.csv` — покадровый лог логики выбора цели
- `track_summary_*.json` — итоговая сводка
- `guidance_state.json` — состояние guidance
- `autopilot_cmd.json` — внешний файл команд для backend `json`

## 12. Что проверять после первого запуска

1. Открывается ли источник видео.
2. Загружается ли модель `best.pt`.
3. Есть ли детекции на экране.
4. Создается ли `out_infer_*.mp4`, если включена запись.
5. Создается ли `guidance_state.json`, если включен export.
6. Доходит ли UDP/MAVLink/MSP до вашей внешней системы.

## 13. Рекомендуемый порядок первого ввода в эксплуатацию

1. Запуск на видеофайле.
2. Проверка логов и `out_infer_*.mp4`.
3. Запуск с backend `json`.
4. Проверка `guidance_state.json` и `autopilot_cmd.json`.
5. Переключение на `proto_udp`.
6. Только после этого переход на live-источник.