Instructions to use rfonod/geo-trax with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- ultralytics
How to use rfonod/geo-trax with ultralytics:
from huggingface_hub import hf_hub_download from ultralytics import YOLO # pick the weights file from this repo's "Files and versions" tab weights = hf_hub_download("rfonod/geo-trax", "<weights>.pt") model = YOLO(weights) source = 'http://images.cocodataset.org/val2017/000000039769.jpg' model.predict(source=source, save=True) - Notebooks
- Google Colab
- Kaggle
Geo-trax: YOLOv8s Vehicle Detector for Drone BEV Imagery
This is the default detection model for Geo-trax, a comprehensive pipeline for extracting georeferenced vehicle trajectories from high-altitude drone (bird's-eye view) video footage. The model detects vehicles in aerial imagery and underpins the results reported in the associated publication.
π¬ This accelerated animation previews some of the capabilities of Geo-trax. Watch the full demonstration (~4 min) on YouTube.
Highlights
- π― 0.951 mAP@50 on the Songdo Vision test split, with mAP@50 β₯ 0.988 on cars and buses.
- π°οΈ Built for high-altitude, top-down drone video (140β150 m), where generic detectors miss small vehicles; native at 1920 px.
- π¦ Drop-in:
pip install geo-traxpulls it automatically, or load it with three lines of Ultralytics; an ONNX export is included. - πΊοΈ It is the detector behind Songdo Traffic, ~700,000 georeferenced vehicle trajectories, and the vehicle masks of the Stabilo Benchmark.
- π No install needed to try it: open the live demo.
Model Details
| Property | Value |
|---|---|
| Architecture | YOLOv8s (HBB, horizontal bounding boxes) |
| Input resolution | 1920 Γ 1920 px |
| Classes | 6 trained (4 primary + 2 auxiliary; see below) |
| Parameters | 11.1 M (11,137,922) |
| Framework | Ultralytics 8.x (Geo-trax itself requires β₯ 8.4.184) |
| Trained on | 19,339 annotated aerial images (679,306 labeled instances); multi-stage, see publication |
| Validated on | Songdo Vision v1 test set (1,084 images, 55,124 vehicle instances) |
Classes and Detection Performance
Metrics reported on the Songdo Vision v1 test split
(1,084 images, 55,124 labeled vehicle instances). The Instances column is the per-class
support in that test set. See Table 3 of the
publication for full results.
| ID | Label | Notes | Instances | Precision | Recall | mAP@50 | mAP@50-95 |
|---|---|---|---|---|---|---|---|
| 0 | Car | incl. vans | 49,508 | 0.979 | 0.981 | 0.992 | 0.835 |
| 1 | Bus | 1,759 | 0.952 | 0.977 | 0.988 | 0.826 | |
| 2 | Truck | 3,052 | 0.887 | 0.916 | 0.935 | 0.722 | |
| 3 | Motorcycle | 805 | 0.827 | 0.866 | 0.888 | 0.463 | |
| 4 | Pedestrian | not evaluated | n/a | n/a | n/a | n/a | n/a |
| 5 | Bicycle | not evaluated | n/a | n/a | n/a | n/a | n/a |
| All | 55,124 | 0.911 | 0.935 | 0.951 | 0.711 |
The model reaches 0.951 mAP@50 and 0.711 mAP@50-95 overall, with near-saturated accuracy on cars and buses (mAP@50 β₯ 0.988). Trucks and especially motorcycles are harder: motorcycles are small, sparse in the test set (805 instances), and the main driver of the lower mAP@50-95.
Dataset version: these metrics were measured against Songdo Vision v1. Songdo Vision v2 is an annotation-quality release that removed 196 invalid boxes and added 1,951 vehicles the original pass had missed, so its test split holds 55,528 instances rather than 55,124. This model has not been retrained or re-evaluated on v2, and the numbers above should not be compared directly against results reported on v2. Note also that the v2 additions were surfaced with a Geo-trax detector before human confirmation, so evaluating this model family on the v2 test split carries a small favourable bias; filtering COCO
id <= 272435restores the v1-provenance test set.
Evaluation Plots
Precision-recall curves and the normalized confusion matrix on the Songdo Vision v1 test set:
![]() Precision-Recall Curve |
![]() Normalized Confusion Matrix |
Note on pedestrian and bicycle classes: The model was trained on pedestrian and bicycle instances; however, these classes are not evaluated and not recommended for use. They were underrepresented in the training data, are not annotated in the Songdo Vision dataset (making reliable evaluation impossible), and achieve poor detection performance in practice.
How to Use
π Try it first, no install: the interactive π€ Space runs this detector in your browser on your own aerial image or short clip.
With Geo-trax (recommended)
This model is the default in Geo-trax and downloads automatically on first use:
python -m pip install geo-trax
geotrax extract video.mp4 # detect, track, and stabilize; auto-downloads the model
geotrax batch video.mp4 --no-geo # full pipeline in pixel coordinates; skip georeferencing
geotrax batch video.mp4 # full pipeline including georeferencing (requires orthophotos)
geotrax batch video.mp4 --sahi # optional SAHI inference for better small-object detection
geotrax extract video.mp4 --set 'class_conf={1: 0.15, 2: 0.4}' # per-class confidence thresholds
geotrax export video.mp4 # georeferenced trajectories to GeoPackage (or --format geojson) for QGIS/kepler.gl
The Geo-trax documentation has a guide per pipeline stage (including georeferencing, SAHI and GIS export), plus a config reference and a CLI reference generated from the code.
Direct Ultralytics inference (PyTorch)
from ultralytics import YOLO
from huggingface_hub import hf_hub_download
weights = hf_hub_download(repo_id="rfonod/geo-trax", filename="geotrax_hbb_yolov8s_1920_v1.pt")
model = YOLO(weights)
results = model("drone_frame.jpg", imgsz=1920, conf=0.25, iou=0.7, classes=[0, 1, 2, 3])
results[0].show()
Tip: The model was trained and validated at 1920 px input resolution. Downscaling to 1280 px is possible with a small accuracy trade-off; going below 960 px significantly degrades detection of small vehicles (motorcycles, distant cars). Pass
classes=[0, 1, 2, 3]to restrict inference to the four evaluated classes and suppress unreliable predictions.
ONNX inference
An ONNX export (opset 12, static 1920 Γ 1920 input) is available for deployment without a PyTorch dependency:
import numpy as np
import onnxruntime as ort
from huggingface_hub import hf_hub_download
onnx_path = hf_hub_download(repo_id="rfonod/geo-trax", filename="geotrax_hbb_yolov8s_1920_v1.onnx")
session = ort.InferenceSession(onnx_path, providers=["CPUExecutionProvider"])
# Prepare input: RGB image resized/padded to 1920Γ1920, normalized to [0, 1]
img = np.random.rand(1, 3, 1920, 1920).astype(np.float32) # replace with real image
outputs = session.run(None, {"images": img})
# outputs[0] shape: (1, 10, 75600); 10 = 4 bbox coords + 6 class scores
Training Data
Training followed a multi-stage strategy starting from YOLOv8s weights pretrained on COCO as the initial foundation. Two successive stages were applied:
Stage 1 (BASE): The model was trained on a large, diverse collection drawn from eight public aerial and drone datasets (CARPK, PUCPR+, CyCAR, UAVDT, HARPY, RAI4VD, UIT-ADrone, and VisDrone) combined with the Songdo Vision v1 dataset, totalling 19,339 training images with 679,306 annotations across 6 classes (car, bus, truck, motorcycle, pedestrian, bicycle).
Stage 2 (FINE): The BASE-trained model was subsequently fine-tuned on a curated, high-quality subset of 9,004 images with 321,368 annotations, emphasising accurate annotations and higher-resolution images, again combined with Songdo Vision v1, to yield the final weights released here.
Training set composition (annotations per class):
| Stage | Images | Annotations | Car | Bus | Truck | Motorcycle | Pedestrian | Bicycle |
|---|---|---|---|---|---|---|---|---|
| BASE | 19,339 | 679,306 | 561,666 | 15,587 | 28,830 | 44,512 | 24,239 | 4,472 |
| FINE | 9,004 | 321,368 | 266,745 | 8,047 | 14,305 | 30,925 | 1,260 | 86 |
Songdo Vision comprises 5,419 annotated drone frames (4,335 training / 1,084 test; 80/20 split) collected during a large-scale urban traffic monitoring experiment in Songdo, South Korea. It covers four primary vehicle classes captured at 140-150 m altitude by DJI Mavic 3 drones. The counts above come from v1, which contributed 217,311 training and 55,124 test instances; the current release is v2 with 218,662 and 55,528 respectively.
Training configuration:
| Setting | Value |
|---|---|
| Initialization | YOLOv8s pretrained on COCO |
| Optimizer | SGD |
| Learning rate (initial / final factor) | 0.01 / 0.01 |
| Momentum | 0.937 |
| Weight decay | 0.0005 |
| Batch size | 8 |
| Early stopping | 50-epoch patience |
| Input resolution | 1920 Γ 1920 px (letterbox padding) |
| Mixed precision | AMP enabled |
| Augmentation | random scaling, translation, horizontal flip, mosaic, colour jitter, Gaussian/median blur, grayscale, CLAHE |
See the publication for complete dataset statistics, training details, and ablation results.
Intended Use and Limitations
- GSD assumption: The bundled Geo-trax config assumes a ground sampling distance (GSD) of
~0.055 m/px (DJI Mavic 3, 4K, 140-150 m altitude). Adjust
extraction.dimension_estimation.gsdfor different hardware or flight altitudes. - Supported classes: Car, bus, truck, and motorcycle (class IDs 0-3). The model was also
trained on pedestrian and bicycle instances; however, these classes achieve poor detection
performance and are not recommended for use (see the class table above). Geo-trax filters to
the four primary classes by default; when using Ultralytics directly, pass
classes=[0, 1, 2, 3]to suppress unreliable predictions.
The Geo-trax and Songdo family
All six Hub repos come from one multi-drone traffic experiment over Songdo, South Korea, and are gathered in the π€ collection Trajectory Extraction and Stabilization.
| Repo | What it is | |
|---|---|---|
| π§ Model | rfonod/geo-trax (this page) |
YOLOv8s vehicle detector for high-altitude drone imagery (0.951 mAP@50) |
| π Space | rfonod/geo-trax |
Run the detector in your browser on your own image or clip |
| π£οΈ Dataset | rfonod/songdo-traffic |
~700,000 georeferenced vehicle trajectories from 10 drones over 20 intersections |
| πΌοΈ Dataset | rfonod/songdo-vision |
5,419 4K frames with 274,190 human-verified vehicle boxes |
| π Dataset | rfonod/songdo-vision-obb |
The same frames with oriented (rotated) vehicle boxes |
| π― Dataset | rfonod/stabilo-benchmark |
Benchmark data for reference-based UAV video stabilization |
Related datasets and resources
- Live demo: interactive π€ Space:
rfonod/geo-trax(Spaces) - Songdo Traffic: the georeferenced vehicle-trajectory dataset this model helps produce via
the Geo-trax pipeline:
10.5281/zenodo.13828383Β· HFrfonod/songdo-traffic - Songdo Vision: the vehicle-detection (annotated image) dataset used to train and validate
this model:
10.5281/zenodo.13828407Β· HFrfonod/songdo-vision - Songdo Vision OBB: the same frames as Songdo Vision v2 with oriented bounding boxes,
introduced with the stabilization benchmark below:
10.5281/zenodo.15050578Β· HFrfonod/songdo-vision-obb - Stabilization benchmark: Stabilo Benchmark,
which evaluates the registration step behind Geo-trax's stabilization on dynamic urban scenes and
annotates its vehicles with this model, via HBB2OBB:
arXiv:2611.17190 Β· data record
10.5281/zenodo.23623540Β· HFrfonod/stabilo-benchmark - Source video recordings (not open access):
10.5075/EPFL.20.500.14299/253923 - Publication: Transportation Research Part C (2025):
10.1016/j.trc.2025.105205Β· arXiv:2411.02136 - Software: Geo-trax: github.com/rfonod/geo-trax Β·
documentation Β·
Zenodo
10.5281/zenodo.12119542Β· demo video
Citation
If you use this model, please cite the associated publication:
@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},
doi = {10.1016/j.trc.2025.105205}
}
If you additionally use the Geo-trax software, please also cite its Zenodo archive, replacing the version and year with the release you used (the example shows the latest at the time of writing). The DOI below is the concept DOI, which always resolves to the latest release; to cite one release specifically, use that version's own DOI from the Zenodo record.
@software{fonod_geotrax,
author = {Fonod, Robert},
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 = {1.6.2},
year = {2026}
}
License
This model is released under the Creative Commons Attribution 4.0 International (CC BY 4.0) license; see the LICENSE file for the full terms. The Geo-trax codebase is distributed separately under the MIT License.
- Downloads last month
- 870
Model tree for rfonod/geo-trax
Base model
Ultralytics/YOLOv8Datasets used to train rfonod/geo-trax
Voxel51/VisDrone2019-DET
rfonod/songdo-vision
Space using rfonod/geo-trax 1
Collection including rfonod/geo-trax
Papers for rfonod/geo-trax
Consensus Capture in Reference-Based UAV Video Stabilization: A Benchmark on Dynamic Urban Scenes
Advanced computer vision for extracting georeferenced vehicle trajectories from drone imagery
Evaluation results
- mAP@0.5 on Songdo Vision (v1)test set self-reported0.951
- mAP@0.5:0.95 on Songdo Vision (v1)test set self-reported0.711
- Precision on Songdo Vision (v1)test set self-reported0.911
- Recall on Songdo Vision (v1)test set self-reported0.935


