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

The directory conf-examples contains a number of sample imgcomp.conf configuration files.

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.

aquire_cmd

Specifies the raspistill command and command line options to use. This line contains all the raspistill options.

brmonitor

Set to 1 for brightness change monitoring. This feature is used together with burst mode in raspistill (-bm option in aquire command). In burst mode, raspistill does not do exposure level tracking, so imgcomp will restart it if necessary to re-acquire the exposure value.

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 imgcomp.conf entry of "scale = 4". Warning, I have not tested this with non-default values.

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 colored 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 acquisition 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="%y%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 "YYMMDD-HHMMSS". An image on July 20 2019 at 11:50:58 would be placed in 190720/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.

class="p">fatigue

Set tins parameter to zero to disable "motion fatigue". Motion fatigue makes imgcomp insensitive to areas that have had a lot of motion. Motion detection is useful to avoid false triggers from tree shadows and such, but it can cause it to miss stuff.

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.

logtofile

Sepcifies text output to be written to a log file instead of to console. Ideally the log file is on a ramdisk to put less wear on flash cards.

movelognames

Where to copy logs files to. I normally have it copy the log file to the pictures directory every hour, so that it's easy to find the log file that goes with the pictures.