mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-04-22 22:56:36 +00:00
Yuzviak
128 lines
7.8 KiB
Markdown
128 lines
7.8 KiB
Markdown
# Локальний план виконання (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` з повноцінною роботою та комітами. |
|