Optical Flow Composite (Global Align) (Legacy)

The classic image-edit workflow has a dirty secret: you don't want the whole generated image, you want just the edited region, composited back onto the untouched original so everything the model didn't change stays pixel-perfect. The problem is finding the changed region cleanly - and the worse problem is that AI editors quietly drift the background while they work (a global camera nudge, a warp). A naive difference mask then comes out garbage, and the composite shows a seam. This node is the version that handles both: it optically aligns the generated image to the original, computes a proper change mask, and blends only the edit back in.

How it works

You feed it two images: original_image (your untouched source) and generated_image (the edit result). It runs optical flow between them to estimate a single global camera shift from the unchanged background pixels - the source calls this "Global Rigid Alignment" - and translates the whole generated image rigidly to cancel the drift before any masking happens. That's the trick that eliminates seam distortion. Then it builds a change mask from ΔE color distance (with occlusion handling for pixels that moved too far to match), cleans it up, and composites the edited region from the generated image onto the original with a feathered boundary.

Three inputs do most of the work, all of which you can leave on defaults:

• delta_e_threshold (−1 auto) - how different a pixel must be to count as "edited." Higher = only obvious edits (smaller mask), lower = subtle changes too. -1 lets the node pick automatically.
• feather_pct (default 2) - how gradually the edit blends into the original at the boundary. Crank it up if you see a hard edge, drop it if fine details are getting washed out.
• flow_quality (medium / fast / ultrafast) - optical flow accuracy. medium is a fine default; drop to fast/ultrafast on big images where speed matters.

The rest - grow_mask_pct (grow/shrink the region), occlusion_threshold (−1 auto), close_radius_pct (fill holes), min_region_pct (drop speckle) - are the fine-tuning knobs you touch when a mask comes out noisy or clipped.

Outputs: composited_image (ready to save or continue the pipeline), change_mask (the detected edit region, if you want it for other purposes), and report - a STRING diagnostics block showing what the auto-tuning chose, the changed percentage, flow shift in pixels, and median ΔE. Read it the first run; it tells you whether the alignment actually worked.

Why it's the right tool

This is the "edited-region mask" pattern from image editing: keep the untouched original, replace only the changed bits. It's what makes local edits to a photo feel surgical rather than regenerated. Where people get burned is expecting a plain image difference to work - camera drift from the editor makes the whole frame "changed," and you end up compositing everything or losing the edit. The flow alignment is the part that makes it actually hold up on real photos.

Watch out for

• Both images should be the same resolution; the node resizes the original to match the generated image's dimensions if they differ.
• Auto thresholds on -1 are good defaults but tune the mask the first time - every edit model drifts differently.
• This is a "composite back" tool, not a generator. It ships in the same pack as the text encoders that produce the edit conditioning, so the full pipeline lives in one collection.

Installing it

Ships in silveroxides/ComfyUI-UtilsCollection. ComfyUI Manager: search ComfyUI-UtilsCollection, install, restart. Or manually:

cd ComfyUI/custom_nodes
git clone https://github.com/silveroxides/ComfyUI-UtilsCollection
cd ComfyUI-UtilsCollection
pip install -r requirements.txt   # opencv-python, typing-extensions

Restart. No model downloads - the optical flow runs on OpenCV, which is the pack's only real dependency. This is the legacy alias of canonical UC_OpticalFlowComposite; the "(Legacy)" name is just the compatibility registration.