Geo-trax

Geo-trax (GEO-referenced TRAjectory eXtraction) is a comprehensive pipeline that extracts high-accuracy, georeferenced vehicle trajectories from high-altitude drone imagery. Built for quasi-stationary aerial monitoring of urban traffic, it turns raw bird's-eye view (BEV) drone footage into precise, real-world vehicle trajectories. The framework combines YOLO detection, multi-object tracking, and video stabilization with a robust orthophoto-based georeferencing stage, producing geo-coordinated, lane-resolved trajectories that are spatially and temporally consistent and ready for large-scale traffic analysis and simulation. It is optimized for urban intersections and arterial corridors, where high-fidelity, vehicle-level insights drive intelligent transportation systems and digital twin applications.

🎬 An accelerated preview of Geo-trax's capabilities. Watch the full ~4 min 4K demo on YouTube.

Why Geo-trax

• 🛰️ Real-world output: georeferenced, lane-resolved trajectories (WGS84 + local CRS) with per-vehicle speed, acceleration, and estimated dimensions, straight from raw BEV drone video.
• 🎯 Accurate detection: YOLOv8s vehicle detector reaching 0.951 mAP@50, trained on more than 19,000 annotated aerial images.
• 🚗 Flexible tracking: four vehicle classes and six selectable multi-object trackers (BoT-SORT, ByteTrack, OC-SORT, and more).
• ⚖️ Drone-motion robust: homography-based stabilization (Stabilo) plus orthophoto image registration for consistent, cross-flight coordinates; both optionally CUDA-accelerated.
• 📊 Proven at scale: powered the Songdo Traffic dataset (roughly 700,000 trajectories across 20 intersections, fleet of 10 drones; see Real-World Deployment).
• ⚙️ One command, one config: geotrax batch runs the whole pipeline; a single YAML drives every stage, with four tuned presets included.

Pipeline

🔍 The core pipeline (solid box) produces stabilized, pixel-coordinate vehicle trajectories. Optional extensions add georeferencing via orthophoto image registration, vision dataset creation through frame (pre-)annotation for custom detector fine-tuning, and visualization, analysis, and probe vehicle validation tools, all applicable to both pixel-coordinate and georeferenced outputs.

Install

python3.11 -m venv .venv && source .venv/bin/activate  # Windows: .venv\Scripts\activate
python -m pip install geo-trax

Python 3.11 to 3.13. Also works with uv (uv pip install geo-trax) and conda. For development:

git clone --depth 1 https://github.com/rfonod/geo-trax.git
cd geo-trax && python -m pip install -e '.[dev]'

# venv (standard library)
python3.11 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

# uv (fastest drop-in for venv + pip)
uv venv --python 3.11
source .venv/bin/activate          # Windows: .venv\Scripts\activate

# Miniconda
conda create -n geo-trax python=3.11 -y
conda activate geo-trax

python -m pip install geo-trax    # pip
uv pip install geo-trax           # uv (faster)

git clone https://github.com/rfonod/geo-trax.git   # add --depth 1 for the latest snapshot only
cd geo-trax
python -m pip install -e .         # pip
# uv pip install -e .              # uv (faster; requires the uv venv above)
# poetry install                   # Poetry (auto-manages its own virtualenv; skip the venv step)

python -m pip install -e '.[dev]'      # development + test tooling
python -m pip install -e '.[export]'   # ONNX export dependencies
python -m pip install -e '.[sahi]'     # SAHI sliced inference for small-object detection (--sahi)
python -m pip install -e '.[docs]'     # documentation site: mkdocs serve / mkdocs build --strict
# uv pip install -e '.[dev]'           # uv equivalents
# poetry install --extras dev          # Poetry equivalents
# poetry install --extras export
# poetry install --extras sahi
# poetry install --extras docs

Quick Start

data/U_video_cut.mp4 is a 5-second sample clip included for immediate testing. See data/README.md for matching orthophotos.

# Pixel-coordinate trajectories (no orthophoto required)
geotrax batch data/U_video_cut.mp4 --no-geo

# Full pipeline: extract, georeference, and analyze (orthophotos required; see data/README.md)
geotrax batch data/U_video_cut.mp4 -orf data/orthophotos -osf data/segmentations -mf data/master_frames --show-lanes

# Scale up: process a whole project tree, then merge multi-drone results into one dataset
geotrax batch path/to/PROCESSED/
geotrax aggregate path/to/PROCESSED/

