ARGUS - Aerial Rescue and Geospatial Utility System

ARGUS is a web application for structured documentation and analysis of drone images in rescue operations. It creates orthophotos from UAV mapping flights (RGB and thermal/IR), presents flight data in a structured manner, evaluates infrared imagery, and offers object detection using custom-trained neural networks. An integrated local LLM (Ollama) can automatically generate scene descriptions.

ARGUS runs as a multi-container Docker application and is accessible from any device on the same network. It is recommended to use a Chromium-based browser.

Note: ARGUS is developed at Westphalian University of Applied Sciences as part of the E-DRZ research project. It is intended for scientific use and does not offer the reliability of commercial software.

360 Video Support: ARGUS now again supports 360° video reconstruction via Stella VSLAM. Upload an equirectangular video; the argus_stella_worker extracts keyframes and 6-DOF camera poses, and produces a sparse and/or dense point cloud. The result opens in a dedicated reconstruction report with a panoramic keyframe tour, an equirectangular video player, and an interactive 3D point-cloud viewer.

---

Table of Contents

• Features
• Prerequisites
• Installation
• Configuration
• Usage
• WebODM Integration (Optional)
• Architecture Overview
• Known Issues
  • Image & Metadata Requirements
• Example Data
• Papers

---

Features

• Orthophoto Generation — Built-in fast mapping pipeline that handles both nadir and angled camera orientations using perspective-correct projection
• Thermal/IR Analysis — Temperature matrix extraction, IR overlays, and hotspot detection
• Object Detection — Two detection backends: a custom Transformer-based model trained on rescue scenarios and a YOLO based with models still in development
• 360° Video Reconstruction — Stella VSLAM extracts keyframes, 6-DOF camera poses, and sparse/dense point clouds from equirectangular videos; viewable as a panoramic keyframe tour, video player, and interactive 3D scene
• AI Scene Descriptions — Local LLM (Ollama with LLaVA) generates automatic image descriptions
• WebODM Integration — Optional high-quality orthophoto generation via OpenDroneMap
• Weather Data — Automatic weather context via OpenWeatherMap API

Prerequisites

• Docker & Docker Compose — Installation guide
• Git (with submodule support)
• (Optional) NVIDIA Container Toolkit — Installation guide — enables GPU-accelerated detection and LLM inference. Without it, everything runs on CPU.

Supported platforms: Linux (primary), Windows (via start-win-argus.cmd / PowerShell wrapper)

Installation

1. Clone the repository with submodules:

   git clone --recursive https://github.com/RoblabWh/argus.git
   cd argus
   

   If you already cloned without --recursive:

   git submodule update --init --recursive
   

2. Start ARGUS:

   ./argus.sh up --build
   

   The first build takes several minutes. On the first launch a .env file is created automatically from .env.example.

3. Open in browser: http://<your-ip>:5173

The startup script (argus.sh) automatically detects your local IP, checks for NVIDIA GPU support, and selects the appropriate Docker Compose configuration.

Configuration

The .env file in the project root controls all settings. It is created automatically on first launch. Key variables:

By default, URLs are written once (on first launch) and then preserved. To rebuild them, pass a flag:

To rewrite URLs every launch without typing flags, set ARGUS_DEFAULT_FLAGS=--update-all-urls in .env. On Windows, the equivalent PowerShell switches are -UpdateApiUrl, -UpdateWebodmUrl, -UpdateAllUrls, -KeepApiUrl, -KeepWebodmUrl, -KeepUrls; ARGUS_DEFAULT_FLAGS uses the same --update-* / --keep-* strings on both platforms.

Auto-sync from .env.example: On every launch, any key present in .env.example but missing from .env is appended with the example value, and the script prints which keys were added. This keeps existing .env files compatible with new releases without you having to copy them in manually.

After editing .env manually, restart the containers for changes to take effect.

Usage

# Start all services (builds if needed)
./argus.sh up --build

# Start without rebuilding
./argus.sh up

# Stop all services
./argus.sh down
# or simply in the running terminal
crtl + c

# Windows
start-win-argus.cmd up --build

Workflow:

1. Create a group and a report in the web UI
2. Upload drone images (RGB and/or thermal)
3. Click Process — images are preprocessed, then an orthophoto is generated
4. Optionally run Detection to identify objects in the images
5. Optionally run Auto Description for AI-generated scene summaries

WebODM Integration (Optional)

For high-quality orthophoto generation via OpenDroneMap:

1. Clone WebODM separately: github.com/OpenDroneMap/WebODM
2. Set the following in your .env:

   ENABLE_WEBODM=true
   WEBODM_PATH=/path/to/WebODM
   WEBODM_USERNAME=your_username
   WEBODM_PASSWORD=your_password
   

3. argus.sh will start WebODM automatically alongside ARGUS.

Architecture Overview

ARGUS consists of the following Docker services:

Database migrations are handled automatically via Alembic on startup.

Known Issues

• Firefox may have problems uploading large files (e.g., high-resolution panoramic photos). Use a Chromium-based browser.
• Running multiple processing tasks simultaneously can lead to unexpected behavior.
• Primarily tested with DJI drones. Other manufacturers may require adding camera model definitions to api/app/cameramodels.json.
• Some older Linux distributions use docker-compose (hyphenated) instead of docker compose. ARGUS requires the modern docker compose plugin syntax.

Image & Metadata Requirements

ARGUS can display images from various cameras/drones. For orthophoto generation, the following EXIF metadata is used:

Thermal/IR images are identified by:

• An ImageSource EXIF tag containing "thermal" or "infrared" (preferred)
• Alternatively: image dimensions or filename pattern (configurable per camera model)

Currently tested with DJI drones (M30T, Mavic Enterprise, Mavic 2, Mavic 3). Other drones may work if they provide the required metadata.

Example Data

• Processed example project: coming soon
• Demo video: ARGUS on YouTube (german)

Papers

1. Redefining Recon: Bridging Gaps with UAVs, 360 Cameras, and Neural Radiance Fields — Surmann et al., IEEE SSRR 2023, Fukushima
2. UAVs and Neural Networks for search and rescue missions — Surmann et al., ISR Europe 2023
3. Lessons from Robot-Assisted Disaster Response Deployments — Surmann et al., Journal of Field Robotics, 2023
4. Deployment of Aerial Robots during the Flood Disaster in Erftstadt/Blessem — Surmann et al., ICARA 2022
5. Deployment of Aerial Robots after a major fire of an industrial hall — Surmann et al., IEEE SSRR 2021

---

Developed at Westphalian University of Applied Sciences — RobLab | Funded by the German Feederal Ministry of Research, Technology and Space (BMFTR)