How druv022/sports-analytics works
1. What this repo does
- This is a Python pipeline that turns a sports broadcast MP4 into per-camera on-screen text timelines.
- The core output is a set of CSV/JSON artifacts in an output directory, plus an optional interactive timeline viewer.
2. Top-level execution flow
- main.py is the primary entrypoint for batch processing.
- The pipeline is stage-based and resumable, with named steps: meta → extract → filter → appearance → cameras → ocr → reference → enrich → associate → aggregate.
- The README’s “resume / from-step / to-step” behavior indicates these stages are the main architectural boundaries.
3. Orchestration layer
- src/broadcast_pipeline/ is the central orchestration package.
- It contains the pipeline controller, config, progress tracking, artifact handling, scene I/O, preflight checks, and the stage-specific coordination code.
- This layer connects all subsystem outputs into the final timeline datasets.
4. Video scene handling
- scene_extractor.py, scene_filter.py, scenes_io.py, video_meta.py, and preflight.py handle video ingestion and scene segmentation.
- This stage converts raw video into scene-level units that downstream camera and OCR logic consume.
- The output of this stage is the temporal backbone of the whole system.
5. Camera assignment subsystem
- src/camera_assignemnt/ contains the logic for identifying and grouping broadcast camera shots.
- It is split into three approaches:
- embedding_cluster/ for appearance/embedding-based clustering,
- homography/ for court geometry and projection-based validation,
- scene_classifier/ for scene-type classification.
- This is a major decision point in the pipeline because camera identity determines how text timelines are grouped.
6. Person appearance subsystem
- src/person_appearance/ extracts and links person-level visual signatures.
- It includes segmentation, color/profile extraction, appearance features, track linking, and signature generation.
- The model and weights are materially important here: yolo11n-seg.onnx is part of the repository, and the README explicitly calls out a YOLO11n-seg download for this stage.
7. OCR and text extraction subsystem
- src/scene_ocr/ handles OCR-specific extraction, geometric normalization, readability/presence filtering, and optional VLM-assisted text handling.
- ocr_runner.py, ocr_autotune.py, text_reference.py, text_enrich.py, and text_associate.py in the pipeline package integrate OCR output into the reference catalog and the final timeline.
- The OCR path appears to combine standard OCR with an optional visual-language model client for harder cases.
8. Aggregation and association
- aggregator.py, camera_merge.py, camera_assignment.py, and text_associate.py are the “join” layer of the system.
- They merge scene, camera, appearance, and OCR outputs into camera-specific text events.
- Final deliverables like aggregated_complete.csv, aggregated_partial.csv, dropped_text.csv, and pipeline_summary.json come from this layer.
9. Interactive visualization subsystem
- src/broadcast_pipeline/viz/ plus static/timeline_viz/ provide the browser-based timeline viewer.
- The viewer supports timeline search, frame previews, camera collages, and camera comparison.
- scripts/serve_timeline_viz.py runs this locally, while docker/viz/ packages the same UI for deployment.
10. Infrastructure and deployment
- docker/viz/ contains a containerized viz service with prewarming and export scripts.
- cloudbuild.yaml suggests Google Cloud Build / Cloud Run deployment for the visualization app.
- The live demo URL in the README confirms this is an externally hosted, data-baked UI rather than only a local tool.
11. Acceleration and environment support
- src/accelerator/ abstracts device/runtime selection, with tests around device behavior.
- The README distinguishes CPU-only vs GPU installs, so hardware capability affects performance and some stage choices.
- pyproject.toml and the extras mentioned in the README indicate the repo is designed for optional feature-based installs.
12. Supporting assets and third-party code
- third_party/tennis_court_detector/ is vendored court-detection logic used by homography/court mapping workflows.
- models/, graphify-out/, and the scripts in scripts/ support training, evaluation, benchmarking, downloads, and ad hoc analysis.
- Tests are organized to mirror the main subsystem boundaries, which reinforces the architecture: pipeline, camera assignment, appearance, OCR, accelerator, and viz.
Main entry points: orchestrator.py Orchestrator · camera_assignment.py Camera assign · aggregator.py Aggregator · extractor.py Appearance
Components 29
Pipeline core
Resumable batch pipeline, stage coordination, artifacts, and shared runtime concerns.
- main.py · Batch entrypoint for running the broadcast pipeline end to end.
main.py - Orchestrator · Coordinates resumable stage execution and step boundaries.
src/broadcast_pipeline/orchestrator.py - Config · Pipeline configuration and run-time options.
src/broadcast_pipeline/config.py - Artifacts · Reads and writes pipeline outputs and intermediate datasets.
src/broadcast_pipeline/artifacts.py - Progress · Progress reporting and stage status tracking.
src/broadcast_pipeline/progress.py - Preflight · Input validation and environment readiness checks.
src/broadcast_pipeline/preflight.py - Video meta · Video-level metadata extraction used before scene processing.
src/broadcast_pipeline/video_meta.py - Scenes I/O · Scene persistence and loading for downstream stages.
src/broadcast_pipeline/scenes_io.py - Scene extract · Derives temporal scene units from the source video.
src/broadcast_pipeline/scene_extractor.py - Scene filter · Filters and refines extracted scenes for later stages.
src/broadcast_pipeline/scene_filter.py - Aggregator · Produces final aggregated CSV and JSON outputs.
src/broadcast_pipeline/aggregator.py
Camera assignment
Subsystems that classify and validate broadcast camera identity.
- Camera assign · Coordinates camera identity assignment across scene outputs.
src/broadcast_pipeline/camera_assignment.py - Camera merge · Merges camera-specific outputs into unified camera timelines.
src/broadcast_pipeline/camera_merge.py - Embed cluster · Embedding-based clustering approach for grouping similar camera shots.
src/camera_assignemnt/embedding_cluster/pipeline.py - Homography · Court geometry and projection-based validation for camera assignment.
src/camera_assignemnt/homography/homography_estimator.py - Scene classifier · Scene-type classifier used as a camera assignment signal.
src/camera_assignemnt/scene_classifier/classifier.py
Person appearance
Extraction of person-level visual signatures and linking.
- Appearance · Person segmentation and visual signature extraction.
src/person_appearance/extractor.py - Signatures · Builds and links person-level appearance signatures.
src/person_appearance/signature.py
OCR and text
Text extraction, cleanup, enrichment, and association.
- OCR runner · Runs OCR over scenes and collects text observations.
src/broadcast_pipeline/ocr_runner.py - Scene OCR · OCR extraction, geometry normalization, readability, and presence logic.
src/scene_ocr/extractor.py - Text ref · Builds the reference catalog for detected text entries.
src/broadcast_pipeline/text_reference.py - Text enrich · Adds structure and metadata to OCR text records.
src/broadcast_pipeline/text_enrich.py - Text associate · Associates text events with cameras and scenes.
src/broadcast_pipeline/text_associate.py
Timeline viz
Browser viewer and its serving/deployment stack.
- Viz server · Serves the interactive timeline viewer and data APIs.
src/broadcast_pipeline/viz/server.py - Timeline UI · Browser-based timeline viewer for search, previews, collages, and camera comparison.
static/timeline_viz/app.js - Viz deploy · Containerized viewer packaging and cloud build deployment.
docker/viz/Dockerfile
Support systems
Acceleration, vendored models, and external court geometry helpers.
- Accelerator · Device and runtime selection for CPU/GPU execution.
src/accelerator/device.py - Court detector · Vendored court detection and homography helpers used by camera workflows.
third_party/tennis_court_detector/homography.py - YOLO seg model · Bundled segmentation model used by person appearance extraction.
yolo11n-seg.onnx
Connections 30
- main.py → Preflight: starts with · Entry point validates inputs and environment before running stages.
- main.py → Orchestrator: invokes · Main hands control to the resumable pipeline coordinator.
- Orchestrator → Config: reads · Pipeline execution is driven by configuration.
- Orchestrator → Progress: tracks · Stage execution reports progress and status.
- Orchestrator → Artifacts: persists · Orchestrator manages intermediate and final artifacts.
- Orchestrator → Video meta: stage · Initial metadata extraction feeds scene processing.
- Orchestrator → Scene extract: stage · Extracts temporal scene units from video.
- Scene extract → Scene filter: feeds · Raw scenes are filtered before downstream use.
- Scene filter → Scenes I/O: writes · Filtered scenes are stored for later stages.
- Scenes I/O → Camera assign: loads · Camera assignment consumes scene-level inputs.
- Camera assign → Embed cluster: uses · One branch groups shots by embedding similarity.
- Camera assign → Homography: uses · One branch validates assignment with court geometry.
- Camera assign → Scene classifier: uses · One branch predicts camera/shot type from scene content.
- Camera assign → Camera merge: produces · Assignment outputs are merged into camera timelines.
- Orchestrator → Appearance: stage · Person appearance processing runs as a major pipeline stage.
- Appearance → Signatures: builds · Visual features are turned into signatures and links.
- Appearance → YOLO seg model: uses · Segmentation depends on the bundled YOLO model asset.
- Orchestrator → OCR runner: stage · OCR stage is orchestrated from the pipeline controller.
- OCR runner → Scene OCR: delegates · OCR runner invokes the scene OCR subsystem.
- Scene OCR → Text ref: feeds · Detected text is organized into a reference catalog.
- Text ref → Text enrich: enriches · Reference text is expanded with derived structure.
- Text enrich → Text associate: associates · Enriched text is linked to cameras and scenes.
- Text associate → Aggregator: joins into · Associated text becomes part of the final aggregation.
- Camera merge → Aggregator: joins into · Merged camera outputs are consumed by aggregation.
- Orchestrator → Aggregator: finalizes · Aggregator produces the end-of-pipeline deliverables.
- Aggregator → Viz server: serves · Aggregated outputs back the interactive viewer.
- Viz server → Timeline UI: renders · Backend serves the browser timeline UI.
- Viz server → Viz deploy: deploys via · Viewer can be packaged and deployed as a containerized service.
- Orchestrator → Accelerator: selects runtime · Pipeline stages can use CPU or GPU acceleration.
- Homography → Court detector: uses · Homography workflows depend on vendored court-detection helpers.