Hy3D Mesh UV Wrap

A generated 3D mesh doesn't come with a usable UV map - it comes with whatever garbage unwrap the VAE extraction left behind. Hy3DMeshUVWrap is the mandatory cleanup: it runs xatlas parametrization over the mesh, producing a clean UV layout, and returns the same mesh with proper UVs. Without this step, the paint and bake stages have nothing sane to project onto and your texture comes out scrambled.

It's a one-in, one-out node: trimesh in, trimesh out. No knobs, no settings. You put it between the geometry stage and the render stage, exactly where it sits in both of kijai's example workflows:

Hy3DGenerateMesh → Hy3DVAEDecode → Hy3DMeshUVWrap → Hy3DRenderMultiView → ...

How it works

The node hands your vertices and faces to xatlas.parametrize, which does the actual UV unwrapping, then rewrites the mesh's vertex and UV data from the result. If you feed it a trimesh scene rather than a single mesh, it concatenates the geometry first. Under the hood this is the same xatlas library Blender and most 3D tools use for automatic UVs, so the output is exactly what you'd expect from an auto-unwrap: functional, not artist-grade. Fine for baking textures onto, not something you'd ship to a game engine without a manual pass.

The known weak spot

xatlas is great up to a point, and that point is roughly 50,000 faces. The node will warn (not fail) when your mesh exceeds that - the code prints "UV wrap: The mesh has more than 50,000 faces, which is not recommended." Bigger meshes make xatlas slow and the unwrap quality drops.

The pack README documents a whole upgrade procedure for exactly this: uninstall the pip xatlas, clone mworchel/xatlas-python with a newer upstream xatlas, flip two #if lines in xatlas.cpp to enable the newer parametrization, and reinstall. It's fiddly but it's the documented fix if you keep hitting the 50k wall. The cheaper fix for most people: run Hy3DFastSimplifyMesh first to get under the threshold, then UV wrap.

Install

Ships with the pack (ComfyUI Manager, search "Hunyuan3DWrapper", or clone into custom_nodes). xatlas is in the pack's requirements.txt, so it installs with the pack - but note the wheel version pip grabs may be the old one the README warns about, which is why the upgrade procedure exists. If your UV wraps are fine, don't touch it; if they're wrong or slow, follow the README's xatlas upgrade.