initial structure implemented

docs -> _docs
2026-04-22 11:36:37 +00:00 · 2025-12-01 14:20:56 +02:00
parent 9134c5db06
commit abc26d5c20
360 changed files with 3881 additions and 101 deletions
@@ -0,0 +1,169 @@
+# Azaion GPS Denied Desktop
+
+**A Resilient, GNSS-Denied Geo-Localization System for Wing-Type UAVs**
+
+GPS-denied UAV localization system using visual odometry and satellite imagery matching for fixed-wing UAVs operating over Eastern/Southern Ukraine.
+
+## Overview
+
+Azaion GPS-Denied addresses the challenge of autonomous navigation in GNSS-denied environments where traditional GPS is unavailable or unreliable. The system is designed for high-speed, fixed-wing UAVs operating without IMU data over visually homogeneous agricultural terrain.
+
+### Key Features
+
+- **Tri-Layer Localization**: Sequential tracking, global re-localization, and metric refinement
+- **Sharp Turn Recovery**: Handles 0% image overlap during banking maneuvers
+- **350m Outlier Tolerance**: Robust to large positional errors from airframe tilt
+- **Real-time Processing**: <5 seconds per frame on RTX 2060/3070
+- **Human-in-the-Loop**: Fallback to user input when automation fails
+
+### Accuracy Targets
+
+| Metric | Target |
+|--------|--------|
+| Photos within 50m error | 80% |
+| Photos within 20m error | 60% |
+| Processing time per frame | <5 seconds |
+| Image registration rate | >95% |
+
+## Architecture
+
+### Processing Layers
+
+| Layer | Purpose | Algorithm | Latency |
+|-------|---------|-----------|---------|
+| L1: Sequential Tracking | Frame-to-frame pose | SuperPoint + LightGlue | ~50-100ms |
+| L2: Global Re-Localization | Recovery after track loss | DINOv2 + VLAD (AnyLoc) | ~200ms |
+| L3: Metric Refinement | Precise GPS anchoring | LiteSAM | ~300-500ms |
+
+### Core Components
+
+- **Factor Graph Optimizer** (GTSAM): Fuses relative and absolute measurements
+- **Atlas Multi-Map**: Route chunks as first-class entities for handling disconnected segments
+- **Satellite Data Manager**: Google Maps tile caching with Web Mercator projection
+
+## Tech Stack
+
+- **Python**: 3.10+ (GTSAM compatibility)
+- **Web Framework**: FastAPI (async)
+- **Database**: PostgreSQL + SQLAlchemy ORM
+- **ML Runtime**: TensorRT (primary), ONNX Runtime (fallback)
+- **Graph Optimization**: GTSAM
+- **Similarity Search**: Faiss
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.10+
+- PostgreSQL 14+
+- NVIDIA GPU with CUDA support (RTX 2060/3070 recommended)
+- [uv](https://docs.astral.sh/uv/) package manager
+
+### Installation
+
+1. **Clone the repository**
+   ```bash
+   git clone <repository-url>
+   cd gps-denied
+   ```
+
+2. **Install uv** (if not already installed)
+   ```bash
+   curl -LsSf https://astral.sh/uv/install.sh | sh
+   ```
+
+3. **Create virtual environment and install dependencies**
+   ```bash
+   uv venv
+   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+   uv pip install -e ".[dev]"
+   ```
+
+4. **Install ML dependencies** (optional, requires CUDA)
+   ```bash
+   uv pip install -e ".[ml]"
+   ```
+
+5. **Set up PostgreSQL database**
+   ```bash
+   createdb gps_denied
+   ```
+
+6. **Configure environment**
+   ```bash
+   cp .env.example .env
+   # Edit .env with your database credentials
+   ```
+
+### Running the Service
+
+```bash
+uvicorn main:app --reload --host 0.0.0.0 --port 8000
+```
+
+### API Documentation
+
+Once running, access the interactive API docs at:
+- Swagger UI: http://localhost:8000/docs
+- ReDoc: http://localhost:8000/redoc
+
+### Running Tests
+
+```bash
+pytest
+```
+
+With coverage:
+```bash
+pytest --cov=. --cov-report=html
+```
+
+## API Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/v1/flights` | Create new flight |
+| GET | `/api/v1/flights/{id}` | Get flight details |
+| GET | `/api/v1/flights/{id}/status` | Get processing status |
+| POST | `/api/v1/flights/{id}/batches` | Upload image batch |
+| POST | `/api/v1/flights/{id}/user-fix` | Submit user GPS anchor |
+| GET | `/api/v1/stream/{id}` | SSE stream for real-time results |
+
+## Project Structure
+
+```
+gps-denied/
+├── main.py                 # FastAPI application entry point
+├── pyproject.toml          # Project dependencies
+├── api/                    # REST API routes
+│   ├── routes/
+│   │   ├── flights.py      # Flight management endpoints
+│   │   ├── images.py       # Image upload endpoints
+│   │   └── stream.py       # SSE streaming
+│   └── dependencies.py     # Dependency injection
+├── components/             # Core processing components
+│   ├── flight_api/         # API layer component
+│   ├── flight_processing_engine/
+│   ├── sequential_visual_odometry/
+│   ├── global_place_recognition/
+│   ├── metric_refinement/
+│   ├── factor_graph_optimizer/
+│   ├── satellite_data_manager/
+│   └── ...
+├── models/                 # Pydantic DTOs
+│   ├── core/               # GPS, Camera, Pose models
+│   ├── flight/             # Flight, Waypoint models
+│   ├── processing/         # VO, Matching results
+│   ├── chunks/             # Route chunk models
+│   └── ...
+├── helpers/                # Utility functions
+├── db/                     # Database layer
+│   ├── models.py           # SQLAlchemy models
+│   └── connection.py       # Async database connection
+└── _docs/                   # Documentation
+```
+
+## License
+
+Proprietary - All rights reserved
+