Football-Referee-Card-Detector

Football Referee Card Detector — YOLOv8m

A YOLOv8m model fine-tuned to detect referee cards (Green, Red, and Yellow) in football/soccer match footage. Trained on a custom dataset built from scratch — no prior dataset existed for this specific task.

This model was developed as part of a larger computer vision pipeline for football match analysis, which included player face recognition (FaceNet + MTCNN + DBSCAN) and emotion detection (DeepFace). Card detection was the hardest component: no existing dataset or off-the-shelf solution was found, so the dataset was curated, annotated, and trained entirely from the ground up.

---

Model Details

---

Classes

Note on Green Cards: Green cards are uncommon in mainstream football but appear in some competitions (e.g. Serie A's fair play experiments, youth football). Including this class makes the model more broadly applicable across different football contexts.

---

Dataset

Source images (pre-augmentation): ~141 unique images collected via Google Images search.

Augmentation applied per source image (3× expansion):

• 50% probability horizontal flip
• 50% probability vertical flip
• Random rotation between −11° and +11°
• Auto-orientation (EXIF stripping)
• Resize to 640 × 640 (stretch)

Annotation class distribution (train split):

• Green Card (class 0): 96 instances
• Red Card (class 1): 148 instances
• Yellow Card (class 2): 155 instances

The dataset was labelled and managed using Roboflow and is publicly available under CC BY 4.0: 👉 Card Detection Dataset on Roboflow Universe

---

Usage

Installation

pip install ultralytics

Inference — Single Image

from ultralytics import YOLO

model = YOLO("best.pt")

results = model.predict(source="your_image.jpg", conf=0.5)
results[0].show()  # display with bounding boxes

Inference — Video / Live Stream

from ultralytics import YOLO

model = YOLO("best.pt")

# Video file
results = model.predict(source="match_clip.mp4", conf=0.5, save=True)

# Webcam / live stream
results = model.predict(source=0, conf=0.5, stream=True)
for result in results:
    result.show()

Accessing Predictions Programmatically

from ultralytics import YOLO

model = YOLO("best.pt")
class_names = {0: "Green Card", 1: "Red Card", 2: "Yellow Card"}

results = model.predict(source="your_image.jpg", conf=0.5)

for result in results:
    for box in result.boxes:
        class_id = int(box.cls)
        confidence = float(box.conf)
        coords = box.xyxy[0].tolist()  # [x1, y1, x2, y2]
        print(f"Detected: {class_names[class_id]} | Confidence: {confidence:.2f} | Box: {coords}")

---

Training Reproduction

The full training notebook is available in the linked GitHub repository. To reproduce training:

1. Download the dataset from Roboflow Universe or use the Roboflow API
2. Run the training notebook on a GPU environment (Kaggle or Colab recommended)
3. Best weights will be saved to runs/detect/train/weights/best.pt

---

Intended Use

This model is designed for:

• Sports analytics pipelines — automated detection of disciplinary events in football matches
• Broadcast analysis — identifying card moments in recorded or live match footage
• Research — a baseline for further work on referee action recognition
• Integration — as a component in larger multi-modal football analysis systems alongside player tracking, face recognition, or action recognition models

---

Limitations

• Dataset size: ~141 unique source images is a small dataset for a production-grade model. Performance may degrade on highly unusual camera angles, heavy motion blur, or non-standard card designs.
• Green Card scarcity: Green cards are rare in real match footage; the model has seen fewer green card examples and may underperform on this class compared to red and yellow.
• No test split: The Roboflow export did not include a separate test split. Reported metrics are on the validation set only.
• Augmentation-based expansion: The 390 training images are augmentations of ~130 unique source images. The model may not generalize as well as one trained on a larger variety of unique source images.
• Confidence threshold sensitivity: A threshold of 0.5 is recommended; lowering it may increase recall but introduce false positives in cluttered scenes.

---

Background & Motivation

This model was built as part of a proof-of-concept football match analysis system. The full pipeline included:

• Player & referee face recognition via FaceNet + MTCNN + DBSCAN (matching against pre-stored embeddings)
• Emotion prediction via DeepFace
• Card detection — this model

Card detection was the most challenging component. No existing dataset or pre-built solution was found for detecting referee cards specifically. After over a month of experimenting with classical computer vision approaches (color segmentation, contour detection, shape heuristics), a reliable solution could not be achieved due to lighting variability, card size inconsistency, and partial occlusion in real match footage.

The decision was made to train a custom detection model. The dataset was collected, annotated end-to-end using Roboflow, and the resulting YOLOv8m model achieved reliable real-time detection even under live stream conditions — validating the approach.

---

Citation

If you use this model or dataset in your work, please cite:

@misc{football-card-detector-2025,
  title        = {Football Referee Card Detector — YOLOv8m},
  author       = {Hassan},
  year         = {2025},
  publisher    = {Hugging Face},
  howpublished = {\url{https://huggingface.co/YOUR_USERNAME/football-card-detector}}
}

---

License

Model weights: AGPL-3.0 license (As the base weights are from yolo!) Dataset: CC BY 4.0 (via Roboflow Universe)