# leap71/picogk architecture

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

- Interactive diagram: https://gitdiagram.com/leap71/picogk
- Repository: https://github.com/leap71/picogk

## Overview

##### Project type and purpose
- PicoGK is primarily a geometry-kernel library written in C#, paired with a C++ runtime (PicoGKRuntime) that wraps OpenVDB.
- It exposes core geometry operations (meshes, voxels, fields) via a “PicoGKRuntime” interop layer, provides a CLI tool and an interactive OpenGL viewer (using GLFW), and ships examples illustrating API usage.

##### File structure
- Top-level directories:
- Documentation/ – how-tos, install guides, architecture notes
- Examples/ – sample C# programs exercising the library
- ViewerEnvironment/ – zipped environment textures for the viewer
- Root .cs files (PicoGK_*.cs) implement the C# library: core data types (Mesh, Voxels, ScalarField, Lattice), I/O modules (.Stl, .VDB, .Csv, .Image), interop (PicoGK__Interop.cs), configuration, utilities, and viewer components (PicoGK_Viewer*.cs).
- No dedicated “src” folder, but the naming convention groups related functionality.

##### Extract architecture insights from README
- Two modules:
- PicoGK (C#) – high-level API, tools, examples
- PicoGKRuntime (C++) – thin extern “C” wrapper around OpenVDB, managed via DllImport
- Dependencies:
- OpenVDB (via PicoGKRuntime)
- GLFW (for the OpenGL viewer)
- Usage model: C# layer calls into C++ runtime → runtime forwards to OpenVDB → results returned to C#.

##### Main components
a. PicoGK C# Library
– Core geometry classes (Mesh, Voxels, Fields)
– I/O modules (.Stl, .VDB, .Csv, .Image)
– Utilities, logging, math helpers
– CLI tool (PicoGK_Cli)
– Viewer (PicoGK_Viewer + Actions, Keyboard, Animation, Timelapse)
b. PicoGKRuntime (C++ extern “C” API)
c. OpenVDB (3rd-party C++ library underneath the runtime)
d. GLFW / OpenGL (for rendering in the viewer)
e. File system (reading/writing STL, VDB, CSV, images)
f. Examples (client code illustrating API calls)

##### Relationships and data flows
- C# Library → PicoGKRuntime via P/Invoke (DllImport)
- PicoGKRuntime → OpenVDB core geometry engine
- C# Viewer → GLFW → GPU (OpenGL) for rendering meshes/voxels
- CLI and Examples → call high-level C# API → triggers runtime calls → file I/O or in-memory geometry ops → output to console, files, or viewer
- File I/O modules ↔ disk (STL, VDB, CSV, PNG, etc.)

##### Architectural patterns and design principles
- Layered architecture: Presentation/CLI/Viewer on top, C# API core in the middle, C++ runtime/interop below, then OpenVDB at the base
- Separation of concerns: I/O, core data structures, interop, viewer controls are all modular .cs files
- Plugin-style extensibility: extern “C” API in PicoGKRuntime allows other kernels to implement the same interface
- Example-driven: a directory of self-contained client apps driving the library

##### Final advice
- Be exhaustive: break out all key .cs files into functional groupings rather than lumping them into “Misc.”
- Data flow end-to-end: from client code (Examples/CLI) through the runtime to OpenVDB, back to viewer or disk
- Keep it simple visually, but list every major component and dependency explicitly

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Examples and CLI
    subgraph "Clients"
        ExamplesCode["Examples/*.cs"]:::external
        TestFiles["Examples/Testfiles/"]:::external
    end
    CLI["PicoGK_Cli.cs"]:::csharp
    ExamplesCode -->|"calls C# API"| CLI

    %% C# Layer
    subgraph "C# Layer"
        subgraph "Core Geometry Classes"
            Mesh["PicoGK_Mesh.cs"]:::csharp
            Voxels["PicoGK_Voxels.cs"]:::csharp
            ScalarField["PicoGK_ScalarField.cs"]:::csharp
            Lattice["PicoGK_Lattice.cs"]:::csharp
            PolyLine["PicoGK_PolyLine.cs"]:::csharp
            TriangleVoxelization["PicoGK_TriangleVoxelization.cs"]:::csharp
            VectorField["PicoGK_VectorField.cs"]:::csharp
            BBox["PicoGK_BBox.cs"]:::csharp
            Types["PicoGK_Types.cs"]:::csharp
        end
        subgraph "I/O Modules"
            MeshIo["PicoGK_MeshIo.cs"]:::csharp
            VoxelsIo["PicoGK_VoxelsIo.cs"]:::csharp
            CsvIo["PicoGK_Csv.cs"]:::csharp
            ImageIo["PicoGK_ImageIo.cs"]:::csharp
            VdbIo["PicoGK_OpenVdbFile.cs"]:::csharp
        end
        subgraph "Utilities & Math"
            Utils["PicoGK_Utils.cs"]:::csharp
            Log["PicoGK_Log.cs"]:::csharp
            MeshMath["PicoGK_MeshMath.cs"]:::csharp
            VectorExt["PicoGK_VectorExt.cs"]:::csharp
            Easing["PicoGK_Easing.cs"]:::csharp
            FieldUtils["PicoGK_FieldUtils.cs"]:::csharp
            FieldMetadata["PicoGK_FieldMetadata.cs"]:::csharp
            Color["PicoGK_Color.cs"]:::csharp
        end
        Config["PicoGK__Config.cs"]:::csharp
        Interop["PicoGK__Interop.cs"]:::csharp
        subgraph "Viewer"
            ViewerMain["PicoGK_Viewer.cs"]:::csharp
            ViewerActions["PicoGK_ViewerActions.cs"]:::csharp
            ViewerKeyboard["PicoGK_ViewerKeyboard.cs"]:::csharp
            ViewerAnimation["PicoGK_ViewerAnimation.cs"]:::csharp
            ViewerTimelapse["PicoGK_ViewerTimelapse.cs"]:::csharp
            Animation["PicoGK_Animation.cs"]:::csharp
        end
    end

    %% Native Layer
    PicoGKRuntime["PicoGKRuntime (C++ extern API)"]:::native
    OpenVDB["OpenVDB Library"]:::external

    %% External Dependencies
    GLFW["GLFW"]:::external
    GPU["GPU (OpenGL)"]:::external
    Disk["File System / Disk"]:::external
    Documentation["Documentation/"]:::external
    ViewerEnv["ViewerEnvironment/"]:::external

    %% Connections
    ExamplesCode -->|"calls C# API"| Mesh
    CLI -->|"calls C# API"| Mesh
    Mesh -->|"uses I/O"| VdbIo
    Mesh -->|"uses I/O"| MeshIo
    Voxels -->|"uses I/O"| VoxelsIo
    ScalarField -->|"uses I/O"| CsvIo
    VectorField -->|"uses I/O"| ImageIo

    MeshIo -->|"STL read/write"| Disk
    VoxelsIo -->|"Voxel file I/O"| Disk
    CsvIo -->|"CSV read/write"| Disk
    ImageIo -->|"Image read/write"| Disk
    VdbIo -->|"VDB read/write"| Disk

    CLI -->|"P/Invoke call"| Interop
    Mesh -->|"P/Invoke call"| Interop
    Voxels -->|"P/Invoke call"| Interop
    ScalarField -->|"P/Invoke call"| Interop

    Interop -->|"calls"| PicoGKRuntime
    PicoGKRuntime -->|"uses"| OpenVDB

    ViewerMain -->|"renders via"| GLFW
    ViewerActions --> GLFW
    ViewerKeyboard --> GLFW
    ViewerAnimation --> GLFW
    ViewerTimelapse --> GLFW

    GLFW -->|"OpenGL draw call"| GPU

    ViewerMain -->|"uses C# API"| Mesh
    ViewerMain -->|"uses C# API"| Voxels

    Documentation --> Mesh
    ViewerEnv --> ViewerMain

    %% Click Events
    click Mesh "https://github.com/leap71/picogk/blob/main/PicoGK_Mesh.cs"
    click Voxels "https://github.com/leap71/picogk/blob/main/PicoGK_Voxels.cs"
    click ScalarField "https://github.com/leap71/picogk/blob/main/PicoGK_ScalarField.cs"
    click Lattice "https://github.com/leap71/picogk/blob/main/PicoGK_Lattice.cs"
    click PolyLine "https://github.com/leap71/picogk/blob/main/PicoGK_PolyLine.cs"
    click TriangleVoxelization "https://github.com/leap71/picogk/blob/main/PicoGK_TriangleVoxelization.cs"
    click VectorField "https://github.com/leap71/picogk/blob/main/PicoGK_VectorField.cs"
    click BBox "https://github.com/leap71/picogk/blob/main/PicoGK_BBox.cs"
    click Types "https://github.com/leap71/picogk/blob/main/PicoGK_Types.cs"

    click MeshIo "https://github.com/leap71/picogk/blob/main/PicoGK_MeshIo.cs"
    click VoxelsIo "https://github.com/leap71/picogk/blob/main/PicoGK_VoxelsIo.cs"
    click CsvIo "https://github.com/leap71/picogk/blob/main/PicoGK_Csv.cs"
    click ImageIo "https://github.com/leap71/picogk/blob/main/PicoGK_ImageIo.cs"
    click VdbIo "https://github.com/leap71/picogk/blob/main/PicoGK_OpenVdbFile.cs"

    click Utils "https://github.com/leap71/picogk/blob/main/PicoGK_Utils.cs"
    click Log "https://github.com/leap71/picogk/blob/main/PicoGK_Log.cs"
    click MeshMath "https://github.com/leap71/picogk/blob/main/PicoGK_MeshMath.cs"
    click VectorExt "https://github.com/leap71/picogk/blob/main/PicoGK_VectorExt.cs"
    click Easing "https://github.com/leap71/picogk/blob/main/PicoGK_Easing.cs"
    click FieldUtils "https://github.com/leap71/picogk/blob/main/PicoGK_FieldUtils.cs"
    click FieldMetadata "https://github.com/leap71/picogk/blob/main/PicoGK_FieldMetadata.cs"
    click Color "https://github.com/leap71/picogk/blob/main/PicoGK_Color.cs"

    click CLI "https://github.com/leap71/picogk/blob/main/PicoGK_Cli.cs"

    click Interop "https://github.com/leap71/picogk/blob/main/PicoGK__Interop.cs"
    click Config "https://github.com/leap71/picogk/blob/main/PicoGK__Config.cs"

    click ViewerMain "https://github.com/leap71/picogk/blob/main/PicoGK_Viewer.cs"
    click ViewerActions "https://github.com/leap71/picogk/blob/main/PicoGK_ViewerActions.cs"
    click ViewerKeyboard "https://github.com/leap71/picogk/blob/main/PicoGK_ViewerKeyboard.cs"
    click ViewerAnimation "https://github.com/leap71/picogk/blob/main/PicoGK_ViewerAnimation.cs"
    click ViewerTimelapse "https://github.com/leap71/picogk/blob/main/PicoGK_ViewerTimelapse.cs"
    click Animation "https://github.com/leap71/picogk/blob/main/PicoGK_Animation.cs"

    click ExamplesCode "https://github.com/leap71/picogk/tree/main/Examples/"
    click TestFiles "https://github.com/leap71/picogk/tree/main/Examples/Testfiles/"
    click Documentation "https://github.com/leap71/picogk/tree/main/Documentation/"
    click ViewerEnv "https://github.com/leap71/picogk/tree/main/ViewerEnvironment/"

    %% Styles
    classDef csharp fill:#cde5f7,stroke:#0366d6,color:#000
    classDef native fill:#f3c4fb,stroke:#a259ff,color:#000
    classDef external fill:#e8f5e9,stroke:#34a853,color:#000
```
