Football Player Detection with YOLOv8

A comprehensive computer vision project for detecting football players, referees, goalkeepers, and balls in football match images using YOLOv8 object detection model.

🎯 Project Overview

This project implements a state-of-the-art object detection system specifically designed for football/soccer analytics. The model can identify and locate:

• Players - Field players from both teams
• Referees - Match officials
• Goalkeepers - Goal keepers
• Ball - The football

📊 Dataset

The dataset contains high-resolution (1920x1080) football match images with bounding box annotations:

• Training Set: ~7,134 annotations
• Validation Set: ~1,175 annotations
• Test Set: ~600 annotations
• Format: CSV annotations with filename, width, height, class, xmin, ymin, xmax, ymax

🚀 Quick Start

1. Install Dependencies

pip install -r requirements.txt

2. Prepare Dataset

Convert CSV annotations to YOLO format:

python src/data_preprocessing.py

This will:

• Convert CSV annotations to YOLO format
• Organize dataset into proper directory structure
• Generate dataset.yaml configuration file

3. Train Model

python src/train_model.py --epochs 100 --batch-size 16 --model yolov8n

Available model sizes: yolov8n, yolov8s, yolov8m, yolov8l, yolov8x

4. Evaluate Model

python src/evaluate.py --model runs/detect/train/weights/best.pt --data dataset.yaml

5. Run Inference

# Single image
python src/inference.py --model runs/detect/train/weights/best.pt --source path/to/image.jpg

# Batch processing
python src/inference.py --model runs/detect/train/weights/best.pt --source path/to/images/ --save-viz

# Video processing
python src/inference.py --model runs/detect/train/weights/best.pt --source path/to/video.mp4

📁 Project Structure

Football AI Analytics/
├── src/
│   ├── data_preprocessing.py    # Convert CSV to YOLO format
│   ├── train_model.py          # Model training script
│   ├── evaluate.py             # Model evaluation
│   ├── inference.py            # Inference and prediction
│   └── visualize.py            # Dataset visualization
├── train/                      # Training images and annotations
├── valid/                      # Validation images and annotations
├── test/                       # Test images and annotations
├── requirements.txt            # Python dependencies
├── config.yaml                 # YOLOv8 configuration
└── README.md                   # This file

🔧 Configuration

Training Parameters

Key training parameters in train_model.py:

epochs = 100          # Number of training epochs
batch_size = 16       # Batch size
image_size = 640      # Input image size
learning_rate = 0.01  # Initial learning rate

Model Configuration

The config.yaml file defines:

• Dataset paths
• Class names and indices
• Number of classes

📈 Model Performance

The model is evaluated using standard object detection metrics:

• mAP@0.5: Mean Average Precision at IoU threshold 0.5
• mAP@0.5:0.95: Mean Average Precision across IoU thresholds 0.5-0.95
• Precision: True positives / (True positives + False positives)
• Recall: True positives / (True positives + False negatives)

🎨 Visualization Tools

Dataset Analysis

python src/visualize.py --dataset . --analysis stats samples characteristics heatmap

This provides:

• Dataset statistics and class distribution
• Sample annotated images
• Class characteristics analysis
• Annotation density heatmaps

Training Curves

Training progress is automatically logged and can be visualized:

python src/evaluate.py --model best.pt --data dataset.yaml --results-dir runs/detect/train

🔍 Inference Options

Command Line Arguments

• --model: Path to trained model weights
• --source: Input source (image/video/directory)
• --conf: Confidence threshold (default: 0.25)
• --iou: IoU threshold for NMS (default: 0.45)
• --save-viz: Save visualization images
• --output: Output directory for results

Programmatic Usage

from src.inference import FootballPlayerInference

# Initialize inference
detector = FootballPlayerInference('path/to/model.pt')

# Predict single image
result = detector.predict_image('image.jpg')

# Visualize predictions
detector.visualize_predictions('image.jpg', result)

🎯 Applications

This model can be used for:

• Sports Analytics: Player tracking and performance analysis
• Broadcast Enhancement: Automatic player identification
• Tactical Analysis: Formation and movement analysis
• Real-time Detection: Live match analysis
• Academic Research: Sports computer vision studies

📊 Performance Optimization

Training Tips

1. Data Augmentation: Enabled by default in YOLOv8
2. Transfer Learning: Uses pre-trained COCO weights
3. Multi-scale Training: Automatic in YOLOv8
4. Hyperparameter Tuning: Use --hyp parameter

Inference Optimization

1. Model Export: Export to ONNX/TensorRT for faster inference
2. Batch Processing: Process multiple images together
3. GPU Acceleration: Automatic CUDA support if available

🐛 Troubleshooting

Common Issues

1. CUDA Out of Memory: Reduce batch size or image size
2. Low mAP: Increase training epochs or check annotation quality
3. Slow Training: Ensure GPU is being used (torch.cuda.is_available())

Performance Issues

• Check annotation quality and consistency
• Ensure balanced class distribution
• Consider data augmentation strategies
• Validate dataset splits

📝 License

This project is for educational and research purposes. Please ensure you have appropriate rights to use the football match images.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📞 Support

For issues and questions:

1. Check the troubleshooting section
2. Review YOLOv8 documentation
3. Open an issue with detailed description

🔄 Updates

• v1.0: Initial release with YOLOv8 implementation
• v1.1: Added comprehensive evaluation metrics
• v1.2: Enhanced visualization tools
• v1.3: Added video processing capabilities

---

Happy Detecting! ⚽