Real-time soccer player tracking system using YOLOv8 and ByteTrack algorithm. Tracks players, ball possession, speed, distance, and team assignments with camera movement compensation.

• Real-time Tracking**: Multi-object tracking of players, referees, and ball
• Team Assignment**: Automatic team identification based on jersey colors
• Ball Possession**: Tracks which player has the ball
• Analytics**: Calculates player speed and distance traveled
• Field Transformation**: Converts camera view to top-down field coordinates
• Camera Compensation**: Accounts for camera movement in tracking
• Field Filtering**: Excludes audience members for better accuracy

• Installation
• Quick Start
• Usage
• Training Custom Models
• Configuration
• Project Structure
• Contributing
• License

• Python 3.8 or higher
• UV package manager (recommended) or pip

1. Clone the repository:

   git clone https://github.com/your-username/soccer-player-tracking.git
   cd soccer-player-tracking

2. Install UV (if not already installed):

   pip install uv

3. Create virtual environment and install dependencies:

   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   uv pip install -e .

   Or with development dependencies:

   uv pip install -e ".[dev]"

1. Place your video in input_videos/ directory

2. Get a model (choose one):

   • Option A: Train custom model (best accuracy):

     pip install roboflow
     python train_model.py

   • Option B: Use pre-trained model (quick start):

     python scripts/download_model.py

3. Update video path in main.py:

   video_path = "input_videos/your_video.mp4"

4. Run tracking:

   python main.py

5. Find output in output_videos/output_video.mp4

from soccer_tracker.tracking import Tracker
from soccer_tracker.utils import read_video, save_video

# Read video
video_frames = read_video("input_videos/match.mp4")

# Initialize tracker
tracker = Tracker("model/best.pt")

# Track objects
tracks = tracker.get_object_tracks(video_frames)

# Process and save
# ... (see main.py for full example)

# Basic tracking
python main.py

# With custom model
python main.py --model custom_model.pt

For best accuracy, train a custom YOLOv8 model on soccer-specific data:

# Install training dependencies
pip install roboflow

# Train with default settings
python train_model.py

# Train on GPU (faster)
python train_model.py --device cuda --model-size s --epochs 150

# Train with custom dataset
python train_model.py --dataset path/to/your/dataset

See TRAINING_GUIDE.md for detailed instructions.

Update field boundaries in src/soccer_tracker/analysis/view_transformer.py:

self.pixel_vertices = np.array([
    [489, 200],   # Top-left
    [236, 813],   # Bottom-left
    [2193, 813],  # Bottom-right
    [1960, 180]   # Top-right
])

Adjust in main.py to exclude audience:

tracker = Tracker(
    model_path,
    field_boundaries=field_boundaries,
    min_bbox_area=1000,  # Increase to exclude smaller detections
    max_bbox_area=40000
)

See FILTERING_GUIDE.md for more details.

soccer-player-tracking/
├── src/
│   └── soccer_tracker/          # Main package
│       ├── tracking/             # Detection and tracking
│       │   ├── tracker.py
│       │   └── camera_movement_estimator.py
│       ├── analysis/             # Analysis modules
│       │   ├── team_assigner.py
│       │   ├── player_ball_assigner.py
│       │   ├── speed_and_distance_estimator.py
│       │   └── view_transformer.py
│       └── utils/                # Utilities
│           ├── bbox_utils.py
│           └── video_utils.py
├── main.py                       # Main entry point
├── train_model.py                # Model training script
├── scripts/                      # Utility scripts
├── pyproject.toml                # Project configuration
├── README.md
├── TRAINING_GUIDE.md
├── FILTERING_GUIDE.md
└── CONTRIBUTING.md

• ultralytics: YOLOv8 model inference
• supervision: ByteTrack tracking algorithm
• opencv-python: Video processing
• numpy: Numerical operations
• pandas: Data manipulation
• scikit-learn: KMeans clustering for team assignment

The system generates annotated videos with:

• Player tracking with team colors
• Ball possession indicators
• Speed and distance metrics
• Team ball control statistics
• Camera movement visualization

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

This project is licensed under the MIT License - see the LICENSE file for details.

• YOLOv8 by Ultralytics
• ByteTrack tracking algorithm
• Supervision library
• Roboflow for dataset

For issues, questions, or contributions, please open an issue on GitHub.

• Quick Start Guide - Get started in minutes
• Training Guide - Train custom models
• Filtering Guide - Improve accuracy
• Contributing Guide - How to contribute
• GitHub Setup - Repository setup instructions

• Real-time video stream processing
• Multi-camera support
• Advanced analytics dashboard
• Export tracking data to JSON/CSV
• Web interface
• API endpoints

If you find this project useful, please consider giving it a star!

Made with ⚽ for soccer analytics