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 package manager

Installation

1. Clone the repository

   git clone <repository-url>
   cd gps-denied
   

2. Install uv (if not already installed)

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

3. Create virtual environment and install dependencies

   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   uv pip install -e ".[dev]"
   

4. Install ML dependencies (optional, requires CUDA)

   uv pip install -e ".[ml]"
   

5. Set up PostgreSQL database

   createdb gps_denied
   

6. Configure environment

   cp .env.example .env
   # Edit .env with your database credentials
   

Running the Service

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

pytest

With coverage:

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