Per-frame Image foreground extractor built on a stateful Gaussian-mixture or K-nearest-neighbour background model. Emits oneof t[Image, Mask] — a one-channel foreground intensity frame, or a boolean foreground mask — with the arm fixed by the wired downstream.
Typical backends
Motion-gated detection on a fixed camera — the foreground is cleaned with morphology before a detector runs on the moving regions.
Live surveillance feed where the foreground mask is rendered for an operator to watch motion in a static scene.
Caveats
- AccuracyThe background model needs to observe several hundred frames before its output stabilizes; foreground extracted during this warm-up is noisy, and the warm-up length grows with
history. - AccuracyA panning or shaking camera and sudden lighting shifts both flood the model with apparent change, saturating the foreground until it re-adapts; the model assumes a largely static scene.
- State lifetimeThe model carries learned background statistics across every tick, so a restart discards it and the first frames after restart are unreliable again.
- FallbackWhen shadow marking is enabled, shadow pixels are written as mid-gray rather than dropped; treating every non-zero pixel as motion silently folds shadows into the foreground unless that behaviour is turned off.
- Parameter interactionFreezing adaptation by setting
learning_rate to zero before the model has seen history frames locks in an under-trained background and produces persistent false foreground.