GUI and Video Acquisition Reference

Window functions
Image handling functions
Video I/O functions
Support/system functions

Window functions

cvNamedWindow

Creates a window (image placeholder)

int cvNamedWindow( const char* name, unsigned long flags );

name: Name of the window which is used as window identifier and appears in the window caption.
flags: Defines window properties. Currently the only supported property is ability to automatically change the window size to fit the image being hold by the window. Use CV_WINDOW_AUTOSIZE for enabling the automatical resizing or 0 otherwise.

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

cvDestroyWindow

Destroys a window

void cvDestroyWindow( const char* name );

name: Name of the window to be destroyed.

The function cvDestroyWindow destroyes the window with the given name.

cvResizeWindow

Sets window sizes

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 the sizes 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 Widget in case of X Window).

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 Widget in case of X 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 be 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(slider) 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) );

HIGHGUI_API void cvSetMouseCallback( const char* window_name, CvMouseCallback on_mouse );

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);

where event is one of CV_EVENT_*, x and y are coordinates of mouse pointer in image coordinates (not window coordinates) and flags is a combination of CV_EVENT_FLAG.

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

Image handling functions

cvLoadImage

Loads an image from file

IplImage* cvLoadImage( const char* filename, int iscolor CV_DEFAULT(1));

filename: Name of file to be loaded.
iscolor: If >0, the loaded image will always have 3 channels;; if 0, the loaded image will always have 1 channel;; if <0, the loaded image will be loaded as is (with number of channels depends on the file).

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.

If "filename" does not contain full path, the file is searched in the current directory and in directories specified by cvAddSearchPath

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.

cvShowImage

Shows the image in the specified window

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

name: Name of the window to attach the image to.
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 will be shown with its original size otherwise the image will be scaled to fit the window.

cvConvertImage

Converts one image to another with optional vertical flip

void cvConvertImage( const CvArr* src, CvArr* dst, int flip CV_DEFAULT(0));

src

Source image.

dst: Destination image.
flip: 1 - to flip image vertically,; 0 - not to flip.

The function cvConvertImage converts one image to another and flips the result vertically if required. This function does the same conversions as cvCvtColor function, but do this automatically accordingly to formats of input and output images.

Video I/O functions

CvCapture

Structure for getting video from camera or AVI file

typedef struct CvCapture CvCapture;

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

cvCaptureFromAVI

Allocates CvCapture structure binds it to the specified AVI file

CvCapture* cvCaptureFromAVI( const char* filename );

filename: Name of the AVI file.

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

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

cvCaptureFromCAM

Allocates CvCapture structure and binds it to the video camera

CvCapture* cvCaptureFromCAM( 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 cvCaptureFromCAM allocates and initialized the CvCapture structure for reading a video stream from the camera. Currently two camera interfaces can be used: Video for Windows (VFW) and Matrox Imaging Library (MIL). To connect to VFW camera the parameter "index" should be in range 0-10, to connect to MIL camera the parameter "index" should be in range 100-115. If -1 is passed then the function searches for VFW camera first and then for MIL camera.

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

cvReleaseCapture

Releases the CvCapture structure

void cvReleaseCapture( CvCapture** capture );

capture: Address of the pointer to CvCapture structure to be released.

The function cvReleaseCapture releases the CvCapture structure allocated by cvCaptureFromAVI or cvCaptureFromCAM.

cvGrabFrame

Grabs frame from camera or AVI

int cvGrabFrame( CvCapture* capture );

capture: CvCapture representing camera or AVI file.

The function cvGrabFrame grabs the frame from camera or AVI. The grabbed frame is stored internally. The purpose of this function is to grab frame fast what 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 get access to the grabbed frame cvGrabFrame should be followed by cvRetrieveFrame.

cvRetrieveFrame

Gets the image grabbed with cvGrabFrame

IplImage* cvRetrieveFrame( CvCapture* capture );

capture: CvCapture representing camera or AVI file.

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

cvQueryFrame

Grabs and returns a frame from camera or AVI

IplImage* cvQueryFrame( CvCapture* capture );

capture: CvCapture representing camera or AVI file.

The function cvQueryFrame grabs a frame from camera or AVI and returns the pointer to grabbed image. Actually this function just successively calls cvGrabFrame and cvRetrieveFrame. The returned image should not be released by the user.

cvGetCaptureProperty

Gets camera/AVI properties

double cvGetCaptureProperty( CvCapture* capture, int property_id );

capture: CvCapture representing camera or AVI file.
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 AVI 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 AVI file.

The function cvGetCaptureProperty retrieves the specified property of camera or AVI.

cvSetCaptureProperty

Sets camera/AVI properties

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

capture: CvCapture representing camera or AVI file.
property_id: property identifier. Can be one of the following:; CV_CAP_PROP_POS_MSEC - (only for AVI)
CV_CAP_PROP_POS_MSEC - set position (only for AVIs)
CV_CAP_PROP_POS_FRAMES - set position (only for AVIs)
CV_CAP_PROP_POS_AVI_RATIO - set position (only for AVIs)
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.
value: value of the property.

The function cvSetCaptureProperty sets the specified property of camera or AVI. Currently the function works only for setting some AVI properties: CV_CAP_PROP_POS_MSEC, CV_CAP_PROP_POS_FRAMES, CV_CAP_PROP_POS_AVI_RATIO

cvCreateAVIWriter

Creates AVI writer

typedef struct CvAVIWriter CvAVIWriter;
CvAVIWriter* cvCreateAVIWriter( const char* filename, int fourcc, double fps, CvSize frameSize )

filename: Name of AVI file to be written to. If file does not exist it is created.
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.
frameSize: Size of the frames of AVI file.

The function cvCreateAVIWriter allocates and initializes the hidden structure CvAVIWriter that is used for writing AVI files frame by frame.

NOTE: Writing to AVIs works under Win32 only

cvReleaseAVIWriter

Releases AVI writer

void cvReleaseAVIWriter( CvAVIWriter** writer );

writer: address of pointer to the released CvAVIWriter structure.

The function cvReleaseAVIWriter closes the AVI file being written and deallocates the memory used by CvAVIWriter structure.

cvWriteToAVI

Writes a frame to AVI file

int cvWriteToAVI( CvAVIWriter* writer, const IplImage* image );

writer: Pointer to CvAVIWriter structure.
image: Frame to be written/appended to AVI file

The function cvWriteToAVI writes/appends one frame to AVI file binded to "writer".

Support/system functions

cvInitSystem

Initializes HighGUI

void 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 are used for creating Application Shell that is a standard way to define a look of HighGUI windows and controls.

cvWaitKey

Waits for pressed key

int cvWaitKey(int delay CV_DEFAULT(0));

delay: Delay in milliseconds.

The function cvWaitKey waits for key event infinitely (delay<=0) or for "delay" milliseconds. Returns the code of pressed key or -1 if key was not 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.

cvAddSearchPath

Adds the specified path to the list of search paths;

/* add folder to the image search path (used by cvLoadImage) */
void cvAddSearchPath( const char* path );

path: Path to add to the search list.

The function cvAddSearchPath adds the specified folder to the search path list. The search path list is used by cvLoadImage function.