# ivandrodri/gpu-voxelizer architecture

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

- Interactive diagram: https://gitdiagram.com/ivandrodri/gpu-voxelizer
- Repository: https://github.com/ivandrodri/gpu-voxelizer

## Overview

Based on our analysis of the file tree and README content, this project is a GPU-accelerated voxelization tool built mostly in CUDA/C++ for processing 3D meshes (using surface voxelization) with an accompanying Python-based Streamlit GUI for visualization and interactions. The project also supports two connector options: a local connector (where both engine and GUI run on the same machine) and a REST API connector (with a simple server implemented in Python) that can be used for remote execution.

- GPU Voxelization Engine:
- Represents the core processing engine written in CUDA/C++.
- Subdivide this into logical modules such as Mesh Processing, Voxelization (surface and the planned bulk voxelization), Mathematical Utilities, and Logging. These modules are present in the “mesh_voxelization” folder.
- Associate the build system (CMake, Dockerfiles) with these components.

- GUI/Visualization Layer:
- Streamlit-based application (voxelizer_gui) that provides the user-facing interface.
- Underline that it follows a Controller-Model-View (CMV) pattern (with modules in “voxelizer_gui/src/gui_components”) to promote modularity and separation of concerns.

- Connectors/Integration Layer:
- “Connector” abstraction from voxelizer_gui/src/connector.
- Two possible realization paths:
- Local Connector – for invoking the GPU engine directly within the same process/machine.
- REST API Connector – where the GUI communicates with a separate REST API server.

- REST API Server (Endpoints):
- “end_points_voxelizer” component that provides a server implemented in Python. This is intended for remote interactions with the voxelization engine.

- Supporting Utilities:
- “shared_utils” for metadata and utility functions.
- External libraries (OpenMeshMirror, glog, cxxopts, googletest) from the “external” directory.
- Dependencies on the CUDA Toolkit, proper NVIDIA drivers, and compiler toolchains.
- Optionally, note that “data” (like STL files and images) is used for input/output and visualization samples.

##### Relationships and Data Flow
- From the Connector to the GPU Voxelization Engine. Depending on the chosen connector (Local vs. REST), indicate either a direct call or an HTTP/REST request.
- From the REST Connector to the REST API Server – if this communication mode is selected.

##### Architectural Patterns and Design Principles
- That the GUI follows a Controller/Model/View (CMV) design pattern, ensuring separation between user-interface logic and business logic.
- Modularity – the distinct separation between the GPU-based processing and the user interface via abstract connectors.
- That the system is designed to be extensible: for example, switching between local and remote (REST API-based) operations is achieved via a connector interface.

