# kijai/comfyui-hunyuan3dwrapper architecture

> Architecture diagram of the GitHub repository kijai/comfyui-hunyuan3dwrapper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kijai/comfyui-hunyuan3dwrapper
- Repository: https://github.com/kijai/comfyui-hunyuan3dwrapper

## Overview

1. This repository is a ComfyUI custom-node wrapper around Tencent’s Hunyuan3D-2 pipeline. The top-level responsibility is to take 2D image inputs and produce 3D assets, with the graph exposed through `nodes.py`, frontend glue in `web/js/jsnodes.js`, and example node graphs in `example_workflows/`.

2. The runtime is split into two major inference subsystems: `hy3dgen/shapegen` for geometry generation and `hy3dgen/texgen` for texture generation. These are orchestrated by package-level pipeline modules rather than a single monolith, which makes the shape and texture stages separable in an architecture diagram.

3. Shape generation is centered in `hy3dgen/shapegen/pipelines.py` and the `models/` subtree. That layer includes preprocessing, conditioning, diffusion/denoising, schedulers, and postprocessing. The model stack combines transformer/DiT-style components, autoencoders, and surface extraction utilities to turn conditioned latent predictions into a mesh or volume representation.

4. Geometry extraction and representation conversion are handled by supporting modules such as `surface_extractors.py`, `volume_decoders.py`, and the standalone `ODC/occupancy_dual_contouring.py`. This indicates the shape subsystem is not only generating latent geometry but also explicitly converting occupancy/volume outputs into watertight mesh surfaces.

5. Texture generation is a separate pipeline under `hy3dgen/texgen`. It contains mesh and UV utilities, multiview alignment, texture warping, mesh simplification, and dehighlighting helpers, plus a `hunyuanpaint` submodule for paint/inpainting-style texture synthesis. The texture stage consumes the mesh produced by shape generation and writes UV-consistent appearance back onto it.

6. The texture subsystem depends on two native acceleration layers: `custom_rasterizer` and `differentiable_renderer`. The rasterizer package includes C++/CUDA kernels and OBJ/GLB I/O, while the differentiable renderer includes mesh processing and rendering code, plus a compiled `mesh_processor` extension used for vertex inpainting. These are performance-critical boundaries in the architecture.

7. Input normalization and asset preparation are handled before either model stage. The repo includes `hy3dgen/rembg.py` for background removal, preprocessors/postprocessors in both `shapegen` and `texgen`, and various utility modules for image alignment, UV handling, and mesh cleanup. This suggests the runtime expects relatively clean foreground-object images as the main input.

8. There is also an optional BPT-based shape branch under `hy3dgen/shapegen/bpt`. It contains a separate model implementation, Michelangelo/BPT-specific modules, and its own requirements/weight download path. Architecturally, this is an alternate geometry pathway rather than the main inference path.

9. The `hy3dshape/` package is the training/fine-tuning side of the codebase, distinct from `hy3dgen/` inference. It contains data loaders, diffusion/flow-matching code, denoisers, autoencoders, training utilities, EMA, logging callbacks, and visualization helpers. If you are drawing boundaries, this is the model development subsystem rather than the ComfyUI runtime subsystem.

10. Configuration and model loading are externalized. YAML configs live in `configs/` and `hy3dshape/configs/`, while the README points to Hugging Face-hosted checkpoints and diffusers-style models that are auto-downloaded at runtime. That means the repo code is mostly orchestration and model glue, with weights supplied separately.

11. The end-to-end data flow is: user input image in ComfyUI -> preprocessing/background removal -> shape generation -> surface extraction/mesh formation -> optional UV/texture generation -> postprocessing and export/preview. The outputs are 3D assets suitable for ComfyUI’s 3D preview and export paths, with OBJ/GLB support visible in the rasterizer and renderer utilities.

12. Operationally, this repo has a mixed Python + native-extension architecture. Python coordinates the graph, model loading, and data flow; C++/CUDA components accelerate rasterization and mesh operations; and ComfyUI provides the host UI/runtime. That separation is the main architectural boundary to capture in a diagram.

