Computer vision · tracking · graph analytics

FIFA Soccer DS analytics

A Python 3.12 research and engineering codebase that turns soccer-video frames into detections, tracker identities, and spatial-temporal graph data.

Scope note: this repository does not ship trained model weights, datasets, calibration, or a GNN checkpoint. It is not presented as a turnkey production service, and no current FPS or model-accuracy claim has been independently verified.

Open repository Read the audit Dependency decisions

Implemented paths

Detection and tracking

Ultralytics inference feeds a ByteTrack-style/Kalman tracker and writes bounded JSON and overlay outputs.

Graph construction

Track histories become spatial-temporal graphs for downstream PyTorch Geometric models.

Batch analysis API

FastAPI manages bounded YouTube analysis tasks, status, cancellation, metrics, and isolated output paths.

Live input

Local files, cameras, and allowlisted RTSP sources can feed the live detector/tracker. WebRTC/HLS re-streaming is not implemented.

Calibrated analytics

Pitch-control aggregates require an explicit, validated homography and usable two-team classification.

Training and export

GraphSAGE training, LoRA fine-tuning, ONNX export, and optional MLflow/DVC integration are present but require deployment-supplied artifacts.

Data flow

frames / local video / approved YouTube URL / allowlisted RTSP
        │
        ▼
Ultralytics detection → tracker identities → spatial-temporal graph
        │                       │                    │
        ├─ detection JSON       ├─ track JSON        └─ optional trained GNN
        └─ overlays             └─ calibrated tactical aggregates (optional)

Reality check

CapabilityStatus
Synthetic/model-double test coverageAvailable in the repository test suite.
Real-media model qualityNot established by the repository; validate with licensed data and a versioned checkpoint.
GPU throughput and memoryNot established by the audit environment; reproduce on the target driver/CUDA hardware.
Events and named-player statisticsNot implemented. Tracker IDs must not be presented as player identities.
Model/data provenanceDeployment responsibility; no tracked artifacts establish it.

Start locally

python3.12 -m venv .venv
source .venv/bin/activate
make setup
make lint
make test

# Requires your own trusted checkpoint and frames
python -m src.pipeline_full \
  --frames-dir /path/to/frames \
  --weights /path/to/trusted-yolo.pt \
  --output-dir outputs/run

The full setup, API security controls, container paths, artifact warnings, and environmental blockers are documented in the repository README and audit reports.