gps-denied-onboard/README.md

# 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