Background Subtraction¶

Create motion masks from video streams using OpenCV's background subtraction algorithm.

How This Block Works¶

This block uses background subtraction (specifically the MOG2 algorithm) to identify pixels that differ from a learned background model and outputs a mask image highlighting motion areas. The block maintains state across frames to build and update the background model:

1. Initializes background model - on the first frame, creates a background subtractor using the specified history and threshold parameters
2. Processes each frame - applies background subtraction to identify pixels that differ from the learned background model
3. Creates motion mask - generates a foreground mask where white pixels represent motion areas and black pixels represent the background
4. Converts to image format - converts the single-channel mask to a 3-channel image format required by workflows
5. Returns mask image - outputs the motion mask as an image that can be visualized or processed further

The output mask image shows motion areas as white pixels against a black background, making it easy to visualize where motion occurred in the frame. This mask can be used for further analysis, visualization, or as input to other processing steps.

Common Use Cases¶

• Motion Visualization: Create visual motion masks to see where movement occurs in video streams for monitoring, analysis, or debugging purposes
• Preprocessing for Motion Models: Generate motion masks as input data for training or inference with motion-based models that require mask data
• Motion Area Extraction: Extract regions of motion from video frames for further processing, analysis, or feature extraction
• Video Analysis: Analyze motion patterns by processing mask images to identify movement trends, activity levels, or motion characteristics
• Background Removal: Use motion masks to separate foreground (moving) objects from static background for segmentation or isolation tasks
• Motion-based Filtering: Use motion masks to filter or focus processing on areas where motion occurs, ignoring static background regions

Connecting to Other Blocks¶

The motion mask image from this block can be connected to:

• Visualization blocks to display the motion mask overlayed on original images or as standalone visualizations
• Object detection blocks to run detection models only on motion regions identified by the mask
• Image processing blocks to apply additional transformations, filters, or analysis to motion mask images
• Data storage blocks (e.g., Local File Sink, Roboflow Dataset Upload) to save motion masks for training data, analysis, or documentation
• Conditional logic blocks to route workflow execution based on the presence or absence of motion in mask images
• Model training blocks to use motion masks as training data for motion-based models or segmentation tasks

Type identifier¶

Use the following identifier in step "type" field: roboflow_core/background_subtraction@v1to add the block as as step in your workflow.

Properties¶

The Refs column marks possibility to parametrise the property with dynamic values available in workflow runtime. See Bindings for more info.

Runtime compatibility¶

soft — runtime hosted_serverless, dedicated_deployment; execution remote; input video

Block keeps per-video state in process memory (keyed by video_metadata.video_identifier). With remote step execution on stateless or multi-replica HTTP runtimes, successive requests may be served by different worker processes, so the state resets between calls and the output is meaningless for tracking / counting / aggregation. Use local step execution in an InferencePipeline for stable cross-frame results.

soft — input image

Block depends on temporal context from video or repeated-frame workflows. With a still image/photo, there is no meaningful history to track, compare, aggregate, or visualize, so the block provides little or no benefit.

Available Connections¶

Input and Output Bindings¶

The available connections depend on its binding kinds. Check what binding kinds Background Subtraction in version v1 has.

{
    "name": "<your_step_name_here>",
    "type": "roboflow_core/background_subtraction@v1",
    "image": "$inputs.image",
    "threshold": 16,
    "history": 30
}