MAI/docs/ARCHITECTURE_RU.md

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

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.