rfonod/geo-trax
GitHub: rfonod/geo-trax
Stars: 28 | Forks: 7
# Geo-trax
[](https://github.com/rfonod/geo-trax/releases) [](https://www.python.org/) [](https://github.com/rfonod/geo-trax/blob/main/LICENSE) [](https://github.com/rfonod/geo-trax)
[](https://doi.org/10.1016/j.trc.2025.105205)
[](https://arxiv.org/abs/2411.02136) [](https://zenodo.org/doi/10.5281/zenodo.12119542) [](https://www.real-lab.ch/geo-trax) [](https://youtu.be/gOGivL9FFLk)
**Geo-trax** (GEO-referenced TRAjectory eXtraction) is a comprehensive pipeline for extracting high-accuracy georeferenced vehicle trajectories from high-altitude drone imagery. Designed specifically for quasi-stationary aerial monitoring in urban traffic scenarios, Geo-trax transforms raw, bird's-eye view (BEV) video footage into precise, real-world vehicle trajectories. The framework integrates state-of-the-art computer vision and deep learning modules for vehicle detection, tracking, and trajectory stabilization, followed by a georeferencing stage that employs image registration to align the stabilized video frames with an orthophoto. This registration enables the accurate mapping of vehicle trajectories to real-world coordinates. The resulting pipeline supports large-scale traffic studies by delivering spatially and temporally consistent trajectory data suitable for traffic behavior analysis and simulation. Geo-trax is optimized for urban intersections and arterial corridors, where high-fidelity vehicle-level insights are essential for intelligent transportation systems and digital twin applications.
🎬 This animation previews some of the capabilities of Geo-trax. Watch the full demonstration (~4 min) on [YouTube](https://youtu.be/gOGivL9FFLk).
## Pipeline diagram
🔍 This diagram shows a high-level overview of the Geo-trax processing pipeline — from raw drone footage to georeferenced vehicle trajectories; it also highlights optional human annotation and auxiliary vision-data generation steps.
## Features
1. **Vehicle Detection**: Utilizes a pre-trained YOLO model to detect vehicles (cars, buses, trucks, and motorcycles) in the video frames.
2. **Vehicle Tracking**: Implements a selected tracking algorithm to follow detected vehicles, ensuring robust trajectory data and continuity across frames.
3. **Trajectory Stabilization**: Corrects for unintentional drone movement by aligning trajectories to a reference frame, using bounding boxes of detected vehicles to enhance stability. Leverages the [Stabilo](https://github.com/rfonod/stabilo) 🌀 library, fine-tuned by [Stabilo-Optimize](https://github.com/rfonod/stabilo-optimize) 🎯, to achieve reliable, consistent stabilization.
4. **Georeferencing**: Maps stabilized trajectories to real-world coordinates using an orthophoto and image registration technique.
5. **Dataset Creation**: Compiles trajectory and related metadata (e.g., velocity, acceleration, dimension estimates) into a structured dataset.
6. **Visualization Tools**: Visualizes extracted trajectories, overlays paths on video frames, and generates plots for traffic data analysis.
7. **Auxiliary Tools**: Data wrangling, analysis, and model training scripts/tools provided to support dataset preparation, advanced analytics, and custom model development.
8. **Customization and Configuration**: Flexible configuration options to adjust pipeline settings, including detection/tracking parameters, stabilization methods, and visualization modes.
## Field Deployment
Geo-trax was validated in a large-scale urban traffic monitoring experiment conducted in Songdo, South Korea. In this study, Geo-trax was used to process aerial video data captured by a fleet of 10 drones, resulting in the creation of the [**Songdo Traffic**](https://doi.org/10.5281/zenodo.13828383) dataset. The underlying vehicle detection model in Geo-trax was trained using the [**Songdo Vision**](https://doi.org/10.5281/zenodo.13828407) dataset. Both datasets are described in detail in the associated publication, see the [citation](#citation) section below.
🎥 *Demo video of Geo-trax applied to the Songdo field experiment:* [https://youtu.be/gOGivL9FFLk](https://youtu.be/gOGivL9FFLk)
## Installation
1. **Clone or fork the repository**:
git clone https://github.com/rfonod/geo-trax.git
cd geo-trax
2. **Create and activate a Python virtual environment** (Python >= 3.10 and <= 3.12), e.g., using [Miniconda3](https://www.anaconda.com/docs/getting-started/miniconda/install):
conda create -n geo-trax python=3.11 -y
conda activate geo-trax
or using [venv](https://docs.python.org/3/library/venv.html):
python3.11 -m venv .venv
source .venv/bin/activate # On Windows, use `.venv\Scripts\activate`
3. **Install dependencies** from `pyproject.toml`:
pip install -e .
4. **[Optional] Install development dependencies** (for development, testing, or other non-core auxiliary scripts):
pip install -e '.[dev]'
## Model Training
The `train/` directory contains scripts for training and exporting custom YOLOv8 detection models using the [Ultralytics](https://github.com/ultralytics/ultralytics) framework, along with a SLURM wrapper for HPC clusters. See [train/README.md](train/README.md) for full usage instructions.
## Batch Processing Example
The `batch_process.py` script can process multiple videos in a directory, including subdirectories, or a single video file.
To view the help message and available options, run:
python batch_process.py -h
Below are some example commands to demonstrate its usage.
#### Example 1: Process all files in a directory without georeferencing
python batch_process.py path/to/videos/ --no-geo
#### Example 2: Customize arguments for a specific video
python batch_process.py video.mp4 -c cfg/custom_config.yaml
#### Example 3: Process and save visualization for a specific video
python batch_process.py video.mp4 --save
#### Example 4: Save tracking results in video without re-running extraction
python batch_process.py video.mp4 --viz-only --save
#### Example 5: Generate plots only for all videos in a directory
python batch_process.py path/to/videos/ --plot-only --plot
## Citation
If you use **Geo-trax** in your research, software, or to generate datasets, please cite the following resources appropriately:
1. **Preferred Citation:** Please cite the associated article for any use of the Geo-trax framework, including research, applications, and derivative work:
@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. **Repository Citation:** If you reference, modify, or build upon the Geo-trax software itself, please also cite the corresponding Zenodo release:
@software{fonod2026geo-trax,
author = {Fonod, Robert},
license = {MIT},
month = may,
title = {Geo-trax: A Comprehensive Framework for Georeferenced Vehicle Trajectory Extraction from Drone Imagery},
url = {https://github.com/rfonod/geo-trax},
doi = {10.5281/zenodo.12119542},
version = {0.8.0},
year = {2026}
}
## Contributions
The georeferencing code was developed with contributions from [Haechan Cho](https://github.com/cho-96).
## License
This project is distributed under the MIT License. See the [LICENSE](LICENSE) file for more details.