# tencent-hunyuan/hunyuan3d-1 architecture

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

- Interactive diagram: https://gitdiagram.com/tencent-hunyuan/hunyuan3d-1
- Repository: https://github.com/tencent-hunyuan/hunyuan3d-1

## Overview

1. This repository is a two-stage 3D generation system. The first stage is a multi-view generator, and the second stage is a sparse-view reconstruction model that turns those views into a 3D mesh. It supports both text-to-3D and image-to-3D through a shared pipeline.

2. The top-level entry points are split by use case:
   - `main.py` is the command-line inference entry for generating 3D assets.
   - `app.py` is the Gradio demo/server entry point for interactive use.
   - `scripts/*.sh` wrap common configurations for standard vs. lite, and for combined vs. step-by-step execution.

3. The orchestration layer lives in `infer/`. This is the main glue code that coordinates the pipeline stages:
   - `text_to_image.py` for prompt-to-image generation when the input is text.
   - `image_to_views.py` for producing the fixed multi-view set.
   - `removebg.py` for preprocessing input images.
   - `views_to_mesh.py` for reconstruction from multi-view images.
   - `gif_render.py` for visualization/output rendering.
   - `utils.py` for shared inference helpers.
   This package is where the end-to-end data flow is assembled.

4. The generation pipeline is separated into standard and lite implementations under `mvd/`:
   - `hunyuan3d_mvd_std_pipeline.py`
   - `hunyuan3d_mvd_lite_pipeline.py`
   These correspond to the multi-view diffusion stage and differ mainly in capacity and memory/runtime tradeoffs. They are the first major model boundary in the system.

5. The reconstruction model is isolated under `svrm/`. This is the second major stage and contains the feed-forward 3D reconstruction network:
   - `svrm/predictor.py` is the high-level predictor interface.
   - `svrm/ldm/models/svrm.py` and `svrm/configs/svrm.yaml` define the model and configuration.
   - `svrm/ldm/modules/translator/img_to_triplane.py` converts image features into triplane-style latent 3D representations.
   - `svrm/ldm/modules/rendering_neus/` contains mesh/rasterization/rendering logic used during reconstruction and supervision.

6. The internal SVRM architecture is modular. It includes:
   - a Dinov2-based image encoder under `svrm/ldm/modules/encoders/dinov2/`,
   - attention and transformer utilities,
   - a renderer / neural surface pipeline under `rendering_neus`,
   - math, ray sampling, and ray marching utilities for volumetric or surface-based rendering.
   This suggests the reconstruction stage is not just mesh decoding; it combines learned feature extraction with differentiable rendering components.

7. The `infer/` pipeline uses a fixed camera layout. The README states the output views are generated at azimuths `0, 60, 120, 180, 240, 300` relative to the input view. That fixed view set is the bridge between the multi-view diffusion stage and the mesh reconstruction stage.

8. Text-to-3D has an extra front-end image synthesis step. The README and tree indicate the text pipeline uses a text-to-image model before multi-view generation. The repo does not ship the text-image backbone itself in this tree, but `README` points to Hunyuan-DiT checkpoints, so the system depends on an external pretrained text-to-image model for prompt conditioning.

9. Image-to-3D starts from an input image and optionally removes the background before view synthesis. That preprocessing boundary matters because the reconstruction quality depends on the object-centric crop/alpha handling before multi-view generation and mesh recovery.

10. Texture and baking are optional post-processing stages. The repo supports:
    - texture mapping / texture shading inside the main pipeline,
    - baking in `third_party/`, which depends on Dust3R and associated utilities.
    Baking is explicitly separated because it introduces an external license and extra dependencies, and it is not required for basic mesh generation.

11. Rendering and export are separate from generation. The pipeline can produce GIFs and rendered previews after mesh creation, but those are output-side concerns rather than part of the core model. This keeps generation, reconstruction, and presentation distinct.

