# Справочник конфигурации

## 1. Общий принцип

У проекта два основных файла конфигурации:

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

Плюс слой env-overrides:

- `runtime_env.py`

Если проект запускается локально, обычно проще править `config.py` и `config_intercept.py`.

Если проект запускается в Docker, лучше использовать env-переменные.

## 2. Главные параметры `config.py`

### Источник и модель

- `MODEL_PATH` — путь к `best.pt`
- `DEVICE` — индекс CUDA-устройства
- `USE_HALF` — half precision на GPU
- `SOURCE` — видеофайл, индекс камеры, RTSP или UDP
- `VIDEO_REALTIME` — pacing по времени источника
- `CAP_BACKEND` — backend OpenCV для камер

### Вывод

- `SHOW_OUTPUT` — показывать окно OpenCV
- `WINDOW_NAME` — имя окна
- `SAVE_INFER_VIDEO` — писать выходное видео
- `OUT_VIDEO_PATH` — базовое имя выходного видео

### Детектор YOLO

- `CONF`
- `IMG_SIZE_ROI`
- `IMG_SIZE_FULL`
- `MAX_DET`
- `TARGET_CLASS_ID`

### KLT

- `KLT_MAX_CORNERS`
- `KLT_QUALITY`
- `KLT_MIN_DIST`
- `KLT_WIN`
- `KLT_MAX_LEVEL`
- `KLT_OUTLIER_THRESH`
- `KLT_OK_Q`
- `KLT_OK_PTS`
- `KLT_REFRESH_WITH_YOLO`

### ByteTrack / Kalman

- `BT_HIGH`
- `BT_LOW`
- `BT_NEW`
- `BT_MATCH_IOU`
- `BT_BUFFER`
- `BT_MIN_HITS`
- `BT_MAX_PREDICT_AGE`
- `KALMAN_HOLD_MAX`

### Guidance

- `GUIDANCE_ENABLE`
- `DRAW_GUIDANCE`
- `GUIDANCE_EXPORT_ENABLE`
- `GUIDANCE_EXPORT_PATH`
- `GUIDANCE_EXPORT_EVERY`
- `GUIDANCE_CMD_SMOOTH`
- `GUIDANCE_POINT_SMOOTH`
- `GUIDANCE_CONF_MIN`
- `GUIDANCE_OVERRIDE_ENABLE`
- `GUIDANCE_OVERRIDE_MISS_GE`
- `GUIDANCE_OVERRIDE_TTL`

## 3. Главные параметры `config_intercept.py`

### Range estimation

- `RANGE_ENABLE`
- `CAMERA_FOCAL_LENGTH_PX`
- `TARGET_KNOWN_SIZE_M`
- `RANGE_MIN_APPARENT_SIZE_PX`
- `RANGE_MAX_M`
- `RANGE_MIN_M`

### Proportional navigation

- `PN_ENABLE`
- `PN_NAV_GAIN`
- `PN_AUGMENTED`
- `PN_AUG_GAIN`
- `PN_MAX_ACCEL_CMD`

### Intercept FSM

- `INTERCEPT_FSM_ENABLE`
- `FSM_ACQUIRE_RANGE_M`
- `FSM_TRACK_CONFIRM_HITS`
- `FSM_INTERCEPT_RANGE_M`
- `FSM_TERMINAL_TAU_SEC`
- `FSM_TERMINAL_RANGE_M`
- `FSM_LOST_TIMEOUT`

### Внешние backend'ы

- `AUTOPILOT_ENABLE`
- `AUTOPILOT_BACKEND`
- `AUTOPILOT_JSON_PATH`
- `AUTOPILOT_JSON_EVERY`
- `MAVLINK_CONNECTION`
- `MSP_PORT`
- `MSP_BAUD`

### Испытательный UDP-протокол

- `PROTO_UDP_ENABLE`
- `PROTO_UDP_HOST`
- `PROTO_UDP_PORT`
- `PROTO_UDP_DESCRIPTOR`

### IMM / расширенные модули

- `IMM_ENABLE`
- `IMM_REPLACE_KALMAN`

## 4. Env-переменные, которые реально поддерживаются

Ниже перечислен точный набор env-overrides из `runtime_env.py`.

### Переопределения `config.py`

- `FPV_MODEL_PATH`
- `FPV_SOURCE`
- `FPV_VIDEO_REALTIME`
- `FPV_SHOW_OUTPUT`
- `FPV_SAVE_INFER_VIDEO`
- `FPV_OUT_VIDEO_PATH`
- `FPV_GUIDANCE_EXPORT_ENABLE`
- `FPV_GUIDANCE_EXPORT_PATH`

### Переопределения `config_intercept.py`

- `FPV_AUTOPILOT_ENABLE`
- `FPV_AUTOPILOT_BACKEND`
- `FPV_AUTOPILOT_JSON_PATH`
- `FPV_MAVLINK_CONNECTION`
- `FPV_MSP_PORT`
- `FPV_PROTO_UDP_ENABLE`
- `FPV_PROTO_UDP_HOST`
- `FPV_PROTO_UDP_PORT`
- `FPV_PROTO_UDP_DESCRIPTOR`

## 5. Как интерпретируется `FPV_SOURCE`

### Камера

```text
FPV_SOURCE=0
```

Если строка состоит только из цифр, она будет преобразована в индекс камеры.

### RTSP / HTTP / UDP / RTMP

```text
FPV_SOURCE=rtsp://192.168.1.10:8554/live
FPV_SOURCE=udp://@0.0.0.0:5600
```

Такие источники открываются как поток.

### Видео-файл

```text
FPV_SOURCE=/data/input/test.mp4
```

## 6. Рекомендуемые пресеты запуска

### Отладка на видеофайле

- `SOURCE` = путь к файлу
- `AUTOPILOT_BACKEND = "json"`
- `SHOW_OUTPUT = True`
- `SAVE_INFER_VIDEO = True`

### Реальный live-поток

- `SOURCE` = камера/RTSP/UDP
- `AUTOPILOT_BACKEND = "json"` на первом этапе
- `SHOW_OUTPUT` по ситуации

### Испытания протокола

- `AUTOPILOT_BACKEND = "proto_udp"`
- `PROTO_UDP_ENABLE = True`
- `PROTO_UDP_HOST` и `PROTO_UDP_PORT` под вашу сеть

## 7. Что лучше менять через env, а что через файлы

Через env лучше менять:

- источник;
- backend;
- пути к выходным файлам;
- включение UDP-протокола;
- сетевые адреса и порты.

Через `config.py` и `config_intercept.py` лучше менять:

- глубокий тюнинг трекера;
- пороги KLT/ByteTrack/Kalman;
- ROI- и recover-параметры;
- параметры PN/FSM;
- экспериментальные флаги.

## 8. Что не переопределяется через env

На текущий момент через env не вынесены все сотни тюнинговых параметров из `config.py`.

Это сделано специально, чтобы:

- оставить Docker-конфигурацию компактной;
- не раздувать runtime API;
- не превращать проект в огромный набор shell-параметров.

Если вам нужно контейнерно менять дополнительный параметр, его можно добавить в `runtime_env.py`.