# fdilmr/ml-football-analysis architecture

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

- Interactive diagram: https://gitdiagram.com/fdilmr/ml-football-analysis
- Repository: https://github.com/fdilmr/ml-football-analysis

## Overview

- Video Input & I/O: Represent the main entry point (main.py) which triggers the pipeline, along with video file sources and output (see examples/output.avi). Also capture FFmpeg-based processing under “utils/video_utils.py”.
- Object Detection & Inference: Include the “inference” folder where multiple YOLO-based Python scripts (yolo_inference.py, roboflow_inference.py, etc.) reside, indicating detection of players, ball, and referees. Note that this component leverages pre-trained YOLOv11 models via Ultralytics.
- camera_movement_estimator (for camera or frame movement estimation)
- trackers (for tracking objects across frames)
- speed_and_distance_estimator (for calculating the speed and distance metrics)
- Assignment & Analysis: Highlight components such as:
- player_ball_assigner (for ball possession and player-ball interactions)
- view_transformer (if used for perspective corrections or view-based modifications)
- Supporting Utilities & Data Handling: Represent the “utils” folder with utility modules (bbox_utils.py, video_utils.py) and note common libraries like OpenCV, NumPy, Pandas, and Matplotlib that aid in data manipulation and frame annotation.
- Training & Experimentation: Show a sub-component for model training and experiments (under the “training” folder and notebooks) that provides evaluation feedback and further fine-tuning.

##### Relationships and Data Flow
- From Tracking, flow to the Analysis components: player position estimation, ball interpolation, speed & distance computation, team assignment, and ball possession detection.

##### Architectural Patterns and Design Principles
- Modular design – each analytical capability (e.g., speed estimation, team assignment) is implemented in its own module to promote separation of concerns and extensibility.
- That the pipeline follows a sequential data-processing pattern: input handling → detection → tracking → analysis → visualization.
- How configuration files and notebooks (such as in “development_and_analysis” and “notebooks”) might be used to experiment and tune parameters outside of the core production pipeline.

