CV Background Subtract (Batch)
Learns the background of a CLIP and returns a foreground mask per frame - the practical way to pull moving subjects out of static-camera footage without a segmentation model. Feed the whole batch (core 'Batch Images' or a video loader) in frame order; the subtractor is created, run over the sequence and dropped inside this one node, because a stateful cv2 model cannot travel through a cached graph. 'warmup_frames' lets the model settle before the masks are kept, so the first frames are not all foreground. START WITH MOG2, and give the model FRAMES: measured on a 200-frame fixed-camera clip, against a temporal-median reference calling 5.0% of the frame moving, MOG2 reads 4.6% and CNT/GSOC/LSBP read 7.9/9.3/13.3% - one range, a fair comparison. Cut the SAME clip to 50 frames and those three jump to 16.0/12.5/16.0% while MOG2 barely moves: they are not less accurate, they are unconverged.
- images
- foreground
- background
- foreground_fraction
Inputs (6)
| Name | Type | Default | Description |
|---|---|---|---|
| images | IMAGE | Batch of frames IN ORDER from a fixed camera. At least 2; the more the model sees, the cleaner the background estimate. | |
| algorithm | COMBO | MOG2 (core) | MOG2/KNN (core OpenCV) are fast, adaptive, give a background plate, and converge in a few dozen frames - the right default for clip-length footage. MOG is the classic mixture model and is the most conservative. CNT is extremely fast. GSOC and LSBP are the most accurate ON LONG SEQUENCES; MEASURED, all three of CNT/GSOC/LSBP read 3-4x the reference on a 50-frame clip and only settle after several hundred frames, so prefer MOG2 unless the clip is long. GMG needs many initialization frames and provides no plate. |
| warmup_frames | INT | 00–1000 | Frames used ONLY to train the model before masks start being collected. The output then has this many fewer frames. 0 keeps every frame, including the noisy first ones. ~12 is plenty for MOG2/KNN. It cannot rescue CNT/GSOC/LSBP on a short clip: those need hundreds of frames of actual sequence, and spending them on warmup just leaves fewer to keep - check 'foreground_fraction' rather than assuming. |
| learning_rateopt | FLOAT | -1.00-1–1 | How fast the background adapts, per frame. -1 (the default) lets the algorithm choose; 0 freezes the model after the warmup, which is what you want when a subject stops moving and would otherwise be absorbed into the background; 1 makes every frame the new background. |
| detect_shadowsopt | BOOLEAN | true | MOG2/KNN only: mark shadows separately (they come out as grey 127 rather than white 255) - see 'shadows_as_foreground'. |
| shadows_as_foregroundopt | BOOLEAN | false | Count detected shadows as part of the subject. Off (the default) keeps the mask to the object itself, which is usually what a matte needs. |
Outputs (3)
| Name | Type | Description |
|---|---|---|
| foreground | MASK | One 0/1 MASK per frame (a MASK batch): the moving / new pixels. Clean it up with morphology and 'CV Keep Largest Component'. |
| background | NPARRAY | The learned background plate, always BGR uint8. MOG2/KNN/GSOC/LSBP provide one directly; CNT's is single-channel and is promoted to BGR; MOG and GMG provide none, so the temporal median of the clip is returned instead. Preview it with 'Preview CV Array'. |
| foreground_fraction | FLOAT | Average fraction of pixels flagged as foreground (0-1) across the kept frames - the number to sanity-check every run against. On static-camera footage a good result is a small minority, roughly 0.05-0.2. Above ~0.3 the model has not settled: use a longer clip or switch to MOG2 rather than raising warmup_frames. Near 0 means nothing moved. |