Image Merge By Pixel Align

Most "merge two images" nodes assume the images already line up. Image Merge By Pixel Align is for when they don't, or when you're not sure: it detects feature points with SIFT, computes the homography that aligns your patch to your base image, and composites the aligned patch on top with a proper feathered blend. It's the node for the jobs that make ordinary merges fall apart - a region you upscaled separately and want to put back, a crop that came back a few pixels off, a composited element that needs to sit exactly where it belongs.

The pack's own example images (ImageMergeByPixelAlign.png and a workflow variant) show it being used to composite a generated patch back into a base image, which is the canonical use. Think: fix a face in one tile of a big image, then blend the repaired patch back in without the seam or the misalignment.

How it works

The mechanism, grounded in the source:

1. Background keying. The patch has a background color you want excluded - set bg_color_r/g/b (default 255/0/255, magenta) and bg_tolerance (default 10). Everything within that color distance is treated as the patch's background and gets cut, not composited.
2. SIFT alignment. sift_features (default 5000) feature points are detected on both images and matched with Lowe's match_ratio threshold (default 0.7). A homography is estimated from the matches, and the patch is warped to align with the base. This is what absorbs the "few pixels off" problem.
3. Core coverage and blend. core_coverage (default 0.6) defines the inner region where the patch fully covers the base; outside it, blend_width (default 30) and blend_strength (default 0.7) control the transition, with blend_mode choosing the curve: smooth (sigmoid), linear, full_gradient, or none.

The inputs that matter

• base_img / patch_img - the two images. The patch gets aligned onto the base.
• bg_color_r/g/b + bg_tolerance - what counts as patch background to exclude. Get this right and the composite is clean; get it wrong and you'll carry a colored fringe.
• core_coverage - how much of the patch is fully opaque. Lower = more blending area.
• blend_width / blend_strength / blend_mode - the feather behavior at the patch edge.
• sift_features / match_ratio - alignment quality. If alignment fails (noisy or low-texture images), raise features and lower the ratio.

One output: IMAGE, the composited result.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/mirabarukaso/ComfyUI_MiraSubPack

This node uses OpenCV (cv2), which is the pack's one real extra dependency - ComfyUI doesn't ship it by default:

pip install opencv-python

(or search "MiraSubPack" in Manager and restart; if the node errors on import, the cv2 install is the fix.)

Notes and gotchas

• It's slow-ish and CPU-bound - SIFT on a big image plus a homography warp is real work, and it runs per batch item.
• Low-texture images defeat SIFT. A flat wall or smooth gradient has no features to match, and alignment can silently fall back to returning the base image (the source catches the error and returns base_img unchanged - which is a silent failure worth knowing about). If your result just doesn't change, check whether the image has enough detail to align at all.
• The background color needs to actually be uniform. The tolerance keying assumes a solid background; a gradient or noisy backdrop will leave remnants.
• If alignment is consistently off, tune match_ratio down (stricter matches) before raising sift_features.