AP Warp Masked Composite Blend (Occlusion)

The README of the AP_OpticalFlow pack opens its "quick workflow" section with this exact node, and that tells you everything: AP Warp Masked Composite Blend (Occlusion) is the one-stop shop for the pack's core move - warp a masked region by optical flow, figure out which parts of that motion are lies, and blend the honest parts back onto the original. It bundles what would otherwise be a three-node chain (AP Apply RAFT Optical Flow (Masked) → AP Flow Occlusion Mask → AP Flow Composite) into a single node, and it's what you'd reach for doing temporal edits on a moving subject: making a face or an object follow the motion between two frames without smearing the frame around it.

The word that makes this pack different from naive warp-and-blend is occlusion. When something moves, background it was covering gets revealed - disoccluded - and the flow field has no honest answer for those pixels. Copy them from the warped frame and you get ghosting and stretching. This node computes an occlusion mask from forward-backward flow consistency (warp the backward flow forward with the forward flow; where the round-trip disagrees, mark it occluded) and keeps those pixels out of the blend.

The inputs that matter

• images, mask, flow_data - frame, region mask, and flow from AP Get RAFT Optical Flow (or AP Load Optical Flow). flow_direction ab/ba fixes reversed motion.
• blend_images (default true) - true returns the composited result; flip it false and you get the pure warped output instead, which is the "I want to inspect the warp before committing" mode.
• alpha_mode - flow_confidence_x_mask (default) weighs the blend by both flow confidence and your mask; flow_confidence alone ignores the mask footprint; mask_only is a hard cut.
• mask_strength / mask_feather - how hard and how softly your mask limits the warp and the composite.
• use_difference_gate + difference_threshold - the README's recommended anti-blur setting: only blend where the warped frame actually differs from the original. Enable it with a low threshold (0.005–0.02) and untouched background stays untouched.
• blend_strength / feather - overall mix and seam softening on the final composite. abs_epsilon / rel_epsilon tune occlusion sensitivity; leave them alone until you see ghosting.

Outputs

Six of them, but you mostly care about two. output_images (IMAGE) is your finished composite. occlusion_mask (MASK) shows what the node decided was disoccluded - preview it when something looks wrong. The rest (warped_images, warped_mask, valid_mask, composite_alpha) are the internals exposed for debugging and for chaining into a manual composite if you outgrow this node.

Install

ComfyUI Manager, search "AP Optical Flow", install, restart. Manually:

cd ComfyUI/custom_nodes
git clone https://github.com/adampolczynski/ComfyUI_AP_OpticalFlow
pip install -r ComfyUI_AP_OpticalFlow/requirements.txt

Only dependency is torchvision>=0.15; RAFT weights download on first flow computation. The composite itself is cheap - the expensive part (flow) happens once upstream and is reused.

Where people get burned: motion runs backwards (swap flow_direction), or the blend reaches into untouched areas (turn on use_difference_gate, lower the threshold, and respect the mask). If you still see ghosting, raise abs_epsilon to treat more pixels as consistent, or just feather the composite and drop blend_strength below 1. On very fast motion the flow itself degrades - the README is honest that this isn't a replacement for real tracking in extreme scenes.