# sproc01/8ballpool architecture

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

- Interactive diagram: https://gitdiagram.com/sproc01/8ballpool
- Repository: https://github.com/sproc01/8ballpool

## Overview

##### Main Components
- Input/Video Loader:
- Receives a video file path via command-line input.
- Responsible for reading the video and splitting it into frames.
- Preprocessing Pipeline:
- Manages frame extraction and any necessary pre-processing before analysis.
- Core Vision Modules:
- Detection Module (implemented in detection.cpp / detection.h): detects balls or objects on the pool table.
- Segmentation Module (segmentation.cpp / segmentation.h): performs segmentation of table regions, balls, etc.
- Table & Minimap Module (table.cpp, tableOrientation.cpp, minimap.h): analyzes table orientation and builds a minimap visualization.
- Tracking Module (tracking.cpp / tracking.h): tracks detected objects across frames.
- Performance & Metrics Engine:
- ComputePerformance, TestAllClip, and ShowSegmentationColored executables use modules such as metrics.cpp, util*.cpp, and compare against ground truth (from the Dataset) for computing IoU, AP, etc.
- Output Generator:
- Combines analysis results (detection, segmentation, minimap overlay) into an output video.

##### Relationships and Interactions
- Data Flow:
- The CLI input flows to the video loader.
- Frames pass through the preprocessing pipeline; then each frame is fed into the detection/segmentation/tracking modules.
- Detected/segmented results are passed to the table orientation and minimap modules, which compute and overlay additional information.
- Processed frames are aggregated into a final output video.
- Evaluation Flow:
- Test executables compare algorithm outputs with the ground truth files (located in the Dataset’s bounding_boxes, frames, and masks directories).
- This flow calculates metrics like mAP and mIoU and outputs performance reports.
- Support Structure:
- Common utilities, constants, and helper functions are defined in the include/ folder and used across the modules.

##### Architectural Patterns and Design Principles
- Modular Structure:
- Each functional aspect such as detection, segmentation, tracking, and table orientation is encapsulated in separate modules/libraries.
- Separation of Concerns:
- There is a clear division between the main processing pipeline (for video transformation and minimap augmentation) and the testing/performance analysis executables.
- Reusability and Extensibility:
- The structure (with separate “src” and “include” folders) allows individual modules to be updated or extended independently.
- Data-Driven Testing:
- Use of a well-organized Dataset folder indicates a design that supports robust evaluation.

- “CLI & Video Input” (front-end of the system).
- “Video Loader & Preprocessor” to represent the initial post–user input stage.
- “Detection Module” (with reference to detection source/header files).
- “Segmentation Module.”
- “Tracking Module.”
- “Table Orientation & Minimap Generator.”
- “Output Assembler & Video Writer.”
- “Performance & Metrics Evaluator” (for ComputePerformance, TestAllClip, etc.).
- “Dataset & Ground Truth” (as an input source for performance evaluation).
- Additional flows where the test executables pull ground truth data from the Dataset to their evaluation modules.
- External Dependencies:
- Notate that CMakeLists.txt handles the build, suggesting a build pipeline component.
- Labels:

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Main Application Pipeline"
        A["CLI & Video Input"]:::component
        B["Video Loader & Preprocessor"]:::component
        C["Detection Module (detection.cpp, detection.h)"]:::module
        D["Segmentation Module (segmentation.cpp, segmentation.h)"]:::module
        E["Tracking Module (tracking.cpp, tracking.h)"]:::module
        F["Table Orientation & Minimap Generator"]:::module
        G["Output Assembler & Video Writer"]:::component

        A -->|"next"| B
        B -->|"process"| C
        B -->|"process"| D
        B -->|"process"| E
        C -->|"results"| F
        D -->|"results"| F
        E -->|"results"| F
        F -->|"assemble"| G
    end

    subgraph "Performance & Evaluation Pipeline"
        H["Performance & Metrics Evaluator (metrics, computePerformance, testAllClip, showSegmentationColored)"]:::module
        I["Dataset & Ground Truth"]:::database

        I -->|"provideGT"| H
    end

    J["Build Pipeline (CMakeLists.txt)"]:::external
    J --- A
    J --- H

    click A "https://github.com/sproc01/8ballpool/blob/main/src/main.cpp"
    click B "https://github.com/sproc01/8ballpool/blob/main/src/main.cpp (handling frame reading and pre-processing)"
    click C "https://github.com/sproc01/8ballpool/blob/main/src/detection.cpp"
    click D "https://github.com/sproc01/8ballpool/blob/main/src/segmentation.cpp"
    click E "https://github.com/sproc01/8ballpool/blob/main/src/tracking.cpp"
    click F "https://github.com/sproc01/8ballpool/blob/main/src/table.cpp"
    click G "https://github.com/sproc01/8ballpool/blob/main/src/main.cpp"
    click H "https://github.com/sproc01/8ballpool/blob/main/src/metrics.cpp"
    click I "https://github.com/sproc01/8ballpool/tree/main/Dataset"

    classDef component fill:#fef2cc,stroke:#d97706,stroke-width:2px;
    classDef module fill:#d1fae5,stroke:#065f46,stroke-width:2px;
    classDef database fill:#dbeafe,stroke:#1e40af,stroke-width:2px;
    classDef external fill:#fee2e2,stroke:#991b1b,stroke-width:2px;
```