Main entry points: [`hy3dgen/shapegen/pipelines.py`](https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dgen/shapegen/pipelines.py) (Shape Pipe), [`hy3dgen/texgen/pipelines.py`](https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dgen/texgen/pipelines.py) (Texture Pipe), [`nodes.py`](https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/nodes.py) (Nodes), [`hy3dgen/shapegen/models/autoencoders/surface_extractors.py`](https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dgen/shapegen/models/autoencoders/surface_extractors.py) (Surface Decode)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["ComfyUI Host"]
  node_nodes_py["Nodes<br/>[nodes.py]"]
  node_web_js["Frontend JS<br/>UI glue<br/>[jsnodes.js]"]
end

subgraph group_shape["Shape Generation"]
  node_shape_pipe["Shape Pipe<br/>pipeline<br/>[pipelines.py]"]
  node_shape_pre["Shape Preprocess<br/>input prep<br/>[preprocessors.py]"]
  node_shape_models["Shape Models<br/>geometry model stack<br/>[hunyuan3ddit.py]"]
  node_shape_extract["Surface Decode<br/>mesh extraction"]
  node_odc["Dual Contouring<br/>geometry conversion"]
  node_shape_post["Shape Postprocess<br/>cleanup/export<br/>[postprocessors.py]"]
  node_rembg["Background Removal<br/>image prep<br/>[rembg.py]"]
end

subgraph group_texture["Texture Generation"]
  node_tex_pipe["Texture Pipe<br/>pipeline<br/>[pipelines.py]"]
  node_tex_utils["Texture Utils<br/>UV/mesh prep<br/>[uv_warp_utils.py]"]
  node_paint["HunyuanPaint<br/>texture synthesis<br/>[pipeline.py]"]
end

subgraph group_native["Native Acceleration"]
  node_raster["Rasterizer<br/>C++/CUDA kernel<br/>[render.py]"]
  node_renderer["Renderer<br/>[mesh_render.py]"]
  node_meshproc["Mesh Processor<br/>compiled extension<br/>[mesh_processor.cpp]"]
end

subgraph group_train["Training Stack"]
  node_shape_train["Shape Training<br/>training runtime<br/>[minimal_demo.py]"]
  node_train_models["Train Models<br/>[hunyuandit.py]"]
  node_train_utils["Train Utils<br/>training support<br/>[utils.py]"]
end

subgraph group_assets["Examples and Configs"]
  node_examples["Example Graphs<br/>workflows"]
  node_configs["Configs<br/>[dit_config.yaml]"]
end

node_nodes_py -->|"invokes"| node_shape_pipe
node_nodes_py -->|"invokes"| node_tex_pipe
node_web_js -->|"binds"| node_nodes_py
node_examples -.->|"demonstrates"| node_nodes_py
node_shape_pipe -->|"prepares input"| node_rembg
node_shape_pipe -->|"uses"| node_shape_pre
node_shape_pre -->|"feeds"| node_shape_models
node_shape_pipe -->|"orchestrates"| node_shape_models
node_shape_models -->|"decodes"| node_shape_extract
node_shape_extract -.->|"can use"| node_odc
node_shape_extract -->|"emits"| node_shape_post
node_shape_pipe -->|"finishes"| node_shape_post
node_tex_pipe -->|"prepares mesh"| node_tex_utils
node_tex_pipe -->|"orchestrates"| node_paint
node_tex_pipe -->|"accelerates"| node_raster
node_tex_pipe -->|"renders"| node_renderer
node_renderer -->|"extends"| node_meshproc
node_tex_utils -.->|"supports"| node_renderer
node_shape_post -->|"hands off"| node_tex_pipe
node_shape_train -->|"trains"| node_train_models
node_train_models -.->|"uses"| node_train_utils
node_shape_train -->|"loads"| node_configs
node_shape_pipe -->|"loads"| node_configs

