# luca-saggese/hunyuan3d-2mini-turbo architecture

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

- Interactive diagram: https://gitdiagram.com/luca-saggese/hunyuan3d-2mini-turbo
- Repository: https://github.com/luca-saggese/hunyuan3d-2mini-turbo

## Overview

##### Project type and purpose
- It can be packaged in Docker for GPU-accelerated inference and loads pretrained models from Hugging Face.

##### File structure
- Top-level files:
- gradio_app.py / gradio_app_diffloading.py – entry points for the UI.
- text2image.py – auxiliary script for 2D image conditioning.
- Dockerfile / .dockerignore – containerization.
- requirements.txt – Python dependencies.
- Core library (hy3dgen):
- rembg.py – background removal component.
- texgen/ – all texture generation pipelines, including:
· custom_rasterizer (pure-Python wrappers + C++/CUDA kernels).
· differentiable_renderer (mesh processing + Python/C++ bridge).
· hunyuanpaint (UNet-based painting).
· pipelines.py – orchestration of texgen stages.
· utils/ – mesh/image utilities (alignment, simplification, UV warping, etc.).
- External model wheels, assets (env maps, example prompts, HTML templates).

##### README for additional insights
- Describes two key acceleration techniques: Lightning Vectset Decoder and Progressive Flow Distillation.
- Shows usage via Docker + Gradio and code snippets for enabling FlashVDM on Hunyuan3D-2 models.
- Lists supported models (Fast vs. Turbo, various size families).

