HighGUI Reference Manual

Simple GUI
Loading and Saving Images
Video I/O
Utility and System Functions
Alphabetical List of Functions

Simple GUI

cvNamedWindow

Creates window

int cvNamedWindow( const char* name, int flags=CV_WINDOW_AUTOSIZE );

name: Name of the window which is used as window identifier and appears in the window caption.
flags: Flags of the window. Currently the only supported flag is CV_WINDOW_AUTOSIZE. If it is set, window size is automatically adjusted to fit the displayed image (see cvShowImage), while user can not change the window size manually.

The function cvNamedWindow creates a window which can be used as a placeholder for images and trackbars. Created windows are reffered by their names.

If the window with such a name already exists, the function does nothing.

cvDestroyWindow

Destroys a window

void cvDestroyWindow( const char* name );

name: Name of the window to be destroyed.

The function cvDestroyWindow destroys the window with a given name.

cvDestroyAllWindows

Destroys all the HighGUI windows

void cvDestroyAllWindows(void);

The function cvDestroyAllWindows destroys all the opened HighGUI windows.

cvResizeWindow

Sets window size

void cvResizeWindow( const char* name, int width, int height );

name: Name of the window to be resized.
width: New width
height: New height

The function cvResizeWindow changes size of the window.

cvMoveWindow

Sets window position

void cvMoveWindow( const char* name, int x, int y );

name: Name of the window to be resized.
x: New x coordinate of top-left corner
y: New y coordinate of top-left corner

The function cvMoveWindow changes position of the window.

cvGetWindowHandle

Gets window handle by name

void* cvGetWindowHandle( const char* name );

name: Name of the window.

The function cvGetWindowHandle returns native window handle (HWND in case of Win32 and GtkWidget in case of GTK+).

cvGetWindowName

Gets window name by handle

const char* cvGetWindowName( void* window_handle );

window_handle: Handle of the window.

The function cvGetWindowName returns the name of window given its native handle (HWND in case of Win32 and GtkWidget in case of GTK+).

cvShowImage

Shows the image in the specified window

void cvShowImage( const char* name, const CvArr* image );

name: Name of the window.
image: Image to be shown.

The function cvShowImage shows the image in the specified window. If the window was created with CV_WINDOW_AUTOSIZE flag then the image is shown with its original size, otherwise the image is scaled to fit the window.

cvCreateTrackbar

Creates the trackbar and attaches it to the specified window

CV_EXTERN_C_FUNCPTR( void (*CvTrackbarCallback)(int pos) );

int cvCreateTrackbar( const char* trackbar_name, const char* window_name,
                      int* value, int count, CvTrackbarCallback on_change );

trackbar_name: Name of created trackbar.
window_name: Name of the window which will e used as a parent for created trackbar.
value: Pointer to the integer variable, which value will reflect the position of the slider. Upon the creation the slider position is defined by this variable.
count: Maximal position of the slider. Minimal position is always 0.
on_change: Pointer to the function to be called every time the slider changes the position. This function should be prototyped as void Foo(int);Can be NULL if callback is not required.

The function cvCreateTrackbar creates the trackbar (a.k.a. slider or range control) with the specified name and range, assigns the variable to be syncronized with trackbar position and specifies callback function to be called on trackbar position change. The created trackbar is displayed on top of given window.

cvGetTrackbarPos

Retrieves trackbar position

int cvGetTrackbarPos( const char* trackbar_name, const char* window_name );

trackbar_name: Name of trackbar.
window_name: Name of the window which is the parent of trackbar.

The function cvGetTrackbarPos returns the ciurrent position of the specified trackbar.

cvSetTrackbarPos

Sets trackbar position

void cvSetTrackbarPos( const char* trackbar_name, const char* window_name, int pos );

trackbar_name: Name of trackbar.
window_name: Name of the window which is the parent of trackbar.
pos: New position.

The function cvSetTrackbarPos sets the position of the specified trackbar.

cvSetMouseCallback

Assigns callback for mouse events

