Ultra-simple machine vision in C with RobotEyez

I use PGM image files a lot in my Engineering Computing class because the provide a really easy way for novice programmers to get started with image processing in C. This file format stores greyscale images in plain text and it’s easy to write C programs that write and read them using only standard library functions. It’s one of a closely related family of refreshingly understandable image file formats called Netpbm. Wikipedia provides a nice PGM example.

For quite a while, I’ve been meaning to create a lightweight DirectShow engine (a standalone executable) that allows C programmers to perform real-time machine vision simply by writing a program that reads and analyses a PGM file. RobotEyez is my first attempt at doing this.

When you run RobotEyez.exe, it opens a video capture device (e.g. webcam) and begins video capture (at the default frame rate and either the default resolution or the requested frame width and height). Individual frames are converted to greyscale and saved to a PGM file (called “frame.pgm”) or files (called "frame0001.pgm", "frame0002.pgm", "frame0003.pgm", etc) at a time interval specified by the user. The user can also specify a command to run after each image is saved. Command line arguments can be used to specify the capture device (by name or number), a delay before the first image is saved, the interval between subsequent saved frames, the total number of frames to save, the command to run after each file is saved, and whether or not a video preview window should be displayed during capture.

Download RobotEyez

The complete source code can be downloaded from the RobotEyes page on Github. If you just want the executable file, it can be downloaded from the following link:

RobotEyez.exe (44KB, 7-3-2012)

Another little program of mine called WatchPGM can be useful to run alongside RobotEyez. When you drag a PGM file into the WatchPGM window, it is displayed. What’s different (and very useful) about WatchPGM is that it keeps a close watch on the file, so that if another program (e.g. RobotEyez) modifies the PGM file on disk, the updated version is automatically displayed. Here’s the link to download the binary version of WatchPGM:

WatchPGM.exe (58KB, 28-11-2011)

RobotEyez Command Line Options

To specify the frame width and height:

/width IMAGE_WIDTH_IN_PIXELS

/height IMAGE_HEIGHT_IN_PIXELS

To specify a delay before first frame is saved to file (default value is 2000 milliseconds):

/delay DELAY_IN_MILLISECONDS

To specify the time interval between saved frame (default value is 1000 milliseconds):

/period PERIOD_IN_MILLISECONDS

To specify the total number of frames to capture to file (default value is 1; specifying a negative value results in indefinite capture):

/frames NUMBER_OF_FRAMES

To add numbering the saved image filenames (by default, the output filename is just "frame.pgm" – i.e. not numbered):

/number_files

To select a capture device by number (default value is 1):

/devnum DEVICE_NUMBER

To select a capture device by name:

/devname DEVICE_NAME

To list available video capture devices:

/devlist

To specify a command to run after each file is saved:

/command COMMAND_TO_RUN

To display a video preview window during capture (by default, no video window is displayed on screen during capture):

/preview

To save captured images as normal bitmap files (e.g. “frame.bmp”) rather than PGM:

/bmp

RobotEyez Example Commands

To capture a single image at 320×240 pixel resolution after a 1 second delay, and save to a bitmap file called "frame.bmp":

RobotEyez /delay 1000 /width 320 /height 240 /bmp

For example, to delay for 3 seconds, then capture ten frames at 1 second intervals from the default capture device to files called "frame0001.pgm", "frame0002.pgm", etc, while displaying the video preview window on screen:

RobotEyez /delay 3000 /period 1000 /frames 10 /number_frames /preview

To capture frames indefinitely at 0.5 second intervals to a file called "frame.pgm", calling a program called "imageproc.exe" after each frame is saved, use the following command:

RobotEyez /frames -1 /period 500 /command imageproc.exe

In the previous example, no video preview window is displayed on screen.

To capture an image from the webcam once every minute for 24 hours (1440 images in total) and save the files as "image0001.bmp", "image0002.bmp", "image0003.bmp", etc:

RobotEyez /frames 1440 /period 60000 /number_files /bmp