# vast-ai-research/triposplat architecture

> Architecture diagram of the GitHub repository vast-ai-research/triposplat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vast-ai-research/triposplat
- Repository: https://github.com/vast-ai-research/triposplat

## Overview

1. **What this repo is**
   TripoSplat is a single-image-to-3D-Gaussian generation pipeline. The architectural center is an inference stack that takes a 2D image, runs a learned model, and exports a variable-sized Gaussian splat representation for downstream rendering or editing.

2. **Core code split**
   The repository is intentionally small and centered on two source files:
   - `triposplat.py`: the main pipeline/orchestration layer.
   - `model.py`: the model definition and related tensor-level logic.
   This split suggests a boundary between “system/inference flow” and “network/components.”

3. **Primary data flow**
   The main flow is:
   input image → preprocessing/loaders → TripoSplat model inference → generated 3D Gaussian parameters → export to `.ply` / `.splat` formats → external viewer or downstream DCC/graphics tool.

4. **Checkpoint boundary**
   Model weights are not stored in the repo; they are downloaded into `ckpts/` from Hugging Face or ModelScope. That makes the learned weights an external dependency boundary, separate from the codebase itself.

5. **Inference entry points**
   There are two runnable paths:
   - `run_example.py` for local example/batch inference.
   - `run_gradio.py` for an interactive demo UI.
   Both are thin application layers over the same core inference code, so they are not separate model implementations.

6. **Export and interoperability**
   The output is designed to be portable: exported `.ply` / `.splat` files can be opened in third-party Gaussian viewers like SparkJS or SuperSplat. This means the repo’s responsibility ends at producing standard splat artifacts, not rendering them itself.

7. **Built-in viewer assets**
   `static/viewer/viewer.html` indicates an embedded browser-based viewer, likely used for previewing results locally. The `static/doc` and `static/example_inputs` directories are supporting assets rather than core logic: documentation imagery and sample inputs for demos/examples.

8. **Demo/UI layer**
   `run_gradio.py` adds a lightweight human-facing interface around the inference pipeline. Architecturally, this is a presentation layer that accepts an uploaded image, invokes the model, and presents downloadable 3D outputs.

9. **Dependency profile**
   The repo emphasizes minimal runtime dependencies. From the README, the practical stack is PyTorch plus small utility libraries (`numpy`, `safetensors`, `pillow`, `tqdm`), with `gradio` only needed for the demo. This matters architecturally because the project is self-contained and avoids larger orchestration frameworks.

10. **Repository boundary**
    There is no separate training code, service backend, or database layer in this repo. It is primarily an inference-and-export package with demo wrappers and static visualization assets, intended to be embedded into pipelines such as ComfyUI or used as a local tool.

