# gmum/medgs architecture

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

- Interactive diagram: https://gitdiagram.com/gmum/medgs
- Repository: https://github.com/gmum/medgs

## Overview

MedGS trains a folded-Gaussian representation of medical image frames, optionally learning image and segmentation heads together, then renders interpolated views or extracts a mesh. The main workflow is dataset ingestion → scene/camera setup → Gaussian optimization → rendering and mesh output. The README documents the user-facing modes; the source index and excerpts support the core model, scene, renderer, and utility connections. Some rendering and mesh internals were not sampled, so those edges rely on README statements rather than claims about their internal implementation.

Main entry points: [`scene/gaussian_model.py`](https://github.com/gmum/medgs/blob/main/scene/gaussian_model.py) (Folded Gaussians), [`train.py`](https://github.com/gmum/medgs/blob/main/train.py) (Training modes), [`render.py`](https://github.com/gmum/medgs/blob/main/render.py) (View rendering), [`gaussian_renderer/__init__.py`](https://github.com/gmum/medgs/blob/main/gaussian_renderer/__init__.py) (Gaussian renderer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Training workflow"]
  node_train["Training modes<br/>[train.py]"]
  node_arguments["Training configuration<br/>[__init__.py]"]
end

subgraph group_representation["Scene and representation"]
  node_readers["Dataset readers<br/>[dataset_readers.py]"]
  node_scene["Scene setup<br/>[__init__.py]"]
  node_camera["Camera transforms<br/>[cameras.py]"]
  node_base_readers["Scene data readers<br/>[dataset_readers.py]"]
  node_colmap["COLMAP loading<br/>[colmap_loader.py]"]
  node_gaussian["Folded Gaussians<br/>[gaussian_model.py]"]
  node_point_gaussian["Point Gaussian model"]
end

subgraph group_outputs["Rendering and outputs"]
  node_renderer["Gaussian renderer<br/>[__init__.py]"]
  node_background_renderer["Background renderer<br/>[__init__.py]"]
  node_render["View rendering<br/>[render.py]"]
  node_mesh["Mesh extraction<br/>[mesh_utils.py]"]
  node_evaluation["Mesh evaluation<br/>[evaluate.py]"]
  node_output_files["Rendered views"]
  node_mesh_files["Mesh results"]
end

subgraph group_internals["Numerical support"]
  node_losses["Training losses<br/>[loss_utils.py]"]
  node_geometry["Geometry utilities<br/>[graphics_utils.py]"]
  node_general["Tensor utilities<br/>[general_utils.py]"]
  node_sh["Spherical harmonics<br/>[sh_utils.py]"]
end

node_user(("Researcher"))
node_frames["Medical frames"]

node_user -->|"starts training"| node_train
node_frames -->|"provides frames"| node_readers
node_train -->|"selects data"| node_readers
node_readers -->|"uses base readers"| node_base_readers
node_base_readers -->|"loads COLMAP"| node_colmap
node_readers -->|"uses camera geometry"| node_geometry
node_train -->|"creates scene"| node_scene
node_scene -->|"initializes model"| node_gaussian
node_scene -->|"builds cameras"| node_camera
node_train -->|"optimizes geometry"| node_gaussian
node_train -->|"uses losses"| node_losses
node_train -->|"reads options"| node_arguments
node_point_gaussian -->|"extends model"| node_gaussian
node_renderer -->|"renders model"| node_gaussian
node_renderer -->|"evaluates colors"| node_sh
node_background_renderer -->|"renders model"| node_gaussian
node_render -->|"renders views"| node_renderer
node_user -->|"requests rendering"| node_render
node_render -->|"writes views"| node_output_files
node_render -->|"loads checkpoint"| node_gaussian
node_mesh -->|"produces mesh"| node_mesh_files
node_evaluation -->|"uses mesh utilities"| node_mesh
node_gaussian -->|"uses tensor helpers"| node_general
node_base_readers -->|"uses transforms"| node_geometry
node_renderer -->|"uses loss utilities"| node_losses

click node_train "https://github.com/gmum/medgs/blob/main/train.py"
click node_readers "https://github.com/gmum/medgs/blob/main/models/scenes/dataset_readers.py"
click node_scene "https://github.com/gmum/medgs/blob/main/scene/__init__.py"
click node_camera "https://github.com/gmum/medgs/blob/main/scene/cameras.py"
click node_base_readers "https://github.com/gmum/medgs/blob/main/scene/dataset_readers.py"
click node_colmap "https://github.com/gmum/medgs/blob/main/scene/colmap_loader.py"
click node_gaussian "https://github.com/gmum/medgs/blob/main/scene/gaussian_model.py"
click node_point_gaussian "https://github.com/gmum/medgs/blob/main/models/flat_splatting/scene/points_gaussian_model.py"
click node_renderer "https://github.com/gmum/medgs/blob/main/gaussian_renderer/__init__.py"
click node_background_renderer "https://github.com/gmum/medgs/blob/main/gaussian_renderer/bg_fg_renderer/__init__.py"
click node_render "https://github.com/gmum/medgs/blob/main/render.py"
click node_mesh "https://github.com/gmum/medgs/blob/main/utils/mesh_utils.py"
click node_evaluation "https://github.com/gmum/medgs/blob/main/evaluate.py"
click node_arguments "https://github.com/gmum/medgs/blob/main/arguments/__init__.py"
click node_losses "https://github.com/gmum/medgs/blob/main/utils/loss_utils.py"
click node_geometry "https://github.com/gmum/medgs/blob/main/utils/graphics_utils.py"
click node_general "https://github.com/gmum/medgs/blob/main/utils/general_utils.py"
click node_sh "https://github.com/gmum/medgs/blob/main/utils/sh_utils.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_train,node_arguments toneBlue
class node_readers,node_scene,node_camera,node_base_readers,node_colmap,node_gaussian,node_point_gaussian toneAmber
class node_renderer,node_background_renderer,node_render,node_mesh,node_evaluation,node_output_files,node_mesh_files toneMint
class node_losses,node_geometry,node_general,node_sh toneRose
class node_user,node_frames toneIndigo
```

## Components

### Training workflow

- [Training modes](https://github.com/gmum/medgs/blob/main/train.py): `train.py`
- [Training configuration](https://github.com/gmum/medgs/blob/main/arguments/__init__.py): `arguments/__init__.py`

### Scene and representation

- [Dataset readers](https://github.com/gmum/medgs/blob/main/models/scenes/dataset_readers.py): `models/scenes/dataset_readers.py`
- [Scene setup](https://github.com/gmum/medgs/blob/main/scene/__init__.py): `scene/__init__.py`
- [Camera transforms](https://github.com/gmum/medgs/blob/main/scene/cameras.py): `scene/cameras.py`
- [Scene data readers](https://github.com/gmum/medgs/blob/main/scene/dataset_readers.py): `scene/dataset_readers.py`
- [COLMAP loading](https://github.com/gmum/medgs/blob/main/scene/colmap_loader.py): `scene/colmap_loader.py`
- [Folded Gaussians](https://github.com/gmum/medgs/blob/main/scene/gaussian_model.py): `scene/gaussian_model.py`
- [Point Gaussian model](https://github.com/gmum/medgs/blob/main/models/flat_splatting/scene/points_gaussian_model.py): `models/flat_splatting/scene/points_gaussian_model.py`

### Rendering and outputs

- [Gaussian renderer](https://github.com/gmum/medgs/blob/main/gaussian_renderer/__init__.py): `gaussian_renderer/__init__.py`
- [Background renderer](https://github.com/gmum/medgs/blob/main/gaussian_renderer/bg_fg_renderer/__init__.py): `gaussian_renderer/bg_fg_renderer/__init__.py`
- [View rendering](https://github.com/gmum/medgs/blob/main/render.py): `render.py`
- [Mesh extraction](https://github.com/gmum/medgs/blob/main/utils/mesh_utils.py): `utils/mesh_utils.py`
- [Mesh evaluation](https://github.com/gmum/medgs/blob/main/evaluate.py): `evaluate.py`
- **Rendered views**
- **Mesh results**

### Numerical support

- [Training losses](https://github.com/gmum/medgs/blob/main/utils/loss_utils.py): `utils/loss_utils.py`
- [Geometry utilities](https://github.com/gmum/medgs/blob/main/utils/graphics_utils.py): `utils/graphics_utils.py`
- [Tensor utilities](https://github.com/gmum/medgs/blob/main/utils/general_utils.py): `utils/general_utils.py`
- [Spherical harmonics](https://github.com/gmum/medgs/blob/main/utils/sh_utils.py): `utils/sh_utils.py`

### Other components

- **Researcher**
- **Medical frames**

## Connections

- Researcher → Training modes: starts training (evidence: `README.md`)
- Medical frames → Dataset readers: provides frames (evidence: `README.md`)
- Training modes → Dataset readers: selects data (evidence: `README.md`)
- Dataset readers → Scene data readers: uses base readers (evidence: `models/scenes/dataset_readers.py`)
- Scene data readers → COLMAP loading: loads COLMAP (evidence: `scene/dataset_readers.py`)
- Dataset readers → Geometry utilities: uses camera geometry (evidence: `models/scenes/dataset_readers.py`)
- Training modes → Scene setup: creates scene (evidence: `train.py`)
- Scene setup → Folded Gaussians: initializes model (evidence: `scene/__init__.py`)
- Scene setup → Camera transforms: builds cameras (evidence: `scene/__init__.py`)
- Training modes → Folded Gaussians: optimizes geometry (evidence: `train.py`)
- Training modes → Training losses: uses losses (evidence: `train.py`)
- Training modes → Training configuration: reads options (evidence: `README.md`)
- Point Gaussian model → Folded Gaussians: extends model (evidence: `models/flat_splatting/scene/points_gaussian_model.py`)
- Gaussian renderer → Folded Gaussians: renders model (evidence: `gaussian_renderer/__init__.py`)
- Gaussian renderer → Spherical harmonics: evaluates colors (evidence: `gaussian_renderer/__init__.py`)
- Background renderer → Folded Gaussians: renders model (evidence: `gaussian_renderer/bg_fg_renderer/__init__.py`)
- View rendering → Gaussian renderer: renders views (evidence: `render.py`)
- Researcher → View rendering: requests rendering (evidence: `README.md`)
- View rendering → Rendered views: writes views (evidence: `README.md`)
- View rendering → Folded Gaussians: loads checkpoint (evidence: `render.py`)
- Mesh extraction → Mesh results: produces mesh (evidence: `README.md`)
- Mesh evaluation → Mesh extraction: uses mesh utilities (evidence: `evaluate.py`)
- Folded Gaussians → Tensor utilities: uses tensor helpers (evidence: `scene/gaussian_model.py`)
- Scene data readers → Geometry utilities: uses transforms (evidence: `scene/dataset_readers.py`)
- Gaussian renderer → Training losses: uses loss utilities (evidence: `gaussian_renderer/__init__.py`)
