droneflow-yolov8n-visdrone-vehicles

DroneFlow — YOLOv8n fine-tuned on VisDrone (vehicles only)

A YOLOv8n detector fine-tuned on VisDrone2019-DET, restricted to the five vehicle classes used by the DroneFlow traffic-flow pipeline. It is meant for aerial/drone footage of road traffic, where objects are small and dense.

Pedestrians, people, bicycles, tricycles and awning-tricycles are not detected — their annotations were removed from the training data on purpose (see Training data below).

Metrics

Evaluated with model.val() at imgsz=1280, outside the training loop.

Per class on test-dev — the split comparable with published VisDrone results:

Per class on val:

Full numbers, including speed, are in metrics.json. The training curve is in results.csv.

Usage

With Ultralytics directly:

from ultralytics import YOLO

model = YOLO("best.pt")            # or hf_hub_download(...) first
results = model.predict("frame.jpg", imgsz=1280, conf=0.35)

Use imgsz=1280 at inference. The model was trained at that resolution and VisDrone is dominated by small objects; running at 640 costs a large amount of recall.

With the DroneFlow CLI, which resolves and caches Hub weights on its own:

droneflow detect \
  --model hf://sobucki/droneflow-yolov8n-visdrone-vehicles/weights/best.pt@v1-vehicles-1280 \
  --imgsz 1280 --video analysis_video.mp4 --crop-metadata crop_metadata.json --output detections.csv

Pinning the tag matters for reproducibility: DroneFlow records the resolved commit in its run_metadata.json, so a run stays traceable even if the tag moves.

Training data

Derived from VisDrone2019-DET (Tianjin University). The original 10 classes were reduced to 5 by dropping the annotations of pedestrian, people, bicycle, tricycle and awning-tricycle and remapping the remaining class ids. More than a third of the original annotations were discarded this way — capacity that would otherwise be spent on categories the pipeline never counts.

Training-set class balance, which explains most of the per-class spread above:

The conversion script is training/scripts/prepare_visdrone_vehicles.py in the project repository.

Training

Environment: Python 3.12.14, PyTorch 2.13.0, Ultralytics 8.4.131, macOS. Inference speed measured during validation at 1280 on MPS: 4.0 ms inference + 5.0 ms postprocessing per image.

Every hyperparameter, the dataset configuration with its sha256, and the full environment are recorded in args.yaml and train_metadata.json, both published alongside the weights.

Limitations

• motor and truck are weak (mAP50 0.38 and 0.45 on test-dev). Motorcycles are only a handful of pixels at typical drone altitude; if your application depends on counting them, validate before trusting it.
• Severe class imbalance. car is 66% of the training instances and is by far the best-detected class. The ranking of the other four largely follows their frequency.
• Domain gap. Training data is VisDrone footage captured in China. This model has never seen the Passo Fundo (Brazil) footage the DroneFlow project targets, and the project's validation against manual counting is a separate experiment whose results are not reflected here.
• Nano model. yolov8n was chosen for speed on consumer hardware. A larger backbone would very likely do better on the small-object classes.
• The model detects vehicles only; it does not track them or count movements. That is the job of the surrounding pipeline.

Licenses

Two layers apply, and both must be respected:

• Weights and code: AGPL-3.0, inherited from Ultralytics YOLOv8.
• Training data: VisDrone2019-DET, by Tianjin University (VisDrone-Dataset), released for academic use. Check the dataset's own terms before any redistribution or commercial use of derivatives.

Please cite VisDrone if you use this model in academic work.

---

Sobre este modelo (PT)

Este modelo faz parte do TCC "Análise de fluxo de trânsito através de visão computacional utilizando filmagens de drone" (Ciência da Computação, Universidade de Passo Fundo), que constrói uma pipeline para contar veículos e identificar movimentos em cruzamentos a partir de vídeo aéreo.

O yolov8n pré-treinado em COCO não dá conta de objetos pequenos vistos de cima, e as classes do COCO não batem com a taxonomia de veículos que o trabalho precisa. Este fine-tuning no VisDrone, restrito a car, van, truck, bus e motor, é a etapa de detecção dessa pipeline.

O número a citar é o do split test-dev: mAP50 de 0,535 e mAP50-95 de 0,340. O split val (0,604 / 0,404) foi usado durante o desenvolvimento e é otimista em comparação.

Duas ressalvas importantes para leitura dos resultados: motor e truck ficam bem abaixo das demais classes, o que decorre em boa parte do desbalanceamento do VisDrone; e o modelo foi treinado sobre imagens do VisDrone, não sobre os vídeos de Passo Fundo cedidos pela Secretaria de Planejamento — a validação contra contagem manual é um experimento à parte, e os números daqui não a substituem.

Os artefatos de proveniência (args.yaml, results.csv, metrics.json, train_metadata.json) estão publicados junto dos pesos para que o experimento inteiro possa ser auditado e reproduzido.