# moorethreads/litegs architecture

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

- Interactive diagram: https://gitdiagram.com/moorethreads/litegs
- Repository: https://github.com/moorethreads/litegs

## Overview

LiteGS is a modular 3D Gaussian-splatting training system with Python and CUDA rendering APIs. Its main workflow loads COLMAP cameras and images, initializes clustered Gaussian primitives, trains them through rendering and density control, and persists checkpoints. The README also documents the staged culling-to-rasterization design and flexible Python/CUDA implementations. Some subsystem details come from README or SOURCE INDEX references rather than sampled implementation excerpts; edges reflect only those documented or shown relationships.

Main entry points: [`litegs/training/trainer.py`](https://github.com/moorethreads/litegs/blob/master/litegs/training/trainer.py) (Training loop), [`litegs/render/__init__.py`](https://github.com/moorethreads/litegs/blob/master/litegs/render/__init__.py) (Cull and activate), [`litegs/io_manager/colmap.py`](https://github.com/moorethreads/litegs/blob/master/litegs/io_manager/colmap.py) (COLMAP reader), [`litegs/training/densify.py`](https://github.com/moorethreads/litegs/blob/master/litegs/training/densify.py) (Density control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Data and persistence"]
  node_colmap["COLMAP reader<br/>[colmap.py]"]
  node_camera_data["Camera and image data<br/>[data.py]"]
  node_ply["PLY I/O<br/>[ply.py]"]
  node_checkpoint["Checkpoint I/O<br/>[checkpoint.py]"]
end

subgraph group_training["Training and scene"]
  node_arguments["Run parameters<br/>[arguments.py]"]
  node_trainer["Training loop<br/>[trainer.py]"]
  node_gaussians["Gaussian primitives<br/>[point.py]"]
  node_clusters["Cluster management<br/>[cluster.py]"]
  node_densify["Density control<br/>[densify.py]"]
  node_optimizer["Sparse optimizer<br/>[optimizer.py]"]
  node_statistics["Training statistics"]
end

subgraph group_rendering["Rendering pipeline"]
  node_render_pre["Cull and activate<br/>[__init__.py]"]
  node_projection["Projection and transforms<br/>[wrapper.py]"]
  node_visibility["Visibility binning<br/>[wrapper.py]"]
  node_raster["Tile rasterization<br/>[wrapper.py]"]
end

subgraph group_compute["Rendering compute"]
  node_compact["Primitive compaction<br/>[compact.h]"]
  node_transform["CUDA transforms<br/>[transform.h]"]
  node_binning["CUDA binning<br/>[binning.h]"]
  node_raster_kernel["CUDA raster kernel<br/>[raster.h]"]
  node_compacted_tensor["Compacted tensors<br/>[CompactedTensor.py]"]
  node_sh["Spherical harmonics"]
end

node_user(("Training user"))

node_user -->|"sets options"| node_arguments
node_trainer -->|"uses settings"| node_arguments
node_trainer -->|"loads scene"| node_colmap
node_colmap -->|"builds frames"| node_camera_data
node_trainer -->|"loads images"| node_camera_data
node_trainer -->|"initializes points"| node_gaussians
node_trainer -->|"clusters points"| node_clusters
node_trainer -->|"renders views"| node_render_pre
node_render_pre -->|"culls clusters"| node_clusters
node_render_pre -->|"projects points"| node_projection
node_projection -->|"invokes transforms"| node_transform
node_render_pre -->|"computes color"| node_sh
node_render_pre -->|"builds visibility"| node_visibility
node_visibility -->|"invokes binning"| node_binning
node_render_pre -->|"rasterizes tiles"| node_raster
node_raster -->|"invokes raster"| node_raster_kernel
node_render_pre -.->|"compacts points"| node_compact
node_trainer -->|"updates density"| node_densify
node_densify -->|"reads statistics"| node_statistics
node_trainer -->|"updates parameters"| node_optimizer
node_optimizer -->|"updates compact gradients"| node_compacted_tensor
node_trainer -->|"saves state"| node_checkpoint
node_trainer -.->|"exports primitives"| node_ply

click node_arguments "https://github.com/moorethreads/litegs/blob/master/litegs/arguments.py"
click node_colmap "https://github.com/moorethreads/litegs/blob/master/litegs/io_manager/colmap.py"
click node_camera_data "https://github.com/moorethreads/litegs/blob/master/litegs/data.py"
click node_ply "https://github.com/moorethreads/litegs/blob/master/litegs/io_manager/ply.py"
click node_checkpoint "https://github.com/moorethreads/litegs/blob/master/litegs/io_manager/checkpoint.py"
click node_trainer "https://github.com/moorethreads/litegs/blob/master/litegs/training/trainer.py"
click node_gaussians "https://github.com/moorethreads/litegs/blob/master/litegs/scene/point.py"
click node_clusters "https://github.com/moorethreads/litegs/blob/master/litegs/scene/cluster.py"
click node_densify "https://github.com/moorethreads/litegs/blob/master/litegs/training/densify.py"
click node_optimizer "https://github.com/moorethreads/litegs/blob/master/litegs/training/optimizer.py"
click node_statistics "https://github.com/moorethreads/litegs/blob/master/litegs/utils/statistic_helper.py"
click node_render_pre "https://github.com/moorethreads/litegs/blob/master/litegs/render/__init__.py"
click node_projection "https://github.com/moorethreads/litegs/blob/master/litegs/utils/wrapper.py"
click node_visibility "https://github.com/moorethreads/litegs/blob/master/litegs/utils/wrapper.py"
click node_raster "https://github.com/moorethreads/litegs/blob/master/litegs/utils/wrapper.py"
click node_compact "https://github.com/moorethreads/litegs/blob/master/litegs/submodules/gaussian_raster/compact.h"
click node_transform "https://github.com/moorethreads/litegs/blob/master/litegs/submodules/gaussian_raster/transform.h"
click node_binning "https://github.com/moorethreads/litegs/blob/master/litegs/submodules/gaussian_raster/binning.h"
click node_raster_kernel "https://github.com/moorethreads/litegs/blob/master/litegs/submodules/gaussian_raster/raster.h"
click node_compacted_tensor "https://github.com/moorethreads/litegs/blob/master/litegs/utils/CompactedTensor.py"
click node_sh "https://github.com/moorethreads/litegs/blob/master/litegs/utils/spherical_harmonics.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_colmap,node_camera_data,node_ply,node_checkpoint,node_user toneBlue
class node_arguments,node_trainer,node_gaussians,node_clusters,node_densify,node_optimizer,node_statistics toneAmber
class node_render_pre,node_projection,node_visibility,node_raster toneMint
class node_compact,node_transform,node_binning,node_raster_kernel,node_compacted_tensor,node_sh toneRose
```

## Components

### Data and persistence

- [COLMAP reader](https://github.com/moorethreads/litegs/blob/master/litegs/io_manager/colmap.py): `litegs/io_manager/colmap.py`
- [Camera and image data](https://github.com/moorethreads/litegs/blob/master/litegs/data.py): `litegs/data.py`
- [PLY I/O](https://github.com/moorethreads/litegs/blob/master/litegs/io_manager/ply.py): `litegs/io_manager/ply.py`
- [Checkpoint I/O](https://github.com/moorethreads/litegs/blob/master/litegs/io_manager/checkpoint.py): `litegs/io_manager/checkpoint.py`

### Training and scene

- [Run parameters](https://github.com/moorethreads/litegs/blob/master/litegs/arguments.py): `litegs/arguments.py`
- [Training loop](https://github.com/moorethreads/litegs/blob/master/litegs/training/trainer.py): `litegs/training/trainer.py`
- [Gaussian primitives](https://github.com/moorethreads/litegs/blob/master/litegs/scene/point.py): `litegs/scene/point.py`
- [Cluster management](https://github.com/moorethreads/litegs/blob/master/litegs/scene/cluster.py): `litegs/scene/cluster.py`
- [Density control](https://github.com/moorethreads/litegs/blob/master/litegs/training/densify.py): `litegs/training/densify.py`
- [Sparse optimizer](https://github.com/moorethreads/litegs/blob/master/litegs/training/optimizer.py): `litegs/training/optimizer.py`
- [Training statistics](https://github.com/moorethreads/litegs/blob/master/litegs/utils/statistic_helper.py): `litegs/utils/statistic_helper.py`

### Rendering pipeline

- [Cull and activate](https://github.com/moorethreads/litegs/blob/master/litegs/render/__init__.py): `litegs/render/__init__.py`
- [Projection and transforms](https://github.com/moorethreads/litegs/blob/master/litegs/utils/wrapper.py): `litegs/utils/wrapper.py`
- [Visibility binning](https://github.com/moorethreads/litegs/blob/master/litegs/utils/wrapper.py): `litegs/utils/wrapper.py`
- [Tile rasterization](https://github.com/moorethreads/litegs/blob/master/litegs/utils/wrapper.py): `litegs/utils/wrapper.py`

### Rendering compute

- [Primitive compaction](https://github.com/moorethreads/litegs/blob/master/litegs/submodules/gaussian_raster/compact.h): `litegs/submodules/gaussian_raster/compact.h`
- [CUDA transforms](https://github.com/moorethreads/litegs/blob/master/litegs/submodules/gaussian_raster/transform.h): `litegs/submodules/gaussian_raster/transform.h`
- [CUDA binning](https://github.com/moorethreads/litegs/blob/master/litegs/submodules/gaussian_raster/binning.h): `litegs/submodules/gaussian_raster/binning.h`
- [CUDA raster kernel](https://github.com/moorethreads/litegs/blob/master/litegs/submodules/gaussian_raster/raster.h): `litegs/submodules/gaussian_raster/raster.h`
- [Compacted tensors](https://github.com/moorethreads/litegs/blob/master/litegs/utils/CompactedTensor.py): `litegs/utils/CompactedTensor.py`
- [Spherical harmonics](https://github.com/moorethreads/litegs/blob/master/litegs/utils/spherical_harmonics.py): `litegs/utils/spherical_harmonics.py`

### Other components

- **Training user**

## Connections

- Training user → Run parameters: sets options (evidence: `litegs/arguments.py`)
- Training loop → Run parameters: uses settings (evidence: `litegs/training/trainer.py`)
- Training loop → COLMAP reader: loads scene (evidence: `litegs/training/trainer.py`)
- COLMAP reader → Camera and image data: builds frames (evidence: `litegs/io_manager/colmap.py`)
- Training loop → Camera and image data: loads images (evidence: `litegs/training/trainer.py`)
- Training loop → Gaussian primitives: initializes points (evidence: `litegs/training/trainer.py`)
- Training loop → Cluster management: clusters points (evidence: `litegs/training/trainer.py`)
- Training loop → Cull and activate: renders views (evidence: `litegs/render/__init__.py`)
- Cull and activate → Cluster management: culls clusters (evidence: `litegs/render/__init__.py`)
- Cull and activate → Projection and transforms: projects points (evidence: `litegs/render/__init__.py`)
- Projection and transforms → CUDA transforms: invokes transforms
- Cull and activate → Spherical harmonics: computes color (evidence: `litegs/render/__init__.py`)
- Cull and activate → Visibility binning: builds visibility (evidence: `litegs/render/__init__.py`)
- Visibility binning → CUDA binning: invokes binning
- Cull and activate → Tile rasterization: rasterizes tiles (evidence: `litegs/render/__init__.py`)
- Tile rasterization → CUDA raster kernel: invokes raster
- Cull and activate → Primitive compaction: compacts points
- Training loop → Density control: updates density (evidence: `litegs/training/trainer.py`)
- Density control → Training statistics: reads statistics (evidence: `litegs/training/densify.py`)
- Training loop → Sparse optimizer: updates parameters (evidence: `litegs/training/trainer.py`)
- Sparse optimizer → Compacted tensors: updates compact gradients (evidence: `litegs/training/optimizer.py`)
- Training loop → Checkpoint I/O: saves state (evidence: `litegs/training/trainer.py`)
- Training loop → PLY I/O: exports primitives
