CLIP (Version 1.03)

CLIP is a C++ template library for image processing. Some of its features are:

• Efficient implementation of common image processing functions.
• Matlab-like constructs for concise programs.
• Easily learnt, but with fine tuning facilities for experts.
• CLIP programs run on MS Windows, Mac OS and Linux.
• Efficient image display through MS Windows and X windows.
• Video input via Video for Windows and Video for Linux. (Quicktime is not supported, so Mac users do not have this feature.)
• Matrix functions to support statistical pattern recognition
• Reads PPM, PGM, BMP, JPEG and APT files. Writes PPM, PGM, BMP and APT. (PPM/PGM are the "native" formats of CLIP.)
• Lots of example programs available.

CLIP is implemented as a single header file called picture.h. To write a clip program, you #include "picture.h", then call whatever facilities you need. This can be done within an integrated environment like MS Visual C++ or through a command line interface (which I recommend).

CLIP is Open Source under the GNU Public Licence. It incorporates code from a number of other Open Source projects, acknowledged at the top of picture.h.

You can download picture.h here, or get the full distribution that includes a suite of useful tools and lots of example programs. I recommend you get the full distribution, but please see the Using CLIP section below for suggestions on installation and configuration.

//
// invert.cpp
// Simple camera-only program that shows the input video and its
// colour negative.
//
#include "picture.h"
int main() {
	colour_picture in(480,640);// Set up picture of 640 cols by 480 rows
	colour_picture out(480,640);
	in.show("Input");
	out.show("Output");
	in.attach_camera();// Connect the picture to the camera
	in.request_frame();
	while(!in.closerequested() && !out.closerequested()) {
		while (!in.frame_delivered())
			;	// Wait for next frame
		in.request_frame(); // Start next frame capture while doing:
		out = in;
		out *= -1;
		in.reshow();
		out.reshow();
		}
	return 0;
	}

