# tommybazar/tbraymarcherplugin architecture

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

- Interactive diagram: https://gitdiagram.com/tommybazar/tbraymarcherplugin
- Repository: https://github.com/tommybazar/tbraymarcherplugin

## Overview

##### Project Type & Purpose
- This is an Unreal Engine 5.4+ plugin (“TBRaymarcherPlugin”) providing real-time volume rendering (raymarching) of medical/volumetric data.
- It ships as a UE plugin with both runtime C++ modules and an editor module, plus HLSL (.usf) shader files, content assets (Blueprints, materials, curves, maps), and third-party libraries (DCMTK).

##### Top-Level Component Breakdown
A. Unreal Engine Host
– Core engine (Core, CoreUObject, Engine, InputCore)
– Editor (for asset import, UMG, Blueprint graph, project settings)
– Render subsystem (Render Thread, RHI Thread)
B. Plugin Modules (in Source/)
– VolumeTextureToolkit (Runtime): low-level volume‐texture creation, DICOM/MHD/RAW loaders
– VolumeTextureToolkitEditor (Editor): drag-and-drop importer, factory, asset creation UI
– RayUtils: utility functions (timers, raymarch helpers) used by other modules
– Raymarcher (Runtime):
- ARaymarchVolume actor (manages volume textures, lights array, clipping plane)
- Compute‐shader wrappers for precomputed illumination (“AddDirLight”, “ChangeDirLight”)
- Blueprint‐callable functions for loading volumes at runtime
- HLSL .usf compute shaders and material includes
– FractalMarcher (Runtime sample): example actor/screens for 2D/3D fractal visualization
– Tests: automated performance/actor tests
– VolumeTextureToolkitEditor: editor widgets and factory code
C. Content Assets (Content/)
– Blueprints: actor wrappers (BP_RaymarchVolume, BP_RaymarchLight, BP_ClipPlane), VR controllers, UI widgets
– Materials & Material Functions: M_Raymarch, M_Intensity_Raymarch, CommonInclude, transfer-function sampling .usf
– Maps: example showcase levels (desktop & VR)
– Meshes: unit cube, plane, subdivided meshes

##### Data & Interaction Flows
1. Editor Asset Import
Editor Module → DCMTK (third-party) → VolumeTextureToolkitEditor.UI → VolumeTextureToolkit → UVolumeAsset + UVolumeTexture assets in Content Browser
2. Game Initialization
Game Thread: Level spawns ARaymarchVolume actor (or Blueprint subclass) and ARaymarchLight / ARaymarchClipPlane
3. Runtime Volume Setup
ARaymarchVolume (game thread) calls VolumeTextureToolkit API → loads persistent or transient UVolumeTexture → assigns to Dynamic Material Instance
4. Illumination Precompute (Render Thread & RHI Thread)
- Compute Shader Passes (“AddDirLightShader.usf”, “ChangeDirLightShader.usf”)
- Shader dispatch per slice to build 3D light‐volume texture
5. Raymarching in Material
- Output rendered image to viewport
6. Blueprint & UI Interactions
- UMG Widgets (WBP_* in Content/Blueprints/Widgets) call Blueprint‐exposed C++ functions on ARaymarchVolume (SetWindowCenter, LoadNewFile, SetTFCurve) via Game Thread → triggers volume/material update → visible next frame

