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.
  • Does not capture video
  • Does not work with USB web cameras (frame rate too low, cameras too unreliable)
  • Has no user interface to speak of
  • 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.

    Imgcomp uses libjpeg. Because I don't like external dependencies, I included a stripped down version of libjpeg in the distribution. This will automatically compile when you compile imgcomp. Compiling everything will take a minute or two.

    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.

    A test version (no live capture) of imgcomp can also be compiled for Windows using the Microsoft Visual C compiler. If you set up the compiler to be on your path, running "make.bat" from the windows command prompt will build the windows build.

    Imgcomp setup scripts (automatic setup)

    Most of the steps of setting up imgcomp described below can be automated by unpacking the archive in the /home/pi/imgcomp directory and running:
    /home/pi/setup-imgcomp

    This automates creating the ram disk and a few other tweaks to make it run better.

    If you want imgcomp to automaticall run at startup, run the script:
    /home/pi/setup-imgcomp-autorun

    This sets imgcomp to run in console mode at startup (Best not to boot your pi into graphical user interface mode). It also adds a cron job to delete the oldest recorded directory in /home/pi/images if free flash space is getting low.

    Manual imgcomp setup

    Enable camera module

    Run raspi-config to enable the camera module

    You also need to make sure that your camera module is installed and functioning. Take some pictures with raspistill to test. Type:

    raspistill -o foo.jpg"

    Then check that foo.jpg is an image of what the camera was pointed at.

    Make a ram disk

    Imgcomp uses raspistill to capture images to the file system. To avoid wearing out the flash card, it's best to capture to a ramdisk. Make a 20 megabyte ramdisk by adding the following line to the end of /etc/fstab :
    tmpfs /ramdisk tmpfs nodev,nosuid,size=20M 0 0

    Note that /etc/fstab is only read at startup, so to make this ramdisk active, you will have to reboot your raspberry pi or type "mount /ramdisk"

    Configure startup on boot

    It's best if imgcomp will automatically start after a power failure. The easiest way to do this is to add a line to /etc/rc.local. Add the following line near the end of rc.local, just above the line that reads exit 0

    su - pi -c "/home/pi/imgcomp/imgcomp" &

    This will cause imgcomp to run on startup. The login prompt will also start, but will quickly become hidden by all the output that imgcomp produces. However, you will still be able to log into the console by typing your username and password. However, your have to do this blindly because your typing will be obscured by all the imgcomp output. After logging in, type "killall -9 imgcomp" to kill the program. You can restart it by typing "imcomp/imgcomp &" from the home directory. Started this way, it will keep running even after you log out.

    Disable screen blanking

    To disable screen blanking in console mode:
    In the file /etc/kbd/config change:

    BLANK_TIME=30 to BLANK_TIME=0
    Also change:
    POWERDOWN_TIME=30 to POWERDOWN_TIME=0
    more on this here

    Disable on screen logo

    I prefer to disable the raspberry pi logo at the top of the screen to leave more room for text. To disable the logo, add logo.nologo to the end of the line in the file /boot/cmdline.txt. The line should look like this:

    dwc_otg.lpm_enable=0 console=ttyAMA0,115200 console=tty1 root=/dev/mmcblk0p2 rootfstype=ext4 elevator=deadline rootwait logo.nologo

    more on this here


    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