# hypothete/unstructured-lumigraph architecture

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

- Interactive diagram: https://gitdiagram.com/hypothete/unstructured-lumigraph
- Repository: https://github.com/hypothete/unstructured-lumigraph

## Overview

##### Project type and purpose
- This is a client-side WebGL “single-page” application that implements the “Unstructured Lumigraph Rendering” algorithm in the browser.
- Purpose: load a multi-view dataset (images + camera poses + proxy mesh), build a Three.js scene, and synthesize novel views by blending camera rays with custom GLSL shaders.

##### File structure
- Top level
- index.html – entry point
- app.js – main application logic
- styles.css – minimal CSS
- vertex.glsl / fragment.glsl – custom GLSL shader programs
- vendor/ – third-party libs (Three.js, shader utilities)
- data/ – four sample datasets (cube, kettle, statue, TV) each with images.txt, cameras.txt, images/, proxy geometry
- package.json – dev scripts (`yarn start` spins up a static HTTP server)
- Patterns
- Single‐Page App: all assets are static, served over HTTP
- Modular code in app.js: Data loader → Scene builder → Renderer → UI controls
- Shaders separate GPU logic (vertex + fragment) from JS orchestration

##### Key insights from README
- A static server (e.g. via `yarn start`) serves HTML, JS, shaders, data.
- User interaction: mouse + keyboard drive a camera controller.
- Datasets follow a uniform folder structure, and app.js contains hooks to parse cameras.txt and images.txt.

##### Main components & interactions
A. Static HTTP Server
- Serves index.html, app.js, CSS, GLSL files, vendor libs, dataset files
B. Client (Browser)
1. Loader Module (in app.js)
– Fetches datasets: cameras.txt, images.txt, proxy.obj, image textures
2. Scene Graph (Three.js)
– Builds mesh (proxy geometry), texture materials, camera frustums
3. Renderer (Three.js + WebGL)
– Compiles vertex.glsl & fragment.glsl into GPU shader programs
4. UI Controller
– Listens for mouse & keyboard, updates Three.js camera parameters
C. GPU Shader Programs
- Vertex Shader: transforms proxy mesh
- Fragment Shader: samples multiple camera textures, computes lumigraph blending
D. Data Store (Filesystem)
- data/<dataset>/{images.txt, cameras.txt, images/, proxy.obj}
E. External Dependencies
- Three.js (in vendor/)
- GLSL utilities (bubble sort, fovBlend code)

##### Architectural patterns & design principles
- Modular separation:
- Data layer (static files + loader)
- Logic layer (app.js modules: DataLoader, SceneBuilder, Renderer, InputHandler)
- Presentation layer (WebGL/GLSL shaders)
- Single‐page, event‐driven render loop pattern
- Dependency injection of dataset name via URL query param
- Reuse of Three.js scene graph for camera & mesh management

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Static Server Layer
    subgraph "Static HTTP Server" 
        direction TB
        SS_HTML["index.html"]:::server
        SS_PKG["package.json"]:::server
    end

    %% Data Store Layer
    subgraph "Data Store (Filesystem)" 
        direction TB
        DS_CUBE["data/cube/"]:::datastore
        DS_KETTLE["data/kettle/"]:::datastore
        DS_STATUE["data/statue/"]:::datastore
        DS_TV["data/tv/"]:::datastore
    end

    %% Browser Layer
    subgraph "Browser (Client)" 
        direction TB
        subgraph "Modules"
            direction TB
            DL["DataLoader"]:::browser
            SG["SceneGraph"]:::browser
            REND["Renderer"]:::browser
            UI["UIController"]:::browser
        end
        subgraph "Shader Programs"
            direction TB
            VS["Vertex Shader"]:::shader
            FS["Fragment Shader"]:::shader
        end
        subgraph "External Dependencies"
            direction TB
            THREE["Three.js"]:::external
            GLSL_UTIL["GLSL Utilities"]:::external
        end
    end

    %% Connections: HTTP GET
    DL -->|GET index.html| SS_HTML
    DL -->|GET app.js & shaders| SS_PKG
    DL -->|GET dataset files| DS_CUBE
    DL -->|GET dataset files| DS_KETTLE
    DL -->|GET dataset files| DS_STATUE
    DL -->|GET dataset files| DS_TV

    %% Data flow inside Browser
    DL -->|"parsed geometry & textures"| SG
    SG -->|"scene graph objects"| REND
    UI -.->|"mouse & keyboard events"| UI
    UI -->|"update camera params"| SG
    UI -->|"trigger render"| REND
    REND -->|"compile shaders"| VS
    REND -->|"compile shaders"| FS
    REND -->|"use shader programs"| VS
    REND -->|"use shader programs"| FS

    %% External deps
    THREE --> SG
    THREE --> REND
    GLSL_UTIL --> VS
    GLSL_UTIL --> FS

    %% Click Events
    click SS_HTML "https://github.com/hypothete/unstructured-lumigraph/blob/main/index.html"
    click SS_PKG "https://github.com/hypothete/unstructured-lumigraph/blob/main/package.json"
    click DL "https://github.com/hypothete/unstructured-lumigraph/blob/main/app.js"
    click SG "https://github.com/hypothete/unstructured-lumigraph/tree/main/vendor/"
    click REND "https://github.com/hypothete/unstructured-lumigraph/blob/main/app.js"
    click UI "https://github.com/hypothete/unstructured-lumigraph/blob/main/app.js"
    click VS "https://github.com/hypothete/unstructured-lumigraph/blob/main/vertex.glsl"
    click FS "https://github.com/hypothete/unstructured-lumigraph/blob/main/fragment.glsl"
    click DS_CUBE "https://github.com/hypothete/unstructured-lumigraph/tree/main/data/cube/"
    click DS_KETTLE "https://github.com/hypothete/unstructured-lumigraph/tree/main/data/kettle/"
    click DS_STATUE "https://github.com/hypothete/unstructured-lumigraph/tree/main/data/statue/"
    click DS_TV "https://github.com/hypothete/unstructured-lumigraph/tree/main/data/tv/"
    click GLSL_UTIL "https://github.com/hypothete/unstructured-lumigraph/tree/main/vendor/"

    %% Styles
    classDef server fill:#c8e6c9,stroke:#2e7d32,color:#2e7d32;
    classDef datastore fill:#e8f5e9,stroke:#388e3c,color:#388e3c;
    classDef browser fill:#bbdefb,stroke:#1976d2,color:#0d47a1;
    classDef shader fill:#fff9c4,stroke:#fbc02d,color:#f57f17;
    classDef external fill:#ffe0b2,stroke:#fb8c00,color:#e65100;
```
