How benpw506/auto-steel-tip-darts-scorer works
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.