Hunyuan 3D 2.1 Mesh UV Wrap

Every textured mesh needs a UV map - the flattened "skin" that tells the texture where each vertex goes. Hy3D21MeshUVWrap is the node that makes one. It takes a TRIMESH, runs it through xatlas' UV unwrapping (mesh_uv_wrap from the pack's hy3dpaint code), and hands back a mesh with UV coordinates attached. That's it. No knobs, no options - one input, one output. The entire node is a single function call.

Which is exactly why it's so easy to forget, and so easy to regret skipping. If you feed an unwrapped mesh into Hy3DMultiViewsGenerator or Hy3DBakeMultiViews, the baking step has nowhere to put color, and you get seams, smears, or a texture that never lands where you want it. In every example workflow the author ships, the order is: decode → postprocess → UV wrap → generate views → bake.

How it works

Xatlas is the de-facto standard open-source UV unwrapper, and this node wraps the Python port. Given an unrolled UV layout, the later paint/bake nodes can project the multi-view renders onto the surface. On a raw mesh straight out of Hy3D21VAEDecode - which can be hundreds of thousands of triangles - this is where a genuinely high-poly mesh starts to push the unwrapper hard.

The one thing to know: the patched xatlas

The pack's README devotes a whole section to this, and it matters. The default xatlas from pip can struggle or crash on very high-poly meshes. The fix the author documents: uninstall pip's xatlas, clone mworchel's xatlas-python with a patched jpcy/xatlas source, flip two #if 0/#endif guards in xatlas.cpp, and install that instead. It's fiddly, it's Windows-centric (the README's PowerShell version is the canonical one), and for 90% of meshes you don't need it. Do the default install first, and reach for the patch only when a big mesh chokes.

Installing it

The node itself installs with the pack:

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

xatlas is in that requirements file, so the plain version comes along for free. The patched rebuild is optional and only worth the effort if you're regularly unwrapping meshes big enough to make stock xatlas cry.

Common issues

If UV wrapping hangs or errors on a dense mesh, you've hit the high-poly case the README warns about - apply the patched xatlas, or (much simpler) drop face count first with Hy3D21MeshlibDecimate or Hy3D21PostprocessMesh. Also note this node expects a TRIMESH from the same pack - you can't just feed it any random MESH output from another node pack without a conversion. Keep the pipeline inside this pack's types and you'll be fine.