# stanislavpetrovv/advanced_raymarching architecture

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

- Interactive diagram: https://gitdiagram.com/stanislavpetrovv/advanced_raymarching
- Repository: https://github.com/stanislavpetrovv/advanced_raymarching

## Overview

##### Project Type & Purpose
- This is a GPU-accelerated 3D ray-marching demo written in Python. It uses ModernGL (a Python wrapper over OpenGL) to set up an OpenGL context, compile/link a set of GLSL shader programs (vertex + fragment shaders), load textures, accept mouse input (zoom via scroll), and render an anti-aliased 3D scene in real time.

##### File Structure Analysis
- **main.py** – Entry point. Sets up window/context, loads resources, handles input, drives the render loop.
- **requirements.txt** – Lists Python dependencies (e.g. ModernGL, GLFW/GLUT bindings, NumPy, etc.).
- **programs/** – Contains GLSL modules:
- vertex.glsl – Vertex shader for full-screen quad.
- fragment.glsl – Main ray-marching fragment shader.
- .glsl, hg_sdf.glsl, material.glsl – Scene SDF definitions and material routines.
- **textures/** – Image assets (e.g. roof textures) loaded by the fragment shader.
- **screenshots/** – Demo output, for documentation only.
- **LICENSE, README.md** – Project metadata.

##### Core Architectural Components
a. **Application Layer (CPU side)**
- Window & Context Manager (GLFW/GLUT via ModernGL)
- Input Handler (mouse scroll events → zoom uniforms)
- Resource Loader (reads .glsl files and texture images)
- Shader Manager (compiles & links GLSL programs)
- Configuration (reads AA setting from fragment.glsl or command line)

b. **Rendering Pipeline (GPU side)**
- Vertex Shader (vertex.glsl) → draws a full-screen quad
- Fragment Shader (fragment.glsl) → ray-marching algorithm
- Scene Definitions (map.glsl, hg_sdf.glsl) → Signed Distance Functions
- Material/Shading (material.glsl) → lighting, shading, anti-aliasing
- Texture Samplers (roof textures) → material detail

c. **External Dependencies**
- ModernGL (OpenGL binding)
- Windowing library (e.g. GLFW)
- NumPy (for any array math)

##### Relationships & Data Flow
1. User scroll input → Input Handler
2. Input Handler updates uniform variables in Shader Manager
3. Resource Loader reads GLSL code & textures at startup
4. Shader Manager compiles & links shaders → sends programs to GPU
- Vertex shader → full-screen primitive
- Fragment shader → ray-marching + SDF evaluations + shading
6. GPU writes to Framebuffer → OS window displays result

##### Architectural Patterns & Principles
- **Pipeline pattern**: clear separation of CPU-side setup vs. GPU-side execution
- **Modularity**: each GLSL file encapsulates a specific concern (geometry, scene SDF, material, main ray-marching)
- **Single responsibility**: main.py orchestrates only resource, input, and loop management

##### Construction Steps
1. Sketch high-level boundaries: CPU vs. GPU vs. External.
3. Populate GPU cluster: Vertex → Fragment → SDF & Material modules → Framebuffer.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CPU-side Cluster
    subgraph "CPU Side" 
        direction TB
        ContextManager["Window & Context Manager\n(Python + ModernGL + GLFW)"]:::cpu
        InputHandler["Input Handler\n(mouse scroll)"]:::cpu
        ResourceLoader["Resource Loader\n(.glsl & textures)"]:::cpu
        ShaderManager["Shader Manager\n(compile & link)"]:::cpu
        RenderLoop(["Render Loop\n(draw calls per frame)"]):::cpu
    end

    %% GPU-side Cluster
    subgraph "GPU Pipeline" 
        direction TB
        VertexShader["Vertex Shader\n(vertex.glsl)\nGLSL 330+"]:::gpu
        FragmentShader["Fragment Shader\n(fragment.glsl)\nGLSL 330+"]:::gpu
        SceneSDF["Scene SDF Modules\n(map.glsl)"]:::gpu
        HGSDF["High-level Geometry SDFs\n(hg_sdf.glsl)"]:::gpu
        MaterialModule["Material & Shading\n(material.glsl)"]:::gpu
        Framebuffer["Framebuffer"]:::gpu
    end

    %% External & I/O
    Textures[("Textures Folder\n(textures/roof)")]:::io
    WindowSystem["OS Windowing System"]:::ext
    GPUHardware["GPU Hardware"]:::ext
    Dependencies[("Python Dependencies\n(requirements.txt)")]:::ext
    Screenshots[("Screenshots\n(screenshots/)")]:::io
    Metadata[("Project Metadata\n(LICENSE, README.md)")]:::ext

    %% Relationships & Data Flow
    Dependencies -->|"listed deps"| ContextManager
    ContextManager -->|"creates window\n& context"| RenderLoop
    InputHandler -->|"scroll input"| RenderLoop
    InputHandler -->|"updates uniforms"| ShaderManager
    ResourceLoader -->|"reads .glsl source"| ShaderManager
    ResourceLoader -->|"loads texture image"| Textures
    ShaderManager -->|"compiles & links"| GPUHardware
    RenderLoop -->|"draw call"| VertexShader
    VertexShader -->|"full-screen primitive"| FragmentShader
    FragmentShader -->|"executes ray-marching"| SceneSDF
    SceneSDF -->|"SDF eval calls"| HGSDF
    HGSDF -->|"geometry definitions"| MaterialModule
    MaterialModule -->|"shading & AA"| Framebuffer
    GPUHardware --> Framebuffer
    Framebuffer -->|"frame buffer output"| WindowSystem

    %% Click Events
    click ContextManager "https://github.com/stanislavpetrovv/advanced_raymarching/blob/main/main.py"
    click InputHandler "https://github.com/stanislavpetrovv/advanced_raymarching/blob/main/main.py"
    click ResourceLoader "https://github.com/stanislavpetrovv/advanced_raymarching/blob/main/main.py"
    click ShaderManager "https://github.com/stanislavpetrovv/advanced_raymarching/blob/main/main.py"
    click RenderLoop "https://github.com/stanislavpetrovv/advanced_raymarching/blob/main/main.py"
    click Dependencies "https://github.com/stanislavpetrovv/advanced_raymarching/blob/main/requirements.txt"
    click VertexShader "https://github.com/stanislavpetrovv/advanced_raymarching/blob/main/programs/vertex.glsl"
    click FragmentShader "https://github.com/stanislavpetrovv/advanced_raymarching/blob/main/programs/fragment.glsl"
    click SceneSDF "https://github.com/stanislavpetrovv/advanced_raymarching/blob/main/programs/map.glsl"
    click HGSDF "https://github.com/stanislavpetrovv/advanced_raymarching/blob/main/programs/hg_sdf.glsl"
    click MaterialModule "https://github.com/stanislavpetrovv/advanced_raymarching/blob/main/programs/material.glsl"
    click Textures "https://github.com/stanislavpetrovv/advanced_raymarching/tree/main/textures/roof"
    click Screenshots "https://github.com/stanislavpetrovv/advanced_raymarching/tree/main/screenshots/"
    click Metadata "https://github.com/stanislavpetrovv/advanced_raymarching/blob/main/README.md"
    click Metadata "https://github.com/stanislavpetrovv/advanced_raymarching/tree/main/LICENSE"

    %% Styles
    classDef cpu fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef gpu fill:#c8e6c9,stroke:#43a047,color:#1b5e20;
    classDef io fill:#ffe0b2,stroke:#fb8c00,color:#e65100;
    classDef ext fill:#d7ccc8,stroke:#6d4c41,color:#3e2723;
```
