yolov9-soccer-ball

Custom YOLOv9 ball detector for amateur-level soccer footage. ~22 MB.

Standard YOLO weights (COCO etc.) struggle to detect a soccer ball at the small pixel scales typical of sideline-camera amateur footage (~3-5 px ball at 50 m distance, 1080p). This checkpoint was fine-tuned specifically on that regime and is the ball detector used by the soccer-video-pipeline project for per-frame ball grounding.

Two inference paths

Both v9b_best.pt (Ultralytics format) and v9b_best.onnx are in this repo. Use the ONNX path if you want to avoid the AGPL Ultralytics runtime dependency.

Option A — ONNX + onnxruntime (Apache 2.0 dependency chain)

pip install onnxruntime opencv-python numpy

import cv2, numpy as np, onnxruntime as ort

sess = ort.InferenceSession("v9b_best.onnx",
                            providers=["CPUExecutionProvider"])  # or CUDAExecutionProvider
img = cv2.imread("path/to/frame.jpg")
# preprocess: BGR->RGB, resize to 1280, normalize 0-1, NCHW
resized = cv2.resize(img, (1280, 1280))
x = resized[..., ::-1].transpose(2, 0, 1).astype(np.float32) / 255.0
x = x[None]  # (1, 3, 1280, 1280)

outputs = sess.run(None, {sess.get_inputs()[0].name: x})
# outputs[0] shape: (1, 5, N) for single-class YOLOv9 — x,y,w,h,conf per anchor
# Apply NMS + confidence threshold; see ultralytics/utils/ops.py for reference

Option B — Ultralytics (AGPL-3.0)

from ultralytics import YOLO
model = YOLO("v9b_best.pt")
results = model("path/to/frame.jpg")
for r in results:
    for box in r.boxes:
        x1, y1, x2, y2 = box.xyxy[0].tolist()
        conf = box.conf[0].item()
        print(f"ball at ({x1:.0f},{y1:.0f})-({x2:.0f},{y2:.0f})  conf={conf:.2f}")

The model outputs a single class (ball). The pipeline default threshold is conf > 0.2 — at amateur-distance footage ball-class confidence typically sits in 0.15-0.35.

Training data

Custom labeled set of amateur soccer match frames, sideline camera, 1080p, varied venues + lighting. Training data not redistributed.

Performance characteristics

• Ball detection coverage: ~63% of frames in production (vs <5% for stock YOLO weights at this camera distance)
• Useful confidence band: 0.15-0.35 — well below the typical "useful" threshold for object detection but the right band for tiny objects
• Frame sampling rate in production: 5 seconds (so ~63% of those sparse samples have a detected ball)

Intended use

Per-frame ball grounding in the soccer-video-pipeline kickoff-pattern detector. Also useful as a standalone amateur-soccer ball detector.

Limitations

• Trained for sideline-camera framings at amateur match distances. Performs worse on close-up footage or drone shots.
• Single-class output (just ball) — no player detection.

License

The weights themselves carry AGPL-3.0 (inherited from the Ultralytics training framework that produced them). The ONNX runtime path lets you use the WEIGHTS without bundling the AGPL CODE — which is the relevant distinction for many downstream projects (your code and the AGPL training tool stay separable).

Related

• Player detector used by the pipeline: uisikdag/weed_soccer_models (yolov8_soccer)
• Pipeline source: github.com/acato/soccer-video-pipeline