Hunyuan 3D 2.1 Mesh Generator

Here's the thing people miss on first contact with this pack: this node does not output a mesh. It outputs latents, and a separate VAE decode node turns those latents into the actual mesh you can export. If you wire it straight into a 3D viewer and see nothing, that's not a bug - it's the pipeline working as designed.

Hunyuan 3D 2.1 Mesh Generator is the workhorse of visualbruno's ComfyUI wrapper around Tencent's Hunyuan3D-2.1 image-to-3D model. This is the pack you reach for when you want a single flat image turned into a textured 3D asset locally, no cloud service, no API key. It builds on the lineage kijai started with his Hunyuan3D wrapper for the 2.0 model; visualbruno ports that energy forward to 2.1 and vendors Tencent's own hy3dshape code inside the repo.

How it works. The node loads the DiT (diffusion transformer) checkpoint through Hunyuan3DDiTFlowMatchingPipeline.from_single_file using the bundled dit_config_2_1.yaml, runs a flow-matching diffusion process conditioned on your image, and produces a latent representation of the shape. It never touches pixels for the output - the latent is a compact shape encoding that the ShapeVAE (in Hy3D21VAEDecode) expands back into a mesh via an octree and marching cubes. The full chain looks like this: image → this node → latents → Hy3D21VAEDecode (+ a VAE) → trimesh → Hy3D21PostprocessMesh → Hy3D21ExportMesh.

The inputs that matter:

• model - a dropdown of every file in ComfyUI/models/diffusion_models. Pick the Hunyuan 3D 2.1 checkpoint you dropped there (the pack's README tells you to place hunyuan3d-dit-v2-1.ckpt, about 6.9 GB).
• image - the picture you're reconstructing. Feed it a clean, single subject on a plain background: the background-removal call is commented out in the source, so this node will happily try to reconstruct the whole scene if you let it.
• steps (default 50) and guidance_scale (default 5.0) - the usual diffusion dials. Lower steps are faster and mushier; 50/5.0 is a fine starting point.
• attention_mode - sdpa (default, nothing extra to install) or sageattn, which only works if you've separately installed the sageattention package. Don't bother unless you know you want it.

One honest quirk: the seed widget goes up to a 64-bit number, but the code masks it to 32 bits, so you effectively only have ~4 billion distinct seeds. Plenty, but don't expect your 17-digit number to matter.

Output. A single latents output of type HY3DLATENT, which wires into Hy3D21VAEDecode. The VAE comes from Hy3D21ModelLoader or Hy3D21VAELoader.

Installing. ComfyUI Manager (search "Hunyuan3d" and install the pack, which pulls requirements.txt), or:

cd ComfyUI/custom_nodes
git clone https://github.com/visualbruno/ComfyUI-Hunyuan3d-2-1
cd ComfyUI-Hunyuan3d-2-1
python -m pip install -r requirements.txt

The pack's README targets Windows 11, Python 3.12, Torch ≥ 2.6. The C++ rasterizer and differentiable-renderer wheels it front-and-centers are for the texturing side of the pack - plain mesh generation doesn't need them, which matters if you're on Linux and don't want to compile anything.

Where people get burned. Python 3.13 breaks the prebuilt wheels, and the community threads about it are basically a support forum by themselves - stick to 3.12. This is also a hungry one: a ~7 GB fp16 DiT plus decode at default 384 octree resolution wants real VRAM; an 8 GB card means offloading and patience. And if you're in the EU, UK, or South Korea, remember Hunyuan's community license excludes those territories - the weights are open, the paperwork is not.