# vaibhavpandeyvpz/trellis-image-to-3d architecture

> Architecture diagram of the GitHub repository vaibhavpandeyvpz/trellis-image-to-3d, 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/vaibhavpandeyvpz/trellis-image-to-3d
- Repository: https://github.com/vaibhavpandeyvpz/trellis-image-to-3d

## Overview

TRELLIS is an image-to-3D generation application. Its main workflow accepts and preprocesses an image, samples a sparse structure and then structured latents, decodes representations, and presents or exports the resulting asset. The README also documents experimental multi-image input, GLB and Gaussian outputs, background removal, configurable sampling, and an interactive viewer. The graph distinguishes the two generation stages and representation-specific outputs; several internal links are omitted or left unverified because the relevant implementation excerpts are incomplete.

Main entry points: [`trellis/pipelines/trellis_image_to_3d.py`](https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/pipelines/trellis_image_to_3d.py) (Image-to-3D pipeline), [`app.py`](https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/app.py) (Gradio interface), [`trellis/models/structured_latent_vae/base.py`](https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/models/structured_latent_vae/base.py) (Structured latent VAE), [`trellis/utils/render_utils.py`](https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/utils/render_utils.py) (3D rendering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Application"]
  node_app["Gradio interface<br/>[app.py]"]
  node_viewer["Browser 3D viewer<br/>[app.py]"]
  node_download["Asset download<br/>[app.py]"]
end

subgraph group_generation["Generation"]
  node_preprocess["Image preprocessing"]
  node_pipeline["Image-to-3D pipeline"]
  node_samplers["Flow samplers<br/>[flow_euler.py]"]
  node_sparseflow["Sparse structure flow"]
  node_sparsevae["Sparse structure VAE"]
  node_slatflow["Structured latent flow"]
  node_slatvae["Structured latent VAE<br/>[base.py]"]
  node_meshdecoder["Mesh decoder<br/>[decoder_mesh.py]"]
  node_gsdecoder["Gaussian decoder<br/>[decoder_gs.py]"]
  node_rfdecoder["Radiance-field decoder<br/>[decoder_rf.py]"]
end

subgraph group_network["Model internals"]
  node_sparse["Sparse tensor operations<br/>[basic.py]"]
  node_attention["Attention layers<br/>[full_attn.py]"]
end

subgraph group_representations["3D representations"]
  node_mesh["Mesh representation<br/>[cube2mesh.py]"]
  node_gaussian["Gaussian representation<br/>[gaussian_model.py]"]
  node_octree["Octree representation<br/>[octree_dfs.py]"]
end

subgraph group_outputs["Viewing and export"]
  node_postprocess["GLB processing"]
  node_render["3D rendering<br/>[render_utils.py]"]
end

node_user(("Image uploader"))

node_user -->|"uploads image"| node_app
node_app -->|"runs generation"| node_pipeline
node_pipeline -.->|"preprocesses input"| node_preprocess
node_pipeline -->|"configures samplers"| node_samplers
node_pipeline -.->|"samples structure"| node_sparseflow
node_pipeline -.->|"encodes structure"| node_sparsevae
node_pipeline -->|"samples latents"| node_slatflow
node_pipeline -->|"decodes latents"| node_slatvae
node_slatvae -->|"uses decoder"| node_meshdecoder
node_slatvae -->|"uses decoder"| node_gsdecoder
node_slatvae -.->|"uses decoder"| node_rfdecoder
node_sparseflow -->|"uses sparse ops"| node_sparse
node_slatflow -->|"uses sparse ops"| node_sparse
node_slatflow -.->|"uses attention"| node_attention
node_meshdecoder -->|"produces mesh"| node_mesh
node_gsdecoder -->|"produces Gaussians"| node_gaussian
node_rfdecoder -.->|"produces field"| node_octree
node_app -->|"creates GLB"| node_postprocess
node_app -->|"renders preview"| node_render
node_render -->|"renders mesh"| node_mesh
node_render -->|"renders Gaussians"| node_gaussian
node_render -->|"renders octree"| node_octree
node_app -->|"shows preview"| node_viewer
node_app -->|"offers downloads"| node_download
node_postprocess -.->|"converts mesh"| node_mesh
node_postprocess -.->|"uses representation"| node_gaussian

click node_app "https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/app.py"
click node_preprocess "https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/pipelines/trellis_image_to_3d.py"
click node_pipeline "https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/pipelines/trellis_image_to_3d.py"
click node_samplers "https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/pipelines/samplers/flow_euler.py"
click node_sparseflow "https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/models/sparse_structure_flow.py"
click node_sparsevae "https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/models/sparse_structure_vae.py"
click node_slatflow "https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/models/structured_latent_flow.py"
click node_slatvae "https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/models/structured_latent_vae/base.py"
click node_meshdecoder "https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/models/structured_latent_vae/decoder_mesh.py"
click node_gsdecoder "https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/models/structured_latent_vae/decoder_gs.py"
click node_rfdecoder "https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/models/structured_latent_vae/decoder_rf.py"
click node_sparse "https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/modules/sparse/basic.py"
click node_attention "https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/modules/attention/full_attn.py"
click node_mesh "https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/representations/mesh/cube2mesh.py"
click node_gaussian "https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/representations/gaussian/gaussian_model.py"
click node_octree "https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/representations/octree/octree_dfs.py"
click node_postprocess "https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/utils/postprocessing_utils.py"
click node_render "https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/utils/render_utils.py"
click node_viewer "https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/app.py"
click node_download "https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/app.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_app,node_viewer,node_download toneBlue
class node_preprocess,node_pipeline,node_samplers,node_sparseflow,node_sparsevae,node_slatflow,node_slatvae,node_meshdecoder,node_gsdecoder,node_rfdecoder toneAmber
class node_sparse,node_attention toneMint
class node_mesh,node_gaussian,node_octree toneRose
class node_postprocess,node_render,node_user toneIndigo
```

## Components

### Application

- [Gradio interface](https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/app.py): `app.py`
- [Browser 3D viewer](https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/app.py): `app.py`
- [Asset download](https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/app.py): `app.py`

### Generation

- [Image preprocessing](https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/pipelines/trellis_image_to_3d.py): `trellis/pipelines/trellis_image_to_3d.py`
- [Image-to-3D pipeline](https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/pipelines/trellis_image_to_3d.py): `trellis/pipelines/trellis_image_to_3d.py`
- [Flow samplers](https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/pipelines/samplers/flow_euler.py): `trellis/pipelines/samplers/flow_euler.py`
- [Sparse structure flow](https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/models/sparse_structure_flow.py): `trellis/models/sparse_structure_flow.py`
- [Sparse structure VAE](https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/models/sparse_structure_vae.py): `trellis/models/sparse_structure_vae.py`
- [Structured latent flow](https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/models/structured_latent_flow.py): `trellis/models/structured_latent_flow.py`
- [Structured latent VAE](https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/models/structured_latent_vae/base.py): `trellis/models/structured_latent_vae/base.py`
- [Mesh decoder](https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/models/structured_latent_vae/decoder_mesh.py): `trellis/models/structured_latent_vae/decoder_mesh.py`
- [Gaussian decoder](https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/models/structured_latent_vae/decoder_gs.py): `trellis/models/structured_latent_vae/decoder_gs.py`
- [Radiance-field decoder](https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/models/structured_latent_vae/decoder_rf.py): `trellis/models/structured_latent_vae/decoder_rf.py`

### Model internals

- [Sparse tensor operations](https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/modules/sparse/basic.py): `trellis/modules/sparse/basic.py`
- [Attention layers](https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/modules/attention/full_attn.py): `trellis/modules/attention/full_attn.py`

### 3D representations

- [Mesh representation](https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/representations/mesh/cube2mesh.py): `trellis/representations/mesh/cube2mesh.py`
- [Gaussian representation](https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/representations/gaussian/gaussian_model.py): `trellis/representations/gaussian/gaussian_model.py`
- [Octree representation](https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/representations/octree/octree_dfs.py): `trellis/representations/octree/octree_dfs.py`

### Viewing and export

- [GLB processing](https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/utils/postprocessing_utils.py): `trellis/utils/postprocessing_utils.py`
- [3D rendering](https://github.com/vaibhavpandeyvpz/trellis-image-to-3d/blob/main/trellis/utils/render_utils.py): `trellis/utils/render_utils.py`

### Other components

- **Image uploader**

## Connections

- Image uploader → Gradio interface: uploads image (evidence: `README.md`)
- Gradio interface → Image-to-3D pipeline: runs generation (evidence: `app.py`)
- Image-to-3D pipeline → Image preprocessing: preprocesses input (evidence: `trellis/pipelines/trellis_image_to_3d.py`)
- Image-to-3D pipeline → Flow samplers: configures samplers (evidence: `trellis/pipelines/trellis_image_to_3d.py`)
- Image-to-3D pipeline → Sparse structure flow: samples structure
- Image-to-3D pipeline → Sparse structure VAE: encodes structure
- Image-to-3D pipeline → Structured latent flow: samples latents (evidence: `trellis/pipelines/trellis_image_to_3d.py`)
- Image-to-3D pipeline → Structured latent VAE: decodes latents (evidence: `trellis/pipelines/trellis_image_to_3d.py`)
- Structured latent VAE → Mesh decoder: uses decoder (evidence: `trellis/models/structured_latent_vae/decoder_mesh.py`)
- Structured latent VAE → Gaussian decoder: uses decoder (evidence: `trellis/models/structured_latent_vae/decoder_gs.py`)
- Structured latent VAE → Radiance-field decoder: uses decoder
- Sparse structure flow → Sparse tensor operations: uses sparse ops (evidence: `trellis/models/sparse_structure_flow.py`)
- Structured latent flow → Sparse tensor operations: uses sparse ops (evidence: `trellis/models/structured_latent_flow.py`)
- Structured latent flow → Attention layers: uses attention
- Mesh decoder → Mesh representation: produces mesh (evidence: `trellis/models/structured_latent_vae/decoder_mesh.py`)
- Gaussian decoder → Gaussian representation: produces Gaussians (evidence: `trellis/models/structured_latent_vae/decoder_gs.py`)
- Radiance-field decoder → Octree representation: produces field
- Gradio interface → GLB processing: creates GLB (evidence: `app.py`)
- Gradio interface → 3D rendering: renders preview (evidence: `app.py`)
- 3D rendering → Mesh representation: renders mesh (evidence: `trellis/utils/render_utils.py`)
- 3D rendering → Gaussian representation: renders Gaussians (evidence: `trellis/utils/render_utils.py`)
- 3D rendering → Octree representation: renders octree (evidence: `trellis/utils/render_utils.py`)
- Gradio interface → Browser 3D viewer: shows preview (evidence: `README.md`)
- Gradio interface → Asset download: offers downloads (evidence: `README.md`)
- GLB processing → Mesh representation: converts mesh
- GLB processing → Gaussian representation: uses representation
