UV Cube Project

UV Cube Project is the unwrap at the heart of Avatar Graph's texture pipeline. It wraps bpy.ops.uv.cube_project, Blender's cube-mapping unwrap: it projects the mesh outward onto an imaginary cube and lays the six sides flat into UV space. That's exactly how the pack maps your generated character image onto the mesh planes that become the avatar - in fact the README's own Plane Texture Unwrap node is described as performing a UV cube project under the hood.

So while it reads like one more auto-generated Blender wrapper, this one is load-bearing. Any time a character image has to sit on geometry without distortion, cube projection is the default answer: it's fast, it handles arbitrary shapes, and it produces the kind of straight-ish islands that read cleanly once you rotate and align them. Reach for it after you've built or imported a mesh layer and before you start adjusting UVs.

How it works

A UV_* EditOps node: enter edit mode, run the operator on the selected faces, exit, return the object. The inputs:

• cube_size - the size of the imaginary cube (default 1). It controls the scale of the projected islands in UV space. Smaller cube → islands use more texture space; tune it to fit your texture's resolution.
• correct_aspect (default true) - correct for non-square texture aspect ratios so the projection isn't squished. Leave it on.
• clip_to_bounds - clamp the projected UVs to the 0–1 texture bounds. On when you want everything packed into the unit square (useful if the texture is meant to fill the whole image).
• scale_to_bounds - scale islands to fit within the texture bounds without clipping. The README's Plane Texture Unwrap node "scaled to bounds" is this option doing its thing - it's why your character's face doesn't get cropped off the texture edge.

The selection caveat applies as always: it unwraps the currently selected faces in the shared scene, so select what you mean before running it.

Inputs that matter

BPY_OBJ, cube_size (texture fit), scale_to_bounds (keep everything inside the image), clip_to_bounds when you want strict packing.

Output: BPY_OBJ - the mesh, unwrapped, for the next node.

Installing it

Part of the Avatar Graph pack (Avatech AI). ComfyUI Manager → search "Avatar Graph", or:

cd ComfyUI/custom_nodes
git clone https://github.com/avatechai/avatar-graph-comfyui
cd avatar-graph-comfyui && python -m pip install -r requirements.txt

Restart after. Pack gotchas: bpy==3.6.0 needs Python 3.10.x or the whole pack fails to import, and first launch downloads the SAM ViT-H model (~2.5 GB) to ComfyUI/models/sams plus two MediaPipe landmarker files.

Common issues

• "No module named bpy" → Python 3.10.x. Standard for this pack.
• Texture is stretched or cut off → check scale_to_bounds (keeps it inside) and cube_size (fits the projection). A wrong cube_size is the usual culprit.
• The unwrap is there but the image looks rotated → cube projection doesn't care about your art's orientation. Follow with UV_AlignRotation (AUTO) to square islands up.
• Nothing unwrapped → no faces selected, or the mesh already has a UV layer the operator is adding to. Select upstream and, if needed, remove/recreate the UV layer.
• Scene resets between runs - project and export in one graph.

This is one of the few genuinely central nodes in the pack's generated mass. If you're making avatars, cube project is the step that turns art into geometry.