##### Technologies, Frameworks, or Libraries
- Use of deep learning frameworks (PyTorch for training/inference).
- OpenCV for video processing and FFmpeg for input/output handling.
- Use YOLOv11 (via Ultralytics and Roboflow) in the detection module.
- Reference peripheral libraries like NumPy, Pandas, and Matplotlib that enable calculations and visualization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Video Input & I/O
    subgraph "Video Input & I/O"
        main["main.py"]:::video
        videoInput["Video File Input"]:::video
        videoUtil["FFmpeg Processing (video_utils.py)"]:::utility
        outputVideo["Output Video (examples/output.avi)"]:::video
    end

    %% Object Detection & Inference
    subgraph "Object Detection & Inference"
        yolo["YOLO Inference (yolo_inference.py)"]:::inference
        roboflow1["Roboflow Inference (roboflow_inference.py)"]:::inference
        roboflow2["Roboflow Inference2 (roboflow_inference2.py)"]:::inference
        results["Detection Results (video_results.json)"]:::inference
    end

    %% Tracking & Estimation Modules
    subgraph "Tracking & Estimation Modules"
        camera["Camera Movement Estimator"]:::tracking
        tracker["Object Tracker"]:::tracking
        speed["Speed & Distance Estimator"]:::tracking
        trackingData["Aggregated Tracking Data"]:::tracking
    end

    %% Assignment & Analysis
    subgraph "Assignment & Analysis"
        team["Team Assigner"]:::analysis
        player["Player Ball Assigner"]:::analysis
        view["View Transformer"]:::analysis
    end

    %% Visualization
    subgraph "Visualization"
        vis["Video Visualization & Annotations"]:::visualization
    end

    %% Supporting Utilities & Data Handling
    subgraph "Supporting Utilities & Data Handling"
        bbox["BBox Utils (bbox_utils.py)"]:::utility
        videoUtilsUtil["Video Utils (video_utils.py)"]:::utility
    end

    %% Training & Experimentation (Feedback Loop)
    subgraph "Training & Experimentation (Feedback Loop)"
        training["Training Module"]:::training
        experimentation["Experimentation Notebooks"]:::training
    end

    %% Data Flow Connections
    %% Video Input Flow
    main --> videoInput
    videoInput --> videoUtil
    videoUtil --> yolo
    videoUtil --> roboflow1
    videoUtil --> roboflow2
    main --> outputVideo

    %% Inference Aggregation
    yolo --> results
    roboflow1 --> results
    roboflow2 --> results
    results --> trackingData

    %% Tracking & Estimation Flow
    trackingData --> camera
    trackingData --> tracker
    trackingData --> speed

    %% Aggregate outputs from tracking modules back into Tracking Data
    camera --> trackingData
    tracker --> trackingData
    speed --> trackingData

    %% Flow from Tracking to Analysis
    trackingData --> team
    trackingData --> player
    trackingData --> view

    %% Analysis to Visualization
    team --> vis
    player --> vis
    view --> vis

    %% Utilities Connections (used by Inference and elsewhere)
    yolo --> bbox
    roboflow1 --> bbox
    roboflow2 --> bbox
    videoUtil --- videoUtilsUtil

    %% Training/Experimentation influence (feedback/tuning)
    training --- main
    training --- yolo
    training --- team
    experimentation --- main
    experimentation --- yolo
    experimentation --- team

    %% Click Events
    click main "https://github.com/fdilmr/ml-football-analysis/blob/main/main.py"
    click outputVideo "https://github.com/fdilmr/ml-football-analysis/blob/main/examples/output.avi"
    click videoUtil "https://github.com/fdilmr/ml-football-analysis/blob/main/utils/video_utils.py"
    click yolo "https://github.com/fdilmr/ml-football-analysis/blob/main/inference/yolo_inference.py"
    click roboflow1 "https://github.com/fdilmr/ml-football-analysis/blob/main/inference/roboflow_inference.py"
    click roboflow2 "https://github.com/fdilmr/ml-football-analysis/blob/main/inference/roboflow_inference2.py"
    click results "https://github.com/fdilmr/ml-football-analysis/blob/main/inference/video_results.json"
    click camera "https://github.com/fdilmr/ml-football-analysis/blob/main/camera_movement_estimator/camera_movement_estimator.py"
    click tracker "https://github.com/fdilmr/ml-football-analysis/blob/main/trackers/tracker.py"
    click speed "https://github.com/fdilmr/ml-football-analysis/blob/main/speed_and_distance_estimator/speed_and_distance_estimator.py"
    click team "https://github.com/fdilmr/ml-football-analysis/blob/main/team_assigner/team_assigner.py"
    click player "https://github.com/fdilmr/ml-football-analysis/blob/main/player_ball_assigner/player_ball_assigner.py"
    click view "https://github.com/fdilmr/ml-football-analysis/blob/main/view_transformer/view_transformer.py"
    click bbox "https://github.com/fdilmr/ml-football-analysis/blob/main/utils/bbox_utils.py"
    click videoUtilsUtil "https://github.com/fdilmr/ml-football-analysis/blob/main/utils/video_utils.py"
    click training "https://github.com/fdilmr/ml-football-analysis/blob/main/training/06_02_TrainingResults/args.yaml"
    click training "https://github.com/fdilmr/ml-football-analysis/blob/main/training/06_02_TrainingResults/events.out.tfevents.1738798552.6e33be6bc1b2.2213.0"
    click training "https://github.com/fdilmr/ml-football-analysis/blob/main/training/06_02_TrainingResults/results.csv"
    click experimentation "https://github.com/fdilmr/ml-football-analysis/blob/main/development_and_analysis/color_assignment.ipynb"
    click experimentation "https://github.com/fdilmr/ml-football-analysis/blob/main/notebooks/football-ai.ipynb"

    %% Styles
    classDef video fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef inference fill:#c8e6c9,stroke:#1b5e20,stroke-width:2px;
    classDef tracking fill:#fff9c4,stroke:#f57f17,stroke-width:2px;
    classDef analysis fill:#ffe0b2,stroke:#e65100,stroke-width:2px;
    classDef visualization fill:#d1c4e9,stroke:#4a148c,stroke-width:2px;
    classDef utility fill:#eeeeee,stroke:#9e9e9e,stroke-dasharray: 5 5,stroke-width:2px;
    classDef training fill:#f8bbd0,stroke:#880e4f,stroke-width:2px;
```