Main entry points: [`triposplat.py`](https://github.com/vast-ai-research/triposplat/blob/main/triposplat.py) (TripoSplat), [`run_gradio.py`](https://github.com/vast-ai-research/triposplat/blob/main/run_gradio.py) (Gradio demo), [`run_example.py`](https://github.com/vast-ai-research/triposplat/blob/main/run_example.py) (Example run), [`model.py`](https://github.com/vast-ai-research/triposplat/blob/main/model.py) (Model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core inference"]
  node_triposplat_py["TripoSplat<br/>pipeline<br/>[triposplat.py]"]
  node_model_py["Model<br/>network<br/>[model.py]"]
  node_preprocess["Preprocess<br/>data prep<br/>[triposplat.py]"]
  node_infer_gaussians{{"Infer splats<br/>inference<br/>[model.py]"}}
  node_postprocess["Postprocess<br/>export prep<br/>[triposplat.py]"]
  node_ply_export["PLY export<br/>[triposplat.py]"]
  node_splat_export["SPLAT export<br/>[triposplat.py]"]
end

subgraph group_apps["Runtimes"]
  node_run_example_py["Example run<br/>cli<br/>[run_example.py]"]
  node_run_gradio_py["Gradio demo<br/>ui<br/>[run_gradio.py]"]
end

subgraph group_assets["Assets"]
  node_viewer_html["Viewer<br/>browser preview<br/>[viewer.html]"]
  node_example_inputs["Sample inputs<br/>asset"]
  node_doc_assets["Docs assets"]
end

subgraph group_external["External boundary"]
  node_input_image["Input image"]
  node_weights[("Checkpoints<br/>external weights")]
  node_external_viewers["Third-party viewers<br/>external tool"]
  node_downstream_tools["Downstream tools<br/>consumer"]
end

node_input_image -->|"load"| node_preprocess
node_preprocess -->|"orchestrate"| node_triposplat_py
node_triposplat_py -->|"calls"| node_model_py
node_model_py -.->|"loads"| node_weights
node_triposplat_py -->|"run"| node_infer_gaussians
node_infer_gaussians -->|"emit"| node_postprocess
node_postprocess -->|"write"| node_ply_export
node_postprocess -->|"write"| node_splat_export
node_ply_export -->|"consume"| node_downstream_tools
node_splat_export -->|"preview"| node_external_viewers
node_triposplat_py -->|"preview"| node_viewer_html
node_run_example_py -->|"uses"| node_triposplat_py
node_run_example_py -->|"reads"| node_example_inputs
node_run_gradio_py -->|"uses"| node_triposplat_py
node_run_gradio_py -->|"shows"| node_viewer_html
node_doc_assets -.->|"supports"| node_run_gradio_py

click node_triposplat_py "https://github.com/vast-ai-research/triposplat/blob/main/triposplat.py"
click node_model_py "https://github.com/vast-ai-research/triposplat/blob/main/model.py"
click node_preprocess "https://github.com/vast-ai-research/triposplat/blob/main/triposplat.py"
click node_infer_gaussians "https://github.com/vast-ai-research/triposplat/blob/main/model.py"
click node_postprocess "https://github.com/vast-ai-research/triposplat/blob/main/triposplat.py"
click node_ply_export "https://github.com/vast-ai-research/triposplat/blob/main/triposplat.py"
click node_splat_export "https://github.com/vast-ai-research/triposplat/blob/main/triposplat.py"
click node_run_example_py "https://github.com/vast-ai-research/triposplat/blob/main/run_example.py"
click node_run_gradio_py "https://github.com/vast-ai-research/triposplat/blob/main/run_gradio.py"
click node_viewer_html "https://github.com/vast-ai-research/triposplat/blob/main/static/viewer/viewer.html"
click node_example_inputs "https://github.com/vast-ai-research/triposplat/tree/main/static/example_inputs"
click node_doc_assets "https://github.com/vast-ai-research/triposplat/tree/main/static/doc"

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_triposplat_py,node_model_py,node_preprocess,node_infer_gaussians,node_postprocess,node_ply_export,node_splat_export toneBlue
class node_run_example_py,node_run_gradio_py toneAmber
class node_viewer_html,node_example_inputs,node_doc_assets toneMint
class node_input_image,node_weights,node_external_viewers,node_downstream_tools toneRose
```

## Components

### Core inference

Main image-to-Gaussian generation pipeline and model logic.

- [TripoSplat](https://github.com/vast-ai-research/triposplat/blob/main/triposplat.py): pipeline · Main orchestration layer for preprocessing, inference, and export. · `triposplat.py`
- [Model](https://github.com/vast-ai-research/triposplat/blob/main/model.py): network · Model definition and tensor-level inference logic. · `model.py`
- [Preprocess](https://github.com/vast-ai-research/triposplat/blob/main/triposplat.py): data prep · Loads and prepares the input image for inference. · `triposplat.py`
- [Infer splats](https://github.com/vast-ai-research/triposplat/blob/main/model.py): inference · Runs the learned model to produce 3D Gaussian parameters. · `model.py`
- [Postprocess](https://github.com/vast-ai-research/triposplat/blob/main/triposplat.py): export prep · Converts model output into portable splat artifacts. · `triposplat.py`
- [PLY export](https://github.com/vast-ai-research/triposplat/blob/main/triposplat.py): export · Writes standard .ply output for downstream tools. · `triposplat.py`
- [SPLAT export](https://github.com/vast-ai-research/triposplat/blob/main/triposplat.py): export · Writes standard .splat output for Gaussian viewers. · `triposplat.py`

### Runtimes

Runnable entry points wrapping the core pipeline.

- [Example run](https://github.com/vast-ai-research/triposplat/blob/main/run_example.py): cli · Local example and batch inference entry point. · `run_example.py`
- [Gradio demo](https://github.com/vast-ai-research/triposplat/blob/main/run_gradio.py): ui · Interactive demo entry point for uploaded images and downloads. · `run_gradio.py`

### Assets

Static viewer, docs, and sample inputs for demos and preview.

- [Viewer](https://github.com/vast-ai-research/triposplat/blob/main/static/viewer/viewer.html): browser preview · Embedded browser-based preview for generated splats. · `static/viewer/viewer.html`
- [Sample inputs](https://github.com/vast-ai-research/triposplat/tree/main/static/example_inputs): asset · Example images used to demonstrate the pipeline. · `static/example_inputs`
- [Docs assets](https://github.com/vast-ai-research/triposplat/tree/main/static/doc): asset · Static documentation and supporting imagery. · `static/doc`

### External boundary

Model checkpoints and third-party tools outside the repository.

- **Input image**: input · Single 2D image used as the source for generation.
- **Checkpoints**: external weights · Downloaded model weights stored outside the repo in ckpts/.
- **Third-party viewers**: external tool · External Gaussian viewers such as SparkJS or SuperSplat.
- **Downstream tools**: consumer · External rendering or editing pipelines that consume exported splats.

## Connections

- Input image → Preprocess: load · The source image is loaded and prepared for inference.
- Preprocess → TripoSplat: orchestrate · Main pipeline coordinates preprocessing and execution.
- TripoSplat → Model: calls · Pipeline invokes the model implementation.
- Model → Checkpoints: loads · Model parameters are provided by external checkpoints.
- TripoSplat → Infer splats: run · Inference produces 3D Gaussian parameters.
- Infer splats → Postprocess: emit · Model output is prepared for export.
- Postprocess → PLY export: write · Produces .ply artifacts.
- Postprocess → SPLAT export: write · Produces .splat artifacts.
- PLY export → Downstream tools: consume · PLY files can be used by external tools.
- SPLAT export → Third-party viewers: preview · SPLAT files can be opened in third-party viewers.
- TripoSplat → Viewer: preview · The pipeline can surface results through the embedded viewer.
- Example run → TripoSplat: uses · Example runner is a thin wrapper over the core pipeline.
- Example run → Sample inputs: reads · Uses bundled sample inputs for local runs.
- Gradio demo → TripoSplat: uses · Demo UI calls into the same core inference path.
- Gradio demo → Viewer: shows · UI can present local preview output through the embedded viewer.
- Docs assets → Gradio demo: supports · Documentation assets support the demo and repo instructions.