# Поиск и устранение проблем

## 1. Не открывается источник видео

Симптом:

- `Capture open failed`

Проверки:

1. Верный ли `SOURCE`.
2. Для камеры: правильный ли индекс `0`, `1`, `2`.
3. Для RTSP: доступен ли поток из этой сети.
4. Для UDP: идет ли поток на указанный порт.
5. Для файла: существует ли путь и читается ли файл.

## 2. Проект запускается, но не использует GPU

Проверки:

1. Установлен ли GPU-вариант `torch`.
2. Совместимы ли версия CUDA и wheel `torch`.
3. Видит ли Python CUDA:

```python
import torch
print(torch.cuda.is_available())
```

4. Не стоит ли CPU-only wheel.

## 3. В Docker нет GPU

Симптом:

- внутри контейнера `torch.cuda.is_available() == False`

Проверки:

1. Установлен ли NVIDIA драйвер на хосте.
2. Установлен ли NVIDIA Container Toolkit.
3. Поддерживает ли ваш Docker runtime `gpus: all`.
4. Не запущен ли контейнер на машине без доступной NVIDIA GPU.

## 4. В Docker не видна обычная webcam на Windows

Это типичная проблема Windows Docker Desktop.

Практические варианты:

- использовать RTSP;
- использовать UDP-видеопоток;
- использовать внешний capture-процесс вне контейнера;
- запускать локально на Windows без Docker.

## 5. Есть видео, но нет детекций

Проверки:

1. Тот ли `MODEL_PATH`.
2. Совместима ли модель с текущим кодом.
3. Правильный ли `TARGET_CLASS_ID`.
4. Не слишком ли высокий `CONF`.
5. Реально ли цель различима на этом разрешении.

## 6. Появляются детекции, но guidance не следует за ними

Важно:

- guidance строится не по "любой текущей рамке YOLO", а по выбранному lock/tracker state;
- при miss может работать удержание через Kalman/KLT;
- статус `HOLD` и `REACQ` означают, что проект находится не в чистой детекции.

Проверки:

1. Что в overlay пишется в строках `miss`, `KLT valid`, `G HOLD` или `G REACQ`.
2. Есть ли свежий `track_log_*.csv`.
3. Не слишком ли жесткие условия handoff/switch.

## 7. Не создается `guidance_state.json`

Проверки:

1. Включен ли `GUIDANCE_EXPORT_ENABLE`.
2. Есть ли права на запись в каталог.
3. Не держит ли файл другой процесс.

Если в логах есть:

```text
Permission denied: guidance_state.json.tmp
```

это обычно означает, что файл временно заблокирован другим процессом или watcher'ом.

## 8. Не работает `proto_udp`

Проверки:

1. `AUTOPILOT_BACKEND = "proto_udp"`
2. `PROTO_UDP_ENABLE = True`
3. Правильные ли `HOST` и `PORT`
4. Видит ли сеть UDP-пакеты
5. Совпадает ли формат пакета с приемником

Практическая проверка:

- поднимите простой UDP listener;
- убедитесь, что приходят пакеты при наличии цели.

## 9. Не работает `mavlink`

Проверки:

1. Установлен ли `pymavlink`
2. Верный ли `MAVLINK_CONNECTION`
3. Доступен ли endpoint
4. Нет ли firewall/маршрутизации, блокирующих UDP

## 10. Не работает `msp`

Проверки:

1. Установлен ли `pyserial`
2. Верный ли `MSP_PORT`
3. Верный ли `MSP_BAUD`
4. Есть ли права доступа к порту

## 11. Видео не пишется

Проверки:

1. `SAVE_INFER_VIDEO = True`
2. Каталог записи существует
3. OpenCV может открыть `VideoWriter`
4. Кодек `mp4v` поддерживается в вашей среде

## 12. Проект слишком медленный

Проверки:

1. Есть ли GPU.
2. Не работает ли все на CPU.
3. Не слишком ли тяжелый full-frame режим.
4. Не включены ли лишние debug-наложения.
5. Не используется ли `SHOW_OUTPUT` там, где окно не нужно.

## 13. Сборка Docker слишком тяжелая

В проекте уже добавлен `.dockerignore`, который исключает:

- `cvat/`
- `dataset_prep/`
- видео
- старые логи
- архивы

Если сборка все равно тяжелая, проверьте:

1. не лежат ли рядом новые большие файлы, не попавшие в ignore;
2. не добавлены ли лишние каталоги в build context.

## 14. Что сделать перед обращением к разработчику

Подготовьте:

1. какой источник видео использовался;
2. локальный запуск или Docker;
3. backend команд;
4. последние `track_log_*.csv` и `track_summary_*.json`;
5. скриншот overlay;
6. точный текст ошибки.