# zju3dv/pgsr architecture

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

- Interactive diagram: https://gitdiagram.com/zju3dv/pgsr
- Repository: https://github.com/zju3dv/pgsr

## Overview

PGSR reconstructs surfaces from multi-view RGB imagery using planar Gaussian splatting. The primary workflow prepares a dataset, loads camera and scene data, trains an adaptive Gaussian representation, then renders views and extracts a mesh; DTU and Tanks and Temples evaluation are additional product branches. The source index supports the principal training, scene, renderer, and rasterization links. Several dataset-specific scripts are not sampled, so their internal calls are not asserted.

Main entry points: [`train.py`](https://github.com/zju3dv/pgsr/blob/main/train.py) (Training loop), [`gaussian_renderer/__init__.py`](https://github.com/zju3dv/pgsr/blob/main/gaussian_renderer/__init__.py) (Plane renderer), [`scene/__init__.py`](https://github.com/zju3dv/pgsr/blob/main/scene/__init__.py) (Scene and cameras), [`scene/gaussian_model.py`](https://github.com/zju3dv/pgsr/blob/main/scene/gaussian_model.py) (Gaussian model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Dataset preparation"]
  node_convert["Dataset conversion<br/>[convert.py]"]
  node_tntconvert["TnT conversion<br/>[convert_tnt.py]"]
end

subgraph group_core["Reconstruction runtime"]
  node_dataset["Scene readers<br/>[dataset_readers.py]"]
  node_colmap["COLMAP loader<br/>[colmap_loader.py]"]
  node_scene["Scene and cameras<br/>[__init__.py]"]
  node_camera["Camera utilities<br/>[camera_utils.py]"]
  node_camera_model["Camera model<br/>[cameras.py]"]
  node_train["Training loop<br/>[train.py]"]
  node_model["Gaussian model<br/>[gaussian_model.py]"]
  node_loss["Training losses<br/>[loss_utils.py]"]
  node_graphics["Geometry utilities<br/>[graphics_utils.py]"]
  node_general["Optimization utilities<br/>[general_utils.py]"]
  node_sh["Spherical harmonics<br/>[sh_utils.py]"]
end

subgraph group_render["Rendering and export"]
  node_renderer["Plane renderer<br/>[__init__.py]"]
  node_rasterizer["Differentiable rasterizer<br/>[__init__.py]"]
  node_raster_api["Rasterization API<br/>[rasterize_points.h]"]
  node_render_export["Render and mesh export<br/>[render.py]"]
  node_tnt_render["TnT rendering<br/>[render_tnt.py]"]
end

subgraph group_eval["Evaluation"]
  node_metrics["Image metrics<br/>[metrics.py]"]
  node_dtu_eval["DTU evaluation<br/>[eval.py]"]
  node_tnt_eval["TnT evaluation<br/>[evaluation.py]"]
  node_lpips["LPIPS metric<br/>[networks.py]"]
end

node_user(("Researcher"))
node_input["Multi-view images"]

node_user -->|"prepares data"| node_convert
node_user -->|"prepares TnT"| node_tntconvert
node_input -->|"converts images"| node_convert
node_convert -.->|"produces scene data"| node_dataset
node_tntconvert -.->|"produces scene data"| node_dataset
node_dataset -->|"loads reconstruction"| node_colmap
node_scene -->|"loads scene info"| node_dataset
node_scene -->|"builds cameras"| node_camera
node_camera -.->|"constructs"| node_camera_model
node_user -->|"starts training"| node_train
node_train -->|"creates scene"| node_scene
node_train -->|"optimizes representation"| node_model
node_train -->|"renders training views"| node_renderer
node_train -->|"computes objectives"| node_loss
node_train -->|"warps patches"| node_graphics
node_model -->|"uses transforms"| node_general
node_model -->|"uses harmonics"| node_sh
node_renderer -->|"reads Gaussians"| node_model
node_renderer -.->|"reads camera"| node_camera_model
node_renderer -->|"rasterizes"| node_rasterizer
node_rasterizer -->|"calls CUDA API"| node_raster_api
node_user -->|"renders and exports"| node_render_export
node_render_export -->|"loads saved scene"| node_scene
node_render_export -->|"renders views"| node_renderer
node_user -->|"renders TnT"| node_tnt_render
node_tnt_render -->|"loads scene"| node_scene
node_tnt_render -->|"renders views"| node_renderer
node_user -->|"evaluates reconstruction"| node_dtu_eval
node_user -->|"evaluates reconstruction"| node_tnt_eval
node_metrics -->|"uses features"| node_lpips

click node_convert "https://github.com/zju3dv/pgsr/blob/main/scripts/preprocess/convert.py"
click node_tntconvert "https://github.com/zju3dv/pgsr/blob/main/scripts/preprocess/convert_tnt.py"
click node_dataset "https://github.com/zju3dv/pgsr/blob/main/scene/dataset_readers.py"
click node_colmap "https://github.com/zju3dv/pgsr/blob/main/scene/colmap_loader.py"
click node_scene "https://github.com/zju3dv/pgsr/blob/main/scene/__init__.py"
click node_camera "https://github.com/zju3dv/pgsr/blob/main/utils/camera_utils.py"
click node_camera_model "https://github.com/zju3dv/pgsr/blob/main/scene/cameras.py"
click node_train "https://github.com/zju3dv/pgsr/blob/main/train.py"
click node_model "https://github.com/zju3dv/pgsr/blob/main/scene/gaussian_model.py"
click node_loss "https://github.com/zju3dv/pgsr/blob/main/utils/loss_utils.py"
click node_graphics "https://github.com/zju3dv/pgsr/blob/main/utils/graphics_utils.py"
click node_general "https://github.com/zju3dv/pgsr/blob/main/utils/general_utils.py"
click node_sh "https://github.com/zju3dv/pgsr/blob/main/utils/sh_utils.py"
click node_renderer "https://github.com/zju3dv/pgsr/blob/main/gaussian_renderer/__init__.py"
click node_rasterizer "https://github.com/zju3dv/pgsr/blob/main/submodules/diff-plane-rasterization/diff_plane_rasterization/__init__.py"
click node_raster_api "https://github.com/zju3dv/pgsr/blob/main/submodules/diff-plane-rasterization/rasterize_points.h"
click node_render_export "https://github.com/zju3dv/pgsr/blob/main/render.py"
click node_tnt_render "https://github.com/zju3dv/pgsr/blob/main/scripts/render_tnt.py"
click node_metrics "https://github.com/zju3dv/pgsr/blob/main/metrics.py"
click node_dtu_eval "https://github.com/zju3dv/pgsr/blob/main/scripts/eval_dtu/eval.py"
click node_tnt_eval "https://github.com/zju3dv/pgsr/blob/main/scripts/tnt_eval/evaluation.py"
click node_lpips "https://github.com/zju3dv/pgsr/blob/main/lpipsPyTorch/modules/networks.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_convert,node_tntconvert,node_input toneBlue
class node_dataset,node_colmap,node_scene,node_camera,node_camera_model,node_train,node_model,node_loss,node_graphics,node_general,node_sh toneAmber
class node_renderer,node_rasterizer,node_raster_api,node_render_export,node_tnt_render toneMint
class node_metrics,node_dtu_eval,node_tnt_eval,node_lpips toneRose
class node_user toneIndigo
```

## Components

### Dataset preparation

- [Dataset conversion](https://github.com/zju3dv/pgsr/blob/main/scripts/preprocess/convert.py): `scripts/preprocess/convert.py`
- [TnT conversion](https://github.com/zju3dv/pgsr/blob/main/scripts/preprocess/convert_tnt.py): `scripts/preprocess/convert_tnt.py`

### Reconstruction runtime

- [Scene readers](https://github.com/zju3dv/pgsr/blob/main/scene/dataset_readers.py): `scene/dataset_readers.py`
- [COLMAP loader](https://github.com/zju3dv/pgsr/blob/main/scene/colmap_loader.py): `scene/colmap_loader.py`
- [Scene and cameras](https://github.com/zju3dv/pgsr/blob/main/scene/__init__.py): `scene/__init__.py`
- [Camera utilities](https://github.com/zju3dv/pgsr/blob/main/utils/camera_utils.py): `utils/camera_utils.py`
- [Camera model](https://github.com/zju3dv/pgsr/blob/main/scene/cameras.py): `scene/cameras.py`
- [Training loop](https://github.com/zju3dv/pgsr/blob/main/train.py): `train.py`
- [Gaussian model](https://github.com/zju3dv/pgsr/blob/main/scene/gaussian_model.py): `scene/gaussian_model.py`
- [Training losses](https://github.com/zju3dv/pgsr/blob/main/utils/loss_utils.py): `utils/loss_utils.py`
- [Geometry utilities](https://github.com/zju3dv/pgsr/blob/main/utils/graphics_utils.py): `utils/graphics_utils.py`
- [Optimization utilities](https://github.com/zju3dv/pgsr/blob/main/utils/general_utils.py): `utils/general_utils.py`
- [Spherical harmonics](https://github.com/zju3dv/pgsr/blob/main/utils/sh_utils.py): `utils/sh_utils.py`

### Rendering and export

- [Plane renderer](https://github.com/zju3dv/pgsr/blob/main/gaussian_renderer/__init__.py): `gaussian_renderer/__init__.py`
- [Differentiable rasterizer](https://github.com/zju3dv/pgsr/blob/main/submodules/diff-plane-rasterization/diff_plane_rasterization/__init__.py): `submodules/diff-plane-rasterization/diff_plane_rasterization/__init__.py`
- [Rasterization API](https://github.com/zju3dv/pgsr/blob/main/submodules/diff-plane-rasterization/rasterize_points.h): `submodules/diff-plane-rasterization/rasterize_points.h`
- [Render and mesh export](https://github.com/zju3dv/pgsr/blob/main/render.py): `render.py`
- [TnT rendering](https://github.com/zju3dv/pgsr/blob/main/scripts/render_tnt.py): `scripts/render_tnt.py`

### Evaluation

- [Image metrics](https://github.com/zju3dv/pgsr/blob/main/metrics.py): `metrics.py`
- [DTU evaluation](https://github.com/zju3dv/pgsr/blob/main/scripts/eval_dtu/eval.py): `scripts/eval_dtu/eval.py`
- [TnT evaluation](https://github.com/zju3dv/pgsr/blob/main/scripts/tnt_eval/evaluation.py): `scripts/tnt_eval/evaluation.py`
- [LPIPS metric](https://github.com/zju3dv/pgsr/blob/main/lpipsPyTorch/modules/networks.py): `lpipsPyTorch/modules/networks.py`

### Other components

- **Researcher**
- **Multi-view images**

## Connections

- Researcher → Dataset conversion: prepares data (evidence: `README.md`)
- Researcher → TnT conversion: prepares TnT (evidence: `README.md`)
- Multi-view images → Dataset conversion: converts images (evidence: `README.md`)
- Dataset conversion → Scene readers: produces scene data
- TnT conversion → Scene readers: produces scene data
- Scene readers → COLMAP loader: loads reconstruction (evidence: `scene/dataset_readers.py`)
- Scene and cameras → Scene readers: loads scene info (evidence: `scene/__init__.py`)
- Scene and cameras → Camera utilities: builds cameras (evidence: `scene/__init__.py`)
- Camera utilities → Camera model: constructs
- Researcher → Training loop: starts training (evidence: `README.md`)
- Training loop → Scene and cameras: creates scene (evidence: `train.py`)
- Training loop → Gaussian model: optimizes representation (evidence: `train.py`)
- Training loop → Plane renderer: renders training views (evidence: `train.py`)
- Training loop → Training losses: computes objectives (evidence: `train.py`)
- Training loop → Geometry utilities: warps patches (evidence: `train.py`)
- Gaussian model → Optimization utilities: uses transforms (evidence: `scene/gaussian_model.py`)
- Gaussian model → Spherical harmonics: uses harmonics (evidence: `scene/gaussian_model.py`)
- Plane renderer → Gaussian model: reads Gaussians (evidence: `gaussian_renderer/__init__.py`)
- Plane renderer → Camera model: reads camera
- Plane renderer → Differentiable rasterizer: rasterizes (evidence: `gaussian_renderer/__init__.py`)
- Differentiable rasterizer → Rasterization API: calls CUDA API (evidence: `submodules/diff-plane-rasterization/diff_plane_rasterization/__init__.py`)
- Researcher → Render and mesh export: renders and exports (evidence: `README.md`)
- Render and mesh export → Scene and cameras: loads saved scene (evidence: `render.py`)
- Render and mesh export → Plane renderer: renders views (evidence: `render.py`)
- Researcher → TnT rendering: renders TnT (evidence: `README.md`)
- TnT rendering → Scene and cameras: loads scene (evidence: `scripts/render_tnt.py`)
- TnT rendering → Plane renderer: renders views (evidence: `scripts/render_tnt.py`)
- Researcher → DTU evaluation: evaluates reconstruction (evidence: `README.md`)
- Researcher → TnT evaluation: evaluates reconstruction (evidence: `README.md`)
- Image metrics → LPIPS metric: uses features (evidence: `metrics.py`)
