Skip to content
Tutorials Center
My learning

Topics

Lesson 49 of 54 ยท Projects

Project: Motion Detector

Build a motion detector with frame differencing: gray, blur, absdiff, threshold, dilate and bounding boxes. Includes live NumPy demos on synthetic frames.

A motion detector watches a stream of frames and answers one question: did something change? Security cameras, wildlife traps, automatic doors and "is anyone at my desk" scripts all start from this idea. The simplest and most instructive version compares each frame with the previous one, keeps the pixels that changed a lot, and wraps boxes around the changed regions.

OpenCV can read a webcam or a video file, but it cannot run on this site, so the real loop appears in read-only blocks. Everything else is live: we create synthetic frames with NumPy (a noisy background and a bright square that moves), then run the same steps (blur, absolute difference, threshold, dilation, region labeling, bounding boxes) with our own NumPy code. The ideas carry over line by line.

Motion in five steps

Gray and blur Smooth away sensor noise.
Difference Current frame minus previous.
Threshold Keep only big changes.
Dilate Join nearby fragments.
1 / 2

The real loop (read-only)

Python
import cv2

cap = cv2.VideoCapture(0)               # 0 = first webcam, or a video file path
ok, frame = cap.read()
previous = cv2.GaussianBlur(cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY), (21, 21), 0)

while True:
    ok, frame = cap.read()
    if not ok:
        break

    gray = cv2.GaussianBlur(cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY), (21, 21), 0)
    delta = cv2.absdiff(previous, gray)
    mask = cv2.threshold(delta, 25, 255, cv2.THRESH_BINARY)[1]
    mask = cv2.dilate(mask, None, iterations=2)

    contours, _ = cv2.findContours(mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
    for contour in contours:
        if cv2.contourArea(contour) < 500:
            continue
        x, y, w, h = cv2.boundingRect(contour)
        cv2.rectangle(frame, (x, y), (x + w, y + h), (0, 255, 0), 2)

    cv2.imshow("motion", frame)
    previous = gray
    if cv2.waitKey(30) & 0xFF == ord("q"):
        break

cap.release()
cv2.destroyAllWindows()

The camera and video handling are covered in Reading and Writing Video and Processing Video Frame by Frame. This project concentrates on what happens to each frame pair.

Real vs stand-in: VideoCapture, GaussianBlur, absdiff, threshold, dilate, findContours and imshow are real OpenCV and cannot run here (there is no camera or window). The live demos replace them with NumPy functions we write ourselves, applied to synthetic frames.

Step 1: synthetic frames

Our "video" is 40 rows by 60 columns. The background is a soft brightness gradient plus a little random noise that changes on every frame, just like sensor noise on a real camera. A bright square moves down and to the right for five frames, stays still on frame 5, then a global brightness change hits on frame 6, and finally a second small object appears on frame 7.

First, the most important beginner trap in this whole project: subtracting uint8 frames. NumPy and OpenCV store 8-bit pixels, and a plain subtraction wraps around below zero. cv2.absdiff avoids that; in NumPy we widen the type first.

Python Frames, and the wrap-around trap

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The mask shows two blocks that touch at a corner: where the square was and where it is now. That "ghost" is a property of frame differencing, because both the pixels the object left and the pixels it covers have changed. We will deal with it in a moment.

Step 2: blur, threshold, dilate, find regions

Real noise needs more care than our gentle noise. In the real loop, a blur before the difference averages away per-pixel noise, and the threshold (25 in the code above) decides how big a brightness change counts as motion. Too low and sensor noise lights up everywhere; too high and slow or faint motion is missed. A dilation then grows each white region a couple of pixels so that fragments of one moving object merge into one blob, instead of ten little ones.

Finally we need one region per mover. findContours does that in OpenCV. Our stand-in is a flood-fill that labels 4-connected pixels, computes each blob's bounding box and area, and ignores blobs below a minimum area. We run it on every frame pair and print what the detector sees.

Python Detect motion across the whole clip

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Read the printout. Frames 1 to 4 each report one box, and that box covers both the old and the new position of the square (the ghost). Frame 5 is still, so no boxes. Frame 6 is a global brightness increase of about 10 levels, which is below the threshold, so it is correctly ignored. Frame 7 reports the second object entering.

The area filter (min_area=40) is your second line of defense. If a stray noise pixel crossed the threshold, it would form a one-pixel blob and be dropped.

Step 3: choosing the threshold

The threshold is the most important tuning parameter. A quick way to choose it is to run the detector on frames you know contain no motion and count how many pixels survive at each threshold.

Python Threshold vs false alarms

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Compare each pair of rows: blurring before the difference cuts false alarms sharply, and raising the threshold cuts them further. On a real camera, indoor scenes with auto-exposure and compressed video produce much more noise than this, which is why the real loop uses a large blur (21 by 21) and a threshold near 25.

Limits of frame differencing, and what to do

  • Ghosts and hollow objects. The previous position also lights up, and the middle of a uniformly colored object may not change at all if it moves slowly. Fix: compare against a reference background (the average of several still frames) instead of the previous frame, or use cv2.createBackgroundSubtractorMOG2() (see Processing Video Frame by Frame), which keeps an adaptive background model.
  • Objects that stop. With consecutive-frame differencing, an object that stops stops being detected. Background subtraction keeps seeing it until it is absorbed into the background.
  • Global lighting changes. Clouds, a light switch or auto-exposure change the whole frame. Use an adaptive background or skip detection when more than, say, 60 percent of the pixels changed at once.
  • Camera shake. Everything moves at once. Stabilize first or discard frames with huge global differences.
  • Speed. Detect on a downscaled frame (see Making OpenCV Fast) and scale the boxes back up.
  • Privacy. Cameras record people. Store only what you need, tell people they are monitored, and respect the law where you live.

Once you can detect motion, the natural next step is to follow each mover from frame to frame: Motion and Object Tracking.

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why use cv2.absdiff (or widen to int16) instead of plain uint8 subtraction when comparing frames?

    With uint8, 100 - 120 becomes 236 instead of -20. absdiff computes the absolute difference with safe arithmetic.
  2. 2. Why does simple frame differencing show two blobs for one moving object?

    The old position changes from object to background and the new position changes from background to object, so both light up in the difference.
  3. 3. What does dilating the thresholded mask achieve?

    Dilation grows white regions, so broken pieces of the same object merge before contours or labels are computed.
  4. 4. A cloud passes and the whole image gets 8 brightness levels darker. With a threshold of 25, what does the detector do?

    The absolute difference is about 8 everywhere, below 25, so no pixel enters the mask. A bigger lighting jump would need special handling.
  5. 5. Which approach avoids ghosts and keeps detecting an object that has stopped moving?

    A background model represents the empty scene, so only the object differs from it, whether it moves or not.

Summary

  • Motion detection by frame differencing: gray, blur, absdiff with the previous frame, threshold, dilate, find regions, filter by area, draw boxes.
  • Never subtract uint8 frames directly: use cv2.absdiff (or widen the type in NumPy).
  • The threshold balances sensitivity against false alarms; blur first and measure the false-alarm rate on a still scene.
  • Frame differencing makes ghosts and loses objects that stop; a background model fixes both.
  • Global lighting changes and camera shake need extra handling.
  • The live demos used NumPy stand-ins on synthetic frames; the cv2 camera loop is read-only here.

Last project in the chapter: Project: Panorama Stitching.