Run geotrax -h or geotrax batch -h for all options. The scale-up commands above run flag-free with the recommended project structure; any other layout works with explicit path flags. To georeference your own footage, Your own data lists the files each location needs and the defaults to change outside South Korea.

Configuration

The entire pipeline is driven by a single, self-contained YAML config: one file for detection, tracking, stabilization, georeferencing, visualization, and plotting. Four presets ship with the package:

geotrax batch video.mp4 -c confident                     # a bundled preset, by name
geotrax config copy                                      # editable copies: <name>_copy.yaml
geotrax batch video.mp4 -c default_copy.yaml             # your edited copy
geotrax batch video.mp4 --set conf=0.35 --set iou=0.6    # one-off overrides of any key

The Configuration guide covers inspecting and copying configs, the --set rules and their interplay with CLI flags, the run metadata, logs, and the update check; the config reference documents every key.

Detection Model

The default detector is YOLOv8s (HBB, 1920 × 1920 px, ~11 M parameters), trained on more than 19,000 annotated aerial images (~679k labeled vehicle instances) and fine-tuned on a curated, high-quality subset. It is hosted on 🤗 Hugging Face and downloads automatically on first use. Results on the Songdo Vision v1 test split (1,084 images; the Detection and tracking guide has the full Table 3, with and without the Songdo Vision training data, and the evaluation plots):

Pedestrian and bicycle classes exist in the weights but are underrepresented, unevaluated, and filtered by default. See the model card for full details.

To use a different model, point --model (CLI) or extraction.model (config) to a local .pt path or hf://<org>/<repo>/<file>.pt; any Ultralytics-compatible model works. An hf:// reference follows the repo's current main; to pin an exact version, add a revision (commit SHA, tag or branch) after the repo name: hf://<org>/<repo>@<revision>/<file>.pt. Class filtering and renaming are covered in the Detection and tracking guide.

Per-Class Confidence Thresholds

A single ultralytics.conf threshold rarely suits every class: rare or harder classes (buses, trucks) often deserve a lower bar than abundant cars. extraction.class_conf sets a threshold per class ID; classes it does not list keep the global conf:

geotrax extract video.mp4 --set 'class_conf={1: 0.15, 2: 0.4}'   # or set extraction.class_conf in a copied config

Each detection is held to the threshold of its own class before it reaches the tracker, so rejected boxes never start or extend a track; with class_conf: null (the default) extraction is unchanged. The Detection and tracking guide explains how the thresholds interact with the per-track class vote and with ultralytics.max_det.

Small-Object Detection with SAHI

For footage where vehicles are near the detection floor (higher altitudes, sub-4K sensors), the extraction stage can optionally run SAHI sliced inference: each frame is split into overlapping slices, the detector runs on every slice (plus one full-frame pass), and the results are merged before tracking. This substantially improves tiny-object recall, at a cost that grows with the number of slices. On 4K footage the default 1920 x 1080 slices with 20% overlap form a 3 x 3 grid, because two overlapping slices cover only 3456 of the 3840 px; that is nine passes plus the full-frame pass, roughly 10x the per-frame detection cost. Slightly larger slices give a 2 x 2 grid at about half that cost; see the SAHI guide.

geotrax extract video.mp4 --sahi     # also available on 'geotrax batch'
geotrax extract video.mp4 --sahi --set sahi.slice_width=2160 --set sahi.slice_height=1215   # 2 x 2 grid on 4K

SAHI is an optional extra (python -m pip install 'geo-trax[sahi]'); without it, the run stops at once with the install command for your setup. It supports YOLO models only and cannot be combined with the tracktrack tracker or with ReID model auto. The SAHI guide covers the slicing and merge settings and which detection settings still apply.

Custom Model Training

Training and export scripts for custom YOLO detectors live in train/, with a SLURM wrapper for HPC clusters. See train/README.md.

Tracking

Six multi-object trackers from Ultralytics are available: BoT-SORT (botsort, the default), ByteTrack (bytetrack), OC-SORT (ocsort), Deep OC-SORT (deepocsort), FastTracker (fasttrack) and TrackTrack (tracktrack). Selection is config-driven, with no code changes:

geotrax extract video.mp4 --set tracker.active=bytetrack

