# Архитектура проекта

## 1. Общая схема

Проект состоит из нескольких слоев:

1. прием кадров;
2. детекция;
3. трекинг и удержание;
4. оценка движения и восстановление;
5. guidance;
6. выдача команд наружу;
7. логирование и отладка.

## 2. Основная точка входа

### `main.py`

Это главный runtime-файл. Он:

- загружает модель YOLO;
- открывает источник через `open_source`;
- запускает YOLO worker;
- создает `AutoGazeROIWorker` и пытается его запустить, но по умолчанию `AUTOGAZE_ENABLE = False`, поэтому модуль обычно не активен;
- инициализирует Kalman, KLT и ByteTrack;
- ведет основной цикл обработки кадров;
- строит итоговый lock и guidance;
- пишет выходное видео и логи.

## 3. Конфигурация

### `config.py`

Содержит:

- путь к модели;
- источник видео;
- настройки YOLO;
- настройки KLT;
- настройки ByteTrack;
- настройки guidance;
- настройки ROI и recovery;
- параметры записи видео и логов.

### `config_intercept.py`

Содержит:

- range estimation;
- proportional navigation;
- intercept FSM;
- настройки backend'ов управления;
- испытательный UDP-протокол;
- IMM/дополнительные модули.

### `runtime_env.py`

Накладывает env-overrides поверх значений из `config.py` и `config_intercept.py`.

Это особенно важно для Docker, потому что позволяет не редактировать код под каждый запуск.

## 4. Источник видео

### `helpers.py`

Ключевые функции:

- `open_source` — открывает `camera`, `stream` или `file`;
- `get_frame_timestamp_seconds` — вычисляет временную метку кадра;
- `sanitize_dt` — стабилизирует `dt`;
- геометрические и ROI-функции.

## 5. Детекция

### `yolo_worker.py`

Асинхронный worker для запуска YOLO.

Работает в двух режимах:

- по ROI;
- по полному кадру.

Возвращает:

- список детекций;
- время инференса;
- признак, использовался ли ROI.

## 6. Трекинг и удержание

### `bytetrack_min_aggressive.py`

Локальная реализация ByteTrack, добавленная в корень проекта для самодостаточного контейнерного runtime.

### `trackers.py`

Базовые Kalman-трекеры.

### `trackers_safe.py`

Более безопасные ограничения для Kalman.

### `trackers_hybrid.py`

Гибридный KLT-трекер.

## 7. Восстановление и anti-stall логика

### `target_handoff.py`

Логика:

- stale lock;
- fast handoff;
- override guidance;
- временное удержание re-anchor-кандидата.

### `template_matching.py`

Fallback через шаблонное сопоставление.

### `camera_motion.py`

Оценка глобального движения камеры и компенсация.

### `motion_saliency.py`

Помогает переоценивать детекции по движению.

### `stationary_killer.py`

Отбрасывает залипшие и статичные треки.

### `autogaze_runner.py`

Опциональный ROI prior для recover. По умолчанию `AUTOGAZE_ENABLE = False`.

## 8. Guidance

### `guidance.py`

Задачи:

- построение точки прицеливания;
- сглаживание команд;
- удержание при miss;
- экспорт `guidance_state.json`;
- отрисовка crosshair, точки и желтой линии.

Именно этот слой строит:

- `aim_x`, `aim_y`;
- `steer_x`, `steer_y`;
- `confidence`;
- `status` (`SEARCH`, `LOCK`, `HOLD`, `REACQ`).

## 9. Наведение и внешние backend'ы

### `autopilot_bridge.py`

Преобразует guidance-state в внешние команды.

Поддерживает:

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

### `range_estimation.py`

Оценка дальности по видимому размеру цели.

### `proportional_navigation.py`

PN-логика.

### `intercept_fsm.py`

FSM фаз:

- `SEARCH`
- `ACQUIRE`
- `TRACK`
- `INTERCEPT`
- `TERMINAL`
- `LOST`

### `imu_fusion.py`

Дополнительный модуль IMU/MAVLink/MSP. Отдельный, не является обязательной частью базового запуска.

## 10. Логирование

### `decision_logger.py`

Записывает:

- покадровые решения;
- причины переключений;
- stale-lock и guidance-reset события.

Выход:

- `track_log_*.csv`
- `track_summary_*.json`

## 11. Что не относится к основному runtime

### `cvat/`

Это отдельный большой каталог для CVAT и не нужен для повседневного запуска трекера.

### `dataset_prep/`

Скрипты подготовки датасета.

Они не нужны для обычного запуска `main.py`.