click node_nodes_py "https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/nodes.py"
click node_web_js "https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/web/js/jsnodes.js"
click node_examples "https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/example_workflows/hy3d_example_01.json"
click node_shape_pipe "https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dgen/shapegen/pipelines.py"
click node_shape_pre "https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dgen/shapegen/preprocessors.py"
click node_shape_models "https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dgen/shapegen/models/hunyuan3ddit.py"
click node_shape_extract "https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dgen/shapegen/models/autoencoders/surface_extractors.py"
click node_odc "https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/ODC/occupancy_dual_contouring.py"
click node_shape_post "https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dgen/shapegen/postprocessors.py"
click node_tex_pipe "https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dgen/texgen/pipelines.py"
click node_tex_utils "https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dgen/texgen/utils/uv_warp_utils.py"
click node_paint "https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dgen/texgen/hunyuanpaint/pipeline.py"
click node_raster "https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dgen/texgen/custom_rasterizer/custom_rasterizer/render.py"
click node_renderer "https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dgen/texgen/differentiable_renderer/mesh_render.py"
click node_meshproc "https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dgen/texgen/differentiable_renderer/mesh_processor.cpp"
click node_rembg "https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dgen/rembg.py"
click node_shape_train "https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dshape/minimal_demo.py"
click node_train_models "https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dshape/hy3dshape/models/denoisers/hunyuandit.py"
click node_train_utils "https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dshape/hy3dshape/utils/utils.py"
click node_configs "https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/configs/dit_config.yaml"

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_nodes_py,node_web_js toneBlue
class node_shape_pipe,node_shape_pre,node_shape_models,node_shape_extract,node_odc,node_shape_post,node_rembg toneAmber
class node_tex_pipe,node_tex_utils,node_paint toneMint
class node_raster,node_renderer,node_meshproc toneRose
class node_shape_train,node_train_models,node_train_utils toneIndigo
class node_examples,node_configs toneTeal
```

## Components

### ComfyUI Host

Wrapper layer exposed to ComfyUI

- [Nodes](https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/nodes.py): ComfyUI nodes · Custom node entrypoints and runtime wiring · `nodes.py`
- [Frontend JS](https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/web/js/jsnodes.js): UI glue · Browser-side node integration for ComfyUI · `web/js/jsnodes.js`

### Shape Generation

Geometry inference subsystem

- [Shape Pipe](https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dgen/shapegen/pipelines.py): pipeline · Coordinates shape generation from conditioned inputs · `hy3dgen/shapegen/pipelines.py`
- [Shape Preprocess](https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dgen/shapegen/preprocessors.py): input prep · Image normalization and conditioning preparation · `hy3dgen/shapegen/preprocessors.py`
- [Shape Models](https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dgen/shapegen/models/hunyuan3ddit.py): geometry model stack · Core geometry models including conditioner, DiT, and autoencoder pieces · `hy3dgen/shapegen/models/hunyuan3ddit.py`
- [Surface Decode](https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dgen/shapegen/models/autoencoders/surface_extractors.py): mesh extraction · Volume decoding and surface extraction into usable geometry · `hy3dgen/shapegen/models/autoencoders/surface_extractors.py`
- [Dual Contouring](https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/ODC/occupancy_dual_contouring.py): geometry conversion · Occupancy-to-mesh extraction utility · `ODC/occupancy_dual_contouring.py`
- [Shape Postprocess](https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dgen/shapegen/postprocessors.py): cleanup/export · Geometry cleanup and final output handling · `hy3dgen/shapegen/postprocessors.py`
- [Background Removal](https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dgen/rembg.py): image prep · Foreground extraction before geometry and texture stages · `hy3dgen/rembg.py`

### Texture Generation

Appearance inference subsystem

- [Texture Pipe](https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dgen/texgen/pipelines.py): pipeline · Coordinates texture synthesis and UV-consistent painting · `hy3dgen/texgen/pipelines.py`
- [Texture Utils](https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dgen/texgen/utils/uv_warp_utils.py): UV/mesh prep · Alignment, UV warping, multiview, simplification, and dehighlighting · `hy3dgen/texgen/utils/uv_warp_utils.py`
- [HunyuanPaint](https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dgen/texgen/hunyuanpaint/pipeline.py): texture synthesis · Paint and inpainting-style texture generation branch · `hy3dgen/texgen/hunyuanpaint/pipeline.py`

### Native Acceleration

C++/CUDA rendering and mesh ops

- [Rasterizer](https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dgen/texgen/custom_rasterizer/custom_rasterizer/render.py): C++/CUDA kernel · Native rasterization and mesh IO acceleration · `hy3dgen/texgen/custom_rasterizer/custom_rasterizer/render.py`
- [Renderer](https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dgen/texgen/differentiable_renderer/mesh_render.py): native renderer · Differentiable rendering and mesh processing layer · `hy3dgen/texgen/differentiable_renderer/mesh_render.py`
- [Mesh Processor](https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dgen/texgen/differentiable_renderer/mesh_processor.cpp): compiled extension · Native mesh processing used for vertex inpainting and cleanup · `hy3dgen/texgen/differentiable_renderer/mesh_processor.cpp`

### Training Stack

Fine-tuning and model development subsystem

- [Shape Training](https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dshape/minimal_demo.py): training runtime · Fine-tuning and diffusion/flow-matching training stack · `hy3dshape/minimal_demo.py`
- [Train Models](https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dshape/hy3dshape/models/denoisers/hunyuandit.py): train models · Training-side denoisers, diffusion transport, and autoencoders · `hy3dshape/hy3dshape/models/denoisers/hunyuandit.py`
- [Train Utils](https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/hy3dshape/hy3dshape/utils/utils.py): training support · EMA, logging, visualizers, and training callbacks · `hy3dshape/hy3dshape/utils/utils.py`

### Examples and Configs

Workflows and config assets

- [Example Graphs](https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/example_workflows/hy3d_example_01.json): workflows · Sample ComfyUI workflows for end-to-end usage · `example_workflows/hy3d_example_01.json`
- [Configs](https://github.com/kijai/comfyui-hunyuan3dwrapper/blob/main/configs/dit_config.yaml): yaml configs · Model and training configuration files · `configs/dit_config.yaml`

## Connections

- Nodes → Shape Pipe: invokes · Custom nodes call into the geometry pipeline
- Nodes → Texture Pipe: invokes · Custom nodes expose texture generation stages
- Frontend JS → Nodes: binds · Frontend glue maps UI controls to custom nodes
- Example Graphs → Nodes: demonstrates · Example workflows show how the wrapper is used
- Shape Pipe → Background Removal: prepares input · Shape generation starts with foreground cleanup
- Shape Pipe → Shape Preprocess: uses · Pipeline applies input preprocessing and conditioning
- Shape Preprocess → Shape Models: feeds · Preprocessed inputs are passed to the geometry model stack
- Shape Pipe → Shape Models: orchestrates · Main geometry pipeline coordinates the core model stack
- Shape Models → Surface Decode: decodes · Latent geometry is converted into surfaces/volumes
- Surface Decode → Dual Contouring: can use · Occupancy outputs may be converted with dual contouring
- Surface Decode → Shape Postprocess: emits · Extracted geometry flows into postprocessing
- Shape Pipe → Shape Postprocess: finishes · Pipeline returns cleaned mesh/geometry outputs
- Texture Pipe → Texture Utils: prepares mesh · Texture pipeline uses UV, alignment, and multiview helpers
- Texture Pipe → HunyuanPaint: orchestrates · Texture generation delegates synthesis to the painting branch
- Texture Pipe → Rasterizer: accelerates · Rasterization is handled by native CUDA/C++ code
- Texture Pipe → Renderer: renders · Differentiable rendering supports texture projection and refinement
- Renderer → Mesh Processor: extends · Compiled mesh processing backs renderer-side mesh edits
- Texture Utils → Renderer: supports · Mesh and UV utilities prepare data for rendering and painting
- Shape Postprocess → Texture Pipe: hands off · Generated geometry becomes the input mesh for texturing
- Shape Training → Train Models: trains · Training pipelines drive the model implementations
- Train Models → Train Utils: uses · Model development relies on training helpers and visualizers
- Shape Training → Configs: loads · Training and model settings are externalized in YAML configs
- Shape Pipe → Configs: loads · Inference pipelines also depend on config files