#define CV_EVENT_MOUSEMOVE      0
#define CV_EVENT_LBUTTONDOWN    1
#define CV_EVENT_RBUTTONDOWN    2
#define CV_EVENT_MBUTTONDOWN    3
#define CV_EVENT_LBUTTONUP      4
#define CV_EVENT_RBUTTONUP      5
#define CV_EVENT_MBUTTONUP      6
#define CV_EVENT_LBUTTONDBLCLK  7
#define CV_EVENT_RBUTTONDBLCLK  8
#define CV_EVENT_MBUTTONDBLCLK  9

#define CV_EVENT_FLAG_LBUTTON   1
#define CV_EVENT_FLAG_RBUTTON   2
#define CV_EVENT_FLAG_MBUTTON   4
#define CV_EVENT_FLAG_CTRLKEY   8
#define CV_EVENT_FLAG_SHIFTKEY  16
#define CV_EVENT_FLAG_ALTKEY    32

CV_EXTERN_C_FUNCPTR( void (*CvMouseCallback )(int event, int x, int y, int flags, void* param) );

void cvSetMouseCallback( const char* window_name, CvMouseCallback on_mouse, void* param=NULL );

window_name

Name of the window.

on_mouse

Pointer to the function to be called every time mouse event occurs in the specified window. This function should be prototyped as

void Foo(int event, int x, int y, int flags, void* param);

where event is one of CV_EVENT_*, x and y are coordinates of mouse pointer in image coordinates (not window coordinates), flags is a combination of CV_EVENT_FLAG, and param is a user-defined parameter passed to the cvSetMouseCallback function call.

param

User-defined parameter to be passed to the callback function.

The function cvSetMouseCallback sets the callback function for mouse events occuting within the specified window. To see how it works, look at opencv/samples/c/ffilldemo.c demo

cvWaitKey

Waits for a pressed key

int cvWaitKey( int delay=0 );

delay: Delay in milliseconds.

The function cvWaitKey waits for key event infinitely (delay<=0) or for "delay" milliseconds. Returns the code of the pressed key or -1 if no key were pressed until the specified timeout has elapsed.

Note: This function is the only method in HighGUI to fetch and handle events so it needs to be called periodically for normal event processing, unless HighGUI is used within some environment that takes care of event processing.

Loading and Saving Images

cvLoadImage

Loads an image from file

/* 8 bit, color or gray - deprecated, use CV_LOAD_IMAGE_ANYCOLOR */
#define CV_LOAD_IMAGE_UNCHANGED  -1
/* 8 bit, gray */
#define CV_LOAD_IMAGE_GRAYSCALE   0
/* 8 bit unless combined with CV_LOAD_IMAGE_ANYDEPTH, color */
#define CV_LOAD_IMAGE_COLOR       1
/* any depth, if specified on its own gray */
#define CV_LOAD_IMAGE_ANYDEPTH    2
/* by itself equivalent to CV_LOAD_IMAGE_UNCHANGED
   but can be modified with CV_LOAD_IMAGE_ANYDEPTH */
#define CV_LOAD_IMAGE_ANYCOLOR    4

IplImage* cvLoadImage( const char* filename, int flags=CV_LOAD_IMAGE_COLOR );

filename: Name of file to be loaded.
flags: Specifies colorness and depth of the loaded image:
The colorness specifies whether the loaded image is to be converted to 3 channels (CV_LOAD_IMAGE_COLOR), 1 channel (CV_LOAD_IMAGE_GRAYSCALE), or left as it was in the input file (CV_LOAD_IMAGE_ANYCOLOR).
Depth specifies whether the loaded image is to be converted to 8 bits per pixel per color channel as was customary in previous versions of OpenCV or left as they were in the input file. If CV_LOAD_IMAGE_ANYDEPTH is passed the pixel format can be 8 bit unsigned, 16 bit unsigned, 32 bit signed or 32 bit floating point.
If conflicting flags are passed the flag with the smaller numerical value wins. That is if CV_LOAD_IMAGE_COLOR | CV_LOAD_IMAGE_ANYCOLOR is passed the image is loaded with 3 channels. CV_LOAD_IMAGE_ANYCOLOR is equivalent to specifying CV_LOAD_IMAGE_UNCHANGED. However, CV_LOAD_IMAGE_ANYCOLOR has the advantage that it can be combined with CV_LOAD_IMAGE_ANYDEPTH. So CV_LOAD_IMAGE_UNCHANGED should not be used any longer.
If you want to load the image as truthfully as possible pass CV_LOAD_IMAGE_ANYDEPTH | CV_LOAD_IMAGE_ANYCOLOR.