##### Technologies and Frameworks
- CUDA and C++ for low-level GPU computations (as seen in the “mesh_voxelization” and “main” directories).
- Python and Streamlit for the GUI visualization (voxelizer_gui).
- CMake for building the C++ code.
- Docker for environment consistency and containerized execution.
- Pre-commit hooks and testing frameworks (googletest, etc.) are used for code quality and testing.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% GPU Voxelization Engine
    subgraph "GPU Voxelization Engine"
        MeshProcessing["Mesh Processing Module"]:::cpp
        Voxelization["Voxelization Module"]:::cpp
        Maths["Mathematical Utilities Module"]:::cpp
        Logging["Logging Module"]:::cpp
        subgraph "Build System"
            CGRoot["CMakeLists.txt (Root)"]:::cpp
            CGMesh["mesh_voxelization/CMakeLists.txt"]:::cpp
            CGMain["main/CMakeLists.txt"]:::cpp
        end
    end

    %% GUI/Visualization Layer
    subgraph "GUI/Visualization Layer"
        GUIApp["Streamlit GUI App"]:::python
        subgraph "CMV - GUI Components"
            Controller["Controller Module"]:::python
            Model["Model Module"]:::python
            View["View Module"]:::python
        end
    end

    %% Connectors/Integration Layer
    subgraph "Connectors/Integration Layer"
        Connector["Connector Abstraction"]:::integration
        ConnectorLocal["Local Connector"]:::integration
        ConnectorREST["REST API Connector"]:::integration
    end

    %% REST API Server
    subgraph "REST API Server"
        Endpoints["REST API Endpoints"]:::python
    end

    %% Supporting Utilities
    subgraph "Supporting Utilities"
        Shared["Shared Utilities"]:::util
        External["External Dependencies"]:::util
        Samples["Sample Data"]:::util
    end

    %% Relationships and Data Flow
    GUIApp -->|"invoke"| Connector
    Controller -->|"orchestrates"| GUIApp
    Connector -->|"uses-local"| ConnectorLocal
    Connector -->|"uses-REST"| ConnectorREST
    ConnectorLocal -->|"direct_call"| MeshProcessing
    ConnectorREST -->|"HTTP_request"| Endpoints
    Endpoints -->|"trigger_job"| MeshProcessing
    MeshProcessing -->|"return_result"| Connector
    Connector -->|"deliver_result"| GUIApp

    %% Build system integration
    CGRoot -->|"builds"| MeshProcessing
    CGMesh -->|"builds"| MeshProcessing
    CGMain -->|"builds"| MeshProcessing

    %% Supporting utilities dependencies
    MeshProcessing -->|"utilizes"| Shared
    MeshProcessing -->|"depends_on"| External
    GUIApp -->|"loads"| Samples

    %% Click Events for GPU Voxelization Engine components
    click MeshProcessing "https://github.com/ivandrodri/gpu-voxelizer/tree/master/mesh_voxelization/mesh"
    click Voxelization "https://github.com/ivandrodri/gpu-voxelizer/tree/master/mesh_voxelization/voxelization"
    click Maths "https://github.com/ivandrodri/gpu-voxelizer/tree/master/mesh_voxelization/maths"
    click Logging "https://github.com/ivandrodri/gpu-voxelizer/tree/master/mesh_voxelization/logging_config"
    click CGRoot "https://github.com/ivandrodri/gpu-voxelizer/blob/master/CMakeLists.txt"
    click CGMesh "https://github.com/ivandrodri/gpu-voxelizer/blob/master/mesh_voxelization/CMakeLists.txt"
    click CGMain "https://github.com/ivandrodri/gpu-voxelizer/blob/master/main/CMakeLists.txt"

    %% Click Events for GUI/Visualization Layer
    click GUIApp "https://github.com/ivandrodri/gpu-voxelizer/blob/master/voxelizer_gui/streamlit_gui/voxelization_app.py"
    click Controller "https://github.com/ivandrodri/gpu-voxelizer/blob/master/voxelizer_gui/src/gui_components/controller.py"
    click Model "https://github.com/ivandrodri/gpu-voxelizer/blob/master/voxelizer_gui/src/gui_components/model.py"
    click View "https://github.com/ivandrodri/gpu-voxelizer/blob/master/voxelizer_gui/src/gui_components/streamlit_view.py"

    %% Click Events for Connectors/Integration Layer
    click Connector "https://github.com/ivandrodri/gpu-voxelizer/blob/master/voxelizer_gui/src/connector/connector.py"
    click ConnectorLocal "https://github.com/ivandrodri/gpu-voxelizer/blob/master/voxelizer_gui/src/connector/connector_local.py"
    click ConnectorREST "https://github.com/ivandrodri/gpu-voxelizer/blob/master/voxelizer_gui/src/connector/connector_rest_api.py"

    %% Click Event for REST API Server
    click Endpoints "https://github.com/ivandrodri/gpu-voxelizer/blob/master/end_points_voxelizer/end_points/end_points.py"

    %% Click Events for Supporting Utilities
    click Shared "https://github.com/ivandrodri/gpu-voxelizer/tree/master/shared_utils"
    click External "https://github.com/ivandrodri/gpu-voxelizer/tree/master/external"
    click Samples "https://github.com/ivandrodri/gpu-voxelizer/tree/master/data"

    %% Styles
    classDef cpp fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef python fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef integration fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef util fill:#FFB6C1,stroke:#000,stroke-width:2px;
```
