UV Sphere Project

Some meshes aren't meant for planar projection. A head, a nose, an eye - anything with real curvature - will stretch badly if you flatten it like a sheet. UV Sphere Project is the answer when the mesh is roughly ball-shaped: it projects the UVs as if a sphere were wrapped around the geometry, which is exactly the right model for a face.

It wraps Blender's bpy.ops.uv.sphere_project() in the Avatar Graph pack's auto-generated UV operator family. In the avatar pipeline, this is the node you reach for after UV Smart Project leaves ugly seams on a curved feature - sphere projection trades those hard angle splits for smooth, pole-to-pole flow.

The settings that matter

• direction - how the projection orients the sphere:
  • VIEW_ON_EQUATOR / VIEW_ON_POLES - the sphere's equator or poles face the view.
  • ALIGN_TO_OBJECT - align to the object's local axes instead. Usually the more predictable pick for a head mesh that has a sensible local orientation.
• align (POLAR_ZX / POLAR_ZY) - which axis becomes the sphere's pole. For a face, you want the pole on the axis that runs through the top of the head, so the front of the face lands around the equator.
• pole (PINCH / FAN) - how the poles are triangulated. FAN radiates triangles out from the pole and is generally less distorting than PINCH.
• seam (bool, default off) - mark the projection's seam edges as seams on the mesh. Turn it on if you want the seam visible for later stitching decisions.
• correct_aspect (bool, default on) - keep aspect ratio correct. Leave it on.
• clip_to_bounds / scale_to_bounds (bool, default off) - clamp the result to the 0–1 texture square and/or scale it to fill. Useful for texture-paint workflows; for avatar export you usually want proportional scaling instead.

How it works

Standard wrapper: edit mode, operator, same BPY_OBJ back. The projection writes a fresh UV layout onto the mesh's UV layer (creating it if there isn't one), discarding whatever was there. Because the result is one big island split only by the seam, it pairs beautifully with downstream pinning and stitching - pin the features you care about, run the projection, and the pinned anchors survive as fixed reference points.

Installing it

Avatar Graph installs as one pack, and Python is the wall: bpy==3.6.0 is pinned, so Python 3.10 is required in your ComfyUI environment. ComfyUI Manager search: "Avatar Graph." Manual:

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 ComfyUI, then let the first launch download the SAM ViT-H model (~2.5 GB) and mediapipe face/pose landmarkers. Add --enable-cors-header for the live editor preview, or export a .GLB via right-click on Avatar Main Output.

Troubleshooting

The classic sphere-project mistake is forgetting it's sphere-shaped: on a boxy or elongated mesh the projection stretches everything toward the poles, and the result looks like a rubber sheet pulled over a football. If that happens, the mesh isn't sphere-like and UV Smart Project (or manual unwrap) is the better tool. Also check align - get the pole axis wrong and the face texture wraps sideways, which reads as "broken" but is just a misconfigured axis.