# tencent/hunyuan3d-2 architecture

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

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

## Overview

##### Project Type and Purpose
- The project is an advanced 3D synthesis system that uses state-of-the-art diffusion models for generating high-resolution textured 3D assets.
- Additionally, the project provides several interfaces for usage: a command-line API server, a Gradio web app, a Blender add-on, and example scripts, making it both a library and a complete production platform (Hunyuan3D-Studio).

##### File Structure Analysis
- Top-level files and folders: Configuration files (.gitignore, LICENSE, setup.py, requirements.txt, etc.), documentation (docs folder), examples (examples folder), and multiple entry points (api_server.py, gradio_app.py, blender_addon.py, minimal_demo.py).
- There is integration with external libraries (e.g., Pytorch, diffusers) and custom native code modules (e.g., CUDA code in the custom_rasterizer_kernel) demonstrating both high-level Python orchestration and lower-level performance-critical components.

##### Key Architectural Components
a. Frontend / User Interfaces:
- CLI / Script-based usage (demonstrated in examples and code snippets).
- API Server (api_server.py) that handles web requests for image-to-3D conversions.
- Gradio Web App (gradio_app.py) for interactive demos.
- Blender Addon (blender_addon.py) to integrate with 3D editing software.
b. Backend / Core Modules:
- Texture Synthesis Module (“hy3dgen/texgen”): Contains differentiable rendering, custom rasterization (with C++/CUDA kernels), and additional pipelines (e.g., Hunyuan3DPaintPipeline).
- Shared Utilities and Pre-/Postprocessing components that support both pipelines.
c. External Dependencies & Services:
- Pytorch and Diffusers for model execution and inference.
- Additional libraries for mesh processing (e.g., trimesh) and custom computation (CUDA modules).

##### Relationships and Data Flow
- The request is managed by the API server or the respective interface entry point.
- Preprocessing → Diffusion Transformer model (Hunyuan3D-DiT) → Bare Mesh generation.
- The resulting mesh is then optionally passed to the Texture Synthesis Pipeline:
- The mesh is input into the texture generation module (Hunyuan3D-Paint) to produce the textured 3D asset.
- The final output (a textured 3D mesh, saved in formats like glb or obj) is then returned to the user or saved for further editing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces Subgraph
    subgraph "User Interfaces"
        API["API Server"]:::ui
        GR["Gradio Web App"]:::ui
        BA["Blender Add-on"]:::ui
        EX["Example Scripts"]:::ui
    end

    %% Input received from any UI
    Input["User Input (Image/Text)"]:::input

    %% UI nodes send request to input
    API --> Input
    GR  --> Input
    BA  --> Input
    EX  --> Input

    %% Shape Generation Module (Core Pipeline)
    SG["Shape Generation Module"]:::core
    Input --> SG

    %% Detailed Shape Generation Pipeline
    subgraph "Shape Generation Pipeline"
        P1["Preprocessing"]:::step
        P2["Diffusion Transformer (Hunyuan3D-DiT)"]:::step
        P3["Bare Mesh Generation"]:::step
    end
    SG --> P1
    P1 --> P2
    P2 --> P3

    %% Optional Texture Synthesis Module
    TS["Texture Synthesis Module"]:::core
    P3 -->|"Optional: Texture Synthesis"| TS

    %% Detailed Texture Synthesis Pipeline
    subgraph "Texture Synthesis Pipeline"
        T1["Differentiable Renderer"]:::step
        T2["Texture Painting (Hunyuan3D-Paint)"]:::step
        T3["Custom Rasterizer Kernel"]:::lowlevel
    end
    TS --> T1
    T1 --> T2
    T2 --> T3

    %% Final output node
    OUT["Final Output: Textured 3D Asset"]:::core
    T3 --> OUT

    %% Supporting components
    MZ["Model Zoo & Libraries"]:::external
    ED["External Dependencies (Pytorch,Diffusers,etc.)"]:::external

    %% Dashed support arrows
    MZ -.-> SG
    MZ -.-> TS
    ED -.-> SG
    ED -.-> TS

    %% Click Events for Component Mapping
    click API "https://github.com/tencent/hunyuan3d-2/blob/main/api_server.py"
    click GR "https://github.com/tencent/hunyuan3d-2/blob/main/gradio_app.py"
    click BA "https://github.com/tencent/hunyuan3d-2/blob/main/blender_addon.py"
    click EX "https://github.com/tencent/hunyuan3d-2/tree/main/examples"
    click SG "https://github.com/tencent/hunyuan3d-2/tree/main/hy3dgen/shapegen"
    click TS "https://github.com/tencent/hunyuan3d-2/tree/main/hy3dgen/texgen"
    click T3 "https://github.com/tencent/hunyuan3d-2/tree/main/hy3dgen/texgen/custom_rasterizer/lib/custom_rasterizer_kernel"

    %% Styles
    classDef ui fill:#ffe6e6,stroke:#cc0000,stroke-width:2,color:#000;
    classDef input fill:#fff2cc,stroke:#b38f00,stroke-width:2,color:#000;
    classDef core fill:#cce5ff,stroke:#0066cc,stroke-width:2,color:#000;
    classDef step fill:#e6ffe6,stroke:#008000,stroke-width:2,color:#000;
    classDef lowlevel fill:#e6e6ff,stroke:#4d4dff,stroke-width:2,color:#000;
    classDef external fill:#fff0f5,stroke:#ff66cc,stroke-width:2,color:#000;
```
