Hunyuan 3D 2.1 Mesh Generator from Folder

The flagship node of the ComfyUI-Hunyuan3d-2-1 pack, and the one that does the actual magic: it runs Tencent's Hunyuan3D 2.1 image-to-3D pipeline on every picture in a folder and drops a ready mesh next to each one. Single-image-to-3D is fine when you have three reference shots; the moment you have a catalog of products, a stack of concept art, or a hundred photos of props from a shoot, clicking through one at a time gets old fast. This node is the "do them all overnight" button.

Hunyuan3D 2.1 is genuinely good at this - it's one of the reasons Tencent's 2026 releases pushed hard into 3D. You feed it one image and get back a textured-capable mesh with UVs, roughly 200k faces by default. "Production-ready" is the pack's own word, and for game-asset placeholder duty or product shots it mostly earns it.

How it works

Under the hood it's the same pipeline as the non-batch generator: a Hunyuan DiT flow-matching model (hunyuan3d-dit-v2-1.ckpt) turns your image into latents, then the ShapeVAE decodes those into an octree volume, which gets turned into a triangle mesh by marching cubes (or dual marching cubes, mc_algo="dmc"). The mesh is then cleaned up and, if you leave simplify on, decimated down to target_face_num faces using the meshlib decimator - 200,000 is a sane default that keeps files light without butchering details.

The pipeline is loaded once and reused across every image, which is the whole point of the batch node. That's also why it's a memory hog: the DiT and the VAE both stay resident while it chews through the folder.

The inputs that matter

Most of the 20-odd knobs you can leave alone. Set these:

• input_folder / output_folder - where the images are, where the meshes land. Paths are plain strings, not ComfyUI model pickers.
• dit_model_name / vae_model_name - the two checkpoints, picked from models/diffusion_models and models/vae respectively.
• file_format - glb (default) or obj. GLB bundles texture data cleanly and is what the rest of this pack expects.
• remove_background - flips on rembg for images that already have messy backgrounds. Leave off if your inputs are already cut out; it costs time per image.
• skip_generated_mesh - leave this on. If an output file already exists, the node skips it. That's your resume-after-crash superpower.
• generate_random_seed - on by default; off and it reuses the fixed seed for every image, which you almost never want.

The niche stuff (octree_resolution, mc_level, num_chunks, box_v) tunes the geometry extraction. Defaults are tuned for the released checkpoint - higher octree_resolution (up to 4096) buys detail at serious VRAM cost.

Outputs

It's an output node returning four strings: the input_folder, the output_folder, plus processed_input_images and processed_output_meshes - the list of files it actually processed and where each mesh landed. Mostly you read these in the console; they're handy if you chain a script onto the end.

Installing the pack

This is not a two-minute install, so read this once and blame me later. Start the normal way:

cd ComfyUI/custom_nodes
git clone https://github.com/visualbruno/ComfyUI-Hunyuan3d-2-1

Then install the Python deps (there are a lot: trimesh, pymeshlab, open3d, diffusers, xatlas, meshlib, …):

pip install -r ComfyUI/custom_nodes/ComfyUI-Hunyuan3d-2-1/requirements.txt

Grab the two checkpoints from HuggingFace and drop them in place:

ComfyUI/models/diffusion_models/hunyuan3d-dit-v2-1.ckpt
ComfyUI/models/vae/hunyuan3d-vae-v2-1.ckpt

The trap: the texture pipeline needs two C++ extensions (custom_rasterizer and the differentiable renderer) compiled in. The README ships prebuilt wheels for Windows + Python 3.12 only (win_amd64). On Windows you can pip install those from hy3dpaint/custom_rasterizer/dist and hy3dpaint/DifferentiableRenderer/dist. On Linux you're compiling them yourself with python setup.py install and you need a working C++ toolchain. People also hit an "optional" xatlas patch for UV-wrapping high-poly meshes - follow the README's PowerShell snippet only if unwrapping chokes on complex geometry.

Common issues

• ModuleNotFoundError: No module named 'hy3dpaint' - the C++ extensions aren't built/installed. That's the #1 Linux failure mode, straight from community threads.
• Missing checkpoint error - the model names you pick must actually exist in those two folders; the enum only lists what's there.
• OOM mid-batch - drop octree_resolution to 256 or turn on force_offload (optional input) so the VAE is shoved off-GPU when a single image finishes.
• License reality check - Hunyuan3D 2.1 ships under Tencent's community license: fine for most of us, but the grant explicitly excludes the EU, UK, and South Korea, and has a 100M monthly-active-users ceiling. If you're commercial in one of those regions, that's a lawyer conversation, not a settings question.