🎨 Quick Merge

If "merge" makes you think of checkpoint merging, forget that immediately. 🎨 Quick Merge (class QuickMergeNode) is the opposite thing: one giant node that pastes a foreground cutout onto a background, then optionally cuts it out, resizes it, repositions it, blends it, filters it, shadows it, upscales it, and does all of that across whole folders of images. The name is doing a lot of heavy lifting - "quick" and "merge" are the two least accurate words here. It's a single-node compositing factory.

You'd reach for this when a normal graph starts to feel like a plate of spaghetti. The usual product-shot pipeline - cut the subject out with BiRefNet, drop it on a background, scale and nudge it, drop a shadow, upscale - takes six or seven nodes in vanilla ComfyUI. This packs the chain behind one socket setup and, crucially, makes it batchable.

What it actually is

Three image inputs in, one composite out. Background is the required canvas. Foreground (optional) is what gets stamped on top, and mask (optional) feeds the light-pipeline (more on that below). Everything else is a toggle.

It's really four engines behind one face:

• Cutout. Turn on ✂️ merge_image and pick ✂️ cutout_model - BiRefNet (lite, standard, HR), RMBG-1.4/2.0, or "None (Use Alpha)" if your foreground already has transparency. These are the real deal: the same BiRefNet weights the ecosystem standardised on for hair and fabric edges, loaded straight from HuggingFace via transformers. BiRefNet_lite is the sensible default; reach for BiRefNet_HR above ~1500px so the model doesn't downscale your edges internally.
• Placement. ✂️ foreground_size, ✂️ foreground_left_right, ✂️ foreground_up_down do exactly what they say, plus flips, rotation, edge shrink/feather, opacity, and a handful of blend modes. The one you'll actually touch first is foreground_size - 1.0 means "fit the foreground onto the background canvas."
• AI upscale. ⚡ ai_upscale runs a RealESRGAN_x2plus model through spandrel, with upscale_by for the factor and tile_size (0 = whole image, 512 default) to keep VRAM sane.
• Batch. 📁 batch_processing with folder paths (more below), pairing either 1-to-1 sequentially or cross-multiplying every foreground with every background.

The four outputs are composited_image (the one you care about), light_mask, and relight_fg_crop / relight_bg_crop. The last three serve a relighting pass downstream: light_mask is your cutout or input mask, blurred into a soft gradient you can feed an IC-Light-style node. If you just want a picture, wire composited_image to a Save Image and ignore the rest.

How it survives big batches

The trick that makes folders possible is chunking and VRAM isolation. batch_chunk_size (default 4) caps how many frames go through the heavy pipeline at once, and the loader normalises every file - a 3-channel .jpg and a 4-channel .png mixed in the same run - into uniform RGBA float32 tensors before the compositor sees them. It clears the CUDA cache between chunks, which is why the README can promise BiRefNet over massive batches without OOM. One gotcha hidden in the source: batch folder paths are relative to your ComfyUI/input directory, not arbitrary filesystem paths. The author patched a path-traversal hole in there, so don't fight it - drop your folders under ComfyUI/input/ and reference them by name.

Install

ComfyUI Manager → search ComfyUI-Quick-Merge (or "Quick Merge"), or the manual way:

cd ComfyUI/custom_nodes
git clone https://github.com/stompy001/ComfyUI-Quick-Merge

Restart ComfyUI. Dependencies are transformers, torchvision, and spandrel - the node tries to auto-install the first three on first import. The heavier cost is model downloads: the cutout weights pull from HuggingFace the first time you run a cutout, and the first upscale downloads RealESRGAN_x2plus.pth from GitHub releases. First runs are slow; subsequent ones cache.

Where people get burned

The README's own warnings are the real ones, not invented friction:

• VRAM. ⚡ ai_upscale above 2.0× over a big batch will happily eat your graphics memory. Keep batch_chunk_size at 1–4 when upscaling. The tooltip says "0 = no limit" but the field's minimum is 1 - treat 1 as the floor, not a suggestion.
• Aspect ratio parity. Studio backgrounds with a podium or table must all be the same resolution and aspect ratio in a folder batch, or the pedestal coordinates drift between frames and your product lands off-target. This is a real constraint, not a warning for show.
• Don't touch auto-position. The auto-position (WiP) toggle is locked down mid-refactor; the node forces it off anyway. Leave it alone.
• First run looks frozen while a segmentation model downloads. It's not dead, it's fetching ~600MB of BiRefNet weights over your connection.

Is it the node for a one-off composite? Overkill - the vanilla image nodes do that in three clicks. It earns its keep when you're stamping a hundred product shots onto a hundred backgrounds without babysitting. That's the workflow this was built for.