Motion Detection

Introduction

One of nicest features of CHDK is its ability to add motion detection to a Canon "Point & Shoot" camera. This functionality is provide through special scripting commands which enables flexible implementation of many clever of motion detection programs. Two particularly popular uses of motion detection include lightning and fireworks photography.

Scripting Functions

To use the CHDK motion detection functions, you need to have a suitable script loaded on your camera. Two simple scripts writting in uBASIC and LUA are posted below and links to more complicated scripts can be found at the end of this page. A little searching of the CHDK wikia and forum will turn up many other useful scripts. Information about loading and running scripts can be found here : Scripts

Note : the uBASIC and LUA motion detection commands each take as many as 16 input parameters. For convenience, these are usually represented as the seqential variables a to p so that convention will be used here.

Key Concepts

CHDK motion detection scripting commands is base on the following concepts :

Zones : The camera field of view is broken into a grid of zones. These zones are used to control how motion is detected. Parameters a & b define the zone setup.

Exclusion Zone : The motion detection zones defined above can get setup so that part of the field of view is ignored. This is useful when there may be motion in parts of your field of view that you do not want to cause a photograph to be taken. There is a good description of how to use exclusion zones posted on this Forum thread. Parameters i,j,k,l & m define the exclusion zone.

Detection Modes : CHDK can be configured to trigger on differenct part of the image. Motion can be detected based on changes of luminance (Y), blue chrominance (U), red chrominance (V) or individual R, G or B values. Parameter c determines which parts will be used to decide that motion has been detected.

Sensitivity : Sensitivity settings determine how much of a change in the cameras image will be detected as motion. There is a threshold adjustment (parameter f) and a pixel step adjustmen (parameter o).

Other : several other parameters are available to tune how the motion detection function works. You can adjust how long the function waits for motion to occur, how long the function wait before attempting to detect motion, how often the function checks for motion and how many actual pixels are tested each time the function tests for motion.

Function : md_detect_motion

The md_detect_motion command carries the main brunt of setting all feature parameters for motion detection. Both the Lua and uBASIC scripting functions in CHDK support this command although there are subtle differences in the implemenation.

uBASIC :

md_detect_motion a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p

LUA:

zones = md_detect_motion( a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p)

Note : parameters i through p are optional. However, an optional parameter can only be specified if all the parameters before it in the function call are also specified.

a : defines the number of columns to split the screen into. If values less than zero if total number of cells is greater than 1024, it defaults to 3 x 3.

b : define the number of rows to split the screen into.

Note : if a or b are less than zero or if total number of cells is greater than 1024, the default grid is 3 x 3.

c : pixel_measure_mode = 1 for Y, 2 for U, 3 for V, 4 for gray, 5 for - R, 6 for G, 7 for B. You may detect motion based on changes of luminance (Y), blue – luminance (U), red – luminance (V) or individual R, G or B values. For non-specialized use, luminance (c = 1) can be used.

d : the time in milliseconds for which md_detect_motion will wait for motion to occur. This parameter is useful if you want to execute periodically some other ubasic commands together with MD If no motion detected, the script can continue to execute some other code and then if required can resume motion detection by calling again md_detect_motion. Practically, this timeout value (parameter d) has to be greater than the trigger delay (parameter p), or else the return variable (parameter h) will always equal 0.

e : measure_interval. The time delay in milliseconds in which to check for a change in a cell's values. If you need to filter out small changes made frequently by faster moving objects (leaves in the wind, or flying insects, for example) you would increase this value so that timed samples are further apart. Very useful when trying to detect changes in very slow moving subjects, i.e. snails, slime-molds, a slow-moving criminal trying to avoid motion detection devices :-), etc.

f : threshold-value for the desired mode that will not result in triggering in normal' operation.

g : determines if the grid showing the detected cells is displayed on the camera's LCD display

h : in uBASIC, the variable specified here will be used to hold the detected cells count passed back from the function. This variable is ignored in the LUA version of the function - the detected cell count is passed back as the return value of the function.

i : determines if the exclusion is inclusive or exclusive. Options: 0-no regions, 1-include, 2-exclude

