Geo-trax

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 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 (ITS) and digital twin applications.

This animation previews some of the capabilities of Geo-trax. Watch the full demonstration (~4min) on YouTube.

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 YOLOv8 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 library, fine-tuned by 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.

Note: This is a preliminary version of the pipeline. Some functionalities, especially auxiliary tools for data wrangling, analysis, and model training, are under development () and will be included in future releases.

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 dataset. The underlying vehicle detection model in Geo-trax was trained using the Songdo Vision dataset. Both datasets are described in detail in the associated publication, see the citation section below.

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

Installation

1. Create and activate a Python virtual environment (Python >= 3.9 and <= 3.12), e.g., using Miniconda3:

   bash conda create -n geo-trax python=3.11 -y conda activate geo-trax

   or using venv:

   bash python3.11 -m venv .venv source .venv/bin/activate # On Windows, use `.venv\Scripts\activate`

2. Clone or fork the repository:

   bash git clone https://github.com/rfonod/geo-trax.git cd geo-trax

3. Install dependencies from pyproject.toml:

   bash pip install -e .

   Note: Installing in editable mode (-e) is recommended, as it allows immediate reflection of code changes.

4. [Optional] Install development dependencies (for development, testing, or other non-core auxiliary scripts):

- In `bash`:

  ```bash
  pip install -e .[dev]
  ```

- In `zsh` (quotes required to prevent shell expansion of `[]`):

  ```zsh
  pip install -e '.[dev]'
  ```

Batch Processing Example

The batch_process.py script can process multiple videos in a directory, including subdirectories, or a single video file.

Example 1: Process all files in a directory without georeferencing

bash python batch_process.py path/to/videos/ --no-geo

Example 2: Customize arguments for a specific video

bash python batch_process.py video.mp4 -c cfg/custom_config.yaml

Example 3: Process and save visualization for a specific video

bash python batch_process.py video.mp4 --save

Example 4: Save tracking results in video without re-running extraction

bash python batch_process.py video.mp4 --viz-only --save

Example 5: Overwrite existing files with no confirmation prompt

bash python batch_process.py path/to/videos/ -o -y

[!TIP] For more details and usage instructions, run:

bash python batch_process.py -h

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:

   bibtex @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:

   bibtex @software{fonod2025geo-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.6.0}, year = {2025} }

Contributions

The georeferencing code was developed with contributions from Haechan Cho.

Contributions from the community are welcome! If you encounter any issues or have suggestions for improvements, please 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.