The Detection and tracking guide compares them (accuracy, speed, appearance ReID, in-tracker camera-motion compensation) and covers tuning their parameters. For a head-to-head comparison on your own data, see tools/compare_tracking.py.

Stabilization

Quasi-stationary drone footage is never perfectly static: wind, GPS drift, and gimbal corrections shift the frame throughout a flight. Geo-trax compensates by registering every frame back to a fixed reference frame with a homography, via Stabilo ⚖️. Tracks are written in both raw and stabilized image coordinates, and the per-frame 3 × 3 transform is saved alongside them.

Registration quality depends on the feature detector. The default is orb, tuned for high-altitude BEV footage with Stabilo-Optimize 🎯 and used for every published result. Five other classical OpenCV detectors and five learning-based kornia models are available through --stab-detector; the Feature detectors guide compares them and explains the rotation and memory caveats of the learned ones before you switch.

Masking, RANSAC, and downsampling parameters live under cfg -> stabilo. To skip stabilization entirely, set extraction.stabilize: false.

Georeferencing

The georeferencing stage turns stabilized pixel trajectories into real-world ones by registering the video's reference frame against a north-up orthophoto of the same location. Output is a per-vehicle CSV with WGS84 coordinates, a local projected CRS, speed, acceleration, and lane / road-section assignment.

This reuses the image-matching machinery from stabilization, but defaults to rsift (RootSIFT) instead of orb. Registering a drone frame against an orthophoto is a cross-domain match, often across years, seasons, and lighting conditions, and is considerably harder than matching consecutive video frames:

geotrax georeference video.mp4 -orf data/orthophotos --geo-detector sift

Orthophotos are required; lane/road-section segmentations and per-location master frames are optional and improve lane assignment and robustness (see the georeferencing guide and data/README.md for how to obtain them). Matching parameters live under cfg -> georef -> matching, kinematic filtering under cfg -> georef -> filtering.

⚠️ Outside South Korea, set georef.transformation.target_crs to a projected CRS for your area (e.g. its UTM zone). The shipped EPSG:5186 is the Songdo one, and speeds, accelerations and dimensions are measured in it; georeferencing warns, naming the UTM zone, when it distorts distances at your site. Your own data describes this and the file formats for a new location.

The learning-based detectors are a poor fit for this stage in particular: the orthophoto is north-up while the drone frame can be at any heading, and every learned model except keynet is upright-only.

GPU acceleration

Object detection already runs on CUDA automatically whenever a compatible GPU and PyTorch build are present (via the ultralytics.device config key, auto by default). The stabilization (--stab-gpu) and georeferencing (--geo-gpu) image-matching steps can optionally be CUDA-accelerated too, through Stabilo. This needs a CUDA-enabled OpenCV build and is Linux/Windows only. Stabilo accelerates the ORB detector only, so --geo-gpu additionally requires --geo-detector orb; there is no CPU fallback, so requesting GPU without a working CUDA device raises an error.

The learning-based detectors use a separate torch device (--stab-device / --geo-device) instead; see Feature detectors. The two cannot be combined.

The full setup (building OpenCV with CUDA, installing geo-trax without overwriting that build, and enabling the GPU per stage) is in the GPU acceleration guide, together with an RTX 4090 benchmark (16.7× faster than the CPU defaults on the sample clip).

Usage

The geotrax CLI provides one subcommand per stage: batch (primary entry point), extract, georeference, visualize, plot, aggregate, export, and config. Run geotrax <subcommand> -h for its options (python -m geotrax works identically).

The documentation site has a guide per stage, plus guides to configuration and to preparing your own data. The stage guides have more examples, the output file formats, the rotated-box visualization modes, master frames, and how to view the GIS exports in the browser, QGIS, or Python. The site's CLI reference and config reference are generated from the code and the shipped config. See data/README.md for sample data, including a sample GIS export of the demo clip.

Real-World Deployment: The Songdo Experiment

Geo-trax was validated in a large-scale urban traffic monitoring campaign in Songdo, South Korea, where it processed footage from a fleet of 10 drones to produce the Songdo Traffic dataset. The detection model was trained on the companion Songdo Vision v1 dataset (a later v2 annotation-quality release exists on Zenodo; the released model has not been retrained on it). The dataset is described in the publication.

🎥 Demo of Geo-trax applied to the Songdo experiment: https://youtu.be/gOGivL9FFLk

