# benpw506/auto-steel-tip-darts-scorer architecture

> Architecture diagram of the GitHub repository benpw506/auto-steel-tip-darts-scorer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/benpw506/auto-steel-tip-darts-scorer
- Repository: https://github.com/benpw506/auto-steel-tip-darts-scorer

## Overview

##### Project Type & Purpose
- This is a full-stack application with dual concerns:
- The “Application” segment implements the core darts scoring system, incorporating game logic (rules, scoring, bust and checkout conditions) along with a graphical interface.
- The “Training” segment handles the model-creation pipeline. It involves dataset preparation, image preprocessing (cropping, labeling via annotate.py), model training, and subsequent prediction using a YOLO v4 network retrained on a custom darts/dartboard dataset.
- The README explains that the project automatically scores a regulation darts match using a single webcam, integrating live image observation with the trained model to detect game events.

##### Analyzing the File Structure
- Top-level directories:
- Application/: Contains core code for the game (e.g., GUI.py, board.py, darts.py, player.py).
- Training/: Contains scripts for preprocessing (combine_labels.py, crop_images.py), data handling (dataloader.py), dataset management (annotate.py, labels.pkl), model training (train.py, loss.py, utils.py), and prediction (predict.py). It also contains model checkpoints and saved weights inside the models/bw_darts folder as well as a YOLO model file (yolov4-tiny.h5).
- Other files: index.py serves as an entry point to run the scoring application. The requirements.txt and LICENSE.txt are standard support files.
- Architectural patterns:
- There is a separation between the production (scoring) code and the model training pipeline.
- Within the Application, an MVC-like setup can be inferred: the GUI, the game logic (rules in board.py and darts.py), and data models for players (player.py).

##### Core Components
a. Application Components:
- GUI Module (GUI.py): Handles user interfacing and visual feedback.
- Game Logic (board.py, darts.py, player.py): Manages the state of the game, scoring rules (including busts and checkouts), and tracking score updates.
- Controller/Entrypoint (index.py): Initiates the application runtime, starting the game scoring process.
- External Camera Feed: Represents the single webcam (e.g., Logitech C920) capturing live video of the dartboard.
- YOLO Model Integration: Although the model file is part of the Training output, its inference is integrated into the scoring application to detect dart hits and board positions.

b. Training Pipeline Components:
- Data Preparation:
- Dataset & Annotation (dataset folder, annotate.py, dummy_dataset.txt): For labeling images.
- Image Preprocessing (crop_images.py): Crops images to focus on key regions.
- Configuration (Training/configs, bw_darts.yaml): Defines settings for training.
- Model Training & Evaluation:
- Training Script (train.py) and Loss Calculation (loss.py): Core training engine.
- Model Checkpointing and Results (models/bw_darts/checkpoint, history.pkl, results.pkl, weights files): Records training progress and final model state.
- Pre-trained Model File (yolov4-tiny.h5): Indicates experimentation with or use of another YOLO variant.
- Prediction:
- Prediction Script (predict.py): For running inference during development/testing.
- Utility functions (utils.py): Supports miscellaneous processes and pipeline cohesion.

##### Relationships & Data Flow
- For the Application:
- The webcam -> GUI -> Game Logic:
- The webcam provides a live video stream.
- The GUI module displays the feed and overlays information.
- The game logic processes model predictions to update scores as per darts rules.
- Integration with the YOLO Model:
- Either an internal module or external inference calls utilize the saved YOLO weights (from the Training branch) to detect darts and dartboard.
- For the Training Pipeline:
- Raw image dataset -> Annotation/Cropping -> Data Loader -> Model Training -> Model Checkpoints & Evaluation:
- The pipeline shows a clear sequential flow culminating in a trained model used by the Application.

