# compvis/edgs architecture

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

- Interactive diagram: https://gitdiagram.com/compvis/edgs
- Repository: https://github.com/compvis/edgs

## Overview

##### Project Type and Purpose
- EDGS is an open-source research codebase for efficient 3D scene reconstruction using Gaussian Splatting. It provides both a CLI/Notebook training pipeline and a Gradio‐based interactive demo.

##### File Structure Analysis
- Top-level scripts:
- train.py, full_eval.py – training and evaluation entrypoints
- gradio_demo.py – launches interactive web demo
- install.sh – environment setup
- Directories:
- configs/ – Hydra YAML configurations
- source/ – core implementation (initialization, training, networks, losses, utils)
- submodules/gaussian-splatting & submodules/RoMa – third-party libs for rasterization and correspondence models
- notebooks/ – example Jupyter workflow
- assets/ – media examples and GIFs
- Key patterns:
- Hydra config management
- Modular pipeline: preprocessing → initialization → training → evaluation → visualization
- External dependencies: pycolmap, PyTorch, WandB, Gradio

##### High-Level Components
a. Data Layer (Input/Output)
- Input sources:
- Local dataset folders (images + COLMAP sparse)
- Single video file ingestion
- Outputs:
- Trained Gaussian model files
- Rendered videos/previews
- Logs/metrics
b. Preprocessing Module
- COLMAP / pycolmap wrapper (source/utils_preprocess.py)
- Image/video → camera poses + sparse point cloud
c. Initialization Module
- corr_init (source/corr_init.py)
- Uses RoMa submodule to extract 2D correspondences and initialize Gaussians
d. Training Engine
- trainer (source/trainer.py) orchestrates epochs
- networks (source/networks.py) defines UDFs for Gaussian Splatting
- losses (source/losses.py), data_utils, timer
- Hydra config injection (`train.gs_epochs`, `train.no_densify`, etc.)
e. Evaluation Module
- full_eval.py calls metrics.py across datasets
f. Visualization & Demo
- source/visualization.py for plots and Open3D previews
- gradio_demo.py provides frontend (Gradio)
g. Configuration Manager
- Hydra (configs/base.yaml, train.yaml) drives parameterization
h. External Services & Libraries
- WandB for logging (optional)
- Hugging Face Spaces for hosted demo
- GPU/CUDA runtime environment

##### Relationships and Data Flow
User → (CLI / Notebook / Gradio) → Preprocessing → Initialization → Training → Evaluation → Visualization → User
- Config Manager ties into each module to supply parameters
- Logging service (WandB) receives data from Training and Evaluation
- Submodules are dependencies of Initialization and Training blocks

##### Architectural Patterns & Design Principles
- Modular pipeline stages (separation of concerns)
- Config-driven execution (Hydra) for reproducibility
- Plugin architecture via submodules (gaussian-splatting, RoMa)
- Multi-interface support (CLI, Notebook, Web UI)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interfaces
    subgraph "User Interfaces"
        direction TB
        CLI("CLI\n(train.py, full_eval.py)"):::ui
        Notebook("Notebook\n(fit_model_to_scene_full.ipynb)"):::ui
        WebUI("Web UI\n(gradio_demo.py)"):::ui
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DataIn["Datasets & Video"]:::data
        DataOut["Outputs:\nTrained Models,\nRendered Videos,\nLogs/Metrics"]:::data
    end

    %% Core Modules
    subgraph "Core Pipeline" 
        direction TB
        Preprocess("Preprocessing\n(pycolmap wrapper)"):::core
        Init("Initialization\n(corr_init & RoMa)"):::core
        Train("Training Engine"):::core
        Eval("Evaluation Module"):::core
        Visual("Visualization & Demo"):::core
    end

    %% Configuration Manager
    Config["Config (Hydra)"]:::config

    %% External Services and Submodules
    subgraph "External Services & Submodules"
        direction TB
        WandB("WandB Logging"):::external
        HFS("Hugging Face Spaces"):::external
        GPU("GPU/CUDA Runtime"):::external
        subgraph "Third-Party Libraries (dashed)" 
            direction TB
            GS("gaussian-splatting"):::submod
            RoMa("RoMa"):::submod
        end
    end

    %% Flows
    CLI -->|runs| Preprocess
    Notebook -->|runs| Preprocess
    WebUI -->|starts| Visual

    DataIn -->|images + poses| Preprocess
    Preprocess -->|camera poses + sparse cloud| Init
    Init -->|initialized Gaussians| Train
    Train -->|trained model + metrics| Eval
    Eval -->|evaluation metrics| Visual
    Visual -->|renders previews| DataOut
    Visual -->|serves demo| WebUI

    Config --> Preprocess
    Config --> Init
    Config --> Train
    Config --> Eval
    Config --> Visual

    Train -->|logs| WandB
    Eval -->|logs| WandB
    WebUI -->|hosted on| HFS

    Init --> GS
    Init --> RoMa
    Train --> GS
    Train --> RoMa

    %% Click Events
    click CLI "https://github.com/compvis/edgs/blob/main/train.py"
    click CLI "https://github.com/compvis/edgs/blob/main/full_eval.py"
    click Notebook "https://github.com/compvis/edgs/blob/main/notebooks/fit_model_to_scene_full.ipynb"
    click WebUI "https://github.com/compvis/edgs/blob/main/gradio_demo.py"
    click DataIn "https://github.com/compvis/edgs/tree/main/assets/examples"
    click Preprocess "https://github.com/compvis/edgs/blob/main/source/utils_preprocess.py"
    click Init "https://github.com/compvis/edgs/blob/main/source/corr_init.py"
    click RoMa "https://github.com/compvis/edgs/tree/main/submodules/RoMa/"
    click GS "https://github.com/compvis/edgs/tree/main/submodules/gaussian-splatting/"
    click Train "https://github.com/compvis/edgs/blob/main/train.py"
    click Train "https://github.com/compvis/edgs/blob/main/source/trainer.py"
    click Train "https://github.com/compvis/edgs/blob/main/source/networks.py"
    click Train "https://github.com/compvis/edgs/blob/main/source/losses.py"
    click Train "https://github.com/compvis/edgs/blob/main/source/data_utils.py"
    click Train "https://github.com/compvis/edgs/blob/main/source/timer.py"
    click Eval "https://github.com/compvis/edgs/blob/main/full_eval.py"
    click Eval "https://github.com/compvis/edgs/blob/main/metrics.py"
    click Visual "https://github.com/compvis/edgs/blob/main/source/visualization.py"
    click Visual "https://github.com/compvis/edgs/blob/main/gradio_demo.py"
    click Config "https://github.com/compvis/edgs/blob/main/configs/gs/base.yaml"
    click Config "https://github.com/compvis/edgs/blob/main/configs/train.yaml"

    %% Styles
    classDef core fill:#D6EAF8,stroke:#21618C,color:#154360;
    classDef data fill:#D5F5E3,stroke:#239B56,color:#186A3B,stroke-dasharray: 5 5;
    classDef external fill:#FDEBD0,stroke:#D35400,color:#A04000;
    classDef ui fill:#FCF3CF,stroke:#B7950B,color:#7D6608,stroke-width:2px;
    classDef config fill:#E8DAEF,stroke:#8E44AD,color:#6C3483;
    classDef submod fill:#F4F6F7,stroke:#566573,color:#2E4053,stroke-dasharray: 2 2;
```
