sportcv-ballnet

The ball head from sportcv: a small heatmap network that finds a pickleball in a 1080p broadcast-style frame.

It exists because the alternative did not fit. WASB was the plan, and at the resolution the ball needs it measured 58.6 ms per frame — 175% of a 33.37 ms budget. This head runs the same job at 9.88 ms (FP16, RTX 3060) and 2.50 ms on TensorRT FP16 (RTX A6000), which is what makes a full analysis pipeline finish faster than the clip plays on one 6 GB laptop GPU.

What it is

Measured

On a held-out rally the model chose nothing on:

Against all labels including the training window: 1.31 px median, 97% within 8 px. Over a 25.6-minute span the head was never trained on, it puts a trajectory on 76–89% of in-rally frames in every minute, median 80% — and the minute it was trained on is not the best one.

The raw detection rate across all frames is 47%, which says nothing about the model: the ball is mostly absent when nobody is playing.

Training data, and why it is this small

396 annotated frames from a single 60-second window — about 1.2% of that window — of one Creative Commons match. Labelling is the expensive input, so the project measured how little would do rather than assuming.

Source footage: *2026.07.25 WD Open — Sabrina Lam + Grace Thomas vs Lingzhe Xu

• Margit Aardmaa*, by @pickleball4you on YouTube, licensed CC BY 3.0. https://www.youtube.com/watch?v=T5rmWjvt8Os

Limitations — read this before using it

• It is overfitted to one match, on purpose. One ball, one set of lights, one camera, one court. It is not a general sports-ball detector and was never trying to be. Treat any other footage as unmeasured until you measure it.
• Pickleball only. No other sport has been run through it.
• The crowd wears the ball's colour, and the court crop was wrong for a while because the ball flies above the court. Both are documented failure modes in the project's DESIGN.md.
• The head always produces a peak, so a confidence threshold is not optional. sp-detect uses 0.35; the distribution is cleanly bimodal (p25 0.047, p75 0.89).

Basketball: ballnet-hoop-v2

The same architecture trained for a basketball broadcast filmed by one camera that pans and zooms from a fixed point (PTZ), on full 1080p frames with no court crop. It is the ball model of sportcv's basketball pilot.

Measured on those 241 held-out frames, against the earlier model on the same frames:

The median error does not favour v1 the way it looks: 110 of the 221 labelled positions in that span were kept from a pre-annotation made with v1's own path, so v1 scores close to zero there by construction. The share within 8 px is the comparison that survives that bias.

ballnet-hoop-v2.peaks.onnx: frames in, ball candidates out

The pre- and post-processing are inside the graph, so a runtime needs no sportcv code around it.

Against sportcv's own Python path (stacking, padding and topk_peaks) on 12 real stacks of the match, the exported peaks moved 0.0001 px at most and the scores 3.6e-7. The shape is fixed to the camera it was trained for.

Limitations

• One match, one camera. It is overfitted to this broadcast on purpose, like the pickleball head, and it is unmeasured on anything else.
• It returns candidates, not the ball: sportcv picks the ball's path among the peaks of consecutive frames (a Viterbi search in the camera's stabilised view), and a single frame's strongest peak is wrong often enough to matter.

Training data

FILIPENSES - VENTA DE BAÑOS (J8 LIGA 2018/2019), by Filipenses Baloncesto Senior Masculino on YouTube, licensed CC BY 3.0. https://www.youtube.com/watch?v=D4XdbDp0vz0. Attribution to the uploader is required in any output derived from it.

Files

Full hashes are pinned in src/sportcv/core/weights.py and checked on every load. A number is evidence only if the artifact behind it can be identified, and a filename identifies nothing.

No TensorRT engine is published here. An engine is tied to a TensorRT version and, without the Ampere-plus flag, to one GPU architecture, so it would be a 50 MB file that silently fails to load for most people. Build your own from ballnet.fp16.onnx; sportcv's exporter checks parity where it is used — in pixels of decoded peak movement against the 1.73 px held-out error — rather than as a tensor difference nobody can act on. Measured at 0.0008 px, which is 0.04% of the model's own error.

Use

uv run sp-detect data/<video>.mp4      # resolves and verifies these weights

Or directly:

import torch
from sportcv.core.ballnet import BallNet
from sportcv.core.weights import resolve

blob = torch.load(resolve("ballnet.pt"), map_location="cpu", weights_only=False)
model = BallNet(width=blob["width"]).eval()
model.load_state_dict(blob["state_dict"])

Licence

The weights and the code are Apache-2.0. The footage they were trained on is CC BY 3.0 and attribution is required in any output derived from it: @pickleball4you for the pickleball head, Filipenses Baloncesto Senior Masculino for the basketball one — YouTube grants 3.0, never 4.0, and the attribution must name the licence the licensor actually granted.

Citation

@software{condados_sportcv_2026,
  author = {Condados, Luis},
  title  = {sportcv: offline sports video analytics from one fixed camera},
  year   = {2026},
  url    = {https://github.com/CondadosAI/sportcv}
}

The architecture owes its framing to the WASB paper, which is the baseline it replaced: Tarashima et al., Widely Applicable Strong Baseline for Sports Ball Detection and Tracking, BMVC 2023. https://arxiv.org/abs/2311.05237