🌍 HunyuanWorld: Image to 3D (Real)

This is the payoff node of the HunyuanWorld pack. Give it an image and a loaded pipeline and it does the thing you actually came for: a textured 3D mesh saved as a GLB file in your ComfyUI output folder, ready to drag into Blender or a game engine. The pack's other two nodes (the Simplified wrapper and the Hybrid) are scaffolds today - this one and its loader are the working half, and this is the half that produces the file.

Why you'd reach for it: image-to-3D is the corner of Tencent's Hunyuan lineup that has almost no open-weights competition, and Hunyuan3D is what took that niche in 2025. This node wraps the official hy3dgen shape and paint pipelines, so you get real geometry, not a depth-map fake. You wire it straight after HunyuanWorldModelLoader - there's a custom HUNYUAN3D_PIPELINE type flowing between them, and nothing else in ComfyUI produces that type.

How it works

Mechanically it's straightforward, which is a relief for a 3D node. It takes your ComfyUI IMAGE tensor, flips it to a PIL image, writes it to a temp PNG, and feeds that path to the Hunyuan3D shape pipeline - the DiT flow-matching model from the official library - which returns a mesh. If apply_texture is on and the loader loaded a texture pipeline, it runs the paint step on that same image and UV-bakes the color onto the mesh. Then it exports the mesh, and tries to render a 512×512 preview of it for you to look at.

The inputs that matter

• pipeline - must come out of HunyuanWorldModelLoader. Nothing else produces the HUNYUAN3D_PIPELINE type, so skip the loader and you'll have a dangling wire.
• image - the reference photo. Single object, clean background, decent lighting; Hunyuan rewards that like most image-to-3D models do.
• apply_texture - on by default. Turn it off only if you want a bare white mesh and faster runs.
• save_mesh and filename_prefix - together these decide whether you get a file and what it's called. The node appends a random 4-digit suffix, so you won't clobber earlier runs.
• seed - optional, default -1 means random. Set it if you want to reproduce a run.

Outputs: mesh_path (a string pointing at the saved .glb), info (a plain-text summary of what you got), and preview_image, which you can drop into a Save Image or Preview Image node.

Installing it

The pack is a normal custom node, but it needs one extra thing most packs don't:

cd ComfyUI/custom_nodes
git clone https://github.com/A043-studios/ComfyUI_HunyuanWorldnode.git
cd ComfyUI_HunyuanWorldnode
python install.py        # or: pip install -r requirements.txt

# The step the requirements file skips - the actual Hunyuan3D library:
git clone https://github.com/tencent/hunyuan3d-2.git
cd hunyuan3d-2
pip install -e .

Restart ComfyUI after that. The pack's own requirements.txt covers torch, diffusers, trimesh and friends but not hy3dgen - so if you skip the pip install -e . step the node loads fine and then dies at runtime with "Hunyuan3D libraries not available." First generation also downloads the model from HuggingFace, which is several gigabytes; the loader's model_name choice decides which one. Start with tencent/Hunyuan3D-2mini.

What people get burned by

The most common surprise is a black preview image. The node renders its preview through trimesh's offscreen scene renderer, and on many setups that silently fails - the code catches it and hands you a black placeholder. The GLB is still saved and still fine; check mesh_path before you assume it broke. Second, texture quality is modest - think game-jam prototype, not AAA. Hunyuan's paint step is known for rough UVs. And a small but sharp gotcha from the community: if you later export the mesh as OBJ, the textures vanish. Stick with the GLB this node writes, since the textures are baked into it.

Keep expectations honest about VRAM too: the full Hunyuan3D-2 wants ~8GB+, the mini variant is the ~4GB test bed. That's why the loader defaults to low-VRAM mode.