# nv-tlabs/3dgrut architecture

> Architecture diagram of the GitHub repository nv-tlabs/3dgrut, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nv-tlabs/3dgrut
- Repository: https://github.com/nv-tlabs/3dgrut

## Overview

3DGRUT combines training and rendering for Gaussian scenes, with 3DGRT ray tracing, 3DGUT rasterization, and a hybrid primary-raster/secondary-ray pipeline. The main workflow is dataset ingestion, model training, rendering and evaluation, with trained scenes also exportable and viewable in an interactive playground. The source index supports several internal links; README statements support the higher-level product workflows. Unsampled subsystems are represented at their exact enclosing directories, and their internal wiring is not inferred.

Main entry points: [`threedgrut/trainer.py`](https://github.com/nv-tlabs/3dgrut/blob/main/threedgrut/trainer.py) (Training loop), [`threedgrut/model/model.py`](https://github.com/nv-tlabs/3dgrut/blob/main/threedgrut/model/model.py) (Gaussian model), [`threedgrut/render.py`](https://github.com/nv-tlabs/3dgrut/blob/main/threedgrut/render.py) (Render and evaluation), [`threedgrut/export`](https://github.com/nv-tlabs/3dgrut/tree/main/threedgrut/export) (Scene export)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Scene Data"]
  node_datasets["Dataset loaders"]
  node_protocols["Batch protocols<br/>[protocols.py]"]
end

subgraph group_learning["Training"]
  node_trainer["Training loop<br/>[trainer.py]"]
  node_model["Gaussian model<br/>[model.py]"]
  node_features["Scene features<br/>[features.py]"]
  node_decoder["Feature decoder<br/>[feature_decoder.py]"]
  node_strategy["Densification"]
  node_optimizers["Optimizers"]
end

subgraph group_rendering["Rendering"]
  node_rendercli["Render and evaluation<br/>[render.py]"]
  node_renderutils["Render utilities<br/>[render.py]"]
  node_grt["3DGRT tracer<br/>[tracer.py]"]
  node_gut["3DGUT rasterizer<br/>[tracer.py]"]
  node_hybrid["Hybrid tracer<br/>[tracer.py]"]
end

subgraph group_delivery["Export and Tools"]
  node_playground["Interactive playground<br/>[engine.py]"]
  node_gui["Training viewer<br/>[gui.py]"]
  node_export["Scene export"]
  node_usd["USD and NuRec"]
  node_ppisp["ISP post-processing"]
  node_files["Exported assets"]
end

node_user(("Scene creator"))
node_evaluator(("Evaluation user"))

node_user -->|"selects data"| node_datasets
node_datasets -.->|"provides batches"| node_protocols
node_trainer -->|"loads data"| node_datasets
node_trainer -->|"trains"| node_model
node_trainer -->|"uses strategy"| node_strategy
node_trainer -->|"uses optimizers"| node_optimizers
node_model -->|"configures features"| node_features
node_model -->|"invokes tracing"| node_grt
node_model -->|"invokes rasterizer"| node_gut
node_trainer -->|"validates renders"| node_rendercli
node_rendercli -->|"renders with"| node_model
node_rendercli -->|"post-processes"| node_renderutils
node_model -.->|"decodes features"| node_decoder
node_user -->|"requests render"| node_rendercli
node_evaluator -->|"requests evaluation"| node_rendercli
node_trainer -->|"opens viewer"| node_gui
node_user -->|"inspects scene"| node_playground
node_playground -.->|"uses hybrid tracing"| node_hybrid
node_user -->|"exports scene"| node_export
node_export -->|"supports USD"| node_usd
node_usd -.->|"applies processing"| node_ppisp
node_export -->|"writes assets"| node_files

click node_datasets "https://github.com/nv-tlabs/3dgrut/tree/main/threedgrut/datasets"
click node_protocols "https://github.com/nv-tlabs/3dgrut/blob/main/threedgrut/datasets/protocols.py"
click node_trainer "https://github.com/nv-tlabs/3dgrut/blob/main/threedgrut/trainer.py"
click node_model "https://github.com/nv-tlabs/3dgrut/blob/main/threedgrut/model/model.py"
click node_features "https://github.com/nv-tlabs/3dgrut/blob/main/threedgrut/model/features.py"
click node_decoder "https://github.com/nv-tlabs/3dgrut/blob/main/threedgrut/model/feature_decoder.py"
click node_strategy "https://github.com/nv-tlabs/3dgrut/tree/main/threedgrut/strategy"
click node_optimizers "https://github.com/nv-tlabs/3dgrut/tree/main/threedgrut/optimizers"
click node_rendercli "https://github.com/nv-tlabs/3dgrut/blob/main/threedgrut/render.py"
click node_renderutils "https://github.com/nv-tlabs/3dgrut/blob/main/threedgrut/utils/render.py"
click node_grt "https://github.com/nv-tlabs/3dgrut/blob/main/threedgrt_tracer/tracer.py"
click node_gut "https://github.com/nv-tlabs/3dgrut/blob/main/threedgut_tracer/tracer.py"
click node_hybrid "https://github.com/nv-tlabs/3dgrut/blob/main/threedgrut_playground/tracer.py"
click node_playground "https://github.com/nv-tlabs/3dgrut/blob/main/threedgrut_playground/engine.py"
click node_gui "https://github.com/nv-tlabs/3dgrut/blob/main/threedgrut/utils/gui.py"
click node_export "https://github.com/nv-tlabs/3dgrut/tree/main/threedgrut/export"
click node_usd "https://github.com/nv-tlabs/3dgrut/tree/main/threedgrut/export/usd"
click node_ppisp "https://github.com/nv-tlabs/3dgrut/tree/main/threedgrut/export/usd/post_processing"

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_datasets,node_protocols,node_evaluator toneBlue
class node_trainer,node_model,node_features,node_decoder,node_strategy,node_optimizers toneAmber
class node_rendercli,node_renderutils,node_grt,node_gut,node_hybrid toneMint
class node_playground,node_gui,node_export,node_usd,node_ppisp,node_files toneRose
class node_user toneIndigo
```

## Components

### Scene Data

- [Dataset loaders](https://github.com/nv-tlabs/3dgrut/tree/main/threedgrut/datasets): `threedgrut/datasets`
- [Batch protocols](https://github.com/nv-tlabs/3dgrut/blob/main/threedgrut/datasets/protocols.py): `threedgrut/datasets/protocols.py`

### Training

- [Training loop](https://github.com/nv-tlabs/3dgrut/blob/main/threedgrut/trainer.py): `threedgrut/trainer.py`
- [Gaussian model](https://github.com/nv-tlabs/3dgrut/blob/main/threedgrut/model/model.py): `threedgrut/model/model.py`
- [Scene features](https://github.com/nv-tlabs/3dgrut/blob/main/threedgrut/model/features.py): `threedgrut/model/features.py`
- [Feature decoder](https://github.com/nv-tlabs/3dgrut/blob/main/threedgrut/model/feature_decoder.py): `threedgrut/model/feature_decoder.py`
- [Densification](https://github.com/nv-tlabs/3dgrut/tree/main/threedgrut/strategy): `threedgrut/strategy`
- [Optimizers](https://github.com/nv-tlabs/3dgrut/tree/main/threedgrut/optimizers): `threedgrut/optimizers`

### Rendering

- [Render and evaluation](https://github.com/nv-tlabs/3dgrut/blob/main/threedgrut/render.py): `threedgrut/render.py`
- [Render utilities](https://github.com/nv-tlabs/3dgrut/blob/main/threedgrut/utils/render.py): `threedgrut/utils/render.py`
- [3DGRT tracer](https://github.com/nv-tlabs/3dgrut/blob/main/threedgrt_tracer/tracer.py): `threedgrt_tracer/tracer.py`
- [3DGUT rasterizer](https://github.com/nv-tlabs/3dgrut/blob/main/threedgut_tracer/tracer.py): `threedgut_tracer/tracer.py`
- [Hybrid tracer](https://github.com/nv-tlabs/3dgrut/blob/main/threedgrut_playground/tracer.py): `threedgrut_playground/tracer.py`

### Export and Tools

- [Interactive playground](https://github.com/nv-tlabs/3dgrut/blob/main/threedgrut_playground/engine.py): `threedgrut_playground/engine.py`
- [Training viewer](https://github.com/nv-tlabs/3dgrut/blob/main/threedgrut/utils/gui.py): `threedgrut/utils/gui.py`
- [Scene export](https://github.com/nv-tlabs/3dgrut/tree/main/threedgrut/export): `threedgrut/export`
- [USD and NuRec](https://github.com/nv-tlabs/3dgrut/tree/main/threedgrut/export/usd): `threedgrut/export/usd`
- [ISP post-processing](https://github.com/nv-tlabs/3dgrut/tree/main/threedgrut/export/usd/post_processing): `threedgrut/export/usd/post_processing`
- **Exported assets**

### Other components

- **Scene creator**
- **Evaluation user**

## Connections

- Scene creator → Dataset loaders: selects data (evidence: `README.md`)
- Dataset loaders → Batch protocols: provides batches (evidence: `threedgrut/datasets/datasetNcore.py`)
- Training loop → Dataset loaders: loads data (evidence: `threedgrut/trainer.py`)
- Training loop → Gaussian model: trains (evidence: `threedgrut/trainer.py`)
- Training loop → Densification: uses strategy (evidence: `threedgrut/trainer.py`)
- Training loop → Optimizers: uses optimizers (evidence: `threedgrut/trainer.py`)
- Gaussian model → Scene features: configures features (evidence: `threedgrut/model/model.py`)
- Gaussian model → 3DGRT tracer: invokes tracing (evidence: `threedgrut/model/model.py`)
- Gaussian model → 3DGUT rasterizer: invokes rasterizer (evidence: `threedgrut/model/model.py`)
- Training loop → Render and evaluation: validates renders (evidence: `threedgrut/trainer.py`)
- Render and evaluation → Gaussian model: renders with (evidence: `threedgrut/render.py`)
- Render and evaluation → Render utilities: post-processes (evidence: `threedgrut/render.py`)
- Gaussian model → Feature decoder: decodes features
- Scene creator → Render and evaluation: requests render (evidence: `README.md`)
- Evaluation user → Render and evaluation: requests evaluation (evidence: `README.md`)
- Training loop → Training viewer: opens viewer (evidence: `threedgrut/trainer.py`)
- Scene creator → Interactive playground: inspects scene (evidence: `README.md`)
- Interactive playground → Hybrid tracer: uses hybrid tracing (evidence: `threedgrut_playground/engine.py`)
- Scene creator → Scene export: exports scene (evidence: `README.md`)
- Scene export → USD and NuRec: supports USD (evidence: `threedgrut/export/__init__.py`)
- USD and NuRec → ISP post-processing: applies processing (evidence: `threedgrut/export/usd/post_processing/ppisp_controller_writer.py`)
- Scene export → Exported assets: writes assets (evidence: `README.md`)
