YOLO Object Detection and Tracking

This repository is a Hugging Face compatible YOLO model repository converted from a source-code project. It provides:

app.py: Gradio image upload demo for Hugging Face Spaces.
inference.py: standalone Python API and CLI for image detection.
src/: existing video detection, BoT-SORT tracking, visualization, analytics, and plotting pipeline.
configs/: detector, tracker, and pipeline configuration.
models/: expected location for uploaded model weights.
examples/: local test inputs and generated outputs.

The current project uses Ultralytics YOLO with the COCO person class by default, making it suitable for detecting people, athletes, players, and event participants in images or videos.

Repository Audit

Capability	Status	Evidence
Trained model weights	Missing locally	No `.pt`, `.onnx`, `.engine`, `.safetensors`, `.pth`, or `.ckpt` files were present.
Detection inference	Present	`src/detection/yolo_detector.py`, new `inference.py`, and `app.py`.
Video tracking pipeline	Present	`src/main.py` with `src/tracking/botsort_tracker.py`.
Evaluation pipeline	Partial	`src/analytics/evaluator.py` provides continuity diagnostics, not formal MOTA/IDF1/HOTA because no ground truth annotations are included.
Analytics pipeline	Present	`src/analytics/metrics.py`, `statistics.py`, and heatmap generation.
Custom training pipeline	Not present	No dataset YAML, training script, or training run artifacts are included. Training can be run through Ultralytics CLI/Python commands below.

Required Model Files

No trained weights were included in the repository at conversion time.

For a self-contained Hugging Face model repo, upload at least one PyTorch YOLO weight file:

Required for this app: models/yolo11n.pt or models/best.pt
Optional export: models/model.onnx
Optional export: models/model.engine
Optional export: models/model.safetensors

The included code resolves weights in this order:

CLI argument such as --model models/best.pt
MODEL_PATH environment variable
models/best.pt
models/yolo11n.pt
models/yolov8n.pt
yolo11n.pt downloaded by Ultralytics on first use

For Hugging Face Spaces, uploading models/yolo11n.pt or models/best.pt is recommended so the app does not depend on runtime downloads.

Generate Or Export Weights

Download the pretrained default weights:

python - <<'PY'
from ultralytics import YOLO
YOLO("yolo11n.pt")
PY
mkdir -p models
cp yolo11n.pt models/yolo11n.pt

Train custom YOLO weights with a YOLO dataset YAML:

yolo detect train \
  model=yolo11n.pt \
  data=/path/to/dataset.yaml \
  epochs=100 \
  imgsz=1280 \
  batch=16 \
  project=runs/detect \
  name=custom-yolo

Copy the trained model into the Hugging Face repo:

mkdir -p models
cp runs/detect/custom-yolo/weights/best.pt models/best.pt

Export optional ONNX and TensorRT artifacts:

yolo export model=models/best.pt format=onnx imgsz=1280
yolo export model=models/best.pt format=engine imgsz=1280 device=0

TensorRT .engine files are hardware, CUDA, TensorRT, and driver specific. Do not treat them as portable replacements for .pt or .onnx.

Installation

git clone https://huggingface.co/<username>/<repo-name>
cd <repo-name>
python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Python Inference

from inference import predict

detections, annotated = predict(
    image="examples/input.jpg",
    model_path="models/best.pt",  # or omit to use local/default resolution
    conf=0.35,
    iou=0.5,
    imgsz=1280,
    classes="person",
)

annotated.save("examples/annotated_output.jpg")
for detection in detections:
    print(detection)

CLI Inference

Run with the default person class filter:

python inference.py \
  --image examples/input.jpg \
  --output examples/annotated_output.jpg \
  --json examples/detections.json

Run with custom weights:

python inference.py \
  --model models/best.pt \
  --image examples/input.jpg \
  --output examples/annotated_output.jpg \
  --classes person \
  --conf 0.35 \
  --iou 0.5 \
  --imgsz 1280

Run all COCO classes:

python inference.py \
  --image examples/input.jpg \
  --output examples/all_classes.jpg \
  --classes ""

