gianpaj/football-players-detection-1

YOLOv8x — Football Players Detection (football_yolo-2)

A YOLOv8x object-detection model fine-tuned to detect the four key entities in football (soccer) broadcast footage: ball, goalkeeper, player, referee. It is the detection backbone of a football-analysis pipeline (tracking, team assignment, ball possession, speed/distance estimation).

Code / project repository: github.com/gianpaj/football_analysis_yolo — the full pipeline that consumes these weights (detection → ByteTrack tracking → team assignment → possession → speed/distance), plus training and usage instructions.

Model Details

Model Description

• Model type: Object detection (YOLOv8x architecture)
• Base model: yolov8x.pt (Ultralytics, COCO-pretrained), fine-tuned
• Framework: Ultralytics 8.4.90 / PyTorch 2.12.1 (CUDA)
• Classes (4): ball, goalkeeper, player, referee
• Input size: 640×640
• Parameters: 68,127,420 (fused: 113 layers)
• Compute: 257.4 GFLOPs
• License: AGPL-3.0 (inherited from Ultralytics YOLOv8; see License)

Files

• weights/best.pt — best checkpoint by validation mAP50-95 (recommended for inference)
• weights/last.pt — final epoch (100) checkpoint
• args.yaml — full training configuration
• results.csv / results.png — per-epoch training/validation curves
• confusion_matrix*.png, Box*_curve.png — evaluation plots

Intended Uses & Limitations

Intended use

• Frame-level detection of players, goalkeepers, referees, and the ball in football video.
• Feeding a downstream tracker (e.g. ByteTrack) and analytics (team assignment via jersey color, possession, speed/distance).
• Educational / research / sports-analytics prototyping.

Out-of-scope & limitations

• Ball detection is weak. The ball is small, fast, and motion-blurred; recall is only 0.40 (≈60% of ball-visible frames are missed) and localization is loose (mAP50-95 0.19). Downstream logic must compensate — e.g. hold/extrapolate the last known ball position across gaps rather than assume a detection every frame. The validation set contains only 35 ball instances, so this metric also has a wide error bar.
• Small evaluation set. Validation is 38 images / 905 instances; test is 13 images. Treat all metrics as indicative, not definitive.
• Single-source domain. Trained on one Roboflow broadcast dataset. Generalization to other leagues, camera setups, resolutions, lighting, or kit colors is unverified. A real multi-camera broadcast (hard cuts between angles) differs substantially from the training footage.
• Goalkeeper vs. player confusion / low GK recall. Goalkeeper recall is 0.78; goalkeepers are visually similar to outfield players and are a rare class, so some are missed or classed as player. (Some downstream pipelines deliberately remap goalkeeper → player.)
• Not a re-identification model. It detects; it does not track identities across frames on its own.

Bias, risks & ethical considerations

Following Mitchell et al., 2018: this model detects generic on-pitch roles and does not perform person identification, biometric recognition, or any demographic inference. Detection quality may vary with skin tone, kit color, camera quality, and broadcast style due to the narrow single-dataset training distribution — do not assume uniform accuracy across all footage. It is intended for aggregate sports analytics, not for surveillance or individual-tracking use cases. Any latency-sensitive or wagering-related downstream use should account for the ball-detection weakness above.

Training Details

Training data

• Dataset: Roboflow football-players-detection-3zvbc, version 1 (workspace roboflow-jvuqo)
• License: CC BY 4.0
• Splits: 612 train / 38 validation / 13 test images
• Classes: ball, goalkeeper, player, referee (nc: 4)
• Downloaded in YOLOv8 format via download-model.py (Roboflow API).

Training procedure

Fine-tuned from yolov8x.pt for 100 epochs on a single NVIDIA GeForce RTX 4060 Ti (16 GB).

Hyperparameter	Value
Base weights	yolov8x.pt (pretrained)
Epochs	100
Batch size	16
Image size	640
Optimizer	auto (SGD-family, Ultralytics default)
Initial LR (lr0)	0.01
Final LR factor (lrf)	0.01
Momentum	0.937
Weight decay	0.0005
Warmup epochs	3
Mixed precision (AMP)	enabled
Loss gains	box 7.5 / cls 0.5 / dfl 1.5
Augmentation	mosaic 1.0 (closed last 10 epochs), fliplr 0.5, HSV h/s/v 0.015/0.7/0.4, translate 0.1, scale 0.5, erasing 0.4, randaugment
Seed / deterministic	0 / true
Total wall-clock	3,163 s (53 min)

The full configuration is in args.yaml. best.pt is the checkpoint with the highest validation mAP50-95 (around epoch 42).

Evaluation

Metrics

Evaluated on the validation split (38 images, 905 instances) with best.pt. Speed: 0.1 ms preprocess, 8.7 ms inference, 0.3 ms postprocess per image on an RTX 4060 Ti.

Class	Images	Instances	Precision	Recall	mAP50	mAP50-95
all	38	905	0.930	0.761	0.834	0.575
ball	35	35	0.794	0.400	0.420	0.188
goalkeeper	27	27	0.982	0.778	0.963	0.717
player	38	754	0.975	0.969	0.991	0.745
referee	38	89	0.969	0.899	0.961	0.650

Summary: Player, referee, and goalkeeper detection are strong (mAP50 ≥ 0.96). The overall averages are dragged down almost entirely by the ball class. See Limitations.

How to Use

For the complete analysis pipeline (tracking, team assignment, possession, speed/distance) see the GitHub repo: github.com/gianpaj/football_analysis_yolo. Standalone detection with these weights:

from ultralytics import YOLO

model = YOLO("weights/best.pt")

# Single image / frame
results = model.predict("frame.jpg", conf=0.1)  # low conf helps ball recall
for r in results:
    print(r.boxes.xyxy, r.boxes.cls, r.boxes.conf)

# Video
results = model.predict("match.mp4", conf=0.1, stream=True)

Tip: a low confidence threshold (conf=0.1) is recommended to recover more (weak) ball detections; pair it with tracking/interpolation to filter false positives and bridge missed ball frames.

License

This model is a fine-tune of Ultralytics YOLOv8 and is therefore distributed under the AGPL-3.0 license (the license of the base model and framework). If you require a non-AGPL/commercial license for the YOLOv8 weights, see Ultralytics licensing.

The training dataset (football-players-detection-3zvbc) is licensed CC BY 4.0 by its Roboflow authors; attribution is due to them for the data.

Citation

Ultralytics YOLOv8

@software{yolov8_ultralytics,
  author  = {Glenn Jocher and Ayush Chaurasia and Jing Qiu},
  title   = {Ultralytics YOLOv8},
  version = {8.0.0},
  year    = {2023},
  url     = {https://github.com/ultralytics/ultralytics},
  license = {AGPL-3.0}
}

Dataset

@misc{football-players-detection-3zvbc,
  title  = {Football Players Detection Dataset},
  author = {Roboflow (roboflow-jvuqo)},
  year   = {2024},
  url    = {https://universe.roboflow.com/roboflow-jvuqo/football-players-detection-3zvbc},
  note   = {CC BY 4.0}
}