OpenCV provides utilities for reading from a wide array of image file types as well as from video and cameras. These utilities are part of a toolkit called HighGUI, which is included in the OpenCV package. We will use some of these utilities to create a simple program that opens an image and displays it on the screen. See Example 2-1.
Example 2-1. A simple OpenCV program that loads an image from disk and displays it on the screen
#include "highgui.h"
int main( int argc, char** argv ) {
IplImage* img = cvLoadImage( argv[1] );
cvNamedWindow( "Example1", CV_WINDOW_AUTOSIZE );
cvShowImage( "Example1", img );
cvWaitKey(0);
cvReleaseImage( &img );
cvDestroyWindow( "Example1" );
}When compiled and run from the command line with a single argument, this program loads an image into memory and displays it on the screen. It then waits until the user presses a key, at which time it closes the window and exits. Let's go through the program line by line and take a moment to understand what each command is doing.
IplImage* img = cvLoadImage( argv[1] );
This line loads the image.[10] The function cvLoadImage() is a high-level
routine that determines the file format to be loaded based on the file name; it also
automatically allocates the memory needed for the image data structure. Note that cvLoadImage() can read a wide variety of image formats, including BMP, DIB, JPEG, JPE, PNG, PBM, PGM, PPM, SR, RAS, and TIFF. A
pointer to an allocated image data structure is then returned. This structure, called
IplImage, is the OpenCV construct with which you will
deal the most. OpenCV uses this structure to handle all kinds of images: single-channel,
multichannel, integer-valued, floating-point-valued, et cetera. We use the pointer that
cvLoadImage()returns to manipulate the image and the
image data.
cvNamedWindow( "Example1", CV_WINDOW_AUTOSIZE );
Another high-level function, cvNamedWindow(), opens a
window on the screen that can contain and display an image. This function, provided by the
HighGUI library, also assigns a name to the window (in this case, "Example1"). Future HighGUI calls that interact with this window
will refer to it by this name.
The second argument to cvNamedWindow() defines window
properties. It may be set either to 0 (the default value) or to CV_WINDOW_AUTOSIZE. In the former case, the size of the window
will be the same regardless of the image size, and the image will be scaled to fit within
the window. In the latter case, the window will expand or contract automatically when an
image is loaded so as to accommodate the image's true size.
cvShowImage( "Example1", img );
Whenever we have an image in the form of an IplImage*
pointer, we can display it in an existing window with cvShowImage(). The cvShowImage() function
requires that a named window already exist (created by cvNamedWindow()). On the call to cvShowImage(), the window will be redrawn with the appropriate image in it, and
the window will resize itself as appropriate if it was created using the CV_WINDOW_AUTOSIZE flag.
cvWaitKey(0);
The cvWaitKey()
function asks the program to stop and wait for a keystroke. If a positive argument is given, the program will wait for
that number of milliseconds and then continue even if nothing is pressed. If the argument is
set to 0 or to a negative number, the program will wait indefinitely for a
keypress.
cvReleaseImage( &img );
Once we are through with an image, we can free the allocated memory. OpenCV expects a
pointer to the IplImage* pointer for this operation.
After the call is completed, the pointer img will be set
to NULL.
cvDestroyWindow( "Example1" );
Finally, we can destroy the window itself. The function cvDestroyWindow() will close the window and de-allocate any associated memory
usage (including the window's internal image buffer, which is holding a copy of the pixel
information from *img). For a simple program, you don't
really have to call cvDestroyWindow() or cvReleaseImage() because all the resources and windows of the
application are closed automatically by the operating system upon exit, but it's a good habit anyway.
Now that we have this simple program we can toy around with it in various ways, but we don't want to get ahead of ourselves. Our next task will be to construct a very simple—almost as simple as this one—program to read in and display an AVI video file. After that, we will start to tinker a little more.
[10] A proper program would check for the existence of argv[1] and, in its absence, deliver an instructional error message for the
user. We will abbreviate such necessities in this book and assume that the reader is
cultured enough to understand the importance of error-handling code.