Skip to content

Motion Detection

Class: MotionDetectionBlockV1

Source: inference.core.workflows.core_steps.classical_cv.motion_detection.v1.MotionDetectionBlockV1

Detect motion in video streams using OpenCV's background subtraction algorithm.

How This Block Works

This block uses background subtraction (specifically the MOG2 algorithm) to detect motion in video frames. The block maintains state across frames to build a background model and track motion patterns:

  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. Filters noise - applies morphological operations to remove noise and combine nearby motion regions into coherent contours
  4. Extracts motion regions - finds contours representing motion areas, filters them by minimum size, and optionally clips them to a detection zone
  5. Simplifies contours - reduces contour complexity to keep detection data manageable
  6. Generates outputs - creates object detection predictions with bounding boxes, determines motion status, triggers alarms when motion starts, and provides motion zone polygons

The block tracks motion state across frames - the alarm output becomes true only when motion transitions from not detected to detected, making it useful for triggering actions when motion first appears.

Common Use Cases

  • Security Monitoring: Detect motion in surveillance cameras to trigger alerts, recordings, or notifications when activity is detected
  • Resource Optimization: Conditionally run expensive inference operations (e.g., object detection, classification) only when motion is detected to save computational resources
  • Activity Detection: Monitor areas for movement to track occupancy, identify entry/exit events, or detect unauthorized access
  • Video Analytics: Analyze video streams to identify motion patterns, track activity levels, or detect anomalies in monitored areas
  • Smart Recording: Trigger video recording or snapshot capture when motion is detected, reducing storage requirements compared to continuous recording
  • Zone Monitoring: Monitor specific areas within a frame using detection zones to focus motion detection on relevant regions while ignoring busy but irrelevant areas

Connecting to Other Blocks

The motion detection outputs from this block can be connected to:

  • Conditional logic blocks (e.g., Continue If) to execute workflow steps only when motion is detected or when alarms trigger
  • Object detection blocks to run detection models only on frames with motion, saving computational resources
  • Notification blocks (e.g., Email Notification, Slack Notification) to send alerts when motion is detected or alarms trigger
  • Data storage blocks (e.g., Roboflow Dataset Upload, CSV Formatter) to log motion events, timestamps, and detection data for analytics
  • Visualization blocks to draw motion zones, bounding boxes, or annotations on frames showing detected motion
  • Filter blocks to filter images or data based on motion status before passing to downstream processing

Type identifier

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

Properties

Name Type Description Refs
name str Enter a unique identifier for this step.. ❌
minimum_contour_area int Minimum area in square pixels for a motion region to be detected. Contours smaller than this threshold are filtered out to ignore noise, small shadows, or minor pixel variations. Lower values increase sensitivity but may detect more false positives (e.g., 100 for very sensitive detection, 500 for only large objects). Default is 200 square pixels.. ✅
morphological_kernel_size int Size of the morphological kernel in pixels used to combine nearby motion regions and filter noise. Larger values merge more distant motion regions into single contours but may also merge separate objects. Smaller values preserve more detail but may leave fragmented detections. The kernel uses an elliptical shape. Default is 3 pixels.. ✅
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.. ✅
detection_zone Union[List[Any], str] Optional polygon zone to limit motion detection to a specific area of the frame. Motion is only detected within this zone, ignoring activity outside. Format: [[x1, y1], [x2, y2], [x3, y3], ...] where coordinates are in pixels. The polygon must have more than 3 points. Can be provided as a list, JSON string, or selector referencing zone outputs from other blocks. Useful for focusing on specific regions (e.g., doorways, windows, restricted areas) while ignoring busy but irrelevant areas. If not provided, motion is detected across the entire frame.. ✅
suppress_first_detections bool If true, suppresses motion detections until the background model has been initialized with enough frames (specified by the history parameter). This prevents false positives from early frames where the background model hasn't learned the scene yet. When false, the block attempts to detect motion immediately, which may produce unreliable results during initialization. Default is true (recommended for most use cases).. ✅

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

Compatible Blocks

Check what blocks you can connect to Motion Detection in version v1.

Input and Output Bindings

The available connections depend on its binding kinds. Check what binding kinds Motion Detection in version v1 has.

Bindings

  • input

    • image (image): The input image or video frame to analyze for motion. The block processes frames sequentially to build a background model - each frame updates the background model and detects motion relative to learned background patterns. Can be connected from workflow inputs or previous steps..
    • minimum_contour_area (integer): Minimum area in square pixels for a motion region to be detected. Contours smaller than this threshold are filtered out to ignore noise, small shadows, or minor pixel variations. Lower values increase sensitivity but may detect more false positives (e.g., 100 for very sensitive detection, 500 for only large objects). Default is 200 square pixels..
    • morphological_kernel_size (integer): Size of the morphological kernel in pixels used to combine nearby motion regions and filter noise. Larger values merge more distant motion regions into single contours but may also merge separate objects. Smaller values preserve more detail but may leave fragmented detections. The kernel uses an elliptical shape. Default is 3 pixels..
    • threshold (integer): 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): 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..
    • detection_zone (Union[zone, list_of_values]): Optional polygon zone to limit motion detection to a specific area of the frame. Motion is only detected within this zone, ignoring activity outside. Format: [[x1, y1], [x2, y2], [x3, y3], ...] where coordinates are in pixels. The polygon must have more than 3 points. Can be provided as a list, JSON string, or selector referencing zone outputs from other blocks. Useful for focusing on specific regions (e.g., doorways, windows, restricted areas) while ignoring busy but irrelevant areas. If not provided, motion is detected across the entire frame..
    • suppress_first_detections (boolean): If true, suppresses motion detections until the background model has been initialized with enough frames (specified by the history parameter). This prevents false positives from early frames where the background model hasn't learned the scene yet. When false, the block attempts to detect motion immediately, which may produce unreliable results during initialization. Default is true (recommended for most use cases)..

  • output

Example JSON definition of step Motion Detection in version v1 
{
    "name": "<your_step_name_here>",
    "type": "roboflow_core/motion_detection@v1",
    "image": "$inputs.image",
    "minimum_contour_area": 200,
    "morphological_kernel_size": 3,
    "threshold": 16,
    "history": 30,
    "detection_zone": "<block_does_not_provide_example>",
    "suppress_first_detections": true
}