Downloads · 30 days
141
53% of all-time downloads
Dura-S/reco-yolo26s-football
reco-yolo26s-football is a object detection model from Dura-S. Use it when you need objects located in an image. It is set up for ultralytics. The card lists the license as agpl-3.0.
A YOLO26s detector for ball, player and referee in amateur football, trained for the automatic camera in reco, an open-source GPU panoramic sports stitcher. The detections drive the virtual camera: where the ball is d…
Downloads · 30 days
141
53% of all-time downloads
All-time downloads
265
Public
Repo size
121 MB
Likes
1
Public
Click a slice to open those files.
.onnx39.5 MB · 66%
From the Hugging Face model README
A YOLO26s detector for ball, player and referee in amateur football, trained for the automatic camera in reco, an open-source GPU panoramic sports stitcher. The detections drive the virtual camera: where the ball is decides where the exported video looks.
This is the checkpoint reco runs in production. Read "What this was trained on" before using it - it is a narrow model, not a general football detector.
What changed in this update. This version replaces the earlier release of this repo. Measured on the same data, it is clearly better at players and referees and about equal on the ball. See "Results" for the numbers and for what they can and cannot show.
| id | name |
|---|---|
| 0 | person |
| 1 | ball |
| 2 | referee |
Note the order: person is 0 and ball is 1, which is not the COCO order. Referee is a separate class from person.
The training images are not published. They show amateur football including minors, recorded without any expectation of public release. Only the weights are shared. Do not ask for the dataset.
The model was trained on 1920x1920 tiles cut from 3840x2880 camera frames. There are two ways to feed it a frame:
x = 0 .. 2880 and
x = 960 .. 3840 (full height), each resized to 1920x1920
(bilinear), run the model on both, map boxes back to the camera
frame and merge the overlap with a per-class NMS. Twice the
inference cost. On our held-out match this finds more balls (see
Results); in an end-to-end test of a similar single-crop variant in
the reco pipeline the extra recall did not carry through to the final
camera tracking, so it is not the app default.Feed it camera frames, not stitched panoramas. reco runs the model on each camera's own frame before any stitching. A stitched panorama is a different domain - reprojected geometry, dewarped lens distortion, a different aspect ratio and a different object scale - and the model has never seen one. Running it at the native scale, i.e. 1920x1920 crops without resizing, finds more small balls but also more false boxes (white boots, a round logo on a jacket); that is not what this checkpoint was trained on.
Selected checkpoint (epoch 259 of 300), measured with imgsz=1920:
| class | precision | recall | mAP50 | mAP50-95 |
|---|---|---|---|---|
| all | 0.852 | 0.825 | 0.862 | 0.685 |
| person | 0.953 | 0.947 | 0.970 | 0.803 |
| ball | 0.751 | 0.636 | 0.682 | 0.465 |
| referee | 0.851 | 0.892 | 0.935 | 0.786 |
The same 248 tiles, the previous release of this repo:
| class | precision | recall | mAP50 | mAP50-95 |
|---|---|---|---|---|
| all | 0.795 | 0.780 | 0.800 | 0.615 |
| person | 0.891 | 0.915 | 0.947 | 0.766 |
| ball | 0.858 | 0.643 | 0.737 | 0.501 |
| referee | 0.635 | 0.784 | 0.717 | 0.580 |
Caveats: this validation set also chose the checkpoint (epoch 259), so the numbers for this model are slightly optimistic. The ball row is better for the previous release, mostly through precision.
200 camera frames (100 random, 100 from play time only) from one match that no model was trained on, labelled by hand. Only balls inside the playing area count (94 balls). Inference with two tiles as described above, confidence threshold 0.10:
| this version | previous release | |
|---|---|---|
| balls found | 64 / 94 (68%) | 70 / 94 (74%) |
| balls found at conf 0.50 | 59% | 57% |
| false boxes in the field at 0.10 | 12 | 25 |
| false boxes in the field at 0.50 | 2 | 2 |
| balls under 12 px found | 8 / 28 | 12 / 28 |
The difference in balls found is not significant (paired sign test: 4 balls only this version, 10 only the previous one, p = 0.18). What the numbers do show: no detectable gain on the ball, and fewer false boxes at a low threshold. Treat them as indicative: the labels were bootstrapped from model predictions and are known to miss some spare balls lying around the pitch, and it is one match.
The same 200 frames, run the way the reco app runs them today (whole frame letterboxed into 1920x1920, one pass, scale 0.5):
| this version | previous release | |
|---|---|---|
| balls found at conf 0.10 | 52 / 94 (55%) | 57 / 94 (61%) |
| balls found at conf 0.50 | 46% | 40% |
| false boxes in the field at 0.10 | 6 | 8 |
| balls under 12 px found | 6 / 28 | 10 / 28 |
Again not significant (5 balls only this version, 10 only the previous one, p = 0.30). Whole-frame inference finds fewer balls than two tiles for both models, so the first table is the best case for the ball.
Ball detection is the open problem in this project, not a solved one. Balls under about 12 px in the camera frame are mostly missed.
Trained from random initialisation, not from COCO or other pre-trained weights, with ultralytics 8.4.146 (the checkpoint records this version; the run was resumed once):
Settings that differ from a default fine-tune: pretrained=False,
imgsz=1920, batch=2, epochs=300, patience=100, optimizer=auto.
All other settings are ultralytics defaults (mosaic on, closed for the
last 10 epochs). The run finished all 300 epochs; the best epoch by
validation fitness was 259. Single 8 GB GPU.
imgsz=1920 is high on purpose. The ball is a handful of pixels across
in a 3840x2880 frame, and training smaller measurably cost detection
quality.
| file | notes |
|---|---|
best.pt | 20.8 MB. Ultralytics checkpoint - load, fine-tune, or re-export from this. Pickle format, so only load it if you trust this repo. |
best.onnx | 39.5 MB. Exported at imgsz=1920, input 1x3x1920x1920, output 1x300x6, exported with NMS. This is what reco loads. |
Both files had the training machine's local filesystem paths removed
before upload (ultralytics stores them in the checkpoint args and in the
ONNX description). The weights themselves are untouched: all weights
compare equal to the originals and predictions are identical. The tool
used is scripts/strip_ultralytics_local_paths.py in the
reco repository.
With ultralytics, on one 1920x1920 tile:
from ultralytics import YOLO
model = YOLO("best.pt")
results = model.predict("tile_1920.jpg", imgsz=1920, conf=0.1)
for box in results[0].boxes:
print(model.names[int(box.cls)], float(box.conf), box.xyxy.tolist())
With onnxruntime, no ultralytics dependency:
import numpy as np, onnxruntime as ort
session = ort.InferenceSession("best.onnx", providers=["CPUExecutionProvider"])
# One tile: RGB, 1920x1920, float32, 0-1, NCHW.
out = session.run(None, {"images": tile})[0] # (1, 300, 6)
# Each row: x1, y1, x2, y2, confidence, class_id (pixels of the 1920 tile).
reco runs this at conf=0.1 and filters afterwards, because a
low-confidence ball detection that a tracker can corroborate is worth
more than a missed one.
AGPL-3.0. This model was trained from scratch, not from Ultralytics'
pre-trained weights, but with the AGPL-3.0-licensed ultralytics package
and its YOLO26 architecture, and the checkpoint itself carries
Ultralytics' own license field
(AGPL-3.0 (https://ultralytics.com/license)). The model is therefore
published under the same terms. If you need it under different terms,
that is between you and
Ultralytics licensing. reco itself is
AGPL-3.0 as well.
Adit-jain/soccana, a
YOLO11 football fine-tune, used as the teacher model to generate the
initial pre-labels for the first part of the data before human
correction. That repository lists no license at the time of writing.