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.

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

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

Пример:

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:

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. Проверка модели

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

best.pt

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

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

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

Примеры:

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 настройте:

AUTOPILOT_BACKEND = "json"

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

• json
• mavlink
• msp
• proto_udp

5.6. Запуск

python main.py

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

Пример:

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-камеры обычно используется:

CAP_BACKEND = cv2.CAP_V4L2
SOURCE = 0

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

Windows 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

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. Сборка

docker compose build

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

8.3. Запуск

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. Примеры

Камера

FPV_SOURCE: "0"

RTSP

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

UDP-видео

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

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

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

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

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

Linux

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

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

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-источник.