ATLAS-GEOFUSE: IMU-Denied UAV Geolocalization

ATLAS-GEOFUSE is a robust, multi-component Hybrid Visual-Geolocalization SLAM architecture. It processes un-stabilized, high-resolution UAV images in environments where IMU and GPS telemetry are completely denied.

It uses an "Atlas" multi-map framework, local TensorRT/PyTorch vision matching (SuperPoint+LightGlue), and asynchronous satellite retrieval to deliver scale-aware <5s relative poses and highly refined <20m absolute global map anchors.

🚀 Quick Start (Docker)

The easiest way to run the system with all complex dependencies (CUDA, OpenCV, FAISS, PyTorch, GTSAM) is via Docker Compose.

Prerequisites:

Docker and Docker Compose plugin installed.
NVIDIA GPU with minimum 6GB VRAM (e.g., RTX 2060).
NVIDIA Container Toolkit installed.

# Build and start the background API service
docker-compose up --build -d

# View the live processing logs
docker-compose logs -f

💻 Local Development Setup

If you want to run the python server natively for development:

# 1. Create a Python 3.10 virtual environment
python -m venv venv
source venv/bin/activate

# 2. Install dependencies
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
pip install fastapi uvicorn[standard] pydantic numpy opencv-python faiss-gpu gtsam sse-starlette sqlalchemy requests psutil scipy
pip install git+https://github.com/cvg/LightGlue.git

# 3. Run the FastAPI Server
python main.py

🧪 Running the Test Suite

The project includes a comprehensive suite of PyTest unit and integration tests. To allow running tests quickly on CPU-only machines (or CI/CD pipelines), Deep Learning models are automatically mocked.

pip install pytest pytest-cov
python run_e2e_tests.py

🌐 API Usage Examples

The system acts as a headless REST API with Server-Sent Events (SSE) for low-latency streaming.

1. Create a Flight

curl -X POST "http://localhost:8000/api/v1/flights" \
     -H "Content-Type: application/json" \
     -d '{
           "name": "Mission Alpha",
           "start_gps": {"lat": 48.0, "lon": 37.0},
           "altitude": 400.0,
           "camera_params": {
               "focal_length_mm": 25.0,
               "sensor_width_mm": 36.0,
               "resolution": {"width": 6252, "height": 4168}
           }
         }'

(Returns flight_id used in subsequent requests)

2. Stream Real-Time Poses (SSE)

Connect to this endpoint in your browser or application to receive live unscaled and refined trajectory data:

curl -N -H "Accept:text/event-stream" http://localhost:8000/api/v1/flights/{flight_id}/stream

3. Ingest Images (Simulated or Real)

Images are sent in batches to process the trajectory.

curl -X POST "http://localhost:8000/api/v1/flights/{flight_id}/images/batch" \
     -F "start_sequence=1" \
     -F "end_sequence=2" \
     -F "batch_number=1" \
     -F "images=@/path/to/AD000001.jpg" \
     -F "images=@/path/to/AD000002.jpg"

⚙️ Environment Variables

Variable	Description	Default
`USE_MOCK_MODELS`	If `1`, bypasses real PyTorch models and uses random tensors. Critical for fast testing on non-GPU environments.	`0`
`TEST_FLIGHT_DIR`	Auto-starts a simulation of the images found in this folder upon boot.	`./test_flight_data`

3.3 KiB Raw Blame History