P.U.L.S.E AI

P.U.L.S.E (Positional and Universal Live Statistical Engine) is a flagship football analytics pipeline that turns raw match video into tracked player IDs, team classification, pitch mapping, and match insights with annotated output.

Highlights

• Dual YOLO detectors for ball + player/GK/referee
• DeepSORT tracking with ghost-track suppression
• SigLIP + UMAP + KMeans team clustering with temporal stability
• Optional homography-based pitch mapping
• Optional analytics: possession, speed/distance, passing, heatmaps
• Annotated video + JSON match report + heatmap images

Requirements

• Python 3.10+
• CUDA optional (runs on CPU)

Install:

pip install -r requirements.txt

Models

Detection models are downloaded via:

python download_models.py

Team classification uses Hugging Face SigLIP weights (downloaded automatically by transformers).

Pitch mapping requires a YOLOv8 pose keypoint model. The mapping pipeline expects it at:

models/detection/yolov8m-pose.pt

Adjust the path in src/mapping/pipeline.py if your model is elsewhere.

Quick Start

python main.py --input-video input_video/match.mp4 --output-dir output

With analytics:

python main.py --input-video input_video/match.mp4 --enable-analysis

With pitch mapping and analytics:

python main.py --input-video input_video/match.mp4 --enable-mapping --enable-analysis

CLI Flags

Flag	Description
--input-video	Required input video path
--output-dir	Output directory (default: output/)
--ball-model-path	YOLOv8 ball model (.pt)
--person-model-path	YOLOv8 player/GK/referee model (.pt)
--tracking-config	Tracking config (configs/tracking.yaml)
--team-classifier-config	Team clustering config (configs/team_classifier.yaml)
--train-teams	Force retrain SigLIP/UMAP/KMeans models
--enable-analysis	Possession, speed, passes, heatmaps
--enable-mapping	Homography mapping (pitch coords)
--homography	Homography output path (models/mapping/homography.pkl)
--mapping-config	Pitch config (configs/mapping.yaml)
--pitch-template	Pitch template JSON path
--pitch-template-image	Pitch template image path
--force-recalibrate	Recompute homography even if it exists
--no-gui	Disable manual calibration GUI
--max-reproj-error	Homography error threshold

Pipeline

Video -> Detection -> Tracking -> Team Classification -> (Mapping) -> (Analysis) -> Output
         (YOLO)       (DeepSORT)    (SigLIP + UMAP + KMeans)  (Homography)  (Optional)

Outputs

• Annotated MP4 in the output directory
• match_report.json when --enable-analysis is set
• Heatmaps (heatmap_team_0.png, heatmap_team_1.png, heatmap_all.png) when mapping is enabled

Project Layout

P.U.L.S.E_AI/
├── main.py
├── download_models.py
├── requirements.txt
├── configs/
├── models/                     # gitignored
├── src/
│   ├── detection/
│   ├── tracking/
│   ├── clustering/
│   ├── mapping/
│   ├── analysis/
│   ├── visualization/
│   └── export/
├── tests/
├── train/
└── assets/

Tests

pytest tests/test_analysis.py -v
pytest tests/ -v