The function cvLoadImage loads an image from the specified file and returns the pointer to the loaded image. Currently the following file formats are supported:

Windows bitmaps - BMP, DIB;
JPEG files - JPEG, JPG, JPE;
Portable Network Graphics - PNG;
Portable image format - PBM, PGM, PPM;
Sun rasters - SR, RAS;
TIFF files - TIFF, TIF;
OpenEXR HDR images - EXR;
JPEG 2000 images - jp2.

cvSaveImage

Saves an image to the file

int cvSaveImage( const char* filename, const CvArr* image );

filename: Name of the file.
image: Image to be saved.

The function cvSaveImage saves the image to the specified file. The image format is chosen depending on the filename extension, see cvLoadImage. Only 8-bit single-channel or 3-channel (with 'BGR' channel order) images can be saved using this function. If the format, depth or channel order is different, use cvCvtScale and cvCvtColor to convert it before saving, or use universal cvSave to save the image to XML or YAML format.

Video I/O functions

CvCapture

Video capturing structure

typedef struct CvCapture CvCapture;

The structure CvCapture does not have public interface and is used only as a parameter for video capturing functions.

cvCreateFileCapture

Initializes capturing video from file

CvCapture* cvCreateFileCapture( const char* filename );

filename: Name of the video file.

The function cvCreateFileCapture allocates and initialized the CvCapture structure for reading the video stream from the specified file.

After the allocated structure is not used any more it should be released by cvReleaseCapture function.

cvCreateCameraCapture

Initializes capturing video from camera

CvCapture* cvCreateCameraCapture( int index );

index: Index of the camera to be used. If there is only one camera or it does not matter what camera to use -1 may be passed.

The function cvCreateCameraCapture allocates and initialized the CvCapture structure for reading a video stream from the camera. Currently two camera interfaces can be used on Windows: Video for Windows (VFW) and Matrox Imaging Library (MIL); and two on Linux: V4L and FireWire (IEEE1394).

To release the sturtcure, use cvReleaseCapture.

cvReleaseCapture

Releases the CvCapture structure

void cvReleaseCapture( CvCapture** capture );

capture: pointer to video capturing structure.

The function cvReleaseCapture releases the CvCapture structure allocated by cvCreateFileCapture or cvCreateCameraCapture.

cvGrabFrame

Grabs frame from camera or file

int cvGrabFrame( CvCapture* capture );

capture: video capturing structure.

The function cvGrabFrame grabs the frame from camera or file. The grabbed frame is stored internally. The purpose of this function is to grab frame fast that is important for syncronization in case of reading from several cameras simultaneously. The grabbed frames are not exposed because they may be stored in compressed format (as defined by camera/driver). To retrieve the grabbed frame, cvRetrieveFrame should be used.

cvRetrieveFrame

Gets the image grabbed with cvGrabFrame

IplImage* cvRetrieveFrame( CvCapture* capture );

capture: video capturing structure.

The function cvRetrieveFrame returns the pointer to the image grabbed with cvGrabFrame function. The returned image should not be released or modified by user.

cvQueryFrame

Grabs and returns a frame from camera or file

IplImage* cvQueryFrame( CvCapture* capture );

capture: video capturing structure.

The function cvQueryFrame grabs a frame from camera or video file, decompresses and returns it. This function is just a combination of cvGrabFrame and cvRetrieveFrame in one call. The returned image should not be released or modified by user.

cvGetCaptureProperty

Gets video capturing properties

double cvGetCaptureProperty( CvCapture* capture, int property_id );

capture: video capturing structure.
property_id: property identifier. Can be one of the following:
CV_CAP_PROP_POS_MSEC - film current position in milliseconds or video capture timestamp
CV_CAP_PROP_POS_FRAMES - 0-based index of the frame to be decoded/captured next
CV_CAP_PROP_POS_AVI_RATIO - relative position of video file (0 - start of the film, 1 - end of the film)
CV_CAP_PROP_FRAME_WIDTH - width of frames in the video stream
CV_CAP_PROP_FRAME_HEIGHT - height of frames in the video stream
CV_CAP_PROP_FPS - frame rate
CV_CAP_PROP_FOURCC - 4-character code of codec. CV_CAP_PROP_FRAME_COUNT - number of frames in video file.

