# sahilnayak7702/football-analysis-computervision architecture

> Architecture diagram of the GitHub repository sahilnayak7702/football-analysis-computervision, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sahilnayak7702/football-analysis-computervision
- Repository: https://github.com/sahilnayak7702/football-analysis-computervision

## Overview

##### Project Type and Purpose
- This is a standalone, command-line computer-vision pipeline for football match analysis. It ingest videos, runs object detection (players, referees, ball), tracks all objects, computes metrics (speed, distance, team IDs), compensates for camera motion and perspective, and writes an annotated output video.

##### Main Architectural Components
a. Video I/O & Preprocessing
- Component: Input Video Manager (utils/video_utils.py)
- Reads raw video frames and forwards them downstream.
b. Perspective & Camera Compensation
- Component: View Transformer (view_transformer/view_transformer.py)
- Applies homography/perspective transform to normalize field view.
- Uses precomputed camera motion stubs (stubs/camera_movement_stub.pkl) and optical-flow.
c. Object Detection Engine
- Component: YOLO Inference (yolo_inference.py)
- Loads YOLOv8 weights (yolov8x.pt or training/*.pt).
d. Tracking
- Component: Tracker (trackers/tracker.py)
- Uses Kalman filtering and association logic to maintain object tracks over time.
- Optionally uses stubs/track_stubs.pkl to warm-start or replay.
e. Assigners & Classification
- Player & Ball Assigner (player_ball_assigner/player_ball_assigner.py): distinguishes ball from players and referees.
f. Metric Computation
- Speed & Distance Estimator (speed_and_distance_estimator/speed_and_distance_estimator.py): computes instantaneous speed and total distance per track.
g. Output Rendering

##### Data & Model Resources
- models/best.pt, models/last.pt: pretrained detection weights.
- stubs/*.pkl: serialized camera/track data for offline testing or warm-start.
- training/…: YOLOv5 training datasets and notebooks (not part of runtime but useful for retraining).

##### Relationships & Data Flow
1. Input Video → Video I/O
2. → Perspective Transformer → Camera Motion Estimator
3. → YOLO Inference → Tracker
4. Tracker → Player & Ball Assigner
5. → Team Assigner → Speed & Distance Estimator
6. → Output Rendering → Annotated Video file

##### Architectural Patterns & Principles
- Pipeline / data-flow architecture: each module consumes frames or track data and emits enriched data.
- Modular separation: detection, tracking, assignment, estimation, rendering each live in its own package.
- Reusability: utils contains shared helpers (bbox_utils, video_utils).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Runtime Pipeline"
        Main["Main Orchestrator (CLI)"]:::io
        InputVideo["Input Video Manager"]:::io
        VTrans["View Transformer"]:::core
        CameraStub["Camera Motion Stub"]:::resource
        YOLO["YOLO Inference Engine"]:::core
        YOLOModel["YOLO Model Weights (yolov8x.pt)"]:::resource
        PreW1["Pretrained Weights (models/best.pt)"]:::resource
        PreW2["Pretrained Weights (models/last.pt)"]:::resource
        Tracker["Tracker"]:::core
        TrackingStub["Tracking Stub"]:::resource
        PBall["Player & Ball Assigner"]:::core
        Team["Team Assigner"]:::core
        SD["Speed & Distance Estimator"]:::core
        Annotator["Video Annotator & Writer"]:::io
        Output["Annotated Video Output"]:::io

        Main -->|runs| InputVideo
        InputVideo -->|frames| VTrans
        CameraStub --> VTrans
        VTrans -->|corrected frames| YOLO
        YOLOModel --> YOLO
        PreW1 --> YOLO
        PreW2 --> YOLO
        YOLO -->|detections| Tracker
        TrackingStub --> Tracker
        Tracker -->|tracks| PBall
        PBall -->|labeled objects| Team
        Team -->|clustered teams| SD
        SD -->|metrics| Annotator
        Annotator -->|writes| Output
    end

    subgraph "Shared Helpers"
        BBoxUtilsFile["Bounding-Box Utilities"]:::helpers
    end

    subgraph "Training Pipeline"
        TrainData["Training Data & Notebooks"]:::resource
        TrainNB["Training Notebooks (*.ipynb)"]:::resource
        TrainData --> YOLO
        TrainNB --> YOLO
    end

    %% Click Events
    click Main "https://github.com/sahilnayak7702/football-analysis-computervision/blob/main/main.py"
    click InputVideo "https://github.com/sahilnayak7702/football-analysis-computervision/blob/main/utils/video_utils.py"
    click VTrans "https://github.com/sahilnayak7702/football-analysis-computervision/blob/main/view_transformer/view_transformer.py"
    click CameraStub "https://github.com/sahilnayak7702/football-analysis-computervision/blob/main/stubs/camera_movement_stub.pkl"
    click YOLO "https://github.com/sahilnayak7702/football-analysis-computervision/blob/main/yolo_inference.py"
    click YOLOModel "https://github.com/sahilnayak7702/football-analysis-computervision/blob/main/yolov8x.pt"
    click PreW1 "https://github.com/sahilnayak7702/football-analysis-computervision/blob/main/models/best.pt"
    click PreW2 "https://github.com/sahilnayak7702/football-analysis-computervision/blob/main/models/last.pt"
    click Tracker "https://github.com/sahilnayak7702/football-analysis-computervision/blob/main/trackers/tracker.py"
    click TrackingStub "https://github.com/sahilnayak7702/football-analysis-computervision/blob/main/stubs/track_stubs.pkl"
    click PBall "https://github.com/sahilnayak7702/football-analysis-computervision/blob/main/player_ball_assigner/player_ball_assigner.py"
    click Team "https://github.com/sahilnayak7702/football-analysis-computervision/blob/main/team_assigner/team_assigner.py"
    click SD "https://github.com/sahilnayak7702/football-analysis-computervision/blob/main/speed_and_distance_estimator/speed_and_distance_estimator.py"
    click BBoxUtilsFile "https://github.com/sahilnayak7702/football-analysis-computervision/blob/main/utils/bbox_utils.py"
    click TrainData "https://github.com/sahilnayak7702/football-analysis-computervision/tree/main/training/football-players-detection-1"
    click TrainNB "https://github.com/sahilnayak7702/football-analysis-computervision/blob/main/training/*.ipynb"

    %% Styles
    classDef io fill:#D0E6FF,stroke:#000,stroke-width:1px
    classDef core fill:#D0FFD6,stroke:#000,stroke-width:1px
    classDef resource fill:#FFE6B3,stroke:#000,stroke-width:1px
    classDef helpers fill:#E6F0FF,stroke:#000,stroke-width:1px
```