j,k,l,m : define a sub-area of the screen where motion-detection is restricted-to or excluded-from.

n : miscellaneous parameter - each bit has a different meaning.

bit 1 = immediate shoot on motion detection. Function issues a key PRESS_FULL on detection of motion for fastest possible response to motion.
bit 2 = log debug information into file (* see note below)
bit 4 = dump liveview image from RAM to a file (* see note below)
bit 8 = on immediate shoot, don't release key PRESS_FULL

OR-ed values are accepted, e.g. use 9 for immediate shoot & don't release shutter.

Note : * use of bit 2 and bit 4 requires a custom CHDK version built with OPT_MD_DEBUG=1 in makefile.inc. Support was removed from standard CHDK versions to save memory.

o : determines the pixel step size. The greatest accuracy of movement-detection results when every pixel is sampled but a faster response suitable for some applications may be obtained with a larger pixel-step.

p : allows a delay of "p" milliseconds before the function starts looking for motion. Useful to allow any camera vibration to settle and maybe for the photographer to get out of the picture area

Function : md_get_cell_diff

This function is designed for advanced analysis of scene changes or to implement more complicated exclusion zones. It is designed to be called immediately after an md_detect_motion has returned. It allows you to determine the actual level of change in any cell in the field of view.

uBASIC :

md_get_cell_diff v,w,x

LUA

x = md_get_cell_diff(v,w)

v : column of the cell to be checked

w : row of the cell to be checked

x : returned value of difference between measurements/comparisons where x will be a difference of 0 to 255 representing the change between the last and present value of the cell being checked.

Note : If md_detect_motion return after a timeout ( i.e no motion) then the returned value will be the average luminosity of the framebuffer.

Debugging

n=2 (debug mode): The debug feature has been removed from standard CHDK builds to save RAM. To use it, a custom CHDK version must now be built (OPT_MD_DEBUG=1 in makefile.inc will enable motion detector debug).

Speed Testing

There has been much discussion on the proper ways to use the sometimes-confusing and highly adaptable user-configurable features of CHDK motion detection. Lengthy discussions on the CHDK Forum on how to get the fastest reaction times for lightning photography have shed some light on the subject (pun not intended). For further clarification on the best ways to implement some of the timing controls, see the "Motion Detection Too Slow?" forum discussion thread. There are scripts optimized to obtain the fastest detection speed possible by using 2 different methods (both available in the same script).

You can find software to allow testing the speed of motion detection on your camera here : Motion Detection Speed Tests

Note also that the MD routine has been reworked for some cameras so the internal "immediate shoot" option is now lightning-fast (literally). Actual speed of response is a function of the buffer arrangement in your camera and the skill of the person who made the camera port. Futher enhancements are always possible.

Sample Scripts

motion.bas

@title Motion Detect uBASIC Script

a=6
b=6
c=1
d=300000
e=200
f=5
g=1
h=0
i=0
j=0
k=0
l=0
m=0
n=0
o=2
p=0

do 

  md_detect_motion a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p

  if( h > 0 ) then
        shoot
  endif

until (0)

end

motion.lua

--[[
@title Motion Detect Lua Script
]]

a=6         -- columns to split picture into 
b=6         -- rows to split picture into 
c=1         -- measure mode (Y,U,V R,G,B) <96> U=0, Y=1, V=2, R=3, G=4, B=5
d=300000    -- timeout (mSec) 
e=200       -- comparison interval (msec) 
f=5         -- threshold (difference in cell to trigger detection)
g=1         -- draw grid (0=no, 1=yes)   
h=0         -- not used in LUA 
i=0         -- region masking mode: 0=no regions, 1=include, 2=exclude
j=0         --      first column
k=0         --      first row
l=0         --      last column
m=0         --      last row
n=0         -- optional parameters  (1=shoot immediate)
o=2         -- pixel step
p=0         -- triggering delay (msec) 

repeat

   zones = md_detect_motion( a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p)

   if( zones > 0 ) then
        shoot()
   end

until (false)

Links