# jhertrampf/yolosquared architecture

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

- Interactive diagram: https://gitdiagram.com/jhertrampf/yolosquared
- Repository: https://github.com/jhertrampf/yolosquared

## Overview

##### Main Components Identification
- Inference Pipeline: This is the core of the project and comprises several sub-components:
- Source Modules: Located under src/inference/source (e.g., GoPro, Images, InternalCamera, Video) – these handle different input data types.
- Detection/Head Modules: Under src/inference/head (including AbstractHead, head.py, evaluation.py, visualization.py) – these likely manage the detection of heads/helmets.
- Stage1 and Stage2 Pipelines: Found in src/inference/stage1 and src/inference/stage2; each contains dedicated pre-processing, prediction (with both Tensorrt and Ultralytics variants), and post-processing scripts. Stage1 detects motorcycles while stage2 focuses on helmet detection inside the motorcycle patches.
- Tracking Component: Located in src/inference/tracker and src/inference/tracking.py – this module links detected motorcycles across frames, annotating them with “violation” or “legal” labels.
- Training Module: Contained within src/train (e.g., yolov8.py) – this module is used to train the YOLO models for detection.
- Configurations and Dependencies:
- General configuration (config.py) which could host global settings.
- Inference-specific configuration (src/inference/inference_config.py) for managing operating modes, image sizes, and other parameters.
- requirements.txt and third-party-licenses highlight the external libraries and licensing of third-party tools.

##### Relationships & Interactions
- Data Flow: Input data (videos/images) is ingested by one of the source components and passed into the Stage1 pipeline for motorcycle detection. From there, regions of interest (ROI) corresponding to detected motorcycles are processed in Stage2 for helmet detection. The head modules then assess whether each detected head is wearing a helmet.
- Training vs. Inference: The training component is separate and used to train the YOLOv8 models. The inference pipeline then utilizes these trained models to process new input data.

##### Architectural Patterns and Design Principles
- Modular Design: The repository is neatly divided into sub-modules (source, head, stage1, stage2, tracker) that encapsulate functionality, supporting separation of concerns.
- Two-Stage Inference: There is a distinct two-stage processing pipeline that first identifies motorcycles and then detects helmets.
- Configurable Pipeline: The presence of configuration scripts (both for general settings and inference-specific settings) suggests an emphasis on flexibility and ease of parameter tuning.
- Extensibility: The abstract classes (e.g., AbstractHead, AbstractLoader) suggest that new sources or detection heads can be integrated without major refactoring.

