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 БД: 8 таблиць (flights, waypoints, geofences, flight_state, frame_results, heading_history, images, chunks).
• Async FlightRepository з повним CRUD, каскадним видаленням. 9 тестів БД.

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

• Endpoints: створення полёту, завантаження батчу зображень (мультипарт).
• Фейковий FlightProcessor для замикання логіки під час тестування REST.

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

• Підписка на події по flight_id через asyncio.Queue (віддача проміжних та уточнених поз).
• Збереження в таблицю frame_results (за допомогою FlightRepository).

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

• Клієнт Google Maps тайлів, локальний кеш.
• Функції піксель <-> GPS (проекції, ENU координати).

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

• FIFO батчів (ImageInputPipeline), менеджер ротацій (ImageRotationManager).
• Асинхронне збереження в кеш image_storage.

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

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

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

• Кросс-вью вирівнювання до тайла Google Maps (F09 LiteSAM Mock).
• Отримання абсолютної GPS координати через Global Place Recognition (F08 AnyLoc/Faiss Mock).

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

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

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

• Оркестрація: process_frame зі State Machine (NORMAL→LOST→RECOVERY→NORMAL), асинхронне доуточнення через SSE після зміни графа.

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

• 6 AC-тестів: нормальний політ (20 кадрів), tracking loss/recovery, perf <5с/кадр, user anchor, sustained throughput (50 кадрів), graph convergence.
• Усього 80 тестів проходять.

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

• Деталізований README: архітектура, структура, endpoints, тести, компоненти, .env, розгортання.

---

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 з повноцінною роботою та комітами.