ComfyUI-Hunyuan3D Introduction
ComfyUI-Hunyuan3D adds a small set of nodes to complement ComfyUI’s built-in Hunyuan3D-2 support. Together, they help turn an input image into a 3D mesh, prepare that mesh for a later texturing workflow, and export it in a usable file format.
The extension fills four practical gaps in an image-to-mesh workflow: loading an image from a URL, converting ComfyUI’s mesh output into a form the later nodes can use, creating UV coordinates, and saving the result. It was designed to support a Graydient image-to-mesh pipeline, but its mesh-preparation and export nodes are useful wherever the same ComfyUI outputs are available.
The resulting mesh is shape-only. UV unwrapping prepares its surface for texture painting or baking; it does not create or apply a texture.
How ComfyUI-Hunyuan3D Works
Think of the workflow as making and preparing a digital sculpture:
- Provide a reference image. Load an image from a local file or, with this extension’s URL loader, from a web address.
- Generate the shape. ComfyUI’s native Hunyuan3D-2 nodes process the image and produce a mesh through
VoxelToMesh. - Prepare the mesh.
Mesh to Trimeshconverts that output for the extension’s subsequent nodes.UV Unwrap Meshthen creates UV coordinates, which act like a flat map of the sculpture’s surface for later painting or baking. - Export the result.
Save Trimeshwrites the prepared mesh to a 3D file.
The pipeline shown in the author’s original README is:
LoadImage / Hy3DLoadImageFromURL
-> ImageOnlyCheckpointLoader (hunyuan3d-dit-v2-mv-turbo)
-> CLIPVisionEncode -> Hunyuan3Dv2ConditioningMultiView
-> KSampler -> VAEDecodeHunyuan3D -> VoxelToMesh
-> Hy3DMeshToTrimesh -> Hy3DUVUnwrapMesh -> Hy3DSaveTrimesh
The Hunyuan3D-2 generation nodes in this example are part of ComfyUI’s native support (comfy_extras.nodes_hunyuan3d). ComfyUI-Hunyuan3D supplies the URL-loading, mesh-conversion, UV-unwrapping, and export steps around them.
ComfyUI-Hunyuan3D Features
- Load Image From URL (
Hy3DLoadImageFromURL) downloads an input image from a URL. It provides an alternative to loading a local image and supports Graydient’sinit_image_urlfield mapping, which cannot use ComfyUI’s usual local-file validation in the same way. - Mesh to Trimesh (
Hy3DMeshToTrimesh) converts the nativeMESHoutput fromVoxelToMeshinto atrimeshobject. This is a compatibility step: place it between mesh generation and the extension’s UV or export nodes. - UV Unwrap Mesh (
Hy3DUVUnwrapMesh) usesxatlasto create a single-chart UV unwrap. This gives the shape-only mesh UV coordinates for a follow-up texture-painting or baking workflow. It prepares a place for texture detail; it does not add that detail itself. - Save Trimesh (
Hy3DSaveTrimesh) exports the mesh as GLB, OBJ, PLY, STL, 3MF, or DAE. Choose an export format based on the requirements of the application or workflow where you plan to use the mesh.
The supplied documentation does not specify additional controls or recommended values for these nodes. The main choices it describes are whether to use a local image or URL, whether to UV unwrap before export, and which supported file format to save.
For a Graydient deployment that needs to return a GLB through an image-only output channel, the author recommends pairing this extension with Meshsmuggler.
ComfyUI-Hunyuan3D Models
The example pipeline names hunyuan3d-dit-v2-mv-turbo as the checkpoint loaded by ImageOnlyCheckpointLoader for Hunyuan3D-2 shape generation. ComfyUI-Hunyuan3D itself adds workflow nodes, not a separate model. The supplied documentation does not list other checkpoints or compare their outputs or performance.
Troubleshooting ComfyUI-Hunyuan3D
The UV or save node cannot use the output from VoxelToMesh.
- Check that
VoxelToMeshis producing the nativeMESHoutput. - Connect that output to
Hy3DMeshToTrimesh. - Connect the converted output to
Hy3DUVUnwrapMeshand thenHy3DSaveTrimesh, as shown in the pipeline above.
A URL-based image input does not work with the usual local image loader.
- Check whether your workflow is supplying a URL rather than a local file.
- Use
Hy3DLoadImageFromURLfor the URL input. - In a Graydient workflow, check that
init_image_urlis mapped to that URL-loading step.
The exported mesh has no painted appearance.
The documented Hunyuan3D-2 workflow produces a shape-only mesh. Hy3DUVUnwrapMesh creates UV coordinates but does not generate a texture. Use a separate texture-painting or baking workflow after unwrapping if your project needs surface color or detail.
Which export format should I choose?
Hy3DSaveTrimesh supports GLB, OBJ, PLY, STL, 3MF, and DAE. Check which format your next application accepts. For the Graydient output workflow described by the author, the intended file is GLB.
Does this extension replace ComfyUI’s Hunyuan3D-2 nodes?
No. It complements ComfyUI’s native Hunyuan3D-2 support. The example pipeline uses native nodes to generate the shape and this extension’s nodes to handle URL input, mesh preparation, UV unwrapping, and export.
Learn More about ComfyUI-Hunyuan3D
- ComfyUI’s native Hunyuan3D-2 nodes: Look for
comfy_extras.nodes_hunyuan3dwhen examining the shape-generation portion of a workflow. The pipeline above shows where those nodes connect to this extension. - Meshsmuggler: See the project linked by the author for the Graydient-specific step of returning a GLB through an image-only output channel.
