Mask Propagate

Plain planar mask propagation is exact for a wall and wrong for a person. Mask Propagate is the middle option: it can warp your mask along the flat plane like Track to Mask, or it can bend it with the surface for subjects that aren't flat - a face, cloth, a bag. Same input, two modes, and it tells you how much it trusts each frame as it goes.

How it works

• planar mode warps the reference mask by the tracked homography. One matrix per frame, essentially free, exact for rigid planes. Think of it as Track to Mask with a confidence readout bolted on.
• grid mode tracks a lattice of control points (default 6×6) from the reference frame with Lucas-Kanade, fits a per-cell similarity to each, and blends them into a smooth deformation field that the mask gets pulled through. Where the optical flow gives up, each control point falls back to the planar homography - so on a rigid plane it never does worse than planar, but on a face it bends with the cheekbone instead of sliding across it.

grid needs the source images to run the flow on. Without them it prints a note and silently falls back to planar - graceful, but worth knowing about.

Confidence comes out as a per-frame list: half from how many lattice points survived, half from the track's own confidence. It's your "does this mask still mean anything here" gauge.

Inputs and outputs

• track_data - the track.
• mask - the reference-frame mask.
• mode - planar (default) or grid.
• images (optional, required for grid) - the source frames.
• downscale (default auto) - resolution for the LK tracking. Lower is faster, slightly less precise.
• grid_size (default 6) - lattice density. More control points means more deformation freedom but more places flow can fail.

Outputs: masks (batch) and confidence (list of floats).

Installing it

Same pack - PlateTrack in Manager or clone + pip install -r requirements.txt. OpenCV only, CPU-friendly.

Where people get burned

• Grid mode with no images wired in silently becomes planar. If your mask stops following the subject, check that you actually connected the frames.
• Grid is still optical-flow-based; a fast-moving or heavily occluded subject will beat it. That's precisely the case where you step up to the Cutie variant, which is a deep segmentation model and doesn't care about optical flow at all.
• Don't crank grid_size to 16 out of curiosity on a long shot - more lattice points means more work and more chances to fail. 6 is a sensible default.

Rule of thumb: planar for planes, grid for bendy things, Cutie for when things get hard. This node covers the first two.