# aaditya29/dfl---bundesliga-data-shootout-analysis architecture

> Architecture diagram of the GitHub repository aaditya29/dfl---bundesliga-data-shootout-analysis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aaditya29/dfl---bundesliga-data-shootout-analysis
- Repository: https://github.com/aaditya29/dfl---bundesliga-data-shootout-analysis

## Overview

##### Project Type and Purpose
- This is a Python-based computer-vision pipeline for sports analytics (specifically soccer) that ingests video, runs object detection using YOLO, tracks objects, computes metrics (speed, distance, camera motion), and outputs annotated video and data.
- The README confirms: “Detect players and ball in video,” “Track movement,” and “Perform analysis.”

##### File-Structure Analysis
- Top-level orchestrator:
- main.py – entry point driving the pipeline.
- yolo-inference.py – utilities to launch YOLO model inference.
- Model assets:
- models/*.pt – trained YOLO weights.
- yolov8s.pt – fallback YOLOv8 small weights.
- Modules (each a component in the pipeline):
- camera_movement_estimator/ – computes camera motion between frames.
- player_ball_assigner/ – attaches detection IDs to players vs ball.
- speed_and_distance_estimator/ – calculates movement metrics (speed, distance).
- team_assigner/ – assigns player detections to home/away teams.
- trackers/ – encapsulates multi-object tracker abstraction.
- view_transformer/ – maps image coordinates to pitch/world coordinates.
- utils/ – helper functions (bbox_utils.py, video_utils.py).
- Data directories:
- input-videos/ – source video files.
- output_videos/ – annotated output.
- runs/detect/ – YOLO’s per-run inference outputs.
- Training:
- training/… – YOLO dataset structure for retraining.

##### Extracted Architecture
- Core pipeline sequence:
Input Video → YOLO Detector → Tracker → Post-Processing & Assignment → Estimators → View Transformer → Output Video & Data.
- External dependencies: OpenCV for frame handling, Ultralytics/YOLO for detection, NumPy/Pandas for data arrays, Matplotlib for plotting, Supervision for annotation.

a. Main Components
- Video Input (input-videos/)
- YOLO Detector (yolo-inference.py + models/*.pt)
- Tracker (trackers/tracker.py)
- Assignment Modules:
- player_ball_assigner
- team_assigner
- Estimators:
- camera_movement_estimator
- speed_and_distance_estimator
- Coordinate Mapper (view_transformer)
- Video/Data Output (output_videos/, CSV, logs)
- Utilities (utils/*.py)
b. Interactions
1. main.py reads raw frames.
3. Tracker ingests detections + previous states → outputs track IDs.
4. Assigners tag each detection as “ball” or “player” and team.
5. Camera Movement Estimator computes global motion from successive frames.
6. Speed & Distance Estimator uses tracked positions + camera motion to compute metrics.
7. View Transformer converts pixel positions to real-world/pitch coordinates.
8. Annotated frames & data streams are written to output.
c. Architectural Patterns
- Modular pipeline: each stage isolated in its own package.
- Single Responsibility per module (detection, tracking, assignment, estimation, transformation).
- Orchestration in main.py using sequential data flow.
d. Technology Stack
- Python 3.x, OpenCV, NumPy, Pandas, Matplotlib
- YOLO (Ultralytics YOLOv5/YOLOv8)
- Supervision (optional annotation library)
- Custom modules for each processing stage.

##### Essential Details
- Main.py at the center or top as orchestrator.
- How YOLO model weights feed into the detection component.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Sources
    subgraph "Data Sources"
        direction TB
        Input["Video Input\n(input-videos/)"]:::data
        Models["YOLO Weights"]:::data
        Runs["YOLO Runs\n(runs/detect/)"]:::data
    end

    %% Core Pipeline
    subgraph "Core Pipeline"
        direction TB
        Main["main.py"]:::orchestrator
        Detection["YOLO Detector\n(yolo-inference.py)"]:::core
        Tracker["Multi-Object Tracker\n(trackers/tracker.py)"]:::core
    end

    %% Post-Processing
    subgraph "Post-Processing"
        direction TB
        PBA["Player vs Ball Assigner\n(player_ball_assigner/)"]:::core
        TA["Team Assigner\n(team_assigner/)"]:::core
        CME["Camera Movement Estimator\n(camera_movement_estimator/)"]:::core
        SDE["Speed & Distance Estimator\n(speed_and_distance_estimator/)"]:::core
    end

    %% Transformation
    View["View Transformer\n(view_transformer/)"]:::core

    %% Outputs
    subgraph "Outputs"
        direction TB
        OutputVid["Annotated Video\n(output_videos/)"]:::data
        OutputData["Metrics CSV & Logs"]:::data
    end

    %% Utilities & Ancillary
    subgraph "Utilities & Training"
        direction TB
        Utils["Utilities\n(utils/)"]:::util
        BBoxUtil["bbox_utils.py"]:::util
        VideoUtil["video_utils.py"]:::util
        Training["Training Data\n(training/football-players-detection-1/)"]:::util
        Notebook["Color Assignment Notebook\n(development_and_analysis/color_assignement.ipynb)"]:::util
        StubsCM["camera_movement_stub.pkl"]:::util
        StubsTR["track_stubs.pkl"]:::util
        Readme["README.md"]:::util
    end

    %% Dependencies and Flow
    Input -->|frames| Main
    Main -->|invokes| Detection
    Models -->|weights| Detection
    Detection -->|detections + bboxes| Tracker
    Tracker -->|tracks| PBA
    PBA -->|labeled detections| TA
    TA -->|team tags| CME
    CME -->|motion data| SDE
    SDE -->|speed & distance| View
    View -->|mapped coords| OutputVid
    View -->|data| OutputData
    Detection -->|run outputs| Runs
    Main -->|orchestrates| Utils
    Utils -->|helpers| Detection
    Utils -->|helpers| Tracker
    Utils -->|helpers| PBA
    Utils -->|helpers| TA
    Utils -->|helpers| CME
    Utils -->|helpers| SDE
    Utils -->|helpers| View

    %% Click events
    click Main "https://github.com/aaditya29/dfl---bundesliga-data-shootout-analysis/blob/main/main.py"
    click Detection "https://github.com/aaditya29/dfl---bundesliga-data-shootout-analysis/blob/main/yolo-inference.py"
    click Models "https://github.com/aaditya29/dfl---bundesliga-data-shootout-analysis/blob/main/models/best.pt"
    click Models "https://github.com/aaditya29/dfl---bundesliga-data-shootout-analysis/blob/main/models/last.pt"
    click Models "https://github.com/aaditya29/dfl---bundesliga-data-shootout-analysis/blob/main/yolov8s.pt"
    click Input "https://github.com/aaditya29/dfl---bundesliga-data-shootout-analysis/tree/main/input-videos/"
    click Runs "https://github.com/aaditya29/dfl---bundesliga-data-shootout-analysis/tree/main/runs/detect/"
    click OutputVid "https://github.com/aaditya29/dfl---bundesliga-data-shootout-analysis/blob/main/output_videos/output_video.avi"
    click CME "https://github.com/aaditya29/dfl---bundesliga-data-shootout-analysis/tree/main/camera_movement_estimator/"
    click CME "https://github.com/aaditya29/dfl---bundesliga-data-shootout-analysis/blob/main/camera_movement_estimator/camera_movement_estimator.py"
    click PBA "https://github.com/aaditya29/dfl---bundesliga-data-shootout-analysis/tree/main/player_ball_assigner/"
    click PBA "https://github.com/aaditya29/dfl---bundesliga-data-shootout-analysis/blob/main/player_ball_assigner/player_ball_assigner.py"
    click SDE "https://github.com/aaditya29/dfl---bundesliga-data-shootout-analysis/tree/main/speed_and_distance_estimator/"
    click SDE "https://github.com/aaditya29/dfl---bundesliga-data-shootout-analysis/blob/main/speed_and_distance_estimator/speed_and_distance_estimator.py"
    click TA "https://github.com/aaditya29/dfl---bundesliga-data-shootout-analysis/tree/main/team_assigner/"
    click TA "https://github.com/aaditya29/dfl---bundesliga-data-shootout-analysis/blob/main/team_assigner/team_assigner.py"
    click Tracker "https://github.com/aaditya29/dfl---bundesliga-data-shootout-analysis/blob/main/trackers/tracker.py"
    click View "https://github.com/aaditya29/dfl---bundesliga-data-shootout-analysis/blob/main/view_transformer/view_transformer.py"
    click Utils "https://github.com/aaditya29/dfl---bundesliga-data-shootout-analysis/tree/main/utils/"
    click BBoxUtil "https://github.com/aaditya29/dfl---bundesliga-data-shootout-analysis/blob/main/utils/bbox_utils.py"
    click VideoUtil "https://github.com/aaditya29/dfl---bundesliga-data-shootout-analysis/blob/main/utils/video_utils.py"
    click Training "https://github.com/aaditya29/dfl---bundesliga-data-shootout-analysis/tree/main/training/football-players-detection-1/"
    click Notebook "https://github.com/aaditya29/dfl---bundesliga-data-shootout-analysis/blob/main/development_and_analysis/color_assignement.ipynb"
    click StubsCM "https://github.com/aaditya29/dfl---bundesliga-data-shootout-analysis/blob/main/stubs/camera_movement_stub.pkl"
    click StubsTR "https://github.com/aaditya29/dfl---bundesliga-data-shootout-analysis/blob/main/stubs/track_stubs.pkl"
    click Readme "https://github.com/aaditya29/dfl---bundesliga-data-shootout-analysis/blob/main/readme.md"

    %% Styles
    classDef data fill:#a8d5ba,stroke:#333,stroke-width:1px
    classDef core fill:#9ec5fe,stroke:#333,stroke-width:1px
    classDef util fill:#feb2a8,stroke:#333,stroke-width:1px
    classDef orchestrator fill:#d3d3d3,stroke:#333,stroke-width:1px
```
