Nodes/ComfyUI_Element_easy/Smart merge images
ComfyUI Node

Smart merge images

The node that fixes pixel drift when Qwen-Edit or Klein edits your image

By supElement·Created 12 months ago·Updated 6 days ago· 14
Smart merge images
  • original_image
  • edited_crop_B
  • original_crop_A
  • split_grid
  • Merged_Image
◄use_tpstrue►
◄Optical_Flowfalse►
◄second_passfalse►
◄Full_Optical_Flowfalse►
◄warp_smooth1.00►
◄color_match▾►
◄color_protectionfalse►
◄Color_p_threshold20►
◄feather_kernel20►
◄use_gputrue►
◄force_recomputefalse►

Smart merge images is the flagship node of this pack, and it exists to solve a very 2026 problem: instruction editors like Qwen-Image-Edit and Flux 2 Klein don't patch your image - they re-emit the whole frame. Pixels you didn't ask to change come back slightly shifted, and the colors drift. So when you crop a region, edit it, and try to stitch it back onto the original, it doesn't line up. This node does the stitching for you: it finds the shared features between the edited crop and the original, warps them back into alignment, matches the color, and merges them into a seam-free result.

How it works

You feed it two images: original_image and edited_crop_B (the edited region to merge back). The node finds matching features between them, computes the transform that re-aligns the edit to the original, and blends. There's also an optional original_crop_A input - and the README's advice is worth taking: for the most reliable merge, use all three, where original_crop_A is the unmodified crop from the original image. That third input gives the matcher a clean reference and dramatically improves alignment.

The knobs are split into stages:

  • match_method - how features are found: SIFT (OpenCV) (fast, classic), or DISK + LightGlue / SIFT + LightGlue (learned matching, more robust).
  • warp_method - how the edit is realigned: Homography (affine-ish plane warp), Homography + Optical Flow, or pure Optical Flow for handling more complex distortion.
  • optical_flow - which flow estimator to use when flow is involved: Farneback, DIS, or RAFT-Small/RAFT-Large (the bigger, the more accurate, the slower).
  • color_match - nine modes including Histogram, LAB_Mean, SeamlessClone (PS Auto Blend), Laplacian Pyramid Blend, and the pack's own Adaptive Local (strong), which is specifically tuned to repair the color shift from editing models. This one has two companion knobs: adapt_thresh (color difference threshold) and adapt_local_match (which local matching flavor the adaptive mask fusion uses).
  • feather_kernel (0–256) - softness of the merge seam. merge_mode - One to One merges a single pair; All to One handles the tiled case.

use_gpu toggles GPU acceleration (default on - flip it off if you're getting VRAM pressure or crash-on-driver weirdness), and force_recompute re-runs the feature matching instead of reusing a cached result, which you'll want after changing inputs.

Tiled merging

v1.4.7 added support for merging multiple crops in one go: edited_crop_B can take a batch of crop images and the node returns a single fully merged Merged_Image. The catch, stated plainly in the README: the input must be a batch, not a list. If you're feeding it from a list-producing node, convert it first with an Image List To Batch node or it won't work.

The model download you should know about

Some of the advanced matching/color options need model files. They're optional - if you don't use those options, nothing downloads. When you do, the node auto-downloads them to ComfyUI/models/elementEasy on first run. If you'd rather pre-stage them (or you're offline), copy the elementEasy folder from the pack's models directory into that same path and it'll skip the download.

Installing it

It ships in supElement/ComfyUI_Element_easy:

cd ComfyUI/custom_nodes
git clone https://github.com/supElement/ComfyUI_Element_easy.git

Restart ComfyUI, or install via ComfyUI Manager by searching ComfyUI_Element_easy. This is the one node in the pack with real dependencies - OpenCV at minimum, plus the matching/flow machinery for the advanced modes - so expect the first run to be heavier than the rest of the pack.

Gotchas

