diff --git a/docs-Lokal/LOCAL_EXECUTION_PLAN.md b/docs-Lokal/LOCAL_EXECUTION_PLAN.md new file mode 100644 index 0000000..0ae48c3 --- /dev/null +++ b/docs-Lokal/LOCAL_EXECUTION_PLAN.md @@ -0,0 +1,121 @@ +# Локальний план виконання (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` з повноцінною роботою та комітами. |