See also: Imgcomp configuration parameters,   Imgcomp detection regions

What is imgcomp for?

The program "imgcomp" is for capturing long term motion triggered time-lapse photographs using a Raspberry Pi with camera module. The intended use is unattended monitoring and surveillance.

Unlike the "motion" package, it is not intended to work like a CCTV camera. Imgcomp was inspired by "trail cameras" - the sort that is left strapped to a tree in the woods to take picture of passing deer and other wildlife, with the images retrieved at a later time. I use such cameras but found that the passive infrared motion sensing would often miss events, especially in winter. Sometimes they would even miss a tractor driving past the camera!

I wrote imgcomp to monitor comings and goings at my rural property when I am not there. Unlike trail cameras, it will not miss anything, so long as it's daylight. However, it cannot be run on battery, and unlike passive infrared, it will not trigger in the dark.

What imgcomp does not do

  • Not for battery powered application. It uses too much power.
  • Not video centric (but has a video mode hack)
  • Does not work with USB web cameras (frame rate too low, cameras too unreliable)
  • Is not for people unfamiliar with using Linux from the command line.

    If you aren't comfortable editing configuration files or running a makefile, before asking me questions, get very familiar with linux. This might take you a few months of study. There is plenty about learning linux on the internet, please don't ask me for pointers. Sorry, I do not have time to teach you

    How imgcomp works

    Imgcomp runs the raspberry pi camera capture program "raspistill" to capture still pictures every second, but can go up to 3 frames per second. Images are captured to a ram disk. Imgcomp then reads the images, and if it detects a change from one image to the next, copies the image to a more permanent directory in flash, organized by time and date. The file date of the original image is used for the time stamp, so organizing is still correct even if images are analyzed after the fact.

    Imgcomp will occasionally restart rapsistill if the exposure has changed by too much because raspistill will not make exposure adjustments during a sequence. Raspistill sometimes stalls and stops taking pictures for unknown reasons. When imgcomp stops seeing new images, it will restart raspistill.

    Imgcomp tries to differentiate between important and unimportant changes. Changes that are localized to part of the image are more important than changes that happen to the whole image. Slow changes (such as clouds moving in) tend to be ignored.

    Compiling imgcomp

    It is assumed that you have raspian already installed on your Raspberry Pi.

    I do not have a binary distribution for imgcomp. Before using imgcomp, you will have to compile it. The compiler is already included in the default installation of raspian. If you don't know what compiling a program is, then you will not have much luck with other aspects of setting up imgcomp.

    You can compile imgcomp by going into the imgcomp directory and typing:

    make

    This will compile imgcomp and the required library.

    I recommend setting up imgcomp to run as user "pi" in the directory /home/pi/imgcomp
    The program "raspistill" will run as user "pi", but for other accounts requires root privileges or messing with group permissions. So just use the user id 'pi' and avoid the hassle.

    Imgcomp setup scripts

    Please see imgcomp/setup/setup-imgcomp.txt for how to set it up.

    How image detection works

    Imgcomp compares successive images. Before doing detection, the images are resized to 1/4 size. (you can also specify 1/2 or 1/8 scaling, but I have only used 1/4 myself). Scaling eliminates pixel noise and makes it less sensitive to very subtle shifts in the image.

    Next, average brightness is computed for both images and noamalization (scaling) values computed for both. After that, brightness and colour differences are computed for each pixel of the image. A histogram of change size is constructed in memory.

    It is assumed a typical change only affects one third of the image, so a difference threshold is computed from the histogram based on that. Change magnitudes are computed based on this threshold.

    After that, the image differences are examined again to find a window of maximum change. This window is computed from a difference map further reduced by 4x, and the window is 4 pixels in size, corresponding to an actual 64x64 pixel window in the source image. This windowing technique biases detection to clustered changes, which makes it less sensitive to distributed changes such as snowflakes, rainfall, or grasses waving in the wind.

    Based on the maximum window found, a global "difference" value is calculated. This threshold is compared to the sensitivity setting. If the change is above the specified sensitivity threshold, the difference is considered significant and the image, as well as the one preceding it are saved.

    Spurious change ignore

    Imgcomp occasionally false-triggers if an insect or a bird flies past the camera. This typically shows up in just one image frame, whereas changes of interest are usually across several frames. Use the option "spurious=1" in the imgcomp.conf file to ignore these spurious changes.
    See also:

    Imgcomp configuration parameters

    Imgcomp detection regions