Image Alpha Mask Merge

Avatar Graph's rigging pipeline runs on layered mesh planes - an eye plane, a mouth plane, the rest of the face - each one textured with a piece of your character image. For that to look right, every layer except the base needs to be transparent everywhere it isn't actually the eye or the mouth, otherwise you get an opaque rectangle floating in front of your character instead of a clean cutout. Image Alpha Mask Merge is the node that produces that cutout: it takes a mask and burns it into an image's alpha channel.

How it works

It's a compositing operation, not a Blender one - straightforward alpha compositing, the same idea Photoshop users know as "add layer mask." You give it a color image and a mask, and it hands back an RGBA image where the mask defines what's opaque and what's see-through. In this pack's actual use case, that mask typically comes from a segmentation step upstream (the README's table mentions an integrated SAM segmentation node earlier in the pipeline) - you segment out "just the eye" or "just the mouth" as a mask, merge it into the source image's alpha here, and now you have a clean, transparent-background texture ready to paint onto a mesh plane.

The inputs and outputs that matter

Both inputs are required - there's nothing optional to configure, which is why this node is easy to drop in:

• image - the source image you want to cut a hole in (or preserve only a piece of).
• mask - defines the cutout. Wherever the mask is "on," that part of the image stays opaque; wherever it's "off," alpha drops out.

Output is a single IMAGE - the merged result, now carrying real transparency, ready to wire into whatever texture slot needs it next (a mesh layer's material, another save node, or straight into Object Load Reference Image-style texturing steps).

How to install it

Same install as every node in this pack: ComfyUI Manager, search "Avatar Graph", or manually:

cd ComfyUI/custom_nodes
git clone https://github.com/avatechai/avatar-graph-comfyui

then pip install -r requirements.txt and restart. This node has no dependency on Blender's bpy module - it's plain image compositing - so if all you need from this pack is alpha merging, you're not on the hook for the Python 3.10 pin that the mesh/rigging nodes require. But since it ships in the same repo as the ones that do need bpy, you'll still install the whole pack's requirements.txt, and on macOS/Linux that means the same Python 3.10 conda environment the README recommends for everything else here.

Common issues & troubleshooting

If the merged image comes out fully opaque or fully transparent, the usual cause is a mask that's inverted or blank relative to what you expected - check the mask on its own (preview it directly) before wiring it in here, rather than debugging the merge itself. And if the resulting texture looks right in ComfyUI's preview but shows as opaque once it's on a mesh plane later in the graph, that's usually a downstream material/shader step not respecting alpha rather than this node - Avatar Graph has a dedicated ObjectSet_UseEmptyImageAlpha toggle for exactly that class of problem on the Blender side, worth checking if you're chasing a transparency issue that only shows up once the image is on an object.