Mask Motion Blur

What it's for

A moving subject photographed with a real shutter is smeared along its direction of travel. A matte of the same subject - from SAM, from a keyer, from anything automated - is sharp, because the models that make mattes don't know about shutters. Composite one against the other and the matte's crisp boundary sits inside the smear, which reads as a cut-out pasted onto live footage. It's one of the tells that makes a comp look fake even when the colour and the edges are perfect.

So you smear the matte by the same amount and in the same direction. That's all this node is: a directional blur that runs on a MASK rather than an IMAGE.

This is the mask-side counterpart of the argument in the KB's post-processing doc, where the de-fake stack is "motion blur + camera shake + grain + aberration + vignetting" - every one of those is a deterministic pass, and the matte needs matching just as much as the picture does. If you're adding motion blur to the picture and not to the alpha, the alpha is now the giveaway.

How it works

It accumulates 2 × distance + 1 copies of the input mask, each one shifted by an integer offset along the blur vector, and divides by the tap count. So it's a uniform (box) directional blur, implemented as shifted adds rather than a convolution - cheap and exact for what it does.

The practical consequence of the integer shifting: offsets are computed as round(i·cos(angle)) and round(i·sin(angle)), so diagonal angles quantise to whole-pixel steps. At long distances that's invisible. At short ones - distance 3, angle 37° - you'll see a faint stair-step in the smear. Round your angle to something sane or push the distance.

distance is clamped to a frame-sized limit internally, and the report tells you when that happens, so typing 9999 gets you a soft warning rather than a hung queue.

Inputs and outputs

Required:

• mask - the matte to smear.
• angle - direction in degrees, 0 = horizontal right. Match this to the plate's smear, not to the direction the subject is moving in the frame - those are the same thing only when the camera is static.
• distance - blur length in pixels along that angle. This is your shutter angle in effect. 20 is the default and is a lot of smear; for typical footage you'll be reaching for 5–15.
• invert - flip the mask polarity before blurring.

Outputs: mask and report.

Where it goes

SAM Mask Generator (MEC) → Mask Motion Blur → Inpaint Crop Pro / composite / grade. Do it after the matte is finished (refined, morphed, feathered) and before it's used, because the whole point is to match the final alpha to the final plate. If you morph or expand after the directional blur you undo the smear where it matters most - at the boundary.

Note it's a blur, so it also softens the matte in the direction of travel. That's correct: a real moving edge is softer in that direction. It does not, however, extend the subject - it can't, because it only has a matte to work with, not the picture. If you need the alpha to grow along the motion vector as well as soften, you'll want a directional dilate, which this doesn't do.

Install

ComfyUI Manager → search "CustomNodePacks", or:

cd ComfyUI/custom_nodes
git clone https://github.com/Code2Collapse/ComfyUI-CustomNodePacks

Restart. Pack-level dependencies are opencv-python, scipy, safetensors; this node is tier 1 - pure tensor math, no model, no VRAM, runs fine on an old 4 GB card. Standard caveat from the README: don't pip install -r requirements.txt blind, because ComfyUI already provides torch/numpy/Pillow and the pack's list can clobber them.

Common issues

• The comp still looks pasted. You matched the direction but not the length, or you matched the matte but not the picture. Both halves need the same treatment; a sharp subject on a blurred background still reads wrong.
• The edge has a stair-step. Short distance with a diagonal angle, as above. Nudge the angle to a multiple of 15° and see whether anyone can tell.
• The whole matte went mushy. distance is swallowing your edge detail - the smear is now wider than the subject. Dial it down; this is a subtle match, not a stylise filter.