Imgcomp configuration

Imgcomp, under normal use, will run on a Raspberry Pi and launch raspistill to capture images every second or so to a ramdisk. Imgcomp monitors the ram disk, comparing successive images and saving those images with changes from the previous one to a folder hierarchy in flash. This involves a lot of configuration options. These are best specified in a configuration file, "imgcomp.conf" file, placed in the current directory.

Imgcomp can also be run on a series of images stored in a folder (using the "-dodir" option),

imgcomp -dodir [images directory name]
This option is primarily used development and diagnostics, but is also useful for re-processing images if too many images were saved on account of setting the different threshold too low.

Imcomp can also be run on just two images. These images will be compared, with debug information printed, and a difference image saved to "diff.ppm". The diff image will be in PPM format (an uncompressed bitmap format). This mode is primarily used for development and diagnostics. The invocation for this would be:

imgcomp [image1.jpg] [image2.jpg]

Imgcomp options

Imgcomp parameters can be provided on the command line or in a file "imgcomp.conf" which is read from the current directory. When parameters are specified in the imgcomp.conf file they are specified in the form:
parameter = value
The same option, specified on the command line, would take the form:
-parameter value

The imgcomp.conf file is read before command line arguments are interpreted. The file "imgcomp.conf.example" contains an example imgcomp.conf file. I recommend you start with that file.

scale
How much to scale jpeg images by before running the detection algorithm. Scaling the image down makes the program run faster and less susceptible to pixel noise. Scale value can be 1, 2, 4 or 8. Default is 4. I only use it with a scaling of 4 myself. This equates to the command line option "-scale 4" or an imcomp.conf entry of "scale = 4"
region
Specifies what region of the image that detection is to be done over. The region is specified as x1-x2,y1-y2. For example 200-600,150-450 would specify and area in the middle, and half the size of a 800x600 image. By default, image detection is over the entire image. Note that these values will be scaled down along with the image for the actual detection algorithm, so the region edges may not be precise to the pixel.
exclude
Specifies a rectangular image to be excluded from detection. The region is specified in the format x1-x2,y1-y2, similar to "region". Multiple exclude regions can be specified. If your detection region contains a lot of excluded areas, I recommend using the "diffmap" option instead.
diffmap
Specifies the name of a jpeg file that is the map of a jpeg image. Areas coloure pure blue in the diffmap will be excluded from detection, and areas of pure red will be twice as sensitive for detection.

Most acquired images do not contain sufficiently pure red or blue areas to be considered "ignore" or "double", so you can take a captured image and paint over areas to ignore (such as trees or waving flags) blue, and perhaps a doorway in red. When imgcomp starts with a diffmap, it shows (in text) which areas are ignore or high weight.

Note that the diffmap is scaled down to the detection resolution, so use of the diffmap may not be accurate to the exact pixel boundary.

More on diffmaps here

dodir
Specifies which directory full of images to process. This is for off-line mode (not using live captures using raspistill). Source images are not deleted.
followdir
Specifies a directory to process and monitor for new images. As new images appear, imgcomp processes them and deletes them. an "aquire_cmd" option is normally used with this mode to launch raspistill to continuously aquire new images.
aquire_cmd
Indicates the command line to launch raspistill with. This line will in turn have a lot of options to pass to raspistill. Potentially, you could have imgcomp run another image aquisition program instead of raspistill. The reason imgcomp launches raspistill is that it will need to be able to restart raspistill if needed. Imgcomp will kill and re-launch raspistill if it detects that image aquisition has stopped. Imgcomp will also check if the image has become too bright or too dim and re-launch raspistill so that raspistill can re-do the auto exposure. The aquire_cmd parameter is only used in followdir mode (ignored in offline "dodir" mode)
savedir
Specifies with directory to save images to.
savenames
Output naming scheme. Uses strftime to format the output name. May include '/' characters to put different images in different directories. The default would be savenames="%m%d/%H/%m%d-%H%M%S". This value causes imgcomp to create a directory for every day and every hour, and save the images with the naming scheme "MMDD-HHMMSS". An image on July 20 at 11:50:58 would be placed in 0720/11/0720-115058. This name will be appended with a space and the diff magnitude value of three digits. In addition, if more than one image is saved in the same second, the space in the name will be replaced with a, b, or c, etc.
sensitivity
Indicates how sensitive the program is. I typically use values around 100. However, this value is highly dependent on image resolution. Change magnitudes peak out around 500 because of the change magnitude is calculated over a limited size region.
spurious
Set to '1' for spurious detection on, '0' for spurious detection off. Default off. Spurious detection ignores any changes where the images before and after the image are identical. This ignores single image events, such as an insect flying past the lens. Changes that do not return to the previous image will not be ignored.
blink_cmd
Raspistill can trigger another program to blink the LED on the raspberry pi camera module when it detects motion.

A separate program, "blink_camera_led" is used to blink the LED.
This program needs to be setuid root to have sufficient privileges for manipulating the hardware I/O lines.
I have only been ableto make my blink_camera_led program work on Raspbery Pi Model B+, can't figure out what I/O lines it connects to on the Raspberry Pi 2. If you can modify the code to work on the Pi 2, that would be much appreciated. Don't tell me "you should do this". Try the change first, then send it to me

timelapse
Specifies a time-lapse interval, in seconds. For example "tl=600" will cause imgcomp to save an image every ten minutes, regardless of whether motion was detected. Time-lapse images will occur on multiples of the specified time. "tl=3600" will save an image on the hour every hour, or whichever image is the first image acquired after the start of an hour.
debug
Output extra debugging information.