Professional football/soccer player and ball detection system using state-of-the-art YOLO11 and Soccana models.

• Python 3.8+
• PyTorch compatible GPU (CUDA, MPS, or CPU)
• 8GB+ RAM recommended

cd /path/to/football
pip install -r requirements.txt

# Detect players and ball with YOLO11 (highest accuracy)
python scripts/detect.py --video match.mp4 --model-type yolo11 --model-size xlarge

# Detect with Soccana model
python scripts/detect.py --video match.mp4 --model-type soccana

# Webcam with live preview
python scripts/detect.py --webcam --model-type yolo11 --preview

High-accuracy object detection model with multiple size variants:

Specialized football detection model from HuggingFace:

• Model: Adit-jain/soccana
• Dataset: Adit-jain/Soccana_player_ball_detection_v1

football/
├── docs/
│   └── README.md              # This documentation
├── models/
│   ├── yolo11/
│   │   └── config.py          # YOLO11 configuration
│   └── soccana/
│       └── config.py          # Soccana configuration
├── scripts/
│   ├── detect.py              # Main detection script
│   ├── finetune_yolo11.py     # YOLO11 fine-tuning
│   ├── finetune_soccana.py    # Soccana fine-tuning
│   └── download_soccana_dataset.py  # Dataset download
├── datasets/                  # Training datasets
├── output/                    # Detection output videos
└── requirements.txt           # Python dependencies

python scripts/detect.py [OPTIONS]

Input (choose one):

• --video PATH - Video file path
• --webcam - Use default webcam
• --stream URL - RTSP/HTTP stream

Model:

• --model-type TYPE - yolo11 or soccana
• --model-size SIZE - For YOLO11: nano, small, medium, large, xlarge
• --custom-model PATH - Custom trained weights

Detection:

• --conf FLOAT - Confidence threshold (default: 0.25)
• --ball-conf FLOAT - Ball detection threshold (default: 0.15)

Output:

• --output PATH - Output video path
• --preview - Show live preview
• --skip N - Process every N frames

# Fine-tune on custom dataset
python scripts/finetune_yolo11.py --dataset /path/to/dataset --epochs 100

# Use specific model size
python scripts/finetune_yolo11.py --dataset /path/to/dataset --model-size large

Note: Dataset path will be added later

# Download dataset first
python scripts/download_soccana_dataset.py

# Fine-tune
python scripts/finetune_soccana.py --epochs 50

Download the Soccana football detection dataset:

python scripts/download_soccana_dataset.py

# Or with custom output path
python scripts/download_soccana_dataset.py --output /custom/path

Dataset will be added later. Expected format:

dataset/
├── train/
│   ├── images/
│   └── labels/
├── valid/
│   ├── images/
│   └── labels/
└── dataset.yaml

When using --preview:

• Q - Quit
• Space - Pause/Resume

MIT License - see LICENSE file for details