##### Key Architectural Patterns & Principles
- Modular plugin design: separate editor vs. runtime code (Editor module never ships to shipping build)
- C++ & HLSL separation: heavy logic in HLSL (.usf) files, C++ wraps shader dispatch and material parameter setup
- Shader reuse: shared functions in “RaymarcherCommon.usf” & “WindowedSampling.usf” used by both material shaders and compute shaders for consistency
- Blueprint‐exposed API: core classes (ARaymarchVolume, ARaymarchLight, ARaymarchClipPlane) expose UFUNCTION APIs for in-editor and runtime tweaking
- Thread separation: Game Thread → Render Thread → RHI Thread → GPU compute passes

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Engine Host
    subgraph "Engine Host"
        direction TB
        CoreEngine["Core Engine\n(Core, CoreUObject, Engine, InputCore)"]:::engine
        EditorModule["Editor Module\n(UMG, Blueprint, Settings)"]:::engine
        RenderSubsystem["Render Subsystem\n(Render Thread, RHI Thread)"]:::engine
    end

    %% Third-Party Libraries
    subgraph "Third-Party"
        direction TB
        DCMTK["DCMTK\n(DICOM Parsing)"]:::thirdparty
    end

    %% Plugin Source Modules
    subgraph "Plugin Source"
        direction TB
        VTT["VolumeTextureToolkit\n(Source/VolumeTextureToolkit)"]:::plugin
        VTTShaders["VTT Shader Utils\n(Shaders/Private)"]:::plugin
        VTTTP["DCMTK Integration"]:::plugin
        VTTEditor["VolumeTextureToolkitEditor\n(Source/VolumeTextureToolkitEditor)"]:::plugin
        RayUtils["RayUtils\n(Source/RayUtils)"]:::plugin
        Raymarcher["Raymarcher\n(Source/Raymarcher)"]:::plugin
        RMShaders["Raymarcher HLSL Shaders\n(Shaders/Private)"]:::plugin
        Fractal["FractalMarcher\n(Source/FractalMarcher)"]:::plugin
        TestsMod["Tests\n(Source/Tests)"]:::plugin
        PluginDesc["Plugin Descriptor\nTBRaymarcherPlugin.uplugin"]:::plugin
        BuildScripts["Module Build Scripts"]:::plugin
    end

    %% Content Assets
    subgraph "Content Assets"
        direction TB
        BActors["Blueprint Actors\n(Content/Blueprints/Actors)"]:::content
        BWidgets["Blueprint Widgets\n(Content/Blueprints/Widgets)"]:::content
        Curves["Transfer Function Curves\n(Content/Curves)"]:::content
        Maps["Example Levels & Maps\n(Content/Maps)"]:::content
        FractalsContent["Fractal Showcase\n(Content/Fractals)"]:::content
        Materials["Materials & Includes\n(Content/Materials)"]:::content
        Meshes["Mesh Assets\n(Content/Meshes)"]:::content
        DefaultRes["Default Resources\n(Content/DefaultResources)"]:::content
        VolumeAssets["UVolumeAsset/Texture\n(Generated Assets)"]:::content
    end

    %% Flows
    EditorModule -->|imports assets| DCMTK
    DCMTK -->|parsing| VTTEditor
    VTTEditor -->|factory creation| VTT
    VTT -->|creates| VolumeAssets

    %% Runtime Initialization
    CoreEngine -->|spawns actors| BActors
    BActors -->|ARaymarchVolume| Raymarcher
    Raymarcher -->|uses| VTT
    Raymarcher -->|dispatch shaders| RenderSubsystem
    RMShaders -->|compute pass| RenderSubsystem
    VTTShaders -->|utility shaders| RenderSubsystem

    %% Shader Pipeline
    Materials -->|includes| RMShaders
    RMShaders -->|pixel raymarch| RenderSubsystem
    RMShaders -->|compute illum| RenderSubsystem

    %% Blueprint & UI
    BWidgets -->|calls API| Raymarcher
    RayUtils -->|helpers| Raymarcher

    %% Module Dependencies
    Raymarcher -->|depends on| RayUtils
    VTT -->|depends on| VTTShaders
    VTT -->|depends on| VTTTP
    VTTTP -->|wraps| DCMTK

    %% Plugin Descriptor & Build Scripts
    PluginDesc -->|defines modules| BuildScripts
    BuildScripts -->|configures| VTT
    BuildScripts -->|configures| VTTEditor
    BuildScripts -->|configures| RayUtils
    BuildScripts -->|configures| Raymarcher
    BuildScripts -->|configures| Fractal
    BuildScripts -->|configures| TestsMod

    %% Click Events
    click VTT "https://github.com/tommybazar/tbraymarcherplugin/tree/5.4/Source/VolumeTextureToolkit"
    click VTTShaders "https://github.com/tommybazar/tbraymarcherplugin/tree/5.4/Source/VolumeTextureToolkit/Shaders/Private"
    click VTTTP "https://github.com/tommybazar/tbraymarcherplugin/tree/5.4/Source/VolumeTextureToolkit/ThirdParty/dcmtk"
    click VTTEditor "https://github.com/tommybazar/tbraymarcherplugin/tree/5.4/Source/VolumeTextureToolkitEditor"
    click RayUtils "https://github.com/tommybazar/tbraymarcherplugin/tree/5.4/Source/RayUtils"
    click Raymarcher "https://github.com/tommybazar/tbraymarcherplugin/tree/5.4/Source/Raymarcher"
    click RMShaders "https://github.com/tommybazar/tbraymarcherplugin/tree/5.4/Source/Raymarcher/Shaders/Private"
    click Fractal "https://github.com/tommybazar/tbraymarcherplugin/tree/5.4/Source/FractalMarcher"
    click TestsMod "https://github.com/tommybazar/tbraymarcherplugin/tree/5.4/Source/Tests"
    click BActors "https://github.com/tommybazar/tbraymarcherplugin/tree/5.4/Content/Blueprints/Actors"
    click BWidgets "https://github.com/tommybazar/tbraymarcherplugin/tree/5.4/Content/Blueprints/Widgets"
    click Curves "https://github.com/tommybazar/tbraymarcherplugin/tree/5.4/Content/Curves"
    click Maps "https://github.com/tommybazar/tbraymarcherplugin/tree/5.4/Content/Maps"
    click FractalsContent "https://github.com/tommybazar/tbraymarcherplugin/tree/5.4/Content/Fractals"
    click Materials "https://github.com/tommybazar/tbraymarcherplugin/tree/5.4/Content/Materials"
    click Meshes "https://github.com/tommybazar/tbraymarcherplugin/tree/5.4/Content/Meshes"
    click DefaultRes "https://github.com/tommybazar/tbraymarcherplugin/tree/5.4/Content/DefaultResources"
    click PluginDesc "https://github.com/tommybazar/tbraymarcherplugin/blob/5.4/TBRaymarcherPlugin.uplugin"
    click BuildScripts "https://github.com/tommybazar/tbraymarcherplugin/blob/5.4/Source/VolumeTextureToolkit/VolumeTextureToolkit.Build.cs"
    click BuildScripts "https://github.com/tommybazar/tbraymarcherplugin/blob/5.4/Source/VolumeTextureToolkitEditor/VolumeTextureToolkitEditor.Build.cs"
    click BuildScripts "https://github.com/tommybazar/tbraymarcherplugin/blob/5.4/Source/RayUtils/RayUtils.build.cs"
    click BuildScripts "https://github.com/tommybazar/tbraymarcherplugin/blob/5.4/Source/Raymarcher/Raymarcher.build.cs"
    click BuildScripts "https://github.com/tommybazar/tbraymarcherplugin/blob/5.4/Source/FractalMarcher/FractalMarcher.build.cs"
    click BuildScripts "https://github.com/tommybazar/tbraymarcherplugin/blob/5.4/Source/Tests/Tests.Build.cs"

    %% Styles
    classDef engine fill:#cccccc,stroke:#333,stroke-width:1px
    classDef plugin fill:#a0c4ff,stroke:#0366d6,stroke-width:1px
    classDef content fill:#d0f4de,stroke:#117a65,stroke-width:1px
    classDef thirdparty fill:#ffd6a5,stroke:#d35400,stroke-width:1px
```