The blocks below document the project layout and data-wrangling workflow used in that campaign; they double as the recommended setup for your own multi-drone projects.

<project>/                                 # project root (name arbitrary)
├── RAW/                                   # untouched drone footage + flight logs (never modified)
│   └── 2022-10-07/D1/PM1/                 # arbitrary nesting, e.g. date / drone / session
│       ├── DJI_0001.MP4  DJI_0001.SRT
│       └── DJI_0002.MP4  DJI_0002.SRT     # drone splits a recording into segments (file-size limit)
├── PROCESSED/                             # pipeline input (auto-detect anchor)
│   └── 2022-10-07/D1/PM1/
│       ├── 0_merged.mp4  0_merged.srt     # merged flight video + log (temporary, deletable)
│       ├── 0_merged.txt                   # cut list: start/end frames, one cut per line (temporary)
│       ├── A1.mp4  A1.csv                 # cut clip + flight log; 'A' = location ID, '1' = sequence
│       ├── A2.mp4  A2.csv                 # next clip at the same location
│       └── results/                       # pipeline outputs, written next to each clip
│           ├── A1.yaml                    # run metadata: the configuration actually used
│           ├── A1.txt                     # pixel-coordinate tracks
│           ├── A1_vid_transf.txt          # stabilization homographies
│           ├── A1_geo_transf.txt          # georeferencing homography
│           ├── A1.csv                     # georeferenced trajectories + kinematics
│           ├── A1_mode_0.mp4              # video with overlaid boxes & trajectories (modes 0/1/2/3/4)
│           └── plots/                     # various trajectory & distribution plots
├── ORTHOPHOTOS/                           # auto-detected sibling of PROCESSED / DATASET
│   ├── A.png                              # orthophoto cut-out, per location
│   ├── A.txt  (or A.tif)                  # georeferencing parameters (or a georeferenced GeoTIFF)
│   ├── ortho_parameters.txt               # (alternative) shared params + per-location A_center.txt
│   ├── master_frames/                     # optional; consistent reference frame per location
│   │   ├── A.png                          #   reference frame image
│   │   └── A.txt                          #   cached master->ortho homography
│   └── segmentations/                     # optional; per-location lane/road geometry
│       ├── A.csv                          #   lane & road-section polygons
│       └── A.png                          #   overlay image (used for plotting only)
└── DATASET/                               # `geotrax aggregate` output (sibling of PROCESSED)
    └── 2022-10-07_A/                      # one intersection-day
        ├── 2022-10-07_A_AM1.csv           # one CSV per flight session (AM1-AM5, PM1-PM5),
        └── 2022-10-07_A_PM1.csv           #   trajectories merged across drones for that session

2022-10-07/D10/PM5/U1.mp4
│          │   │   └── clip: location ID 'U' + sequence number '1'
│          │   └────── flight session: AM1-AM5 (morning) / PM1-PM5 (afternoon)
│          └────────── drone ID (D1, D2, ...)
└───────────────────── capture date (ISO 8601, YYYY-MM-DD)

Citation

If you use Geo-trax in your research or software, please cite:

1. Journal article (preferred for any use of the framework):

@article{fonod2025advanced,
  title = {Advanced computer vision for extracting georeferenced vehicle trajectories from drone imagery},
  author = {Fonod, Robert and Cho, Haechan and Yeo, Hwasoo and Geroliminis, Nikolas},
  journal = {Transportation Research Part C: Emerging Technologies},
  volume = {178},
  pages = {105205},
  year = {2025},
  publisher = {Elsevier},
  doi = {10.1016/j.trc.2025.105205},
  url = {https://doi.org/10.1016/j.trc.2025.105205}
}

2. Software archive (when referencing or building on the code itself):

@software{fonod2026geo-trax,
  author = {Fonod, Robert},
  title = {Geo-trax: A Comprehensive Framework for Georeferenced Vehicle Trajectory Extraction from Drone Imagery},
  year = {2026},
  month = nov,
  version = {1.6.1},
  license = {MIT},
  doi = {10.5281/zenodo.12119542},
  url = {https://github.com/rfonod/geo-trax}
}

Contributions

Early code received key contributions from Haechan Cho (georeferencing) and Sohyeong Kim (video/flight-log merging). Community contributions are welcome: open a GitHub Issue or submit a pull request.

License

This project is distributed under the MIT License. See the LICENSE for more details.