Football-PitchVision

End-to-end soccer computer vision pipeline
Pitch keypoints · Player detection & tracking · Ball tracking · Team classification · Tactical radar overlay

---

👋 Intro

Football-PitchVision is a computer vision toolkit for soccer (football) broadcast video analysis built on Roboflow's ecosystem. It runs the full pipeline from raw video to a tactical bird's-eye radar view using YOLOv8 for detection, SigLIP + UMAP + KMeans for team classification, and Supervision for all annotation and tracking.

Born from roboflow/sports, this fork adds streamlined workflows and a focus on match-ready radar output.

---

✨ Features

Mode	What it does
Pitch Detection	Detects 32 keypoints (corners, penalty spots, center circle, etc.) + edges
Player Detection	Detects players, goalkeepers, referees, and the ball
Ball Detection	Sliding-window inference + centroid tracking with trail visualization
Player Tracking	Consistent IDs across frames via ByteTrack + ellipse annotations
Team Classification	SigLIP → UMAP → KMeans pipeline; goalkeepers assigned by proximity
Radar	Full pipeline: homography transform projects all players onto a top-down pitch overlay

---

💻 Install

# Install the sports library
pip install git+https://github.com/DesusLove/Football-PitchVision.git

# Install soccer example dependencies
cd examples/soccer
pip install -r requirements.txt

# Download pretrained models (~400 MB)
./setup.sh

Requirements: Python 3.8+ | macOS, Linux, or Windows

---

⚽ Datasets

Pre-trained models come from these datasets on Roboflow Universe:

Use case	Dataset	Train your own
Player detection	Download
Ball detection	Download
Pitch keypoint detection	Download

Original source: DFL Bundesliga Data Shootout (Kaggle).

---

🚀 Usage

Run any of the 6 modes with a single command:

python main.py \
  --source_video_path data/2e57b9_0.mp4 \
  --target_video_path data/output.mp4 \
  --device cpu \
  --mode <MODE>

Set --device to cpu, mps (Apple Silicon), or cuda (NVIDIA).

Pitch Detection

Detects soccer field boundaries and 32 keypoints.

python main.py --source_video_path data/2e57b9_0.mp4 \
  --target_video_path data/pitch-output.mp4 \
  --device mps --mode PITCH_DETECTION

Player Detection

Detects players, goalkeepers, referees, and the ball.

python main.py --source_video_path data/2e57b9_0.mp4 \
  --target_video_path data/player-detection.mp4 \
  --device mps --mode PLAYER_DETECTION

Ball Detection

Sliding-window ball detection with a fading centroid trail.

python main.py --source_video_path data/2e57b9_0.mp4 \
  --target_video_path data/ball-tracking.mp4 \
  --device mps --mode BALL_DETECTION

Player Tracking

ByteTrack-based consistent player IDs.

python main.py --source_video_path data/2e57b9_0.mp4 \
  --target_video_path data/player-tracking.mp4 \
  --device mps --mode PLAYER_TRACKING

Team Classification

Assigns team colors using SigLIP embeddings + UMAP + KMeans.

python main.py --source_video_path data/2e57b9_0.mp4 \
  --target_video_path data/team-classification.mp4 \
  --device mps --mode TEAM_CLASSIFICATION

Radar

Full end-to-end pipeline: pitch → players → classification → homography → top-down radar overlay.

python main.py --source_video_path data/2e57b9_0.mp4 \
  --target_video_path data/radar-output.mp4 \
  --device mps --mode RADAR

---

🤖 Models

Model	Purpose
YOLOv8 (detection)	Player, goalkeeper, referee, and ball detection
YOLOv8 (keypoint)	32-keypoint soccer pitch detection
SigLIP	Visual feature extraction from player crops
UMAP	Dimensionality reduction for team clustering
KMeans	Clusters players into 2 teams

---

🗺️ Roadmap

• Frame smoothing to eliminate radar flickering
• Jersey number OCR (character recognition on player crops)
• Player re-identification across camera cuts
• Offline data export to JSON/CSV for post-match analysis
• Multi-camera support with cross-camera homography
• Web UI for uploading video and viewing results

---

📦 Project Structure

Football-PitchVision/
├── sports/                    # Reusable library package
│   ├── annotators/soccer.py   # Pitch drawing, Voronoi diagrams
│   ├── common/ball.py         # BallTracker, BallAnnotator
│   ├── common/team.py         # TeamClassifier (SigLIP + UMAP + KMeans)
│   ├── common/view.py         # ViewTransformer (homography)
│   └── configs/soccer.py      # Pitch dimensions, vertices, edges
├── examples/soccer/
│   ├── main.py                # CLI entry point (6 modes)
│   ├── data/                  # Sample videos + pretrained weights
│   ├── notebooks/             # Training notebooks (Colab-ready)
│   ├── setup.sh               # Model download script
│   └── requirements.txt
├── setup.py
└── README.md

---

🤝 Contributing

Contributions are welcome! Open an issue or submit a PR for:

• New sports (basketball, American football)
• Improved tracking / re-identification
• Performance optimizations
• Bug fixes

---

© License

• Code: MIT License
• YOLOv8 weights: AGPL-3.0 (Ultralytics)
• Sports library: MIT License (Supervision)