gps-denied-onboard/docs-Lokal/LOCAL_EXECUTION_PLAN.md

Локальний план виконання (gps-denied-onboard)

Призначення: поетапна реалізація сервісу геолокалізації знімків БПЛА за спеками у цьому репозиторії.
Режим роботи: ведеться розробка у гілці stage1 з пушами в репозиторій.
Опорні документи: docs/00_problem/, docs/01_solution/, docs/02_components/, docs/03_tests/.

---

1. Цілі та критерії успіху

• Відтворити архітектуру ASTRAL-Next / гібрид VO + кросс-вью + фактор-граф згідно з decomposition_plan.md.
• Досягти приймальних критеріїв з acceptance_criteria.md (точність, стійкість до виїздів/виражів, <5 с на кадр на цільовій GPU, REST + SSE).
• Покрити інтеграційні та приймальні сценарії з docs/03_tests/ по мірі готовності компонентів.

---

2. Затверджені архітектурні рішення (LOCAL DECISIONS)

Замість відкритих питань ми зафіксували наступний стек для локального прототипу:

1. Джерело супутникових карт: Google Maps API (з імплементацією патерну Strategy для легкої заміни в майбутньому).
2. Математичний оптимізатор (Factor Graph): GTSAM (Python Bindings) для уникнення C++ збірки на етапі MVP та збереження єдиного Python-процесу.
3. БД та Черги: SQLite (ресурсна економія, жодних фонових контейнерів) та asyncio.Queue для In-Memory SSE стрімінгу замість Redis.
4. Формат ground-truth / Ваги: Вимагає ручного завантаження тестових наборів та вагів моделей до локальних папок (Етап 0.5).

---

3. Необхідні ресурси

3.1. Апаратне

• ПК або ноутбук з NVIDIA GPU (мінімум RTX 2060, бажано 8+ ГБ VRAM).
• RAM: 32 ГБ бажано.
• Диск: десятки ГБ під кеш тайлів та ваги моделей.

3.2. Програмне

• OS: Linux з драйверами NVIDIA + CUDA.
• Python 3.11+, віртуальне середовище (venv/uv).
• Git — робота в гілці stage1.

---

4. Рекомендований стек

Шар	Технологія
API	FastAPI, Pydantic v2
Стрим	SSE (наприклад, sse-starlette)
CV/DL	PyTorch
Граф поз	GTSAM (Python)
БД	SQLite + SQLAlchemy 2 + Alembic
Контейнери	(опційно для SQLite)

---

5. Поетапний план виконання (детально)

Етап 0 — Ініціалізація репозиторію коду (локально) ✅

• Створено структуру пакета src/gps_denied/, pyproject.toml, залежності.
• Налаштовано .gitignore: .env, data/, weights/, __pycache__, *.db.
• Результат: сервіс запускається, health endpoint працює, тест пройдено.

Етап 0.5 — Підготовка даних та моделей (Data Provisioning)

• Токени: Зафіксувати Google Maps API key у .env.
• Дані: Завантажити тестові зображення у папку data/test_flights.
• Ваги: Завантажити ваги SuperPoint, LightGlue, LiteSAM локально в weights/.

Етап 1 — Конфігурація та доменні моделі ✅

• Реалізовано завантаження конфігів з .env через pydantic-settings (config.py).
• Pydantic-схеми: GPSPoint, CameraParameters, Flight*, Waypoint, Batch*, SSE events.

Етап 2 — База даних полёту

• SQLite БД: міграції (flights, waypoints, frame results, chunk state).
• Репозиторії / DAO під інтерфейс IFlightDatabase.

Етап 3 — REST API + завантаження батчів

• Endpoints: створення полёту, завантаження батчу зображень (мультипарт).

Етап 4 — SSE та менеджер результатів

• Підписка на події по flight_id через asyncio.Queue (віддача проміжних та уточнених поз).

Етап 5 — Супутникові тайли та координати (Google Maps)

• Клієнт Google Maps тайлів, локальний кеш.
• Coordinate transformer: піксель ↔ WGS84.

Етап 6 — Черга зображень і ротації

• FIFO батчів, менеджер ротацій для кросс-вью.

Етап 7 — Model manager та послідовний VO

• Завантаження локальних вагів (SuperPoint+LightGlue), побудова ланцюжка відносних оцінок.

Етап 8 — Глобальне місце та метричне уточнення

• Кросс-вью вирівнювання до тайла Google Maps.

Етап 9 — Фактор-граф і чанки (GTSAM)

• Побудова чинників (відносні VO + абсолютні якорі). Оптимізація траєкторії через GTSAM.

Етап 10 — Повний цикл обробки

• Оркестрація: process_frame, асинхронне доуточнення через SSE після зміни графа.

Етап 11 — Приймальні тести та продуктивність

• Прогін AC-сценаріїв, замір швидкодії (<5с/кадр).

Етап 12 — Локальна експлуатація

• Документація локального запуску, README.md.

---

6. Залежності між етапами

0 → 0.5 → 1 → 2 → 3 → 4
                  ↘ 5 → 6 → 7 → 8 → 9 → 10 → 11 → 12

---

7. Резюме

Що	Зміст
Рішення	Google Maps (Карти), GTSAM Python (Граф), SQLite (БД).
Етапи	0–12: Від ініціалізації до готових AC-метрик (з урахуванням підготовки даних в 0.5).
Гілка	stage1 з повноцінною роботою та комітами.