# toannguyenkhanh/badminton-analysis architecture

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

- Interactive diagram: https://gitdiagram.com/toannguyenkhanh/badminton-analysis
- Repository: https://github.com/toannguyenkhanh/badminton-analysis

## Overview

##### Project Type and Purpose
- The README clearly states that this is a computer vision project aimed at detecting badminton players and shuttlecocks during matches.
- Core functionality includes data preparation, training models for detection (using pretrained YOLO weights), and then using these models to analyze videos/images.
- The project is not a web service but a data processing and machine vision application with distinct training, detection, and tracking modules.

##### File Structure to Identify Main Components
a. Core Scripts and Entry Points
- main.py: Likely the primary entry for running analysis on videos or images.
- dataset.py and open_image.py: Utility scripts for handling datasets and image inputs.
- test_open_image.py: For unit testing image processing functions.

b. Tracking Module
- The tracker directory contains modules (player_tracker.py and shuttle_tracker.py) that likely encapsulate the logic for tracking the detected objects across frames.

c. Training Pipeline
- The train directory houses the training scripts and models:
- train.py as the driver for training.
- Separate directories for player_output and shuttle_output, each with model configuration files (args.yaml), event logs, results.csv, and model weights (best.pt, last.pt).
- Pretrained YOLO models (yolov8n.pt and yolov8s.pt) are also included here.

d. Utility Functions
- The utils directory includes video_utils.py, which is probably responsible for video processing tasks such as frame extraction, video writing, etc.

e. Miscellaneous
- The last_detect directory containing pkl files suggests that previous detection results might be cached or used for incremental processing.

##### Architectural Patterns & Relationships
- Input: Video/images (as indicated by dataset preparation and open_image.py).
- Preprocessing: dataset.py and video_utils.py for input handling.
- Model Inference: main.py likely coordinates the use of trained models to perform detection.
- Tracking: Tracker modules (player_tracker.py and shuttle_tracker.py) analyze detection output across frames.
- Training: train/train.py and related subdirectories manage model training and configuration.

##### Technology & Frameworks Highlighted
- Computer vision algorithms, particularly those related to object detection (YOLO models are used).
- Python as the primary programming language.
- YAML configuration files (args.yaml) that indicate customizable model parameters.
- Logging and results tracking for training (events.out.tfevents and results.csv).

##### Elements
- A “Preprocessing & Data Handling” component where dataset.py and utils/video_utils.py reside.
- A “Tracking Module” that directly interacts with the detection output (tracker/player_tracker.py, tracker/shuttle_tracker.py).
- An “Output/Results” component showcasing results such as the output video (output_video.mp4) and stored detection results (in last_detect and train outputs).

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Input Data"]:::input

    subgraph "Preprocessing & Data Handling"
        B1["dataset.py"]:::data
        B2["open_image.py"]:::data
        B3["test_open_image.py"]:::data
        B4["video_utils.py"]:::data
    end

    C["main.py (Inference)"]:::inference

    subgraph "Tracking Module"
        D1["player_tracker.py"]:::tracking
        D2["shuttle_tracker.py"]:::tracking
    end

    E["Cached Detections (last_detect)"]:::output

    subgraph "Training Pipeline"
        F1["train.py"]:::training
        F2["Player Output"]:::training
        F3["Shuttle Output"]:::training
        F4["yolov8n.pt"]:::training
        F5["yolov8s.pt"]:::training
    end

    A --> B1
    B1 --> B2
    B2 --> B3
    B3 --> B4
    B4 --> C
    C --> D1
    C --> D2
    D1 --> E
    D2 --> E
    F1 -.-> C

    click B1 "https://github.com/toannguyenkhanh/badminton-analysis/blob/main/dataset.py"
    click B2 "https://github.com/toannguyenkhanh/badminton-analysis/blob/main/open_image.py"
    click B3 "https://github.com/toannguyenkhanh/badminton-analysis/blob/main/test_open_image.py"
    click B4 "https://github.com/toannguyenkhanh/badminton-analysis/blob/main/utils/video_utils.py"
    click C "https://github.com/toannguyenkhanh/badminton-analysis/blob/main/main.py"
    click D1 "https://github.com/toannguyenkhanh/badminton-analysis/blob/main/tracker/player_tracker.py"
    click D2 "https://github.com/toannguyenkhanh/badminton-analysis/blob/main/tracker/shuttle_tracker.py"
    click F1 "https://github.com/toannguyenkhanh/badminton-analysis/blob/main/train/train.py"
    click F2 "https://github.com/toannguyenkhanh/badminton-analysis/tree/main/train/player_output"
    click F3 "https://github.com/toannguyenkhanh/badminton-analysis/tree/main/train/shuttle_output"
    click F4 "https://github.com/toannguyenkhanh/badminton-analysis/blob/main/train/yolov8n.pt"
    click F5 "https://github.com/toannguyenkhanh/badminton-analysis/blob/main/train/yolov8s.pt"
    click E "https://github.com/toannguyenkhanh/badminton-analysis/tree/main/last_detect"

    classDef input fill:#a2d5f2,stroke:#333,stroke-width:2px;
    classDef data fill:#f7e1a0,stroke:#333,stroke-width:2px;
    classDef inference fill:#c2f0c2,stroke:#333,stroke-width:2px;
    classDef tracking fill:#f2a2e8,stroke:#333,stroke-width:2px;
    classDef training fill:#d5a6bd,stroke:#333,stroke-width:2px;
    classDef output fill:#e0e4cc,stroke:#333,stroke-width:2px;
```
