Light-Tool: Image Overlay

Compositing in ComfyUI is a solved problem, technically, but the stock answer is a grab-bag of ImageCompositeMasked, alpha fiddling, and a quiet hope that nobody checks the edges. Light-Tool: ImageOverlay is the leaner version: one base image, one overlay, one mask, and it does the classic overlay * alpha + base * (1 - alpha) blend that every compositor learns on day one.

Three inputs, all required: origin_image (the base), overlay_image (what goes on top), and overlay_mask (which pixels of the overlay show). The mask is typed as IMAGE, not MASK - the node converts it to grayscale internally, so you can wire in a mask-as-image, an alpha channel extract, or even a soft gradient. Whatever you feed it, black hides the overlay and white reveals it, with everything between acting as partial opacity.

The mechanism. It's a per-pixel weighted sum. The overlay is multiplied by the mask, the base by 1 - mask, and the two are added. That's the entire trick, and it's the correct one for clean hard-edge or soft-edge compositing. Two implementation details matter in practice:

• The images must be the same size. If overlay_image and origin_image differ, you get a ValueError. The node doesn't scale either input to match. That's a feature dressed as an inconvenience: you stay in control of dimensions, and you'll usually be resizing the overlay (this pack's ResizeImage does the job) before you blend.
• The mask and overlay are read from the batch in a way that assumes single images. The loop iterates over origin_image frames but pulls overlay_image and overlay_mask as whole tensors each time. Feed one overlay over one base and you're on happy ground; trying to do per-frame different overlays in a batch is where it gets weird.

The one trap. Your mask convention. If you built a mask where the subject is black on a white background - the standard "cutout" output of a lot of background-removal pipelines - the formula will hide exactly what you want to show. The pack has InvertMask for precisely this, and it's the fix you'll reach for the first time the blend looks backwards.

When you'd actually reach for it. Watermarking, label overlays, and especially the "masked subject over a new background" pattern: load a cutout (RGBA), flatten it to RGB, grab its alpha as a mask, and overlay it on a generated background. Because it takes an explicit mask rather than sniffing the alpha channel, it also works when your overlay doesn't carry alpha at all - that's the niche where the stock nodes make you jump through hoops.

Installing. Part of ComfyUI-Light-Tool, installed all at once. ComfyUI Manager → search ComfyUI-Light-Tool → Install → restart, or:

cd ComfyUI/custom_nodes
git clone https://github.com/ihmily/ComfyUI-Light-Tool.git
pip install -r requirements.txt

No model files involved. The notable dependency is opencv-python, and if you already run ControlNet aux preprocessors you've got it.

Honest verdict: for same-size masked compositing it's one of the cleanest single nodes around. For anything that needs the overlay scaled or repositioned, you're adding resize nodes either way - the pack's SimpleImageOverlay (not covered here) handles positioning if that's your real need.