⚠️ IMPORTANT: Geo-trax is currently in its preliminary stages and under active development. Not all features are complete, and significant changes may occur. It is recommended for experimental use only. Please report any issues you encounter, and feel free to contribute to the project. Geo-trax (GEO-referenced TRAjectory eXtraction) is an end-to-end pipeline for extracting high-accuracy, georeferenced vehicle trajectories from high-altitude, bird’s-eye view drone footage, addressing critical challenges in urban traffic analysis and real-world georeferencing. Designed for quasi-stationary drone monitoring of intersections or road segments, Geo-trax utilizes advanced computer vision and deep learning methods to deliver high-quality data and support scalable, precise traffic studies. This pipeline transforms raw, top-down video data into georeferenced vehicle trajectories in real-world coordinates, enabling detailed analysis of vehicle dynamics and behavior in dense urban environments. The pipeline includes the following key components: 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 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 (👷🏼): Provides tools to visualize the extracted trajectories, overlaying paths on video frames and generating various plots for traffic data analysis.7. Customization and Configuration (✅): Offers flexible configuration options to adjust the pipeline settings, including detection and tracking parameters, stabilization methods, and visualization modes. This is a preliminary version of the pipeline with some functionalities not being implemented (👷🏼). Future releases will include more detailed documentation, a more user-friendly interface, and additional functionalities. 🚀 Planned Enhancements Release Plan Version 1.0.0 Complete georeferencing functionality (Point 4 above). Comprehensive dataset creation with all metadata (Point 5 above). Visualization and plotting tools (Point 6 above). Tools for comparing extracted trajectories with on-board sensor data. Basic documentation and examples covering all core functionalities. Version >1.0.0 Release tools for (re-)training the detection model. Pre-processing tools for raw video input. Expanded documentation and tutorials (docs folder). List of known limitations, e.g., ffmpeg backend version discrepancies in OpenCV. Comprehensive unit tests for critical functions and end-to-end tests for the entire pipeline. Publishing on PyPI for simplified installation and distribution. Version 2.0.0 Upgrades to the latest ultralytics (>8.2) and numpy (>2.0) versions. Support for additional tracking algorithms and broader vehicle type recognition. Transition to a modular package layout for enhanced maintainability. Implementation of batch inference and multi-thread processing to improve scalability. Automated testing workflows with GitHub Actions. 📝 Changes (v0.1.0 -> v0.2.0): Dependency Update to Stabilo v1.0.0: Upgraded Stabilo version from v0.1.0 to v1.0.0 in requirements.txt. The new version of Stabilo improves the robustness of the bounding box conversion function, particularly for handling sudden dynamic changes. README.md update: Made minor improvements for clarity and conciseness, including added citation details. References: Added a citation reference to the preprint paper for research-related attribution and updated link to stabilo-optimize Full Changelog: https://github.com/rfonod/geo-trax/compare/v0.1.0...v0.2.0

If you use this software, please cite the software and the paper.