# half-potato/ever_training architecture

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

- Interactive diagram: https://gitdiagram.com/half-potato/ever_training
- Repository: https://github.com/half-potato/ever_training

## Overview

##### Project Type and Purpose
- This project implements a real-time differentiable emission-only volume rendering approach based on “Exact Volumetric Ellipsoid Rendering” (EVER). Its purpose is to train, render, and evaluate 3D scenes using a primitive-based, exactly computed volume rendering method, offering advantages over methods like 3D Gaussian Splatting.
- The README emphasizes high-performance rendering (∼30 FPS) on high-end hardware, support for advanced camera effects (defocus blur, distortion), and integrations with interactive remote viewers (SIBR).

##### Analyzing the File Structure
- Top-level files and directories:
- Multiple scripts for training (train.py), rendering (render.py), evaluation (metrics.py, full_eval.py, partial_eval.py), and hosting an interactive render server (host_render_server.py).
- Dedicated directories such as “arguments” (handling command line arguments), “gaussian_renderer” (likely containing rendering related modules including a special “ever.py”), “scene” (managing camera selection, dataset readers, and scene-related processing), “lpipsPyTorch” (for perceptual similarity measurements) and “utils” (providing general, camera, graphics, math, and system utilities).
- Other directories and submodules (e.g., “SIBR_viewers” for remote viewing and “submodules/simple-knn”) indicate that the system leverages well-separated components.

##### Key Components of the System and Their Relationships
a. Data Input & Dataset Processing:
- Dataset readers and loaders in the “scene” directory (colmap_loader.py, dataset_readers.py) manage input from COLMAP, NeRF Synthetic, and Zip-NeRF data.
- Scripts like "convert.py" and "extract_metadata.py" likely process or extract metadata from scene data.
b. Training Module:
- The training process is managed by train.py, which relies on modules from “scene”, “arguments”, and the “utils” packages.
- Training involves computing a volumetric model (note files such as scene/gaussian_model.py) using real-time differentiable volume rendering.
c. Rendering Pipeline:
- The render.py script, along with additional utilities, is focused on generating view synthesis renderings from a trained model.
- Canvas elements from the “gaussian_renderer” (such as fast_renderer.py and network_gui.py) are critical here.
d. Evaluation & Metrics:
- Evaluation workflows include metrics.py, full_eval.py, and partial_eval.py. These evaluate rendering errors and measure performance (like FPS with measure_fps.py) and perceptual quality (via lpipsPyTorch).
e. Interactive Viewing:
- The hosting of an interactive server via host_render_server.py for using SIBR remote viewers is another key component.
- The SIBR_viewers directory and provided instructions in the README show how the server connects with external viewer applications.
f. Supporting Utilities and Submodules:
- Generic utilities in the “utils” directory support camera operations (including specific variants like camera_utils_zipnerf.py), graphics, math, and system-level operations.
- The “arguments” directory and configuration scripts (like install.bash and run.sh) standardize the command-line setting and deployment aspects.
- The “submodules” folder indicates additional 3rd-party (or homemade) components like the simple-knn implementation, which might be used for some geometric processing.