##### Architectural Patterns & Principles
- Separation of Concerns: Distinct modules for UI/game logic versus model training.
- Pipeline Architecture: Training pipeline that transforms raw images through multiple stages.
- Integration of Machine Learning and Traditional Application Logic: Distinct boundaries where the scoring system “consumes” ML predictions.
- Reusability & Modularity: Files organized to support updating either the training components or the game interface independently.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Section
    subgraph "Application"
        AE("Application Entrypoint"):::app
        WI("Webcam Input"):::external
        GUI("GUI Module"):::app
        subgraph "Game Logic"
            BR("Board & Rules"):::app
            DM("Darts Mechanics"):::app
            PD("Player Data Models"):::app
        end
        YII("YOLO Inference Engine"):::app
    end

    %% Connections in Application
    AE --> GUI
    WI --> GUI
    GUI -->|"processes"| BR
    GUI -->|"processes"| DM
    GUI -->|"processes"| PD
    YII -->|"feeds"| BR
    YII -->|"feeds"| DM
    YII -->|"feeds"| PD

    %% Training Pipeline Section
    subgraph "Training Pipeline"
        %% Dataset Preparation Subgraph
        subgraph "Dataset Preparation"
            Ann("Annotation Script"):::train
            LS("Labels Storage"):::train
            DDR("Dummy Dataset Reference"):::train
        end
        IPM("Image Preprocessing Module"):::train
        Config("Configuration"):::train
        %% Model Training & Evaluation Subgraph
        subgraph "Model Training & Evaluation"
            TS("Training Script"):::train
            LC("Loss Calculation"):::train
            subgraph "Checkpointing & Results"
                CD("Checkpoint Directory"):::train
                TH("Training History"):::train
                RS("Results Storage"):::train
                WFData("Weights File (Data)"):::train
                WFIndex("Weights File (Index)"):::train
            end
        end
        YOLO("YOLO Model File"):::train
        PM("Prediction Module"):::train
        UF("Utility Functions"):::train
    end

    %% Sequential Flow in Training Pipeline
    DDR --> IPM
    IPM --> Config
    Config --> TS
    TS --> LC
    TS --> CD
    CD --> YOLO
    YOLO --> PM
    UF --> PM

    %% Integration from Training to Application
    YOLO -->|"provides model"| YII

    %% Styles
    classDef app fill:#a7c7e7,stroke:#333,stroke-width:1px;
    classDef train fill:#f9d29d,stroke:#333,stroke-width:1px;
    classDef external fill:#d0e1f9,stroke:#333,stroke-width:1px;

    %% Click Events for Application Components
    click AE "https://github.com/benpw506/auto-steel-tip-darts-scorer/blob/main/index.py"
    click GUI "https://github.com/benpw506/auto-steel-tip-darts-scorer/blob/main/Application/src/GUI.py"
    click BR "https://github.com/benpw506/auto-steel-tip-darts-scorer/blob/main/Application/src/board.py"
    click DM "https://github.com/benpw506/auto-steel-tip-darts-scorer/blob/main/Application/src/darts.py"
    click PD "https://github.com/benpw506/auto-steel-tip-darts-scorer/blob/main/Application/src/player.py"
    click YII "https://github.com/benpw506/auto-steel-tip-darts-scorer/blob/main/Training/models/yolov4-tiny.h5"

    %% Click Events for Training Pipeline Components
    click Ann "https://github.com/benpw506/auto-steel-tip-darts-scorer/blob/main/Training/dataset/annotate.py"
    click LS "https://github.com/benpw506/auto-steel-tip-darts-scorer/blob/main/Training/dataset/labels.pkl"
    click DDR "https://github.com/benpw506/auto-steel-tip-darts-scorer/blob/main/Training/dummy_dataset.txt"
    click IPM "https://github.com/benpw506/auto-steel-tip-darts-scorer/blob/main/Training/crop_images.py"
    click Config "https://github.com/benpw506/auto-steel-tip-darts-scorer/blob/main/Training/configs/bw_darts.yaml"
    click TS "https://github.com/benpw506/auto-steel-tip-darts-scorer/blob/main/Training/train.py"
    click LC "https://github.com/benpw506/auto-steel-tip-darts-scorer/blob/main/Training/loss.py"
    click CD "https://github.com/benpw506/auto-steel-tip-darts-scorer/tree/main/Training/models/bw_darts/checkpoint"
    click TH "https://github.com/benpw506/auto-steel-tip-darts-scorer/blob/main/Training/models/bw_darts/history.pkl"
    click RS "https://github.com/benpw506/auto-steel-tip-darts-scorer/blob/main/Training/models/bw_darts/results.pkl"
    click WFData "https://github.com/benpw506/auto-steel-tip-darts-scorer/blob/main/Training/models/bw_darts/weights.data-00000-of-00001"
    click WFIndex "https://github.com/benpw506/auto-steel-tip-darts-scorer/blob/main/Training/models/bw_darts/weights.index"
    click PM "https://github.com/benpw506/auto-steel-tip-darts-scorer/blob/main/Training/predict.py"
    click UF "https://github.com/benpw506/auto-steel-tip-darts-scorer/blob/main/Training/utils.py"
```