##### Essential details to capture
- The two acceleration techniques inside the VDM flow.
- The interplay between Python orchestration and C++/CUDA kernels.
- Model loading from Hugging Face and caching.
- Docker/GPU boundary.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        direction TB
        GradioUI["Gradio Web UI"]:::ui
        GradioDiff["Gradio Diffloading UI"]:::ui
        CLI["CLI / 2D Conditioning Script"]:::ui
    end

    %% Orchestration / Pipeline Layer
    subgraph "Orchestration / Pipeline Layer"
        direction TB
        BackgroundRemover["Background Remover"]:::pipeline
        ShapeGenPL["ShapeGen Pipeline"]:::pipeline
        TexGenPL["TexGen Pipeline"]:::pipeline
    end

    %% Model Components
    subgraph "Model Components"
        direction TB
        subgraph "ShapeGen Models"
            direction TB
            AutoBlocks["Attention Blocks"]:::model
            AutoProcs["Attention Processors"]:::model
            AutoModel["Autoencoder Model"]:::model
            SurfaceExt["Surface Extractors"]:::model
            VolumeDec["Volume Decoders"]:::model
            Conditioner["Conditioner"]:::model
            Denoiser["Hunyuan3D Denoiser"]:::model
        end
        subgraph "Texture Components"
            direction TB
            TexturePainter["HunyuanPaint UNet Painter"]:::model
            TextureUtils["Texture Utilities"]:::model
        end
    end

    %% Native Code Modules
    subgraph "Native Code Modules"
        direction TB
        CustomRasterizer["Custom Rasterizer"]:::native
        DiffRenderer["Differentiable Renderer"]:::native
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        Pretrained["Pretrained Models (Hugging Face)"]:::external
        DockerContainer["Docker Container"]:::external
        AssetsTemplates["Assets & Templates"]:::external
        Dependencies["Python Dependencies"]:::external
        GPU["GPU Runtime"]:::external
    end

    %% Connections
    GradioUI -->|triggers| ShapeGenPL
    GradioUI -->|triggers| TexGenPL
    GradioDiff -->|triggers| ShapeGenPL
    GradioDiff -->|triggers| TexGenPL
    CLI -->|runs| ShapeGenPL

    ShapeGenPL -->|uses| BackgroundRemover
    ShapeGenPL -->|loads weights| Pretrained
    ShapeGenPL -->|invokes| AutoBlocks
    ShapeGenPL -->|invokes| AutoProcs
    ShapeGenPL -->|invokes| AutoModel
    ShapeGenPL -->|invokes| SurfaceExt
    ShapeGenPL -->|invokes| VolumeDec
    ShapeGenPL -->|invokes| Conditioner
    ShapeGenPL -->|invokes| Denoiser

    TexGenPL -->|renders| CustomRasterizer
    TexGenPL -->|renders| DiffRenderer
    TexGenPL -->|invokes| TexturePainter
    TexGenPL -->|invokes| TextureUtils
    TexGenPL -->|loads weights| Pretrained

    DockerContainer -->|wraps| GradioUI
    DockerContainer -->|wraps| GradioDiff
    DockerContainer -->|wraps| CLI
    DockerContainer -->|wraps| ShapeGenPL
    DockerContainer -->|wraps| TexGenPL
    DockerContainer -->|provides| GPU

    Dependencies -->|required by| GradioUI
    Dependencies -->|required by| ShapeGenPL
    Dependencies -->|required by| TexGenPL

    AssetsTemplates -->|provides| GradioUI
    AssetsTemplates -->|provides| ShapeGenPL
    AssetsTemplates -->|provides| TexGenPL

    %% Click Events
    click GradioUI "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/gradio_app.py"
    click GradioDiff "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/gradio_app_diffloading.py"
    click CLI "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/text2image.py"
    click DockerContainer "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/tree/main/Dockerfile"
    click DockerContainer "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/.dockerignore"
    click Dependencies "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/requirements.txt"
    click AssetsTemplates "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/tree/main/assets/env_maps/"
    click AssetsTemplates "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/tree/main/assets/example_images/"
    click AssetsTemplates "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/assets/example_prompts.txt"
    click AssetsTemplates "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/assets/modelviewer-template.html"
    click AssetsTemplates "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/assets/modelviewer-textured-template.html"
    click BackgroundRemover "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/rembg.py"
    click ShapeGenPL "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/shapegen/pipelines.py"
    click ShapeGenPL "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/shapegen/preprocessors.py"
    click ShapeGenPL "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/shapegen/postprocessors.py"
    click ShapeGenPL "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/shapegen/schedulers.py"
    click ShapeGenPL "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/shapegen/utils.py"
    click AutoBlocks "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/shapegen/models/autoencoders/attention_blocks.py"
    click AutoProcs "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/shapegen/models/autoencoders/attention_processors.py"
    click AutoModel "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/shapegen/models/autoencoders/model.py"
    click SurfaceExt "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/shapegen/models/autoencoders/surface_extractors.py"
    click VolumeDec "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/shapegen/models/autoencoders/volume_decoders.py"
    click Conditioner "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/shapegen/models/conditioner.py"
    click Denoiser "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/shapegen/models/denoisers/hunyuan3ddit.py"
    click TexGenPL "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/texgen/pipelines.py"
    click CustomRasterizer "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/texgen/custom_rasterizer/custom_rasterizer/render.py"
    click CustomRasterizer "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/texgen/custom_rasterizer/custom_rasterizer/io_glb.py"
    click CustomRasterizer "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/texgen/custom_rasterizer/custom_rasterizer/io_obj.py"
    click CustomRasterizer "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/tree/main/hy3dgen/texgen/custom_rasterizer/lib/custom_rasterizer_kernel/"
    click DiffRenderer "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/texgen/differentiable_renderer/mesh_processor.cpp"
    click DiffRenderer "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/texgen/differentiable_renderer/mesh_processor.py"
    click DiffRenderer "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/texgen/differentiable_renderer/mesh_render.py"
    click DiffRenderer "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/texgen/differentiable_renderer/mesh_utils.py"
    click DiffRenderer "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/texgen/differentiable_renderer/camera_utils.py"
    click TexturePainter "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/texgen/hunyuanpaint/pipeline.py"
    click TexturePainter "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/texgen/hunyuanpaint/unet/modules.py"
    click TextureUtils "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/texgen/utils/alignImg4Tex_utils.py"
    click TextureUtils "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/texgen/utils/counter_utils.py"
    click TextureUtils "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/texgen/utils/dehighlight_utils.py"
    click TextureUtils "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/texgen/utils/imagesuper_utils.py"
    click TextureUtils "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/texgen/utils/multiview_utils.py"
    click TextureUtils "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/texgen/utils/simplify_mesh_utils.py"
    click TextureUtils "https://github.com/luca-saggese/hunyuan3d-2mini-turbo/blob/main/hy3dgen/texgen/utils/uv_warp_utils.py"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef pipeline fill:#DFFFE0,stroke:#0A7E07,color:#0A7E07
    classDef model fill:#FFEFD0,stroke:#D97A00,color:#D97A00
    classDef native fill:#FFD0D0,stroke:#D62828,color:#D62828
    classDef external fill:#E0E0E0,stroke:#555,color:#555
```
