UnwrapUV_xatlas

Generated and scanned meshes usually have no usable UVs - or none at all. UnwrapUV_xatlas (from ComfyUI-3D-MeshTool) fixes that by running the mesh through xatlas, the C++ auto-unwrap library behind a lot of modern UV tooling (the README calls it "the latest 2023 UV unwrapping algorithm"). One connection, and your mesh comes out with fresh UV coordinates ready for texture baking or painting.

This is the node that saves you a Blender round-trip when you're doing 3D in ComfyUI: generate a mesh, unwrap it here, and you're ready to bake.

How it works

It takes a MESH plus an optional UV_options object, then:

1. Converts the mesh's vertices and faces to numpy arrays.
2. Builds an xatlas.Atlas(), adds the mesh, and calls generate() - xatlas's chart-packing pass that cuts the surface into charts and packs them into the UV square.
3. Pulls back the resulting UV vertices (vt), UV face indices (ft), and the vmapping array that links original vertices to UV vertices.
4. Writes vt/ft back into the mesh as torch tensors on the mesh's own device.

The UV_options input is a chart_options object - either the output of the pack's UV_options node or nothing at all. Leave it unconnected and xatlas's built-in defaults apply, which is perfectly fine for most meshes.

Outputs

• mesh (MESH) - the same mesh, now with vt/ft populated
• vmapping (LIST) - the vertex → UV-vertex mapping, useful if you're re-indexing per-vertex data (like vertex colors or custom attributes) into UV space

Note the caveat: this replaces any UVs the mesh already had. If you were hoping to keep an existing UV layout, back it up with Mesh_Data_Get first.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/807502278/ComfyUI-3D-MeshTool
cd ComfyUI-3D-MeshTool
pip install -r requirements.txt

Restart ComfyUI. Or via ComfyUI Manager, search "ComfyUI-3D-MeshTool". The unwrap runs on xatlas, which is in the pack's requirements - a compiled wheel for most platforms, so the install is usually painless. No model downloads.

Common issues

xatlas needs a clean, manifold-ish mesh to do a good job. Run Mesh_Cleanup first on scanned geometry - unwrapping a mesh full of duplicate vertices and non-manifold faces produces chaotic charts. If the output mesh's UVs look like a mess of tiny islands, your input mesh is the problem, not the unwrapper. And since generate() runs on CPU, very dense meshes (millions of faces) can take a while - the node isn't hung, it's packing.