##### Architectural Patterns and Technology Stack
- Architectural Patterns:
- Separation of concerns: distinct modules for training, rendering, evaluation and interactive viewing.
- A modular design that separates scene/data processing, rendering engine (gaussian_renderer), and client/server interactive viewer (using SIBR protocol).
- Command-line driven configuration using the “arguments” modules enhances flexibility.
- Technologies and Dependencies:
- The project uses NVIDIA’s OptiX for ray tracing, and SlangD for shader compilation.
- PyTorch is used for deep learning aspects (notably during training and evaluation).
- Additional libraries include OpenCV, GLFW, Eigen, and others as provided in the dependency list.
- The integration with SIBR indicates standardized viewer protocols/messaging.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Input & Dataset Processing
    subgraph "1. Data Input & Dataset Processing"
        DI1["Colmap Loader"]:::data
        DI2["Dataset Readers"]:::data
        DI3["Convert Script"]:::data
        DI4["Extract Metadata"]:::data
    end

    %% Training Module
    subgraph "2. Training Module"
        TR1["Training Script"]:::training
        TR2["Gaussian Model"]:::training
        TR3["Arguments"]:::utility
    end

    %% Rendering Pipeline
    subgraph "3. Rendering Pipeline"
        RE1["Render Script"]:::rendering
        RE2["EVER Renderer"]:::rendering
        RE3["Fast Renderer"]:::rendering
        RE4["Network GUI"]:::rendering
    end

    %% Evaluation & Metrics
    subgraph "4. Evaluation & Metrics"
        EV1["Metrics"]:::evaluation
        EV2["Full Evaluation"]:::evaluation
        EV3["Partial Evaluation"]:::evaluation
        EV4["FPS Measurement"]:::evaluation
        EV5["LPIPS"]:::evaluation
    end

    %% Interactive Viewing
    subgraph "5. Interactive Viewing"
        IV1["Render Server"]:::viewer
        IV2["SIBR Viewers"]:::viewer
    end

    %% Supporting Utilities & Submodules
    subgraph "6. Supporting Utilities & Submodules"
        UT1["Utilities"]:::utility
        UT2["Simple KNN"]:::utility
    end

    %% Data flow arrows
    DI1 -->|"feeds"| TR1
    DI2 -->|"feeds"| TR1
    DI3 -->|"feeds"| TR1
    DI4 -->|"feeds"| TR1

    TR1 -->|"trainsModel"| TR2
    TR1 -->|"suppliesModel"| RE1
    TR1 -->|"evaluationData"| EV1
    TR1 -->|"evaluationData"| EV2
    TR1 -->|"evaluationData"| EV3
    TR1 -->|"evaluationData"| EV4
    TR1 -->|"evaluationData"| EV5

    RE1 -->|"streaming"| IV1

    %% Supporting Utilities dotted connections
    UT1 -.-> TR1
    UT1 -.-> RE1
    UT1 -.-> EV1
    UT1 -.-> IV1
    UT2 -.-> TR1

    %% Click Events
    click DI1 "https://github.com/half-potato/ever_training/blob/master/scene/colmap_loader.py"
    click DI2 "https://github.com/half-potato/ever_training/blob/master/scene/dataset_readers.py"
    click DI3 "https://github.com/half-potato/ever_training/blob/master/convert.py"
    click DI4 "https://github.com/half-potato/ever_training/blob/master/extract_metadata.py"
    click TR1 "https://github.com/half-potato/ever_training/blob/master/train.py"
    click TR2 "https://github.com/half-potato/ever_training/blob/master/scene/gaussian_model.py"
    click TR3 "https://github.com/half-potato/ever_training/tree/master/arguments"
    click RE1 "https://github.com/half-potato/ever_training/blob/master/render.py"
    click RE2 "https://github.com/half-potato/ever_training/blob/master/gaussian_renderer/ever.py"
    click RE3 "https://github.com/half-potato/ever_training/blob/master/gaussian_renderer/fast_renderer.py"
    click RE4 "https://github.com/half-potato/ever_training/blob/master/gaussian_renderer/network_gui.py"
    click EV1 "https://github.com/half-potato/ever_training/blob/master/metrics.py"
    click EV2 "https://github.com/half-potato/ever_training/blob/master/full_eval.py"
    click EV3 "https://github.com/half-potato/ever_training/blob/master/partial_eval.py"
    click EV4 "https://github.com/half-potato/ever_training/blob/master/measure_fps.py"
    click EV5 "https://github.com/half-potato/ever_training/tree/master/lpipsPyTorch"
    click IV1 "https://github.com/half-potato/ever_training/blob/master/host_render_server.py"
    click IV2 "https://github.com/half-potato/ever_training/tree/master/SIBR_viewers"
    click UT1 "https://github.com/half-potato/ever_training/tree/master/utils"
    click UT2 "https://github.com/half-potato/ever_training/tree/master/submodules/simple-knn"

    %% Styles
    classDef data fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef training fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef rendering fill:#cce5ff,stroke:#0066cc,stroke-width:2px;
    classDef evaluation fill:#ffe6cc,stroke:#ff9900,stroke-width:2px;
    classDef viewer fill:#e6ccff,stroke:#9933ff,stroke-width:2px;
    classDef utility fill:#f2f2f2,stroke:#666666,stroke-width:2px;
```
