# GUI and Video Acquisition Reference

- Window functions
  - NamedWindow
  - DestroyWindow
  - ResizeWindow
  - GetWindowHandle
  - GetWindowName
  - CreateTrackbar
  - GetTrackbarPos
  - SetTrackbarPos
  - SetMouseCallback
- Image handling functions
  - LoadImage
  - SaveImage
  - ShowImage
  - ConvertImage
- Video I/O functions
  - CvCapture
  - CaptureFromAVI
  - CaptureFromCAM
  - ReleaseCapture
  - GrabFrame
  - RetrieveFrame
  - QueryFrame
  - GetCaptureProperty
  - SetCaptureProperty
  - CreateAVIWriter
  - ReleaseAVIWriter
  - WriteToAVI
- Support/system functions
  - InitSystem
  - WaitKey
  - AddSearchPath

## HighGUI overview

TODO

## 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.