The "batch not list" rule for tiled merging is the number one tripwire. After that: the merge only works when the images actually share enough common features - if the edit changed too much (completely new content, no overlap), there's nothing to align and the result will be rough. Start with SIFT (OpenCV) for speed and only escalate to LightGlue/RAFT when alignment is bad. And the Adaptive Local (strong) color mode is specifically the fix for Qwen-Edit-style color shift - if that's your problem, use it rather than the generic modes.

CategoryElement_easy/image

Inputs (15)

NameTypeDefaultDescription
original_imageIMAGE原始背景图(未编辑), 只用第一张。支持 List / Batch / 单张。 Original background image; only the first is used. Accepts list / batch / single.
edited_crop_BIMAGEAI 编辑后的局部裁块, 将对齐并贴回背景。支持 List / Batch / 单张, 尺寸可不同。 AI-edited crop(s) to align and composite back. Accepts list / batch / single; sizes may differ.
use_tpsBOOLEANtrueTPS 非刚性畸变校正: 开 = LoFTR/TPS 校正(推荐); 关 = 仅单应性定位, 最快。 TPS non-rigid correction: ON = LoFTR/TPS (recommended); OFF = homography-only placement, fastest.
Optical_FlowBOOLEANfalse逐块光流精修: 开 = 在定位/TPS 上叠加逐块光流。整图精修由 Full_Optical_Flow 单独控制。 Per-crop optical-flow refinement: ON = per-crop flow on top of placement/TPS. Full-image polish is controlled by Full_Optical_Flow.
second_passBOOLEANfalse二阶段精校: 逐块光流之后再跑一次小幅逐块光流(位移上限 4px), 不依赖 TPS。 Second-pass refinement: one extra small-amplitude per-crop flow pass (4px cap) after the first flow; independent of TPS.
Full_Optical_FlowBOOLEANfalse整图光流精修: 开 = 合成后对整张成品再做一次低幅光流修正(位移上限 12px), 与逐块光流相互独立。 Full-image flow polish: ON = one extra low-amplitude flow pass on the whole merged image (12px cap); independent of per-crop flow.
warp_smoothFLOAT1.000–4整图光流场的平滑强度(仅 Full_Optical_Flow 开时生效)。 Smoothing strength of the full-image flow field (Full_Optical_Flow ON only).
color_matchCOMBO色彩/融合策略。 Color / blend strategy.
color_protectionBOOLEANfalse保护分块内的 AI 改色。阈值见 Color_p_threshold。 Protect AI recolors. See Color_p_threshold.
Color_p_thresholdFLOAT203–120改色判定阈值(仅 color_protection 开时生效), 越小保护范围越大, 默认 20。 Recolor threshold (color_protection ON only); smaller = wider protection; default 20.
feather_kernelINT200–256羽化半径(px), 越大过渡越柔, 一般 15~40。连接 split_grid 时 0~100 对应其 feather 0~1.0。 Feather radius (px); larger = softer, typical 15~40. With split_grid, 0~100 maps to its feather 0~1.0.
use_gpuBOOLEANtrueGPU 加速特征匹配与色彩匹配; 光流/TPS/无缝克隆仍在 CPU。 Use GPU for feature and color matching; optical flow / TPS / seamless clone stay on CPU.
force_recomputeBOOLEANfalse清空对齐缓存并重新计算。 Clear the alignment cache and recompute.
original_crop_AoptIMAGE可选: 编辑前裁块, 与 B 同视角。提供后走 B→A→BG 桥接对齐, 更稳; 按索引配对。 Optional: pre-edit crop with the same view as B. Enables bridge alignment B→A→BG (more reliable); paired by index.
split_gridoptELEMENT_TILE_GRID可选: ElementTileSplit 的 grid, 启用渐变/圆角羽化与逐 tile 合成。 Optional: grid from ElementTileSplit; enables fade/rounded feathering and per-tile compositing.

Outputs (1)

NameTypeDescription
Merged_ImageIMAGE融合后的完整图像(batch) | Merged image(s) as a standard batch