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
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 worksImgcomp 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 imgcompIt 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:
This will compile imgcomp and the required library.
I recommend setting up imgcomp to run as user "pi" in the directory /home/pi/imgcomp
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:
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:
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 moduleRun 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 diskImgcomp 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 bootIt'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 blankingTo disable screen blanking in console mode:
In the file /etc/kbd/config change:
BLANK_TIME=30 to BLANK_TIME=0
Disable on screen logoI 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
How image detection worksImgcomp 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 ignoreImgcomp 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.