Download invert.cpp and/or a compiled version for Microsoft Windows. (Remember that you need a camera connected for this program. If you don't have a camera but would like to try a CLIP program before you compile your own, try "pixelate" below -- that works both on the pictures from a camera and on image files.)

invert.cpp illustrates the default "simple" usage of CLIP that does not appear to involve templates and that uses member function calls with the minimum of parameters (all the other parameters being defaults). To get a faster program these defaults can be overridden. The README file that comes with the full CLIP distribution explains how.

More examples

Here are some more example programs. You can just pull these into Visual C++, for example, together with picture.h and get fully functioning interactive applications. All are included in the full distribution.

• pixelate.cpp works with a camera or with picture files. If you give command line arguments, it cycles through those files; if you don't, it operates on the camera picture instead. If you don't give arguments and don't have a camera connected, it operates on a boring default image. As suggested by the name, it pixelates the input image according to a user-controlled parameter. You can also download a compiled version for Microsoft Windows.
• gaussfilter.cpp illustrates the operation of a gaussian filter. Again it works with files or camera images.
• apttest.cpp is a file-only application that takes just one command-line argument then lets you assess APT compression of that picture at different quality settings.
• radialcorr.cpp is a simple radial correction program that lets you adjust the amount of barrel/pincushion distortion. It works on files or the camera image.
• canny.cpp is an implementation of the Canny edge detector that works on files or the camera.
• fijiart.cpp takes a filename command-line argument corresponding to a picture and lets you manipulate it as if it were texture-mapped terrain.
• cliptris.cpp is a CLIP implementation of tetris.

Using CLIP

The CLIP distribution zip file contains picture.h, a set of test pictures, some useful utilities, the above examples, all the programs included in the CLIP tutorial, and a README file to help you configure CLIP.

CLIP adopts the Unix software tools philosophy: "Let each program do one thing well". CLIP programs are therefore most suited to running in a command-line environment. In MS Windows I use cygwin; you might prefer the MSDOS command prompt. If you download the full distribution and then expand the zip file, you will get a directory structure with the following levels:

• clip - the top level directory containing configuration scripts and the following subdirectories:
  • bin - where, by default, all CLIP executables live
    • src - sources for CLIP utilities and other programs used as tools in the tutorials
  • include - containing picture.h (i.e. CLIP itself) and a little file called usage.h that several of the utilities use.
  • examples - example programs
  • tutorial - containing the programs listed in the CLIP tutorials so students don't have to type them in again.
  • pics - some famous and imfamous test images
  • sequence - a short image sequence captured from a webcam
  • progs - initially empty. It is recommended that this is where you develop CLIP programs.

CLIP programs can be efficiently compiled with cpic - a batch file / shell script that lives in bin. There are various versions; one of these is selected when you run the appropriate makeall script as described below. The important thing to note about cpic is that it puts the compiled executable in the bin directory not in the same directory as the source. This is so that CLIP programs are accessible from anywhere once compiled. However, if you prefer to keep executable and source together, you can easily edit the appropriate cpic script in bin. cpic takes the name of the program you are compiling without its extension.

Here is the step-by-step guide to configuring CLIP and its utilities:

1. Get the CLIP distribution and unpack it into the directory structure shown above. Start up a command prompt or terminal window for the system you are using (e.g. an xterm in Linux, a cygwin terminal window or MSDOS command prompt in MS Windows). Change directory to the clip directory that you have just unpacked. NOTE: If you are using .NET, you must start the command prompt through the start menu item Visual Studio .NET Tools. This is required to set up the paths appropriately.
2. Decide how you are going to run CLIP:
   • If on a Mac:
     • If you want image display, you need to run X, and follow step 3.1 below.
     • If you're happy without image display, you can run under Carbon (the normal Mac window system), and follow step 3.2 below.
   • If on Linux:
     • If running X (you probably are), follow step 3.1 below.
     • If not running X, follow step 3.2 below.
   • If on a PC:
     • If you have MS Visual C++ or .NET incorporating C++ and you wish to use that compiler: If you want to develop and compile using the cygwin command line, follow step 3.3 below. If you want to develop and compile using the MSDOS command line, follow step 3.4 below.
     • If you have cygwin and Xfree installed, and want to use the gcc compiler, follow step 3.5 below.
     • If you have cygwin and gcc but no Xfree and no other compiler, you will not be able to display images. Follow step 3.2 below.
3. 1. Copy makeall.xwin to makeall, then run makeall:

      		$ cp makeall.xwin makeall
      		$ makeall
      

   2. Copy makeall.nowin to makeall, then run makeall:

      		$ cp makeall.nowin makeall
      		$ makeall
      

   3. Copy makeall.cygwin_vc to makeall, then run makeall:

      		$ cp makeall.cygwin_vc makeall
      		$ makeall
      

   4. Run the makeall batchfile:

      		C:\some_directory_list\clip> makeall
      

   5. Copy makeall.cygwin_gcc to makeall, then run makeall:

      		$ cp makeall.cygwin_gcc makeall
      		$ makeall
      

4. Wait a few minutes. If you are using gcc (i.e. compiling on Linux or Mac or under gcc in cygwin), there will be no feedback while the package compiles (unless it is going wrong). Don't interrupt makeall or else not everything will get made! makeall sets up cpic in the bin directory so that it is suitable for your chosen configuration. If you decide to change the way you use CLIP in future, you should reconfigure everything by running the appropriate makeall and recompiling all your existing CLIP programs with the new cpic. When makeall finishes running it asks you to edit a configuration file so that the bin directory is in your "PATH": i.e. so that the command interpreter can find CLIP programs. You must make this edit and then start up a new shell or command prompt so that the changes take effect.
5. You can now test your CLIP installation, e.g. by changing directory to the pics subdirectory and typing "di baboon512". If all has gone well you should be looking at a brightly-coloured picture of a baboon or mandrill.

Other documentation

The first three CLIP tutorials as used in my Media ECAD course are:

• Tutorial 1
• Tutorial 2
• Tutorial 3