Geo-trax: A Comprehensive Framework for Georeferenced Vehicle Trajectory Extraction from Drone Imagery

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.

📌 Important: If you use this code in your work, kindly acknowledge it by citing the following article:

Robert Fonod, Haechan Cho, Hwasoo Yeo, Nikolas Geroliminis (2025). Advanced computer vision for extracting georeferenced vehicle trajectories from drone imagery, Transportation Research Part C: Emerging Technologies, vol. 178, 105205. DOI: 10.1016/j.trc.2025.105205

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 below).
• ⚙️ One command, one config: geotrax batch runs the whole pipeline; a single YAML drives every stage, with four tuned presets included.

Features

• Detection: YOLOv8s on aerial BEV imagery; detects car (incl. vans), bus, truck, and motorcycle; optional per-class confidence thresholds (extraction.class_conf) and SAHI sliced inference for improved small-object recall (--sahi).
• Tracking: six multi-object trackers (BoT-SORT default); see Tracking for a comparison; optional per-track frame-gap interpolation.
• Stabilization: homography-based trajectory correction via Stabilo ⚖️, tuned with Stabilo-Optimize 🎯; optional CUDA acceleration (--stab-gpu).
• Georeferencing: frame-to-orthophoto registration; outputs lat/lon, local CRS, speed, acceleration, and lane assignment per vehicle; optional CUDA acceleration (--geo-gpu).
• Visualization: track overlays on original, stabilized, or static-reference video, in five rendering modes (incl. oriented bounding boxes).
• Analysis: trajectory maps, kinematic distributions, and class/dimension charts, per-video or aggregated across drones and sessions; GIS export (GeoPackage/GeoJSON) of trajectories for QGIS, ArcGIS, or kepler.gl (geotrax export).
• Scaling & tooling: batch-processes directory trees and aggregates multi-drone data; includes standalone utilities for end-to-end data preparation, training, evaluation, and validation.

🚀 Planned Enhancements

• Comprehensive documentation in a dedicated docs/ folder. A tools/README.md index already covers the auxiliary scripts.
• Modularized, OOP-based pipeline with custom reference frame support and georeferencing leveraging Stabilo's image-matching backend.
• Simulation and scenario export: geotrax export --format sumo (and/or OpenDRIVE, CommonRoad) to turn an extracted dataset into a drop-in scenario for traffic simulators and digital twins, reusing the lane and road-section geometry already carried by the orthophoto segmentations.
• Live/online mode: ingest RTMP-style drone feeds for real-time georeferenced output, for live monitoring and incident detection rather than offline batches.
• Batch inference and multi-thread processing, plus distributed fan-out (Ray, Dask, or Slurm) so geotrax batch scales across a cluster for multi-drone, multi-intersection campaigns.
• Real-world map visualization (e.g., MovingPandas, contextily) and an interactive web viewer with map-based playback and filtering by class, lane, speed, and time, so datasets can be explored without writing plotting code. (geotrax export already produces GeoPackage/GeoJSON layers that open directly in QGIS or kepler.gl.)

🔗 Related Projects

Geo-trax integrates with and complements several specialized tools:

• Stabilo ⚖️: Python library for video and trajectory stabilization using robust homography transformations. Supports various feature detectors, RANSAC algorithms, and user-defined masks. Used as Geo-trax's core stabilization engine.
• Stabilo-Optimize 🎯: benchmarking and hyperparameter optimization framework for Stabilo. Evaluates stabilization performance through ground truth-free assessment using random perturbations. Used to fine-tune Geo-trax stabilization parameters.
• HBB2OBB 📦: converts horizontal bounding boxes to oriented bounding boxes using SAM segmentation models. Can enhance Geo-trax outputs when object orientation is needed for downstream analysis.

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 dataset. Both are described in the associated publication.

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

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 = sep,
     version = {1.5.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 file for more details.

Full Changelog

https://github.com/rfonod/geo-trax/compare/v1.5.0...v1.5.1