# ruyi-zha/r2_gaussian architecture

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

- Interactive diagram: https://gitdiagram.com/ruyi-zha/r2_gaussian
- Repository: https://github.com/ruyi-zha/r2_gaussian

## Overview

Based on our review of the file tree and the README, this project is a specialized tomographic reconstruction system that uses a variation of 3D Gaussian Splatting (hence “r2_gaussian”) for CT reconstruction. It integrates components for data generation, point cloud initialization, training a radiative Gaussian model, and evaluation – with significant parts running on GPU using CUDA-based submodules for rasterization and voxelization.

- Data Generation & Preprocessing:
- “data_generator” directory as a module responsible for preparing synthetic, real, or NAF-format datasets.
- That this component converts raw CT data (or volumes) into a format with projection images, metadata JSON, or pickle files. Denote that it also supports different scanner configurations (cone beam/parallel beam) via YAML configuration files.

- Point Cloud Initialization:
- “initialize_pcd.py” and corresponding scripts in the “data_generator” and root level. This module generates initial point clouds (stored as *.npy) for the Gaussian splatting model using either the FDK method or random sampling.
- Dependency on external tools (e.g., TIGRE) used during initialization.

- The Training Module (Core Algorithm):
- Break out the “r2_gaussian” directory with its subcomponents:
▪ “r2_gaussian/gaussian”: Contains the main implementations of the Gaussian model (including model initialization, updating, and rendering queries).
▪ “r2_gaussian/dataset”: Implements dataset loading and camera handling – essential for matching the projection data with the reconstruction process.
▪ “r2_gaussian/arguments” and “r2_gaussian/utils”: Hold supporting functions for configuration, experiment logging, and various mathematics/graphics utilities.

- GPU-Accelerated Rendering:
- “r2_gaussian/submodules/xray-gaussian-rasterization-voxelization” folder that provides CUDA-based routines for rasterizing and voxelizing the Gaussians for fast 3D rendering and evaluation. This is critical for the speed of both training and inference.

- Evaluation & Visualization:
- “test.py” and “scripts/visualize_scene.py” components to denote post-training evaluation and demo visualization (rendering 2D/3D outputs).
- Integrate details from the README about logging (tensorboard events) and evaluation scripts that allow quick inspection of rendering quality.

##### Relationships and Data Flow
- How raw input data flows from the Data Generation component (data_generator) into the Point Cloud Initialization step.
- How the output (initial point clouds / metadata) is then consumed by the Training Module.
- How the training process utilizes utility functions and submodules (rasterization/voxelization) during the iterative optimization.
- How the trained model is evaluated by the Testing/Evaluation module.

##### Architectural Patterns and Design Principles
- GPU/CUDA Acceleration: Mark the specialized submodules that enable parallel processing in rendering or rasterization.

##### Relevant Technologies and Frameworks
- Conda Environment: Note that installation is managed via Conda (environment.yml).
- CUDA and CMake: Indicate the use of CUDA routines (e.g., in submodules) with build support via CMake.
- Python-based CLI: Express that the overall orchestration is driven by Python scripts (train.py, test.py, etc.) with command-line arguments for configuration.
- External Libraries: Reference TIGRE and the dependencies on modules like “Naive-neRF” and “Gaussian Splatting” forks.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Preparation
    subgraph "Data Preparation"
        DG["Data Generator"]:::dataGen
    end

    %% Point Cloud Initialization
    subgraph "Point Cloud Initialization"
        PCI["initialize_pcd.py"]:::init
        PCIGA["data_generator/initialize_pcd_all.py"]:::init
        TIGRE["TIGRE (External)"]:::external
    end

    %% Training Module
    subgraph "Training Module"
        T1["train.py"]:::training
        T2["scripts/train_all.py"]:::training
        subgraph "Gaussian Model (r2_gaussian/gaussian)"
            GM1["gaussian_model.py"]:::training
            GM2["initialize.py"]:::training
            GM3["render_query.py"]:::training
        end
        DS["Dataset Handling (r2_gaussian/dataset)"]:::training
        ARG["Arguments (r2_gaussian/arguments)"]:::training
        UT["Utils (r2_gaussian/utils)"]:::training
    end

    %% GPU-Accelerated Rendering
    subgraph "GPU-Accelerated Rendering"
        GPU["CUDA Rasterization & Voxelization"]:::gpu
    end

    %% Evaluation & Visualization
    subgraph "Evaluation & Visualization"
        EV1["test.py"]:::eval
        EV2["scripts/visualize_scene.py"]:::eval
    end

    %% Connections - Data Flow
    DG -->|"raw_data"| PCI
    DG -->|"raw_data"| PCIGA
    TIGRE ---|"dependency"| PCI

    PCI -->|"initial_point_cloud"| T1
    PCIGA -->|"initial_point_cloud"| T1

    ARG ---|"configs"| T1
    UT ---|"utilities"| T1
    DS ---|"dataset_info"| T1

    T1 -->|"training_targets"| GM1

    GM3 -->|"render_queries"| GPU

    T1 -->|"trained_model"| EV1
    T2 --> EV1
    GPU -->|"render_outputs"| EV2

    %% Styles
    classDef dataGen fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef init fill:#F9E79F,stroke:#7D6608,stroke-width:2px;
    classDef training fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef gpu fill:#A9CCE3,stroke:#2471A3,stroke-width:2px;
    classDef eval fill:#ABEBC6,stroke:#1D8348,stroke-width:2px;
    classDef external fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;

    %% Click Events
    click DG "https://github.com/ruyi-zha/r2_gaussian/tree/main/data_generator"
    click PCI "https://github.com/ruyi-zha/r2_gaussian/blob/main/initialize_pcd.py"
    click PCIGA "https://github.com/ruyi-zha/r2_gaussian/blob/main/data_generator/initialize_pcd_all.py"
    click T1 "https://github.com/ruyi-zha/r2_gaussian/blob/main/train.py"
    click T2 "https://github.com/ruyi-zha/r2_gaussian/blob/main/scripts/train_all.py"
    click GM1 "https://github.com/ruyi-zha/r2_gaussian/blob/main/r2_gaussian/gaussian/gaussian_model.py"
    click GM2 "https://github.com/ruyi-zha/r2_gaussian/blob/main/r2_gaussian/gaussian/initialize.py"
    click GM3 "https://github.com/ruyi-zha/r2_gaussian/blob/main/r2_gaussian/gaussian/render_query.py"
    click DS "https://github.com/ruyi-zha/r2_gaussian/tree/main/r2_gaussian/dataset"
    click ARG "https://github.com/ruyi-zha/r2_gaussian/tree/main/r2_gaussian/arguments"
    click UT "https://github.com/ruyi-zha/r2_gaussian/tree/main/r2_gaussian/utils"
    click GPU "https://github.com/ruyi-zha/r2_gaussian/tree/main/r2_gaussian/submodules/xray-gaussian-rasterization-voxelization"
    click EV1 "https://github.com/ruyi-zha/r2_gaussian/blob/main/test.py"
    click EV2 "https://github.com/ruyi-zha/r2_gaussian/blob/main/scripts/visualize_scene.py"
```
