# Локальний план виконання (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 — Ініціалізація репозиторію коду (локально)
- Створити структуру пакета, `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 + YAML.
- Pydantic-схеми: Flight, Waypoint, ImageBatch, події SSE.

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