12. The `third_party/` directory is a clear boundary for non-core integration code. It includes Dust3R-based matching/baking helpers, camera/image utilities, and mesh baking scripts. These components are only needed for the optional texture-baking workflow, not for the core text/image-to-3D path.

13. Operationally, the architecture is GPU-centric and checkpoint-driven. The user downloads pretrained weights into `weights/` and then selects either the lite or standard pipeline, with an additional `--save_memory` mode for lower VRAM at the cost of slower execution. That means memory footprint is an important deployment boundary in this repo.

14. In diagram terms, the main flow is:
    input prompt or image -> optional text-to-image / background cleanup -> multi-view generation (`mvd`) -> sparse-view reconstruction (`svrm`) -> optional texture mapping / baking (`third_party`) -> optional rendering/export.
    The two model stages are the primary subsystems, and `infer/` is the orchestration layer that connects them.

Main entry points: [`infer/utils.py`](https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/infer/utils.py) (infer utils), [`infer/views_to_mesh.py`](https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/infer/views_to_mesh.py) (views to mesh), [`infer/image_to_views.py`](https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/infer/image_to_views.py) (image to views), [`infer/text_to_image.py`](https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/infer/text_to_image.py) (text to image)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoints["Entry points"]
  node_main_py["main.py<br/>cli entry<br/>[main.py]"]
  node_app_py["app.py<br/>demo entry<br/>[app.py]"]
  node_scripts["scripts<br/>run wrappers"]
end

subgraph group_orchestration["Inference flow"]
  node_infer_utils["infer utils<br/>shared helpers<br/>[utils.py]"]
  node_text_to_image["text to image<br/>prompt front-end<br/>[text_to_image.py]"]
  node_removebg["remove bg<br/>preprocess<br/>[removebg.py]"]
  node_image_to_views["image to views<br/>view assembly<br/>[image_to_views.py]"]
  node_views_to_mesh["views to mesh<br/>reconstruction bridge<br/>[views_to_mesh.py]"]
end

subgraph group_generation["Multi-view generation"]
  node_mvd_std["MVD std<br/>multi-view diffusion"]
  node_mvd_lite["MVD lite<br/>multi-view diffusion"]
end

subgraph group_reconstruction["SVRM reconstruction"]
  node_svrm_predictor["predictor<br/>svrm api<br/>[predictor.py]"]
  node_svrm_model["svrm model<br/>3d recon model<br/>[svrm.py]"]
  node_img_to_triplane["to triplane<br/>latent translator<br/>[img_to_triplane.py]"]
  node_dinov2_encoder["dinov2 encoder<br/>image encoder"]
  node_rendering_neus["rendering neus<br/>neural surface"]
  node_svrm_utils["svrm utils<br/>camera/math utils"]
end

subgraph group_postprocess["Post-processing"]
  node_gif_render["gif render<br/>output render<br/>[gif_render.py]"]
  node_third_party_bake["baking tools<br/>optional bake"]
end

node_main_py -->|"loads pipeline"| node_infer_utils
node_app_py -->|"loads pipeline"| node_infer_utils
node_scripts -->|"invoke"| node_main_py
node_infer_utils -->|"text path"| node_text_to_image
node_infer_utils -->|"image path"| node_removebg
node_infer_utils -->|"stage 1"| node_image_to_views
node_infer_utils -->|"stage 2"| node_views_to_mesh
node_infer_utils -->|"outputs"| node_gif_render
node_text_to_image -->|"feeds views"| node_mvd_std
node_text_to_image -->|"feeds views"| node_mvd_lite
node_removebg -->|"clean input"| node_image_to_views
node_image_to_views -->|"generates"| node_mvd_std
node_image_to_views -->|"generates"| node_mvd_lite
node_mvd_std -->|"6 views"| node_views_to_mesh
node_mvd_lite -->|"6 views"| node_views_to_mesh
node_views_to_mesh -->|"calls"| node_svrm_predictor
node_svrm_predictor -->|"owns"| node_svrm_model
node_svrm_model -->|"encodes"| node_img_to_triplane
node_img_to_triplane -->|"uses"| node_dinov2_encoder
node_svrm_model -->|"renders"| node_rendering_neus
node_rendering_neus -->|"geometry"| node_svrm_utils
node_views_to_mesh -.->|"optional"| node_third_party_bake
node_gif_render -.->|"postprocess"| node_third_party_bake

