UV Unwrap

If you've ever wondered how a flat character illustration turns into something you can paint textures onto in 3D, UV Unwrap is that step. It's part of Avatar Graph (avatar-graph-comfyui), a node pack by Avatech that turns ComfyUI into a lightweight rigging tool - you segment a character image, build a mesh for each body part, and wire up shape keys so the thing can blink and talk in real time. UV Unwrap is one of the plumbing nodes that makes texturing those meshes possible.

Under the hood this node is a direct wrapper around Blender's own bpy.ops.uv.unwrap operator - literally the same "Unwrap" command you'd hit in Blender's UV editor. Avatar Graph embeds bpy (Blender-as-a-library) inside ComfyUI, and most of its nodes, this one included, are thin passthroughs of a real Blender operator's parameters. So if you already know Blender's unwrap tool, you already know this node.

What it does: it takes the mesh on the incoming BPY_OBJ and flattens its 3D surface into 2D UV space, so a texture image can be mapped onto it correctly instead of stretching and smearing. You'd reach for this right after generating or editing a mesh layer (say, the mesh for an eye or a mouth cut from your segmented character art) and before you try to project a texture onto it.

The inputs that actually matter for a beginner:

• method - ANGLE_BASED or CONFORMAL. Angle-based tries to minimize angle distortion and generally looks better on organic shapes; conformal is faster and simpler but distorts more. Angle-based is the safer default for anything that isn't a perfect flat plane.
• fill_holes - leave this on (it's the default). It patches non-manifold gaps in the mesh before unwrapping so the operation doesn't choke on holes.
• margin - the padding between UV islands, as a fraction. The tiny default (0.001) is fine unless you're seeing texture bleed between parts at the seams, in which case bump it up slightly.

correct_aspect and use_subsurf_data are edge cases you can leave alone unless you know you need them - correct_aspect adjusts for non-square texture images, and use_subsurf_data only matters if your mesh has a Subdivision Surface modifier, which nothing else in this basic pipeline sets up. margin_method just controls how the margin number gets interpreted (scaled vs. absolute vs. fraction) - leave it on the default unless your margin isn't behaving how you expect.

The output is the same BPY_OBJ, now carrying UV data, ready to feed into whatever texturing or export step comes next.

Installing it: this node lives inside the whole Avatar Graph pack, not standalone, so you install the pack once and get all ~100 nodes including this one. Easiest path is ComfyUI Manager - search for "Avatar Graph" or avatar-graph-comfyui. Manually, it's cd ComfyUI/custom_nodes && git clone https://github.com/avatechai/avatar-graph-comfyui, then pip install -r requirements.txt inside that folder, then restart.

Here's the part that actually trips people up: Avatar Graph needs Python 3.10.x specifically, because the bpy package it depends on is compiled against that exact interpreter version. If your ComfyUI environment is on 3.11 or 3.12 (common these days), the install will fail or the node pack won't load at all - set up a dedicated conda env (conda create --name comfyui python=3.10) rather than fighting your existing environment. If you want the live preview in Avatech's web viewer, you also need to launch ComfyUI with --enable-cors-header (Mac users add --force-fp16 too); skip that flag and everything still runs, you just export a .glb/.gltf and view it elsewhere instead.

One more thing worth knowing: this whole pack is explicitly a work in progress per the README, so don't be shocked if node behavior shifts between versions. And since BPY_OBJ is Avatar Graph's own handle type, this node only works wired to a mesh that came from earlier in an Avatar Graph chain - you can't feed it a mesh type from an unrelated 3D pack.