# city-super/gsdf architecture

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

- Interactive diagram: https://gitdiagram.com/city-super/gsdf
- Repository: https://github.com/city-super/gsdf

## Overview

##### Project type and purpose
- GSDF is a dual‐branch neural rendering and reconstruction framework combining 3D Gaussian Splatting (“GS branch” under `gaussian_splatting/…`) and neural Signed Distance Fields (“SDF branch” under `instant_nsr/…`).
- Its goal is joint training of two complementary scene representations, with mutual guidance to improve both rendering quality and geometric reconstruction.

##### File structure
- Top‐level scripts:
- `train.py`/`render.py`/`metrics.py`/`launch.py` orchestrate training, rendering, and evaluation.
- `configs/…` contains YAML configs for datasets and experiments.
- Core packages:
- `gaussian_splatting/…` implements the GS branch: argument parsing, gaussian renderer, scene loader, LPIPS module, and two C++/CUDA submodules (`diff-gaussian-rasterization` and `simple-knn`).
- `instant_nsr/…` implements the SDF branch: dataset loaders, model definitions (NeRF/SDF), training systems (criterions, optimizers), and supporting utilities.
- `utils/…` modules are duplicated under both branches, providing camera, image, kernel‐grid, loss, and visualization utilities.
- External dependencies: PyTorch, CUDA, CMake, Colmap outputs, optional `tiny-cuda-nn`.

##### README for additional insights
- Provides a high‐level “pipeline.png” showing data feeding into GS and SDF, joint supervision, and final outputs (renderings and geometry).
- Specifies data organization under a `data/` folder, and training/evaluation commands.

##### Elements
- Green for SDF branch components
- Gray for common utilities
- Orange for C++/CUDA submodules

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Ingestion"
        DATA["Raw Images + SfM Outputs"]:::data
    end

    subgraph "Config Manager"
        CONFIG["YAML Configs (configs/)"]:::config
    end

    subgraph "GS Branch"
        GS_ARG["Argument Parser"]:::gs
        COLMAP_LOADER["Colmap Loader"]:::gs
        GS_RENDERER["GS Renderer"]:::gs
        CUDA_RAST["C++/CUDA Rasterizer"]:::submod
        KNN["K-NN Submodule"]:::submod
        LPIPS["LPIPS Module"]:::gs
    end

    subgraph "SDF Branch"
        SDF_LOAD["SDF Data Loaders"]:::sdf
        SDF_MODEL["SDF & NeRF Models"]:::sdf
        SDF_SYSTEM["Training Systems"]:::sdf
    end

    subgraph "Common Utils"
        UTIL_GS["GS Utils"]:::util
        UTIL_SDF["SDF Utils"]:::util
    end

    subgraph "Scripts & Evaluation"
        TRAIN["train.py"]:::script
        RENDER["render.py"]:::script
        METRICS["metrics.py"]:::script
        LAUNCH["launch.py"]:::script
    end

    OUTPUTS["Outputs (models, logs)"]:::outputs

    DATA --> COLMAP_LOADER
    DATA --> SDF_LOAD
    CONFIG -.-> GS_ARG
    CONFIG -.-> SDF_LOAD

    GS_ARG --> COLMAP_LOADER
    COLMAP_LOADER --> GS_RENDERER
    GS_RENDERER --> CUDA_RAST
    GS_RENDERER --> KNN
    GS_RENDERER --> LPIPS

    SDF_LOAD --> SDF_MODEL
    SDF_MODEL --> SDF_SYSTEM
    SDF_SYSTEM --> SDF_MODEL

    GS_RENDERER <-->|"mutual guidance & joint loss"| SDF_SYSTEM

    GS_RENDERER --> TRAIN
    SDF_SYSTEM --> TRAIN
    GS_RENDERER --> RENDER
    SDF_SYSTEM --> RENDER

    TRAIN --> OUTPUTS
    RENDER --> METRICS
    METRICS --> OUTPUTS

    click COLMAP_LOADER "https://github.com/city-super/gsdf/blob/main/gaussian_splatting/scene/colmap_loader.py"
    click SDF_LOAD "https://github.com/city-super/gsdf/blob/main/instant_nsr/datasets/colmap.py"
    click CONFIG "https://github.com/city-super/gsdf/tree/main/configs/"
    click GS_ARG "https://github.com/city-super/gsdf/blob/main/gaussian_splatting/arguments/__init__.py"
    click GS_RENDERER "https://github.com/city-super/gsdf/blob/main/gaussian_splatting/gaussian_renderer/network_gui.py"
    click CUDA_RAST "https://github.com/city-super/gsdf/tree/main/gaussian_splatting/submodules/diff-gaussian-rasterization/"
    click KNN "https://github.com/city-super/gsdf/tree/main/gaussian_splatting/submodules/simple-knn/"
    click LPIPS "https://github.com/city-super/gsdf/blob/main/gaussian_splatting/lpipsPyTorch/modules/lpips.py"
    click SDF_MODEL "https://github.com/city-super/gsdf/tree/main/instant_nsr/models/"
    click SDF_SYSTEM "https://github.com/city-super/gsdf/tree/main/instant_nsr/systems/"
    click UTIL_GS "https://github.com/city-super/gsdf/tree/main/gaussian_splatting/utils/"
    click UTIL_SDF "https://github.com/city-super/gsdf/tree/main/instant_nsr/utils/"
    click TRAIN "https://github.com/city-super/gsdf/blob/main/train.py"
    click RENDER "https://github.com/city-super/gsdf/blob/main/render.py"
    click METRICS "https://github.com/city-super/gsdf/blob/main/metrics.py"
    click LAUNCH "https://github.com/city-super/gsdf/blob/main/launch.py"

    classDef data fill:#fac,stroke:#333;
    classDef config fill:#ccc,stroke:#333;
    classDef gs fill:#cce5ff,stroke:#333;
    classDef sdf fill:#d4edda,stroke:#333;
    classDef submod fill:#ffe5b4,stroke:#333;
    classDef util fill:#e0e0e0,stroke:#333;
    classDef script fill:#e2ccff,stroke:#333;
    classDef outputs fill:#fff3cd,stroke:#333;
```
