# Локальний план виконання (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` з повноцінною роботою та комітами. |