Gaffers Guide SDK

Gaffers Guide SDK is a modular sports computer vision library for tracking, spatial mapping, and tactical analysis workflows. It is designed as a pip-installable Python SDK with lightweight base modules and optional heavy ML vision components.

Installation

Base install (Parsers & IO):

pip install gaffers-guide

Full ML install (YOLO/SAHI Vision):

pip install "gaffers-guide[vision]"

Quickstart & Usage

Spatial Mapping (No ML required):

import numpy as np
from gaffers_guide.spatial import HomographyEngine

corners_px = np.array(
    [[120.0, 50.0], [1800.0, 45.0], [1900.0, 1030.0], [80.0, 1035.0]],
    dtype=np.float64,
)

engine = HomographyEngine()
mapping = engine.fit(corners_px, frame_shape=(1080, 1920))
pitch_point = mapping.pixel_to_pitch((960.0, 540.0))
print(pitch_point.to_dict())

Tactical IO:

from pathlib import Path
from gaffers_guide.io import parse_tracking_json

tracking = parse_tracking_json(Path("tracking_data.json"))
print(tracking.keys())

The Full Engine:

from pathlib import Path
from gaffers_guide.pipeline import MatchAnalysisPipeline
from gaffers_guide.pipeline.config import PipelineConfig

pipeline = MatchAnalysisPipeline.from_profile("balanced")
report_path = pipeline.process_video(
    PipelineConfig(
        video=Path("match.mp4"),
        output_dir=Path("output"),
        quality_profile="balanced",
    )
)
print(report_path)