> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/workflows/blocks/blocks/video-processing/background-subtraction.md).
# 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@v1` to add the block as a step in your workflow.
### Properties
| **Name** | **Type** | **Description** | Refs |
| ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
| `name` | `str` | Enter a unique identifier for this step.. | ❌ |
| `threshold` | `int` | Threshold value for the squared Mahalanobis distance used by the MOG2 background subtraction algorithm. Controls sensitivity to motion - smaller values increase sensitivity (detect smaller changes) but may produce more false positives, larger values decrease sensitivity (only detect significant changes) but may miss subtle motion. Recommended range is 8-32. Default is 16.. | ✅ |
| `history` | `int` | Number of previous frames used to build the background model. Controls how quickly the background adapts to changes - larger values (e.g., 50-100) create a more stable background model that's less sensitive to temporary changes but adapts slowly to permanent background changes. Smaller values (e.g., 10-20) allow faster adaptation but may treat moving objects as background if they stop moving. Default is 30 frames.. | ✅ |
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 a persistent WebRTC session 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.
### Input and Output Bindings
The available connections depend on its binding kinds. Check what binding kinds `Background Subtraction` in version `v1` has.
Input and output bindings
* input
* `image` ([*`image`*](/workflows/developer-guide/developer-guide/kinds/image.md)): The input image or video frame to process for background subtraction. The block processes frames sequentially to build a background model - each frame updates the background model and creates a motion mask showing areas that differ from the learned background. Can be connected from workflow inputs or previous steps..
* `threshold` ([*`integer`*](/workflows/developer-guide/developer-guide/kinds/integer.md)): Threshold value for the squared Mahalanobis distance used by the MOG2 background subtraction algorithm. Controls sensitivity to motion - smaller values increase sensitivity (detect smaller changes) but may produce more false positives, larger values decrease sensitivity (only detect significant changes) but may miss subtle motion. Recommended range is 8-32. Default is 16..
* `history` ([*`integer`*](/workflows/developer-guide/developer-guide/kinds/integer.md)): Number of previous frames used to build the background model. Controls how quickly the background adapts to changes - larger values (e.g., 50-100) create a more stable background model that's less sensitive to temporary changes but adapts slowly to permanent background changes. Smaller values (e.g., 10-20) allow faster adaptation but may treat moving objects as background if they stop moving. Default is 30 frames..
* output
* `image` ([`image`](/workflows/developer-guide/developer-guide/kinds/image.md)): Image in workflows.
Example JSON definition
```json
{
"name": "",
"type": "roboflow_core/background_subtraction@v1",
"image": "$inputs.image",
"threshold": 16,
"history": 30
}
```