Gradio App

Run locally:

python app.py

Then open the local URL printed by Gradio. The app accepts an image upload, runs YOLO detection, displays bounding boxes, and returns detection JSON.

Existing Video Tracking Pipeline

Place a video at data/raw/input.mp4, then run:

python -m src.main

Or pass paths explicitly:

python -m src.main \
  --input data/raw/basketball.mp4 \
  --output data/processed/basketball_tracked.mp4

Outputs:

data/processed/tracked_output.mp4
data/metadata/analytics.json
data/metadata/frame_counts.csv
data/metadata/track_history.csv
reports/figures/object_count_over_time.png
reports/figures/confidence_distribution.png
reports/figures/movement_heatmap.png

Hugging Face Spaces Compatibility

This repository includes the files Spaces expects:

README.md
app.py
requirements.txt
inference.py
models/
examples/
src/
configs/

Spaces will install requirements.txt and launch app.py because the README metadata sets:

sdk: gradio
app_file: app.py
python_version: 3.11

Upload Weights With Hugging Face CLI

Install and authenticate:

pip install -U huggingface_hub
huggingface-cli login

Create a model repository:

huggingface-cli repo create <repo-name> --type model

Clone it:

git clone https://huggingface.co/<username>/<repo-name>
cd <repo-name>

Copy this project into the cloned repository, then add weights:

mkdir -p models
cp /path/to/best.pt models/best.pt

Track model files with Git LFS:

git lfs install
git lfs track "*.pt" "*.onnx" "*.engine" "*.safetensors"
git add .gitattributes

Push the repository:

git add README.md app.py inference.py requirements.txt configs src models examples .gitignore .gitattributes
git commit -m "Create Hugging Face YOLO model repository"
git push

Push later updates:

git add .
git commit -m "Update model repository"
git push

Deploy On Hugging Face Spaces

Create a Space:

huggingface-cli repo create <space-name> --type space --space_sdk gradio

Clone the Space:

git clone https://huggingface.co/spaces/<username>/<space-name>
cd <space-name>

Copy these files into the Space repository:

cp -r /path/to/yolo-repo/app.py \
      /path/to/yolo-repo/inference.py \
      /path/to/yolo-repo/requirements.txt \
      /path/to/yolo-repo/README.md \
      /path/to/yolo-repo/models \
      /path/to/yolo-repo/examples \
      .

Commit and push:

git lfs install
git add .
git commit -m "Deploy YOLO Gradio Space"
git push

Model Card

Model Description

This repository wraps Ultralytics YOLO for object detection and includes a BoT-SORT video tracking pipeline. By default it uses yolo11n.pt, a pretrained COCO detector, filtered to the person class for sports and public-event footage.

Intended Use

Person detection in images.
Athlete/player/participant detection when those subjects map to COCO person.
Multi-object video tracking through the included src.main pipeline.
Demo and deployment through Hugging Face Spaces.

Out-of-Scope Use

Identity recognition or biometric identification.
Formal tracking benchmark reporting without ground truth annotations.
Safety-critical surveillance decisions without human review.
TensorRT deployment across different hardware using a prebuilt .engine.

Training Data

No custom training data is included. The default model is a pretrained Ultralytics YOLO model trained for COCO-style object detection.

Evaluation

The repository includes practical tracking diagnostics:

Total unique objects tracked.
Average active tracks per frame.
Track duration statistics.
Detection confidence distribution.
Short-track fragmentation ratio.

It does not include ground-truth labels, so it cannot compute formal MOTA, IDF1, HOTA, mAP on a custom dataset, or other benchmark metrics without additional annotation files.

Limitations

Default detections are limited to COCO classes.
The default app is image detection only; video tracking is available through the CLI pipeline.
Similar uniforms, heavy occlusion, motion blur, and dense crowds can fragment tracks.
Runtime download fallback requires internet access unless weights are uploaded under models/.

License

The runtime depends on Ultralytics. Review the Ultralytics package and model license terms before commercial use.

Downloads last month: -