The function cvGetCaptureProperty retrieves the specified property of camera or video file.

cvSetCaptureProperty

Sets video capturing properties

int cvSetCaptureProperty( CvCapture* capture, int property_id, double value );

capture: video capturing structure.
property_id: property identifier. Can be one of the following:
CV_CAP_PROP_POS_MSEC - position in milliseconds from the file beginning
CV_CAP_PROP_POS_FRAMES - position in frames (only for video files)
CV_CAP_PROP_POS_AVI_RATIO - position in relative units (0 - start of the file, 1 - end of the file)
CV_CAP_PROP_FRAME_WIDTH - width of frames in the video stream (only for cameras)
CV_CAP_PROP_FRAME_HEIGHT - height of frames in the video stream (only for cameras)
CV_CAP_PROP_FPS - frame rate (only for cameras)
CV_CAP_PROP_FOURCC - 4-character code of codec (only for cameras).
value: value of the property.

The function cvSetCaptureProperty sets the specified property of video capturing. Currently the function supports only video files: CV_CAP_PROP_POS_MSEC, CV_CAP_PROP_POS_FRAMES, CV_CAP_PROP_POS_AVI_RATIO

cvCreateVideoWriter

Creates video file writer

typedef struct CvVideoWriter CvVideoWriter;
CvVideoWriter* cvCreateVideoWriter( const char* filename, int fourcc, double fps, CvSize frame_size, int is_color=1 );

filename: Name of the output video file.
fourcc: 4-character code of codec used to compress the frames. For example, CV_FOURCC('P','I','M','1') is MPEG-1 codec, CV_FOURCC('M','J','P','G') is motion-jpeg codec etc. Under Win32 it is possible to pass -1 in order to choose compression method and additional compression parameters from dialog.
fps: Framerate of the created video stream.
frame_size: Size of video frames.
is_color: If it is not zero, the encoder will expect and encode color frames, otherwise it will work with grayscale frames (the flag is currently supported on Windows only).

The function cvCreateVideoWriter creates video writer structure.

cvReleaseVideoWriter

Releases AVI writer

void cvReleaseVideoWriter( CvVideoWriter** writer );

writer: pointer to video file writer structure.

The function cvReleaseVideoWriter finishes writing to video file and releases the structure.

cvWriteFrame

Writes a frame to video file

int cvWriteFrame( CvVideoWriter* writer, const IplImage* image );

writer: video writer structure.
image: the written frame

The function cvWriteFrame writes/appends one frame to video file.

Utility and System Functions

cvInitSystem

Initializes HighGUI

int cvInitSystem( int argc, char** argv );

argc: Number of command line arguments.
argv: Array of command line arguments

The function cvInitSystem initializes HighGUI. If it wasn't called explicitly by the user before the first window is created, it is called implicitly then with argc=0, argv=NULL. Under Win32 there is no need to call it explicitly. Under X Window the arguments may be used to customize a look of HighGUI windows and controls.

cvConvertImage

Converts one image to another with optional vertical flip

void cvConvertImage( const CvArr* src, CvArr* dst, int flags=0 );

src: Source image.
dst: Destination image. Must be single-channel or 3-channel 8-bit image.
flags: The operation flags:
CV_CVTIMG_FLIP - flip the image vertically CV_CVTIMG_SWAP_RB - swap red and blue channels. In OpenCV color images have BGR channel order, however on some systems the order needs to be reversed before displaying the image (cvShowImage does this automatically).

The function cvConvertImage converts one image to another and flips the result vertically if required. The function is used by cvShowImage.

Alphabetical List of Functions

C

ConvertImage	CreateFileCapture	CreateVideoWriter
CreateCameraCapture	CreateTrackbar

D

DestroyAllWindows

DestroyWindow

G

GetCaptureProperty	GetWindowHandle	GrabFrame
GetTrackbarPos	GetWindowName

R

ReleaseCapture	ResizeWindow
ReleaseVideoWriter	RetrieveFrame

S

SaveImage	SetMouseCallback	ShowImage
SetCaptureProperty	SetTrackbarPos

W

WaitKey

WriteFrame