Extract Boundary Points

This node bridges the gap between "I segmented a region of a face" and "I have a mesh." Avatar Graph's whole pitch is rigging a real-time avatar out of a single character portrait - you select the eyes, the mouth, whatever needs to move - and something has to turn those selected blobs into actual polygon outlines that Blender's bpy mesh API can build geometry from. That something is Extract Boundary Points: it runs OpenCV contour-finding on your segmentation mask, picks the biggest contour, and hands back a clean list of (x, y) points tracing its outline.

How it works

Under the hood it's straightforward computer vision, not anything Avatar Graph invented: grayscale the image, run cv2.findContours, and if there's more than one contour (segmentation is never perfectly clean), keep only the largest by area. Everything smaller is discarded - so if your segmentation left stray specks or you fed it an image with two disconnected blobs, only one survives.

The inputs and outputs that matter

• image (IMAGE, required) - the segmented mask, not the original photo. This needs to already isolate the region you care about (say, the mouth) as a distinct blob against the rest of the image.
• n_points (INT, default -1, range -1 to 100) - this is the knob you'll actually touch. -1 keeps every point along the contour, which on a real photo can be hundreds of pixel-level points - dense, jagged, and not great for building clean mesh geometry from. Set it to something like 20–40 and the node evenly downsamples the contour to that many points, giving you a much more workable outline for the mesh-building steps downstream.

Two outputs: POINTS, the list of boundary points (each carries x, y, and a couple of internal bookkeeping fields) that feeds into whatever builds your mesh layer next, and IMAGE, a copy of your input with the detected contour drawn on top in green - genuinely useful as a sanity check before you commit to building geometry from it.

How to install it

Via ComfyUI Manager: search "Avatar Graph" (avatar-graph-comfyui), install, restart. Manually:

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

Same constraint as the rest of the pack: bpy==3.6.0 is pinned in requirements.txt, and that only installs on Python 3.10.x. Windows users get a bundled Python 3.10 ComfyUI zip from the README; Mac/Linux users should build a dedicated conda env rather than trying to force an existing 3.11/3.12 environment to accept it. This node's own dependency, opencv-contrib-python, comes along with that same install - along with segment-anything and mediapipe for the rest of the pack's segmentation pipeline, so expect a heavier-than-usual install.

Common issues & troubleshooting

"No contours found." This is a message the node raises itself, and it's exactly what it sounds like: your input image has no distinct segment for OpenCV to trace - either it's an unsegmented photo (feed it a mask, not the raw portrait), or the mask is empty/uniform (all one color, nothing selected). Check that whatever produced your segmentation actually painted a distinct region - the node's own hint is to make sure clicking your target (e.g. the mouth) shows a proper solid colored area over it before this step runs.

The outline looks jagged or over-detailed. That's n_points = -1 giving you the raw, unsimplified contour. Drop it to a smaller value for a cleaner mesh outline - there's no "right" number, but 20–40 is a reasonable starting point for a facial feature like an eye or mouth.

Wrong region got traced. Since the node only keeps the single largest contour by area, if your segmentation mask has more than one blob and the one you actually want is the smaller one, this node will silently discard it. Clean up the mask upstream rather than relying on this node to pick correctly.