click node_main_py "https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/main.py"
click node_app_py "https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/app.py"
click node_scripts "https://github.com/tencent-hunyuan/hunyuan3d-1/tree/main/scripts"
click node_infer_utils "https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/infer/utils.py"
click node_text_to_image "https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/infer/text_to_image.py"
click node_removebg "https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/infer/removebg.py"
click node_image_to_views "https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/infer/image_to_views.py"
click node_views_to_mesh "https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/infer/views_to_mesh.py"
click node_gif_render "https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/infer/gif_render.py"
click node_mvd_std "https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/mvd/hunyuan3d_mvd_std_pipeline.py"
click node_mvd_lite "https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/mvd/hunyuan3d_mvd_lite_pipeline.py"
click node_svrm_predictor "https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/svrm/predictor.py"
click node_svrm_model "https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/svrm/ldm/models/svrm.py"
click node_img_to_triplane "https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/svrm/ldm/modules/translator/img_to_triplane.py"
click node_dinov2_encoder "https://github.com/tencent-hunyuan/hunyuan3d-1/tree/main/svrm/ldm/modules/encoders/dinov2"
click node_rendering_neus "https://github.com/tencent-hunyuan/hunyuan3d-1/tree/main/svrm/ldm/modules/rendering_neus"
click node_svrm_utils "https://github.com/tencent-hunyuan/hunyuan3d-1/tree/main/svrm/utils"
click node_third_party_bake "https://github.com/tencent-hunyuan/hunyuan3d-1/tree/main/third_party"

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_main_py,node_app_py,node_scripts toneBlue
class node_infer_utils,node_text_to_image,node_removebg,node_image_to_views,node_views_to_mesh toneAmber
class node_mvd_std,node_mvd_lite toneMint
class node_svrm_predictor,node_svrm_model,node_img_to_triplane,node_dinov2_encoder,node_rendering_neus,node_svrm_utils toneRose
class node_gif_render,node_third_party_bake toneIndigo
```

## Components

### Entry points

CLI, demo, and launch scripts

- [main.py](https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/main.py): cli entry · Command-line inference entry for 3D generation · `main.py`
- [app.py](https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/app.py): demo entry · Gradio demo/server entry for interactive use · `app.py`
- [scripts](https://github.com/tencent-hunyuan/hunyuan3d-1/tree/main/scripts): run wrappers · Shell wrappers for standard/lite and combined/step-by-step runs · `scripts`

### Inference flow

Shared pipeline glue and stage routing

- [infer utils](https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/infer/utils.py): shared helpers · Common inference helpers and shared plumbing · `infer/utils.py`
- [text to image](https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/infer/text_to_image.py): prompt front-end · Text-conditioned image synthesis before multi-view generation · `infer/text_to_image.py`
- [remove bg](https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/infer/removebg.py): preprocess · Background removal and object-centric cleanup for input images · `infer/removebg.py`
- [image to views](https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/infer/image_to_views.py): view assembly · Produces the fixed multi-view set used by reconstruction · `infer/image_to_views.py`
- [views to mesh](https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/infer/views_to_mesh.py): reconstruction bridge · Runs sparse-view reconstruction from generated views · `infer/views_to_mesh.py`

### Multi-view generation

Standard and lite diffusion pipelines

- [MVD std](https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/mvd/hunyuan3d_mvd_std_pipeline.py): multi-view diffusion · Standard-capacity multi-view generator · `mvd/hunyuan3d_mvd_std_pipeline.py`
- [MVD lite](https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/mvd/hunyuan3d_mvd_lite_pipeline.py): multi-view diffusion · Lower-memory multi-view generator · `mvd/hunyuan3d_mvd_lite_pipeline.py`

### SVRM reconstruction

Sparse-view 3D recovery stack

- [predictor](https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/svrm/predictor.py): svrm api · High-level predictor interface for sparse-view reconstruction · `svrm/predictor.py`
- [svrm model](https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/svrm/ldm/models/svrm.py): 3d recon model · Main SVRM model definition and configuration-bound core · `svrm/ldm/models/svrm.py`
- [to triplane](https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/svrm/ldm/modules/translator/img_to_triplane.py): latent translator · Maps image features into triplane-style 3D latents · `svrm/ldm/modules/translator/img_to_triplane.py`
- [dinov2 encoder](https://github.com/tencent-hunyuan/hunyuan3d-1/tree/main/svrm/ldm/modules/encoders/dinov2): image encoder · Backbone image encoder used by SVRM · `svrm/ldm/modules/encoders/dinov2`
- [rendering neus](https://github.com/tencent-hunyuan/hunyuan3d-1/tree/main/svrm/ldm/modules/rendering_neus): neural surface · Differentiable rendering, rasterization, mesh, and supervision utilities · `svrm/ldm/modules/rendering_neus`
- [svrm utils](https://github.com/tencent-hunyuan/hunyuan3d-1/tree/main/svrm/utils): camera/math utils · Camera, image, logging, and geometric utilities for reconstruction · `svrm/utils`

### Post-processing

Rendering, export, and optional baking

- [gif render](https://github.com/tencent-hunyuan/hunyuan3d-1/blob/main/infer/gif_render.py): output render · Creates preview animations and rendered outputs · `infer/gif_render.py`
- [baking tools](https://github.com/tencent-hunyuan/hunyuan3d-1/tree/main/third_party): optional bake · Dust3R-based matching and mesh baking integration · `third_party`

## Connections

- main.py → infer utils: loads pipeline · CLI uses shared inference helpers
- app.py → infer utils: loads pipeline · Demo uses shared inference helpers
- scripts → main.py: invoke · Shell wrappers launch CLI inference modes
- infer utils → text to image: text path · Orchestrates prompt-to-image front end
- infer utils → remove bg: image path · Runs preprocessing for image inputs
- infer utils → image to views: stage 1 · Builds fixed multi-view set
- infer utils → views to mesh: stage 2 · Sends views into reconstruction
- infer utils → gif render: outputs · Produces preview renders and GIFs
- text to image → MVD std: feeds views · Text-driven image output is passed into multi-view generation
- text to image → MVD lite: feeds views · Lite configuration can be used for text-driven generation
- remove bg → image to views: clean input · Object-centric image is forwarded to view synthesis
- image to views → MVD std: generates · Standard diffusion pipeline synthesizes canonical views
- image to views → MVD lite: generates · Lite diffusion pipeline synthesizes canonical views
- MVD std → views to mesh: 6 views · Standard multi-view output becomes reconstruction input
- MVD lite → views to mesh: 6 views · Lite multi-view output becomes reconstruction input
- views to mesh → predictor: calls · Reconstruction bridge invokes SVRM predictor
- predictor → svrm model: owns · High-level interface wraps the core model
- svrm model → to triplane: encodes · Transforms image features into 3D latent representation
- to triplane → dinov2 encoder: uses · Depends on DINOv2 image features
- svrm model → rendering neus: renders · Uses differentiable surface/rendering components
- rendering neus → svrm utils: geometry · Consumes camera and math utilities during reconstruction
- views to mesh → baking tools: optional · Baking and texture workflows are separate and optional
- gif render → baking tools: postprocess · Rendered outputs can follow baked or textured assets