##### Additional Hints
- Given the heavy reliance on deep learning and computer vision, include notes on where GPU acceleration might be used.
- Mention that the design enables plugging in alternative data sources or even additional processing stages by following the established modular boundaries.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Inference Pipeline
    subgraph "Inference Pipeline"
        %% Data Sources
        subgraph "Data Sources"
            DS1("AbstractLoader.py")
            DS2("GoPro.py")
            DS3("Images.py")
            DS4("InternalCamera.py")
            DS5("Video.py")
            DS6("visualize_source.py")
        end

        %% Stage1: Motorcycle Detection Pipeline
        subgraph "Stage1: Motorcycle Detection"
            S1_1("preprocessing.py")
            S1_2("predict_tenssorrt.py")
            S1_3("predict_ultralytics.py")
            S1_4("postprocessing.py")
            S1_5("stage1.py")
            S1_6("engine.py")
        end

        %% Stage2: Helmet Detection Pipeline
        subgraph "Stage2: Helmet Detection"
            S2_1("preprocessing.py")
            S2_2("predict_tenssorrt.py")
            S2_3("predict_ultralytics.py")
            S2_4("postprocessing.py")
            S2_5("stage2.py")
        end

        %% Detection/Head Modules
        subgraph "Detection/Head Modules"
            DH_1("AbstractHead.py")
            DH_2("head.py")
            DH_3("evaluation.py")
            DH_4("visualization.py")
        end

        %% Tracking Component
        subgraph "Tracking Module"
            T_1("preprocessing.py")
            T_2("postprocessing.py")
            T_3("sort.py")
            T_4("tracker.py")
            T_5("tracking.py")
        end

        %% Visualization Utilities
        subgraph "Visualization Utilities"
            VU("visualization_utils.py")
        end
    end

    %% Training Module
    subgraph "Training Module"
        TM("yolov8.py")
    end

    %% Configurations & Dependencies
    subgraph "Configurations & Dependencies"
        Config1("config.py")
        Config2("inference_config.py")
        Dep1("requirements.txt")
        Dep2("third-party-licenses")
    end

    %% Connections
    %% Data Sources feed into Stage1
    DS1 -->|"feeds"| S1_1
    DS2 -->|"feeds"| S1_1
    DS3 -->|"feeds"| S1_1
    DS4 -->|"feeds"| S1_1
    DS5 -->|"feeds"| S1_1
    DS6 -->|"feeds"| S1_1

    %% Stage1 output feeds into Stage2
    S1_5 -->|"ROI extraction"| S2_1

    %% Stage2 output goes to Detection/Head Modules for helmet evaluation
    S2_5 -->|"helmet detection"| DH_1

    %% Stage2 also feeds into Tracking Module for object tracking
    S2_5 -->|"tracking"| T_5

    %% Detection/Head Modules and Tracking Module both provide data to Visualization Utilities
    DH_4 -->|"overlay"| VU
    T_5 -->|"annotate"| VU

    %% Training Module supplies trained models to Stage1 and Stage2
    TM -->|"trainedModel"| S1_5
    TM -->|"trainedModel"| S2_5

    %% Configurations & Dependencies influence Inference Pipeline
    Config1 -->|"config"| S1_1
    Config2 -->|"config"| S1_1
    Dep1 -->|"deps"| S1_1
    Dep2 -->|"deps"| S1_1

    %% Class Definitions for styling
    classDef dataSource fill:#a6cee3,stroke:#1f78b4,stroke-width:2px;
    classDef stage fill:#b2df8a,stroke:#33a02c,stroke-width:2px;
    classDef detection fill:#fb9a99,stroke:#e31a1c,stroke-width:2px;
    classDef tracking fill:#fdbf6f,stroke:#ff7f00,stroke-width:2px;
    classDef training fill:#cab2d6,stroke:#6a3d9a,stroke-width:2px;
    classDef config fill:#ffff99,stroke:#999900,stroke-width:2px;
    classDef dependencies fill:#d9d9d9,stroke:#636363,stroke-width:2px;
    classDef visUtil fill:#ccebc5,stroke:#006400,stroke-width:2px;

    %% Assigning classes
    class DS1,DS2,DS3,DS4,DS5,DS6 dataSource;
    class S1_1,S1_2,S1_3,S1_4,S1_5,S1_6 stage;
    class S2_1,S2_2,S2_3,S2_4,S2_5 stage;
    class DH_1,DH_2,DH_3,DH_4 detection;
    class T_1,T_2,T_3,T_4,T_5 tracking;
    class TM training;
    class Config1,Config2 config;
    class Dep1,Dep2 dependencies;
    class VU visUtil;

    %% Click Events
    click DS1 "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/source/AbstractLoader.py"
    click DS2 "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/source/GoPro.py"
    click DS3 "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/source/Images.py"
    click DS4 "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/source/InternalCamera.py"
    click DS5 "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/source/Video.py"
    click DS6 "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/source/visualize_source.py"

    click DH_1 "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/head/AbstractHead.py"
    click DH_2 "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/head/head.py"
    click DH_3 "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/head/evaluation.py"
    click DH_4 "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/head/visualization.py"

    click S1_1 "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/stage1/preprocessing.py"
    click S1_2 "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/stage1/predict_tenssorrt.py"
    click S1_3 "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/stage1/predict_ultralytics.py"
    click S1_4 "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/stage1/postprocessing.py"
    click S1_5 "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/stage1/stage1.py"
    click S1_6 "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/stage1/engine.py"

    click S2_1 "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/stage2/preprocessing.py"
    click S2_2 "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/stage2/predict_tenssorrt.py"
    click S2_3 "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/stage2/predict_ultralytics.py"
    click S2_4 "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/stage2/postprocessing.py"
    click S2_5 "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/stage2/stage2.py"

    click T_1 "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/tracker/preprocessing.py"
    click T_2 "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/tracker/postprocessing.py"
    click T_3 "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/tracker/sort.py"
    click T_4 "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/tracker/tracker.py"
    click T_5 "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/tracking.py"

    click VU "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/visualization_utils.py"

    click TM "https://github.com/jhertrampf/yolosquared/blob/main/src/train/yolov8.py"

    click Config1 "https://github.com/jhertrampf/yolosquared/blob/main/config.py"
    click Config2 "https://github.com/jhertrampf/yolosquared/blob/main/src/inference/inference_config.py"

    click Dep1 "https://github.com/jhertrampf/yolosquared/blob/main/requirements.txt"
    click Dep2 "https://github.com/jhertrampf/yolosquared/tree/main/third-party-licenses"
```
