# tencent-hunyuan/hunyuan3d-2 architecture

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

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

## Overview

##### Project type and purpose
- This is a full-stack, research-grade 3D asset generation system (Hunyuan3D 2.0).

##### File structure
- Top-level python scripts:
- api_server.py (launches HTTP endpoints)
- gradio_app.py (hosts interactive UI)
- blender_addon.py (Blender integration)
- Core library: hy3dgen/
- shapegen/: data preprocessors, diffusion transformer models, scheduler, pipelines.py, postprocessors
- texgen/: custom rasterizer (C++/CUDA), differentiable_renderer (mesh processor & renderer), hunyuanpaint (UNet), pipelines.py, utilities
- Configuration and build: setup.py, requirements.txt
- Examples & assets: examples/ scripts for common workflows, assets/ sample images, models, templates, docs/ full documentation.

##### README for additional insights
- Two-stage architecture:
B. Texture generation paints UV texture maps on the mesh.
- Interfaces: diffusers-like Python API, Gradio UI, REST API, Blender Addon.
- External dependencies: PyTorch, Hugging Face models, trimesh, custom C++/CUDA rasterizer, differentiable renderer.

##### Make the pipeline detail explicit
- Image loader → Preprocessor → Noise scheduler → DiT FlowMatching model → Surface extractor → Mesh postprocessor
- Mesh + image → UV unwrapping (custom rasterizer compile/install) → Differentiable renderer (mesh_processor → mesh_render) → UNet paint model → Texture postprocessors (align, simplify)
- At interfaces, annotate how Gradio_app.py or api_server.py instantiate and orchestrate these pipelines, and how blender_addon.py proxies requests to the local API server.
- Model checkpoint storage (Hugging Face repository) as an external dependency.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Input Layer
    subgraph "Input"
        direction TB
        Images["Multiview / Single-view Images"]:::dataPrepro
        Prompt["Optional Prompt Text"]:::dataPrepro
    end

    %% Shape Generation Pipeline
    subgraph "Shape Generation (Hunyuan3D-DiT)"
        direction TB
        SG_Pre["Preprocessor"]:::dataPrepro
        SG_Sched["DiT Scheduler"]:::ml
        SG_AE["Autoencoder Model"]:::ml
        SG_DN["Denoiser (DiT)"]:::ml
        SG_SurfExt["Surface Extractor"]:::ml
        SG_VolDec["Volume Decoder"]:::ml
        SG_Post["Postprocessor"]:::dataPrepro
        SG_Pipe["ShapeGen Pipeline"]:::ml
    end

    %% Texture Generation Pipeline
    subgraph "Texture Generation (Hunyuan3D-Paint)"
        direction TB
        TG_Rast["Custom Rasterizer"]:::render
        TG_DiffRend["Differentiable Renderer"]:::render
        TG_Process["Mesh Processor"]:::render
        TG_Render["Mesh Render"]:::render
        TG_CamUtils["Camera Utils"]:::render
        TG_Paint["UNet Paint Model"]:::ml
        TG_PostWarp["UV Warp Utils"]:::render
        TG_PostSimp["Simplify Mesh Utils"]:::render
        TG_PostAlign["AlignImg4Tex Utils"]:::render
        TG_Pipe["TextureGen Pipeline"]:::ml
    end

    %% Model Store
    HF["Hugging Face Model Store"]:::ext

    %% Output
    OutputMesh["Textured Mesh (.glb/.obj)"]:::dataPrepro

    %% Interfaces
    subgraph "Interfaces & Deployment"
        direction TB
        PYAPI["Python API"]:::ui
        GRADIO["Gradio App"]:::ui
        RESTAPI["REST API Server"]:::ui
        BLENDER["Blender Add-on"]:::ui
    end

    %% Data Flow Connections
    Images --> SG_Pre
    Prompt --> SG_Pre
    SG_Pre --> SG_Sched
    SG_Sched --> SG_AE
    SG_AE --> SG_DN
    SG_DN --> SG_SurfExt
    SG_SurfExt --> SG_VolDec
    SG_VolDec --> SG_Post
    SG_Post --> SG_Pipe
    SG_Pipe --> TG_Rast
    SG_Pipe --> TG_DiffRend
    TG_Rast --> TG_Pipe
    TG_DiffRend --> TG_Process
    TG_Process --> TG_Render
    TG_Render --> TG_CamUtils
    TG_CamUtils --> TG_Paint
    TG_Paint --> TG_PostWarp
    TG_PostWarp --> TG_PostSimp
    TG_PostSimp --> TG_PostAlign
    TG_PostAlign --> TG_Pipe
    TG_Pipe --> OutputMesh

    %% Interface Orchestration
    PYAPI --> SG_Pipe
    PYAPI --> TG_Pipe
    GRADIO --> PYAPI
    RESTAPI --> SG_Pipe
    RESTAPI --> TG_Pipe
    BLENDER --> RESTAPI

    %% External Dependencies
    SG_AE --> HF
    SG_DN --> HF
    TG_Paint --> HF

    %% Click Events
    click SG_Pre "https://github.com/tencent-hunyuan/hunyuan3d-2/blob/main/hy3dgen/shapegen/preprocessors.py"
    click SG_Sched "https://github.com/tencent-hunyuan/hunyuan3d-2/blob/main/hy3dgen/shapegen/schedulers.py"
    click SG_AE "https://github.com/tencent-hunyuan/hunyuan3d-2/blob/main/hy3dgen/shapegen/models/autoencoders/model.py"
    click SG_DN "https://github.com/tencent-hunyuan/hunyuan3d-2/blob/main/hy3dgen/shapegen/models/denoisers/hunyuan3ddit.py"
    click SG_SurfExt "https://github.com/tencent-hunyuan/hunyuan3d-2/blob/main/hy3dgen/shapegen/models/autoencoders/surface_extractors.py"
    click SG_VolDec "https://github.com/tencent-hunyuan/hunyuan3d-2/blob/main/hy3dgen/shapegen/models/autoencoders/volume_decoders.py"
    click SG_Post "https://github.com/tencent-hunyuan/hunyuan3d-2/blob/main/hy3dgen/shapegen/postprocessors.py"
    click SG_Pipe "https://github.com/tencent-hunyuan/hunyuan3d-2/blob/main/hy3dgen/shapegen/pipelines.py"
    click TG_Pipe "https://github.com/tencent-hunyuan/hunyuan3d-2/blob/main/hy3dgen/texgen/pipelines.py"
    click TG_Rast "https://github.com/tencent-hunyuan/hunyuan3d-2/blob/main/hy3dgen/texgen/custom_rasterizer/custom_rasterizer/render.py"
    click TG_DiffRend "https://github.com/tencent-hunyuan/hunyuan3d-2/blob/main/hy3dgen/texgen/differentiable_renderer/mesh_processor.py"
    click TG_Render "https://github.com/tencent-hunyuan/hunyuan3d-2/blob/main/hy3dgen/texgen/differentiable_renderer/mesh_render.py"
    click TG_CamUtils "https://github.com/tencent-hunyuan/hunyuan3d-2/blob/main/hy3dgen/texgen/differentiable_renderer/camera_utils.py"
    click TG_Paint "https://github.com/tencent-hunyuan/hunyuan3d-2/blob/main/hy3dgen/texgen/hunyuanpaint/pipeline.py"
    click TG_Paint "https://github.com/tencent-hunyuan/hunyuan3d-2/blob/main/hy3dgen/texgen/hunyuanpaint/unet/modules.py"
    click TG_PostWarp "https://github.com/tencent-hunyuan/hunyuan3d-2/blob/main/hy3dgen/texgen/utils/uv_warp_utils.py"
    click TG_PostSimp "https://github.com/tencent-hunyuan/hunyuan3d-2/blob/main/hy3dgen/texgen/utils/simplify_mesh_utils.py"
    click TG_PostAlign "https://github.com/tencent-hunyuan/hunyuan3d-2/blob/main/hy3dgen/texgen/utils/alignImg4Tex_utils.py"
    click RESTAPI "https://github.com/tencent-hunyuan/hunyuan3d-2/blob/main/api_server.py"
    click GRADIO "https://github.com/tencent-hunyuan/hunyuan3d-2/blob/main/gradio_app.py"
    click BLENDER "https://github.com/tencent-hunyuan/hunyuan3d-2/blob/main/blender_addon.py"

    %% Styles
    classDef dataPrepro fill:#ADD8E6,stroke:#1E90FF,color:#000000
    classDef ml fill:#B0E0E6,stroke:#4682B4,color:#000000
    classDef render fill:#FFD700,stroke:#FF8C00,color:#000000
    classDef ui fill:#98FB98,stroke:#2E8B57,color:#000000
    classDef ext fill:#D3D3D3,stroke:#A9A9A9,color:#000000
```
