Background Subtractor

The background_subtractor component utilizes a set of OpenCV functions to implement motion detection using an algorithm called background subtraction.

It works by creating a running average of frames, and then comparing the current frame to this average.
If enough changes have occurred, motion will be detected.
By using a running average, the "background" image will adjust to daylight, stationary objects etc.
This blogpost from PyImageSearch explains this procedure quite well.

Configuration

Configuration example

background_subtractor:
  motion_detector:
    cameras:
      camera_one:
        fps: 1
        mask:
          - coordinates:
              - x: 400
                y: 200
              - x: 1000
                y: 200
              - x: 1000
                y: 750
              - x: 400
                y: 750
      camera_two:
        fps: 2
        trigger_recorder: true

background_subtractormap required

Component configuration.

motion_detectormap required

Motion detector domain config.

camerasmap required

Camera-specific configuration. All subordinate keys corresponds to the camera_identifier of a configured camera.

<CAMERA_IDENTIFIER>map required

Camera identifier. Valid characters are lowercase a-z, numbers and underscores.

trigger_recorderboolean (optional, default: false)

If true, detected motion will start the recorder.

recorder_keepaliveboolean (optional, default: true)

If true, recording will continue until no motion is detected.

max_recorder_keepaliveinteger (optional, default: 30)

Value in seconds for how long motion is allowed to keep the recorder going when no objects are detected.
Use this to prevent never-ending recordings.
Only applicable if recorder_keepalive: true.
A value of 0 disables this functionality.

Lowest value: 0

fpsfloat (optional, default: 1)

The FPS at which the motion detector runs.
Higher values will result in more scanning, which uses more resources.

Lowest value: 0

areafloat (optional, default: 0.08)

How big the detected area must be in order to trigger motion.

Lowest value: 0

Highest value: 1

widthinteger (optional, default: 300)

Frames will be resized to this width before applying the motion detection algorithm to save computing power.

heightinteger (optional, default: 300)

Frames will be resized to this height before applying the motion detection algorithm to save computing power.

masklist (optional)

A mask is used to exclude certain areas in the image from motion detection.

coordinateslist required

List of X and Y coordinates to form a polygon

Minimum items: 3

xinteger required

X-coordinate (horizontal axis).

yinteger required

Y-coordinate (vertical axis).

thresholdinteger (optional, default: 15)

The minimum allowed difference between our current frame and averaged frame for a given pixel to be considered motion. A smaller value leads to higher sensitivity and a larger value leads to lower sensitivity.

Lowest value: 0

Highest value: 255

alphafloat (optional, default: 0.1)

How much the current image impacts the moving average.
Higher values impacts the average frame a lot and very small changes may trigger motion.
Lower value impacts the average less, and fast objects may not trigger motion. More can be read here.

Lowest value: 0

Highest value: 1

Motion detector

A motion detector scans an image for moving parts.

info

Detected motion can, if configured, signal an object detector to start scanning. This is good because object detection uses far more resources compared to motion detection.

Recorder

A motion detector can start the recorder if trigger_recorder is set to true, meaning an object detector is not strictly needed.

Mask

Masks are used to exclude certain areas in the image from motion detection. All movement within the mask will be ignored.

The coordinates form a polygon around the masked area.
To easily generate coordinates you can use a tool like image-map.net.
Just upload an image from your camera, choose the Poly shape and start drawing your mask.
Then click Show me the code! and adapt it to the config format.
Coordinates coords="522,11,729,275,333,603,171,97" should be turned into this:

background_subtractor:
  motion_detector:
    cameras:
      camera_one:
        ...
        mask:
          - coordinates:
              - x: 522
                y: 11
              - x: 729
                y: 275
              - x: 333
                y: 603
              - x: 171
                y: 97

Paste your coordinates here and press Get config to generate a config example

Troubleshooting

To enable debug logging for background_subtractor, add the following to your config.yaml

/config/config.yaml
logger:
  logs:
    viseron.components.background_subtractor: debug

Background Subtractor

Configuration​

Motion detector​

Mask​

Troubleshooting​

Configuration

Motion detector

Mask

Troubleshooting