Match Analyzer

A computer-vision pipeline for football match videos: player/referee/ball detection and tracking, camera-movement compensation, team assignment by jersey color, ball possession tracking, perspective transformation, and per-player speed/distance estimation.

Credit

This project is adapted from abdullahtarek/football_analysis (MIT-style tutorial project by Abdullah Tarek — see his YouTube channel for the original walkthrough). The core architecture — YOLO detection, ByteTrack-style tracking, KMeans jersey clustering, optical-flow camera movement, and perspective transformation — comes from that project. This repo restructures the modules, adds a CLI, and adapts it for a different clip.

Modules

• tracking/ — YOLO detection + object tracking (players, referees, ball)
• team_assigner/ — KMeans jersey-color clustering to assign team labels
• possession/ — assigns ball possession to the nearest player each frame
• camera_movement_estimator/ — optical flow to compensate for camera pan
• view_transformer/ — perspective transform, pixels → real-world meters
• metrics/ — per-player speed and distance covered
• utils/ — video I/O and bounding-box helpers

Setup

pip install ultralytics supervision opencv-python numpy matplotlib pandas scikit-learn

Download the trained detection weights and place at models/best.pt: https://drive.google.com/file/d/1DC2kCygbBWUKheQ_9cFziCsYVSRw6axK/view?usp=sharing

Drop your input clip in input_videos/.

Run

python analyze_match.py --input input_videos/your_clip.mp4 --output output_videos/result.avi

Options:

• --model — path to YOLO weights (default models/best.pt)
• --track-stub / --camera-stub — cache file paths for tracks / camera movement, so re-runs on the same video skip recomputation
• --no-cache — ignore any existing cache and recompute everything from scratch (use this any time you switch to a different input video)