Modules

[ std_ptz.so ]

This module is used for controlling pan/tilt/zoom cameras. The user is
expected to determine several preset positions before hand, and also to
provide a script which pans the camera to a pre-determined position 
before returning. Each preset position is treated as a camera instance.
A separate sequence file implements the timing and control of the panning
itself. Note that this module should be the first module in the camera
stanza. The following illustrates a single PTZ camera with 2 camera
positions defined :

  camera {
    name "eagle_eye1"
    input {
      module "std_ptz.so"
      params {
        sequence "/path/to/positions.conf"
        position 1
      }
      module "input_http.so"
      params {
        ...
      }
    }
    ...
  }
  camera {
    name "eagle_eye2"
    input {
      module "std_ptz.so"
      params {
        sequence "/path/to/positions.conf"
        position 2
      }
      module "input_http.so"
      params {
        ...
      }
    }
    ...
  }

The sequence file for the above 2 positions looks like this :

  # look at driveway
  1 600 /path/to/cam_control.sh 1
  # look at porch
  2 300 /path/to/cam_control.sh 2

There are essentially 3 columns in a sequence file. The first is the camera
position number, the second is the duration to spend at that position (in
seconds), and the third is the command (script) to execute, which is expected
to pan the camera to that position. In the above example, executing the
"cam_control.sh" script, passing it an argument of "1" presumably sets the
camera to position 1. This camera instance is active for 600 seconds, after
which the second camera instance becomes active for 300 seconds, and so on.

[ input_http.so ]

This module uses libcurl to pull images from a webcam. The user must specify
a URL where the image can be downloaded from. The following configuration 
illustrates the bare minimum required :

  camera {
    ...
    input {
      module "input_http.so"
      params {
        url "http://admin:admin@192.168.1.10/image.jpg"
      }
    }
    ...
  }

Mandatory parameters :

  url - the URL at which we may obtain a camera image.

Optional parameters :

  poll_freq_ms - how often we'll pull a fresh image, in milliseconds.
                 default: 5000

[ input_v4l2.so ]

This module uses V4L2 API to capture images from /dev/videoX (presumably
a webcam). The raw data from the camera is expected to be in YUV422 format
and is encoded to jpeg data using libjpeg. No parameters are required in
order for the module to work. The following configuration is sufficient :

  camera {
    ...
    input {
      module "input_v4l2.so"
    }
    ...
  }

Optional parameters :

  videodev     - the character special device of the camera.
                 default: "/dev/video0"
  jpeg_quality - jpeg quality when writing data
                 default: 90, range 0-100
  width        - the width of the frame to be captured.
                 default: 640
  height       - the height of the frame to be captured.
                 default: 480
  poll_freq_ms - how often we'll pull a fresh image, in milliseconds.
                 default: 5000

Note that the actual capture width/height depends on whether the resolution
is supported by the camera. This module will abort if an unsupported
resolution is requested.

[ std_noise.so ]

This module sets the noise threshold for the camera and calculates the
motion heat map. The value of the noise threshold determines the amount
of variation a pixel undergoes between frames to be considered a change.

The motion heatmap is an array, equal to the resolution of the camera image,
which designates frequency that change is detected for each pixels. Each
value represents a pixel and has a range between 0.0 to 1.0. When a pixel
is determined to have changed, the corresponding pixel in the heatmap is
incremented towards 1.0 by a certain percentage. Once in a while, the entire
heat map is "cooled down" by decrementing all values towards 0.0 by a certain
percentage. Thus, over time, the heatmap will have "bright" regions where
motion is always occuring, and "dark" regions where almost no motion is ever
detected. In order to better visualize this heatmap, this module may be
configured to periodical dump the heatmap to a PPM file.

This is an optional module. If the user intends to use it, the following
illustrates the bare minimum required :

  camera {
    ...
    noise {
      module "std_noise.so"
      params {
        heatmap_dat "/path/to/heatmap.dat"
      }
    }
    ...
  }

When run for the first time, the heat map array elements are initialized to
0.0. This module will then periodically save the contents of the heat map to
the file specified in its configuration. This heat map file is loaded should
jmotion get restarted. If the user subsequently changes the camera resolution,
the module detects that the heat map file is no longer valid and reinitializes
the heat map array elements to 0.0.

Mandatory parameters :

  heatmap - the path to the heat map data file

Optional parameters :

  noise_level - amount of change for a pixel to be considered changed.
                default: 48, range 0-255
  inc_factor  - percentage by which to increment an active pixel.
                default: 1.0, range 0.0-100.0
  dec_factor  - percentage by which to decrement all pixels during cool down.
                default: 1.0, range 0.0-100.0
  cool_down   - how often we cool down the heat map, in seconds.
                default: 600
  heatmap_ppm - the PPM file which visually represents the heatmap.
                default: none, example "/path/to/myheatmap.ppm"
  dump_freq   - how often the heatmap (and ppm) are written to disk in seconds.
                default: 300

[ std_detection.so ]

This module examines the differences between frames to determine if motion
of interest has occured. The motion heat map is used to assist in this. For
example, pixels that are changing very frequently should be ignored (eg, trees
moving in the wind). This module creates a sorted list of all the data points
in the heat map (recall their values are between 0.0 and 1.0). Next, the
"sensitivity" parameter determines the cut off point in the sorted list. Thus,
if "sensitivity" is low (eg, 10%), then only the bottom 10% pixels will be
examined for movement (ie, regions which almost never observe motion). If
"sensitivity" is high (eg, 80%), then even pixels where change is common will
be examined.

Now that we've determined which pixels will be checked for change, the
"motion_thres" parameter determines how many pixels must have changed in order
to be considered movement. This parameter is a percentage. Thus, if the value
is set to 1%, and our image resolution is 640x480, then 1% equals :

  (1 / 100) * (640 * 480) = 3072

Thus, if 3072 or more pixels change, then this module flags the frame as
having motion.

This is an optional module. If the user intends to use it, the following
illustrates the bare minimum required : 

  camera {
    ...
    detection {
      module "std_detection.so"
    } 
    ...
  } 

Optional parameters:

  sensitivity  - determines the heatmap cut off threhold.
                 default: 80.0, range 0.0-100.0
  motion_thres - amount of change to be considered motion.
                 default: 0.5, range 0.0-100.0

[ output_jpeg.so ]

This module saves the current jpeg image to disk (ie, the file keeps getting
replaced with a newer one). In addition, it can save every frame captured into
an archive (ie, like a continuous recorder). Files that are too old can also
be automatically deleted. If the frame is tagged as having motion detected, an
additional copy of the image is saved into a separate location.

The following illustrates the bare minimum configuration :

  camera {
    ...
    output {
      module "output_jpeg.so"
      params {
        cur_frame "/path/to/current.jpg"
      }
    }
    ...
  }

Mandatory parameters :

  cur_frame - The jpeg file which holds the current jpeg frame.

Optional parameters :

  save_dir   - all frames captured will be archived here.
               default: none, example "/path/to/cam1_archive"
  max_age    - archive image files older than this (in seconds) are deleted.
               default: 3600
  check_freq - how often (in seconds) we check for old files to delete.
               default: 180
  motion_dir - if a frame is tagged as having motion detected, save it here.
               default: none, example "/path/to/cam1_motion"