opencv/doc/HighGui.tex

   1 While OpenCV was designed for use in full-scale
   2 applications and can be used within functionally rich UI frameworks (such as Qt, WinForms or Cocoa) or without any UI at all, sometimes there is a need to try some functionality quickly and visualize the results. This is what the HighGUI module has been designed for.
   3
   4 It provides easy interface to:
   5 \begin{itemize}
   6     \item create and manipulate windows that can display images and "remember" their content (no need to handle repaint events from OS)
   7     \item add trackbars to the windows, handle simple mouse events as well as keyboard commmands
   8     \item read and write images to/from disk or memory.
   9     \item read video from camera or file and write video to a file.
  10 \end{itemize}
  11
  12 \ifCPy
  13
  14 \section{User Interface}
  15
  16 \ifC
  17 \cvCPyFunc{ConvertImage} % XXX:TBD
  18 Converts one image to another with an optional vertical flip.
  19
  20 \cvdefC{void cvConvertImage( const CvArr* src, CvArr* dst, int flags=0 );}
  21
  22 \begin{description}
  23 \cvarg{src}{Source image.}
  24 \cvarg{dst}{Destination image. Must be single-channel or 3-channel 8-bit image.}
  25 \cvarg{flags}{The operation flags:
  26 \begin{description}
  27 \cvarg{CV\_CVTIMG\_FLIP}{Flips the image vertically}
  28 \cvarg{CV\_CVTIMG\_SWAP\_RB}{Swaps the red and blue channels. In OpenCV color images have \texttt{BGR} channel order, however on some systems the order needs to be reversed before displaying the image (\cross{ShowImage} does this automatically).}
  29 \end{description}}
  30 \end{description}
  31
  32 The function \texttt{cvConvertImage} converts one image to another and flips the result vertically if desired. The function is used by \cross{ShowImage}.
  33
  34 \fi
  35
  36 \cvCPyFunc{CreateTrackbar}
  37 Creates a trackbar and attaches it to the specified window
  38
  39 \cvdefC{
  40 int cvCreateTrackbar( \par const char* trackbarName, \par const char* windowName,
  41                       \par int* value, \par int count, \par CvTrackbarCallback onChange );
  42 }
  43 \cvdefPy{CreateTrackbar(trackbarName, windowName, value, count, onChange) -> None}
  44
  45 \begin{description}
  46 \cvarg{trackbarName}{Name of the created trackbar.}
  47 \cvarg{windowName}{Name of the window which will be used as a parent for created trackbar.}
  48 \ifPy
  49 \cvarg{value}{Initial value for the slider position, between 0 and \texttt{count}.}
  50 \else
  51 \cvarg{value}{Pointer to an integer variable, whose value will reflect the position of the slider. Upon creation, the slider position is defined by this variable.}
  52 \fi
  53 \cvarg{count}{Maximal position of the slider. Minimal position is always 0.}
  54 \ifPy
  55 \cvarg{onChange}{
  56 OpenCV calls \texttt{onChange} every time the slider changes position.
  57 OpenCV will call it as \texttt{func(x)} where \texttt{x} is the new position of the slider.}
  58 \else
  59 \cvarg{onChange}{
  60 Pointer to the function to be called every time the slider changes position.
  61 This function should be prototyped as \texttt{void Foo(int);}  Can be NULL if callback is not required.}
  62 \fi
  63 \end{description}
  64
  65 The function \texttt{cvCreateTrackbar} creates a trackbar (a.k.a. slider or range control) with the specified name and range, assigns a variable to be syncronized with trackbar position and specifies a callback function to be called on trackbar position change. The created trackbar is displayed on the top of the given window.
  66 \ifC
  67 \begin{lstlisting}
  68 CV_EXTERN_C_FUNCPTR( void (*CvTrackbarCallback)(int pos) );
  69 \end{lstlisting}
  70 \fi
  71
  72 \cvCPyFunc{DestroyAllWindows}
  73 Destroys all of the HighGUI windows.
  74
  75 \cvdefC{void cvDestroyAllWindows(void);}
  76 \cvdefPy{DestroyAllWindows()-> None}
  77
  78 The function \texttt{cvDestroyAllWindows} destroys all of the opened HighGUI windows.
  79
  80 \cvCPyFunc{DestroyWindow}
  81 Destroys a window.
  82
  83 \cvdefC{void cvDestroyWindow( const char* name );}
  84 \cvdefPy{DestroyWindow(name)-> None}
  85
  86 \begin{description}
  87 \cvarg{name}{Name of the window to be destroyed.}
  88 \end{description}
  89
  90 The function \texttt{cvDestroyWindow} destroys the window with the given name.
  91
  92 \cvCPyFunc{GetTrackbarPos}
  93 Returns the trackbar position.
  94
  95 \cvdefC{int cvGetTrackbarPos( \par const char* trackbarName, \par const char* windowName );}
  96 \cvdefPy{GetTrackbarPos(trackbarName,windowName)-> None}
  97
  98 \begin{description}
  99 \cvarg{trackbarName}{Name of the trackbar.}
 100 \cvarg{windowName}{Name of the window which is the parent of the trackbar.}
 101 \end{description}
 102
 103 The function \texttt{cvGetTrackbarPos} returns the current position of the specified trackbar.
 104
 105 \ifC
 106
 107 \cvCPyFunc{GetWindowHandle}
 108 Gets the window's handle by its name.
 109
 110 \cvdefC{void* cvGetWindowHandle( const char* name );}
 111
 112 \begin{description}
 113 \cvarg{name}{Name of the window}.
 114 \end{description}
 115
 116 The function \texttt{cvGetWindowHandle} returns the native window handle (HWND in case of Win32 and GtkWidget in case of GTK+).
 117
 118 \cvCPyFunc{GetWindowName}
 119 Gets the window's name by its handle.
 120
 121 \cvdefC{const char* cvGetWindowName( void* windowHandle );}
 122
 123 \begin{description}
 124 \cvarg{windowHandle}{Handle of the window.}
 125 \end{description}
 126
 127 The function \texttt{cvGetWindowName} returns the name of the window given its native handle (HWND in case of Win32 and GtkWidget in case of GTK+).
 128
 129 \cvCPyFunc{InitSystem}
 130 Initializes HighGUI.
 131
 132 \cvdefC{int cvInitSystem( int argc, char** argv );}
 133
 134 \begin{description}
 135 \cvarg{argc}{Number of command line arguments}
 136 \cvarg{argv}{Array of command line arguments}
 137 \end{description}
 138
 139 The function \texttt{cvInitSystem} initializes HighGUI. If it wasn't
 140 called explicitly by the user before the first window was created, it is
 141 called implicitly then with \texttt{argc=0}, \texttt{argv=NULL}. Under
 142 Win32 there is no need to call it explicitly. Under X Window the arguments
 143 may be used to customize a look of HighGUI windows and controls.
 144
 145 \fi
 146
 147 \cvCPyFunc{MoveWindow}
 148 Sets the position of the window.
 149
 150 \cvdefC{void cvMoveWindow( const char* name, int x, int y );}
 151 \cvdefPy{MoveWindow(name,x,y)-> None}
 152
 153 \begin{description}
 154 \cvarg{name}{Name of the window to be moved.}
 155 \cvarg{x}{New x coordinate of the top-left corner}
 156 \cvarg{y}{New y coordinate of the top-left corner}
 157 \end{description}
 158
 159 The function \texttt{cvMoveWindow} changes the position of the window.
 160
 161 \cvCPyFunc{NamedWindow}
 162 Creates a window.
 163
 164 \cvdefC{int cvNamedWindow( const char* name, int flags );}
 165 \cvdefPy{NamedWindow(name,flags=CV\_WINDOW\_AUTOSIZE)-> None}
 166
 167 \begin{description}
 168 \cvarg{name}{Name of the window in the window caption that may be used as a window identifier.}
 169 \cvarg{flags}{Flags of the window. Currently the only supported flag is \texttt{CV\_WINDOW\_AUTOSIZE}. If this is set, window size is automatically adjusted to fit the displayed image (see \cross{ShowImage}), and the user can not change the window size manually.}
 170 \end{description}
 171
 172 The function \texttt{cvNamedWindow} creates a window which can be used as a placeholder for images and trackbars. Created windows are referred to by their names.
 173
 174 If a window with the same name already exists, the function does nothing.
 175
 176 \cvCPyFunc{ResizeWindow}
 177 Sets the window size.
 178
 179 \cvdefC{void cvResizeWindow( const char* name, int width, int height );}
 180 \cvdefPy{ResizeWindow(name,width,height)-> None}
 181
 182 \begin{description}
 183 \cvarg{name}{Name of the window to be resized.}
 184 \cvarg{width}{New width}
 185 \cvarg{height}{New height}
 186 \end{description}
 187
 188 The function \texttt{cvResizeWindow} changes the size of the window.
 189
 190 \cvCPyFunc{SetMouseCallback}
 191 Assigns callback for mouse events.
 192
 193 \cvdefC{void cvSetMouseCallback( const char* windowName, CvMouseCallback onMouse, void* param=NULL );}
 194 \cvdefPy{SetMouseCallback(windowName, onMouse, param) -> None}
 195
 196
 197 \begin{description}
 198 \cvarg{windowName}{Name of the window.}
 199
 200 \ifC  % {
 201 \cvarg{onMouse}{Pointer to the function to be called every time a mouse event occurs in the specified window. This function should be prototyped as
 202 \texttt{void Foo(int event, int x, int y, int flags, void* param);}
 203 where \texttt{event} is one of \texttt{CV\_EVENT\_*}, \texttt{x} and \texttt{y} are the coordinates of the mouse pointer in image coordinates (not window coordinates), \texttt{flags} is a combination of \texttt{CV\_EVENT\_FLAG\_*}, and \texttt{param} is a user-defined parameter passed to the \texttt{cvSetMouseCallback} function call.}
 204 \else % }{
 205 \cvarg{onMouse}{Callable to be called every time a mouse event occurs in the specified window. This callable should have signature
 206 \texttt{ Foo(event, x, y, flags, param)-> None }
 207 where \texttt{event} is one of \texttt{CV\_EVENT\_*}, \texttt{x} and \texttt{y} are the coordinates of the mouse pointer in image coordinates (not window coordinates), \texttt{flags} is a combination of \texttt{CV\_EVENT\_FLAG\_*}, and \texttt{param} is a user-defined parameter passed to the \texttt{cvSetMouseCallback} function call.}
 208 \fi   % }
 209
 210 \cvarg{param}{User-defined parameter to be passed to the callback function.}
 211 \end{description}
 212
 213 The function \texttt{cvSetMouseCallback} sets the callback function for mouse events occuring within the specified window.
 214
 215 The \texttt{event} parameter is one of:
 216
 217 \begin{description}
 218 \cvarg{CV\_EVENT\_MOUSEMOVE}{Mouse movement}
 219 \cvarg{CV\_EVENT\_LBUTTONDOWN}{Left button down}
 220 \cvarg{CV\_EVENT\_RBUTTONDOWN}{Right button down}
 221 \cvarg{CV\_EVENT\_MBUTTONDOWN}{Middle button down}
 222 \cvarg{CV\_EVENT\_LBUTTONUP}{Left button up}
 223 \cvarg{CV\_EVENT\_RBUTTONUP}{Right button up}
 224 \cvarg{CV\_EVENT\_MBUTTONUP}{Middle button up}
 225 \cvarg{CV\_EVENT\_LBUTTONDBLCLK}{Left button double click}
 226 \cvarg{CV\_EVENT\_RBUTTONDBLCLK}{Right button double click}
 227 \cvarg{CV\_EVENT\_MBUTTONDBLCLK}{Middle button double click}
 228 \end{description}
 229
 230 The \texttt{flags} parameter is a combination of :
 231
 232 \begin{description}
 233 \cvarg{CV\_EVENT\_FLAG\_LBUTTON}{Left button pressed}
 234 \cvarg{CV\_EVENT\_FLAG\_RBUTTON}{Right button pressed}
 235 \cvarg{CV\_EVENT\_FLAG\_MBUTTON}{Middle button pressed}
 236 \cvarg{CV\_EVENT\_FLAG\_CTRLKEY}{Control key pressed}
 237 \cvarg{CV\_EVENT\_FLAG\_SHIFTKEY}{Shift key pressed}
 238 \cvarg{CV\_EVENT\_FLAG\_ALTKEY}{Alt key pressed}
 239 \end{description}
 240
 241 \cvCPyFunc{SetTrackbarPos}
 242 Sets the trackbar position.
 243
 244 \cvdefC{void cvSetTrackbarPos( \par const char* trackbarName, \par const char* windowName, \par int pos );}
 245 \cvdefPy{SetTrackbarPos(trackbarName,windowName,pos)-> None}
 246
 247 \begin{description}
 248 \cvarg{trackbarName}{Name of the trackbar.}
 249 \cvarg{windowName}{Name of the window which is the parent of trackbar.}
 250 \cvarg{pos}{New position.}
 251 \end{description}
 252
 253 The function \texttt{cvSetTrackbarPos} sets the position of the specified trackbar.
 254
 255 \cvCPyFunc{ShowImage}
 256 Displays the image in the specified window
 257
 258 \cvdefC{void cvShowImage( const char* name, const CvArr* image );}
 259 \cvdefPy{ShowImage(name,image)-> None}
 260
 261 \begin{description}
 262 \cvarg{name}{Name of the window.}
 263 \cvarg{image}{Image to be shown.}
 264 \end{description}
 265
 266 The function \texttt{cvShowImage} displays the image in the specified window. If the window was created with the \texttt{CV\_WINDOW\_AUTOSIZE} flag then the image is shown with its original size, otherwise the image is scaled to fit in the window. The function may scale the image, depending on its depth:
 267 \begin{itemize}
 268     \item If the image is 8-bit unsigned, it is displayed as is.
 269     \item If the image is 16-bit unsigned or 32-bit integer, the pixels are divided by 256. That is, the value range [0,255*256] is mapped to [0,255].
 270     \item If the image is 32-bit floating-point, the pixel values are multiplied by 255. That is, the value range [0,1] is mapped to [0,255].
 271 \end{itemize}
 272
 273 \cvCPyFunc{WaitKey}
 274 Waits for a pressed key.
 275
 276 \cvdefC{int cvWaitKey( int delay=0 );}
 277 \cvdefPy{WaitKey(delay=0)-> int}
 278
 279 \begin{description}
 280 \cvarg{delay}{Delay in milliseconds.}
 281 \end{description}
 282
 283 The function \texttt{cvWaitKey} waits for key event infinitely ($ \texttt{delay} <= 0$) or for \texttt{delay} milliseconds. Returns the code of the pressed key or -1 if no key was pressed before the specified time had elapsed.
 284
 285 \textbf{Note:} This function is the only method in HighGUI that can 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.
 286
 287
 288 \section{Reading and Writing Images and Video}
 289
 290 \cvCPyFunc{LoadImage}
 291 Loads an image from a file as an IplImage.
 292
 293 \cvdefC{
 294 IplImage* cvLoadImage( \par const char* filename, \par int iscolor=CV\_LOAD\_IMAGE\_COLOR );}
 295 \cvdefPy{LoadImage(filename, iscolor=CV\_LOAD\_IMAGE\_COLOR)->None}
 296
 297 \begin{description}
 298 \cvarg{filename}{Name of file to be loaded.}
 299 \cvarg{iscolor}{Specific color type of the loaded image:
 300 \begin{description}
 301 \cvarg{CV\_LOAD\_IMAGE\_COLOR}{the loaded image is forced to be a 3-channel color image}
 302 \cvarg{CV\_LOAD\_IMAGE\_GRAYSCALE}{the loaded image is forced to be grayscale}
 303 \cvarg{CV\_LOAD\_IMAGE\_UNCHANGED}{the loaded image will be loaded as is.}
 304 \end{description}
 305 }
 306 \end{description}
 307
 308 The function \texttt{cvLoadImage} loads an image from the specified file and returns the pointer to the loaded image. Currently the following file formats are supported:
 309 \begin{itemize}
 310 \item Windows bitmaps - BMP, DIB
 311 \item JPEG files - JPEG, JPG, JPE
 312 \item Portable Network Graphics - PNG
 313 \item Portable image format - PBM, PGM, PPM
 314 \item Sun rasters - SR, RAS
 315 \item TIFF files - TIFF, TIF
 316 \end{itemize}
 317
 318 Note that in the current implementation the alpha channel, if any, is stripped from the output image, e.g. 4-channel RGBA image will be loaded as RGB.
 319
 320 \cvCPyFunc{LoadImageM}
 321 Loads an image from a file as a CvMat.
 322
 323 \cvdefC{
 324 CvMat* cvLoadImageM( \par const char* filename, \par int iscolor=CV\_LOAD\_IMAGE\_COLOR );}
 325 \cvdefPy{LoadImageM(filename, iscolor=CV\_LOAD\_IMAGE\_COLOR)->None}
 326
 327 \begin{description}
 328 \cvarg{filename}{Name of file to be loaded.}
 329 \cvarg{iscolor}{Specific color type of the loaded image:
 330 \begin{description}
 331 \cvarg{CV\_LOAD\_IMAGE\_COLOR}{the loaded image is forced to be a 3-channel color image}
 332 \cvarg{CV\_LOAD\_IMAGE\_GRAYSCALE}{the loaded image is forced to be grayscale}
 333 \cvarg{CV\_LOAD\_IMAGE\_UNCHANGED}{the loaded image will be loaded as is.}
 334 \end{description}
 335 }
 336 \end{description}
 337
 338 The function \texttt{cvLoadImageM} loads an image from the specified file and returns the pointer to the loaded image.
 339 urrently the following file formats are supported:
 340 \begin{itemize}
 341 \item Windows bitmaps - BMP, DIB
 342 \item JPEG files - JPEG, JPG, JPE
 343 \item Portable Network Graphics - PNG
 344 \item Portable image format - PBM, PGM, PPM
 345 \item Sun rasters - SR, RAS
 346 \item TIFF files - TIFF, TIF
 347 \end{itemize}
 348
 349 Note that in the current implementation the alpha channel, if any, is stripped from the output image, e.g. 4-channel RGBA image will be loaded as RGB.
 350
 351 \cvCPyFunc{SaveImage}
 352 Saves an image to a specified file.
 353
 354 \cvdefC{int cvSaveImage( const char* filename, const CvArr* image );}
 355 \cvdefPy{SaveImage(filename,image)-> None}
 356
 357 \begin{description}
 358 \cvarg{filename}{Name of the file.}
 359 \cvarg{image}{Image to be saved.}
 360 \end{description}
 361
 362 The function \texttt{cvSaveImage} saves the image to the specified file. The image format is chosen based on the \texttt{filename} extension, see \cross{LoadImage}. 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 \texttt{cvCvtScale} and \texttt{cvCvtColor} to convert it before saving, or use universal \texttt{cvSave} to save the image to XML or YAML format.
 363
 364
 365 \cvclass{CvCapture}\label{CvCapture}
 366 Video capturing structure.
 367
 368 \cvdefC{typedef struct CvCapture CvCapture;}
 369
 370 The structure \texttt{CvCapture} does not have a public interface and is used only as a parameter for video capturing functions.
 371
 372 \cvCPyFunc{CaptureFromCAM} % XXX:Called cvCreateCameraCapture in manual
 373 Initializes capturing a video from a camera.
 374
 375 \cvdefC{CvCapture* cvCaptureFromCAM( int index );}
 376 \cvdefPy{CaptureFromCAM(index) -> CvCapture}
 377
 378 \begin{description}
 379 \cvarg{index}{Index of the camera to be used. If there is only one camera or it does not matter what camera is used -1 may be passed.}
 380 \end{description}
 381
 382 The function \texttt{cvCaptureFromCAM} allocates and initializes 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).
 383
 384 To release the structure, use \cross{ReleaseCapture}.
 385
 386
 387 \cvCPyFunc{CaptureFromFile} % XXX:Called cvCreateFileCapture in manual
 388 Initializes capturing a video from a file.
 389
 390 \cvdefC{CvCapture* cvCaptureFromFile( const char* filename );}
 391 \cvdefPy{CaptureFromFile(filename) -> CvCapture}
 392
 393 \begin{description}
 394 \cvarg{filename}{Name of the video file.}
 395 \end{description}
 396
 397 The function \texttt{cvCaptureFromFile} allocates and initializes the CvCapture structure for reading the video stream from the specified file. Which codecs and file formats are supported depends on the back end library. On Windows HighGui uses Video for Windows (VfW), on Linux ffmpeg is used and on Mac OS X the back end is QuickTime. See VideoCodecs for some discussion on what to expect and how to prepare your video files.
 398
 399 After the allocated structure is not used any more it should be released by the \cross{ReleaseCapture} function.
 400
 401 \cvCPyFunc{GetCaptureProperty}
 402 Gets video capturing properties.
 403
 404 \cvdefC{double cvGetCaptureProperty( CvCapture* capture, int property\_id );}
 405 \cvdefPy{GetCaptureProperty(capture, property\_id)->double}
 406
 407 \begin{description}
 408 \cvarg{capture}{video capturing structure.}
 409 \cvarg{property\_id}{Property identifier. Can be one of the following:
 410 \begin{description}
 411 \cvarg{CV\_CAP\_PROP\_POS\_MSEC}{Film current position in milliseconds or video capture timestamp}
 412 \cvarg{CV\_CAP\_PROP\_POS\_FRAMES}{0-based index of the frame to be decoded/captured next}
 413 \cvarg{CV\_CAP\_PROP\_POS\_AVI\_RATIO}{Relative position of the video file (0 - start of the film, 1 - end of the film)}
 414 \cvarg{CV\_CAP\_PROP\_FRAME\_WIDTH}{Width of the frames in the video stream}
 415 \cvarg{CV\_CAP\_PROP\_FRAME\_HEIGHT}{Height of the frames in the video stream}
 416 \cvarg{CV\_CAP\_PROP\_FPS}{Frame rate}
 417 \cvarg{CV\_CAP\_PROP\_FOURCC}{4-character code of codec}
 418 \cvarg{CV\_CAP\_PROP\_FRAME\_COUNT}{Number of frames in the video file}
 419 \cvarg{CV\_CAP\_PROP\_BRIGHTNESS}{Brightness of the image (only for cameras)}
 420 \cvarg{CV\_CAP\_PROP\_CONTRAST}{Contrast of the image (only for cameras)}
 421 \cvarg{CV\_CAP\_PROP\_SATURATION}{Saturation of the image (only for cameras)}
 422 \cvarg{CV\_CAP\_PROP\_HUE}{Hue of the image (only for cameras)}
 423 \end{description} }
 424 \end{description}
 425
 426 The function \texttt{cvGetCaptureProperty} retrieves the specified property of the camera or video file.
 427
 428 \cvCPyFunc{GrabFrame}
 429 Grabs the frame from a camera or file.
 430
 431 \cvdefC{int cvGrabFrame( CvCapture* capture );}
 432 \cvdefPy{GrabFrame(capture) -> int}
 433
 434 \begin{description}
 435 \cvarg{capture}{video capturing structure.}
 436 \end{description}
 437
 438 The function \texttt{cvGrabFrame} grabs the frame from a camera or file. The grabbed frame is stored internally. The purpose of this function is to grab the frame \emph{quickly} so that syncronization can occur if it has to read from several cameras simultaneously. The grabbed frames are not exposed because they may be stored in a compressed format (as defined by the camera/driver). To retrieve the grabbed frame, \cross{RetrieveFrame} should be used.
 439
 440
 441 \cvCPyFunc{QueryFrame}
 442 Grabs and returns a frame from a camera or file.
 443
 444 \cvdefC{IplImage* cvQueryFrame( CvCapture* capture );}
 445 \cvdefPy{QueryFrame(capture) -> iplimage}
 446
 447 \begin{description}
 448 \cvarg{capture}{video capturing structure.}
 449 \end{description}
 450
 451 The function \texttt{cvQueryFrame} grabs a frame from a camera or video file, decompresses it and returns it. This function is just a combination of \cross{GrabFrame} and \cross{RetrieveFrame}, but in one call. The returned image should not be released or modified by the user.  In the event of an error, the return value may be NULL.
 452
 453 \ifC
 454 \cvCPyFunc{ReleaseCapture}
 455 Releases the CvCapture structure.
 456
 457 \cvdefC{void cvReleaseCapture( CvCapture** capture );}
 458
 459 \begin{description}
 460 \cvarg{capture}{Pointer to video the capturing structure.}
 461 \end{description}
 462
 463 The function \texttt{cvReleaseCapture} releases the CvCapture structure allocated by \cross{CaptureFromFile} or \cross{CaptureFromCAM}.
 464 \fi
 465
 466 \cvCPyFunc{RetrieveFrame} % XXX:Different than manual
 467 Gets the image grabbed with cvGrabFrame.
 468
 469 \cvdefC{IplImage* cvRetrieveFrame( CvCapture* capture );}
 470 \cvdefPy{RetrieveFrame(capture) -> iplimage}
 471
 472 \begin{description}
 473 \cvarg{capture}{video capturing structure.}
 474 \end{description}
 475
 476 The function \texttt{cvRetrieveFrame} returns the pointer to the image grabbed with the \cross{GrabFrame} function. The returned image should not be released or modified by the user.  In the event of an error, the return value may be NULL.
 477
 478
 479 \cvCPyFunc{SetCaptureProperty}
 480 Sets video capturing properties.
 481
 482 \cvdefC{int cvSetCaptureProperty( \par CvCapture* capture, \par int property\_id, \par double value );}
 483 \cvdefPy{SetCaptureProperty(capture, property\_id,value)->None}
 484
 485 \begin{description}
 486 \cvarg{capture}{video capturing structure.}
 487 \cvarg{property\_id}{property identifier. Can be one of the following:
 488
 489 \begin{description}
 490 \cvarg{CV\_CAP\_PROP\_POS\_MSEC}{Film current position in milliseconds or video capture timestamp}
 491 \cvarg{CV\_CAP\_PROP\_POS\_FRAMES}{0-based index of the frame to be decoded/captured next}
 492 \cvarg{CV\_CAP\_PROP\_POS\_AVI\_RATIO}{Relative position of the video file (0 - start of the film, 1 - end of the film)}
 493 \cvarg{CV\_CAP\_PROP\_FRAME\_WIDTH}{Width of the frames in the video stream}
 494 \cvarg{CV\_CAP\_PROP\_FRAME\_HEIGHT}{Height of the frames in the video stream}
 495 \cvarg{CV\_CAP\_PROP\_FPS}{Frame rate}
 496 \cvarg{CV\_CAP\_PROP\_FOURCC}{4-character code of codec}
 497 \cvarg{CV\_CAP\_PROP\_BRIGHTNESS}{Brightness of the image (only for cameras)}
 498 \cvarg{CV\_CAP\_PROP\_CONTRAST}{Contrast of the image (only for cameras)}
 499 \cvarg{CV\_CAP\_PROP\_SATURATION}{Saturation of the image (only for cameras)}
 500 \cvarg{CV\_CAP\_PROP\_HUE}{Hue of the image (only for cameras)}
 501 \end{description} }
 502
 503 \cvarg{value}{value of the property.}
 504 \end{description}
 505
 506 The function \texttt{cvSetCaptureProperty} sets the specified property of video capturing. Currently the function supports only video files: \texttt{CV\_CAP\_PROP\_POS\_MSEC, CV\_CAP\_PROP\_POS\_FRAMES, CV\_CAP\_PROP\_POS\_AVI\_RATIO}.
 507
 508 NB This function currently does nothing when using the latest CVS download on linux with FFMPEG (the function contents are hidden if 0 is used and returned).
 509
 510
 511 \cvCPyFunc{CreateVideoWriter} % XXX Different than manual
 512 Creates the video file writer.
 513
 514 \cvdefC{
 515 typedef struct CvVideoWriter CvVideoWriter;
 516 CvVideoWriter* cvCreateVideoWriter( \par const char* filename, \par int fourcc, \par double fps, \par CvSize frame\_size, \par int is\_color=1 );
 517 }\cvdefPy{CreateVideoWriter(filename, fourcc, fps, frame\_size, is\_color) -> CvVideoWriter}
 518
 519 \begin{description}
 520 \cvarg{filename}{Name of the output video file.}
 521 \cvarg{fourcc}{4-character code of codec used to compress the frames. For example,
 522 \texttt{CV\_FOURCC('P','I','M,'1')} is a MPEG-1 codec,
 523 \texttt{CV\_FOURCC('M','J','P','G')} is a motion-jpeg codec etc.
 524 Under Win32 it is possible to pass -1 in order to choose compression method and additional compression parameters from dialog. Under Win32 if 0 is passed while using an avi filename it will create a video writer that creates an uncompressed avi file.}
 525 \cvarg{fps}{Framerate of the created video stream.}
 526 \cvarg{frame\_size}{Size of the  video frames.}
 527 \cvarg{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).}
 528 \end{description}
 529
 530 The function \texttt{cvCreateVideoWriter} creates the video writer structure.
 531
 532 Which codecs and file formats are supported depends on the back end library. On Windows HighGui uses Video for Windows (VfW), on Linux ffmpeg is used and on Mac OS X the back end is QuickTime. See VideoCodecs for some discussion on what to expect.
 533
 534
 535 \ifC
 536 \cvCPyFunc{ReleaseVideoWriter}
 537 Releases the AVI writer.
 538
 539 \cvdefC{void cvReleaseVideoWriter( CvVideoWriter** writer );}
 540
 541 \begin{description}
 542 \cvarg{writer}{Pointer to the video file writer structure.}
 543 \end{description}
 544
 545 The function \texttt{cvReleaseVideoWriter} finishes writing to the video file and releases the structure.
 546 \fi
 547
 548
 549 \cvCPyFunc{WriteFrame}
 550 Writes a frame to a video file.
 551
 552 \cvdefC{int cvWriteFrame( CvVideoWriter* writer, const IplImage* image );}
 553 \cvdefPy{WriteFrame(writer, image)->int}
 554
 555 \begin{description}
 556 \cvarg{writer}{Video writer structure}
 557 \cvarg{image}{The written frame}
 558 \end{description}
 559
 560 The function \texttt{cvWriteFrame} writes/appends one frame to a video file.
 561
 562 \fi
 563
 564 \ifCpp
 565
 566 \section{User Interface}
 567
 568 \cvCppFunc{createTrackbar}
 569 Creates a trackbar and attaches it to the specified window
 570
 571 \cvdefCpp{int createTrackbar( const string\& trackbarname,\par
 572                     const string\& winname,\par
 573                     int* value, int count,\par
 574                     TrackbarCallback onChange CV\_DEFAULT(0),\par
 575                     void* userdata CV\_DEFAULT(0));}
 576 \begin{description}
 577 \cvarg{trackbarname}{Name of the created trackbar.}
 578 \cvarg{winname}{Name of the window which will be used as a parent of the created trackbar.}
 579 \cvarg{value}{The optional pointer to an integer variable, whose value will reflect the position of the slider. Upon creation, the slider position is defined by this variable.}
 580 \cvarg{count}{The maximal position of the slider. The minimal position is always 0.}
 581 \cvarg{onChange}{Pointer to the function to be called every time the slider changes position. This function should be prototyped as \texttt{void Foo(int,void*);}, where the first parameter is the trackbar position and the second parameter is the user data (see the next parameter). If the callback is NULL pointer, then no callbacks is called, but only \texttt{value} is updated}
 582 \cvarg{userdata}{The user data that is passed as-is to the callback; it can be used to handle trackbar events without using global variables}
 583 \end{description}
 584
 585 The function \texttt{createTrackbar} creates a trackbar (a.k.a. slider or range control) with the specified name and range, assigns a variable \texttt{value} to be syncronized with trackbar position and specifies a callback function \texttt{onChange} to be called on the trackbar position change. The created trackbar is displayed on the top of the given window.
 586
 587 \cvCppFunc{getTrackbarPos}
 588 Returns the trackbar position.
 589
 590 \cvdefCpp{int getTrackbarPos( const string\& trackbarname, \par const string\& winname );}
 591 \begin{description}
 592 \cvarg{trackbarname}{Name of the trackbar.}
 593 \cvarg{winname}{Name of the window which is the parent of the trackbar.}
 594 \end{description}
 595
 596 The function returns the current position of the specified trackbar.
 597
 598
 599 \cvCppFunc{imshow}
 600 Displays the image in the specified window
 601
 602 \cvdefCpp{void imshow( const string\& winname, \par const Mat\& image );}
 603 \begin{description}
 604 \cvarg{winname}{Name of the window.}
 605 \cvarg{image}{Image to be shown.}
 606 \end{description}
 607
 608 The function \texttt{imshow} displays the image in the specified window. If the window was created with the \texttt{CV\_WINDOW\_AUTOSIZE} flag then the image is shown with its original size, otherwise the image is scaled to fit in the window. The function may scale the image, depending on its depth:
 609 \begin{itemize}
 610     \item If the image is 8-bit unsigned, it is displayed as is.
 611     \item If the image is 16-bit unsigned or 32-bit integer, the pixels are divided by 256. That is, the value range [0,255*256] is mapped to [0,255].
 612     \item If the image is 32-bit floating-point, the pixel values are multiplied by 255. That is, the value range [0,1] is mapped to [0,255].
 613 \end{itemize}
 614
 615
 616 \cvCppFunc{namedWindow}
 617 Creates a window.
 618
 619 \cvdefCpp{void namedWindow( const string\& winname, \par int flags );}
 620 \begin{description}
 621 \cvarg{name}{Name of the window in the window caption that may be used as a window identifier.}
 622 \cvarg{flags}{Flags of the window. Currently the only supported flag is \texttt{CV\_WINDOW\_AUTOSIZE}. If this is set, the window size is automatically adjusted to fit the displayed image (see \cross{imshow}), and the user can not change the window size manually.}
 623 \end{description}
 624
 625 The function \texttt{namedWindow} creates a window which can be used as a placeholder for images and trackbars. Created windows are referred to by their names.
 626
 627 If a window with the same name already exists, the function does nothing.
 628
 629 \cvCppFunc{setTrackbarPos}
 630 Sets the trackbar position.
 631
 632 \cvdefCpp{void setTrackbarPos( const string\& trackbarname, \par const string\& winname, int pos );}
 633 \begin{description}
 634 \cvarg{trackbarname}{Name of the trackbar.}
 635 \cvarg{winname}{Name of the window which is the parent of trackbar.}
 636 \cvarg{pos}{The new position.}
 637 \end{description}
 638
 639 The function sets the position of the specified trackbar in the specified window.
 640
 641
 642 \cvCppFunc{waitKey}
 643 Waits for a pressed key.
 644
 645 \cvdefCpp{int waitKey(int delay=0);}
 646 \begin{description}
 647 \cvarg{delay}{Delay in milliseconds. 0 is the special value that means "forever"}
 648 \end{description}
 649
 650 The function \texttt{waitKey} waits for key event infinitely (when $\texttt{delay}\leq 0$) or for \texttt{delay} milliseconds, when it's positive. Returns the code of the pressed key or -1 if no key was pressed before the specified time had elapsed.
 651
 652 \textbf{Note:} This function is the only method in HighGUI that can 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.
 653
 654 \section{Reading and Writing Images and Video}
 655
 656 \cvCppFunc{imdecode}
 657 Reads an image from a buffer in memory.
 658 \cvdefCpp{Mat imdecode( const Mat\& buf, \par int flags );}
 659 \begin{description}
 660 \cvarg{buf}{The input array of vector of bytes}
 661 \cvarg{flags}{The same flags as in \cross{imread}}
 662 \end{description}
 663
 664 The function reads image from the specified buffer in memory.
 665 If the buffer is too short or contains invalid data, the empty matrix will be returned.
 666
 667 See \cross{imread} for the list of supported formats and the flags description.
 668
 669 \cvCppFunc{imencode}
 670 Encode an image into a memory buffer.
 671 \cvdefCpp{bool imencode( const string\& ext,\par
 672                const Mat\& img,\par
 673                vector<uchar>\& buf,\par
 674                const vector<int>\& params=vector<int>());}
 675 \begin{description}
 676 \cvarg{ext}{The file extension that defines the output format}
 677 \cvarg{img}{The image to be written}
 678 \cvarg{buf}{The output buffer; resized to fit the compressed image}
 679 \cvarg{params}{The format-specific parameters; see \cross{imwrite}}
 680 \end{description}
 681
 682 The function compresses the image and stores it in the memory buffer, which is resized to fit the result.
 683 See \cross{imwrite} for the list of supported formats and the flags description.
 684
 685
 686 \cvCppFunc{imread}
 687 Loads an image from a file.
 688
 689 \cvdefCpp{Mat imread( const string\& filename, \par int flags=1 );}
 690
 691 \begin{description}
 692 \cvarg{filename}{Name of file to be loaded.}
 693 \cvarg{flags}{Specifies color type of the loaded image:}
 694 \begin{description}
 695     \cvarg{>0}{the loaded image is forced to be a 3-channel color image}
 696     \cvarg{=0}{the loaded image is forced to be grayscale}
 697     \cvarg{<0}{the loaded image will be loaded as-is (note that in the current implementation the alpha channel, if any, is stripped from the output image, e.g. 4-channel RGBA image will be loaded as RGB if $flags\ge0$).}
 698 \end{description}
 699 \end{description}
 700
 701 The function \texttt{imread} loads an image from the specified file and returns it. If the image can not be read (because of missing file, improper permissions, unsupported or invalid format), the function returns empty matrix (\texttt{Mat::data==NULL}).Currently, the following file formats are supported:
 702 \begin{itemize}
 703 \item Windows bitmaps - \texttt{*.bmp, *.dib} (always supported)
 704 \item JPEG files - \texttt{*.jpeg, *.jpg, *.jpe} (see \textbf{Note2})
 705 \item JPEG 2000 files - \texttt{*.jp2} (see \textbf{Note2})
 706 \item Portable Network Graphics - \texttt{*.png}  (see \textbf{Note2})
 707 \item Portable image format - \texttt{*.pbm, *.pgm, *.ppm} (always supported)
 708 \item Sun rasters - \texttt{*.sr, *.ras} (always supported)
 709 \item TIFF files - \texttt{*.tiff, *.tif}  (see \textbf{Note2})
 710 \end{itemize}
 711
 712 \textbf{Note1}: The function determines type of the image by the content, not by the file extension.
 713
 714 \textbf{Note2}: On Windows and MacOSX the shipped with OpenCV image codecs (libjpeg, libpng, libtiff and libjasper) are used by default; so OpenCV can always read JPEGs, PNGs and TIFFs. On MacOSX there is also the option to use native MacOSX image readers. But beware that currently these native image loaders give images with somewhat different pixel values, because of the embedded into MacOSX color management.
 715
 716 On Linux, BSD flavors and other Unix-like open-source operating systems OpenCV looks for the supplied with OS image codecs. Please, install the relevant packages (do not forget the development files, e.g. "libjpeg-dev" etc. in Debian and Ubuntu) in order to get the codec support, or turn on \texttt{OPENCV\_BUILD\_3RDPARTY\_LIBS} flag in CMake.
 717
 718 \cvCppFunc{imwrite}
 719 Saves an image to a specified file.
 720
 721 \cvdefCpp{bool imwrite( const string\& filename, \par const Mat\& img,\par
 722               const vector<int>\& params=vector<int>());}
 723 \begin{description}
 724 \cvarg{filename}{Name of the file.}
 725 \cvarg{img}{The image to be saved.}
 726 \cvarg{params}{The format-specific save parameters, encoded as pairs \texttt{paramId\_1, paramValue\_1, paramId\_2, paramValue\_2, ...}. The following parameters are currently supported:
 727 \begin{itemize}
 728     \item In the case of JPEG it can be a quality (\texttt{CV\_IMWRITE\_JPEG\_QUALITY}), from 0 to 100 (the higher is the better), 95 by default.
 729     \item In the case of PNG it can be the compression level (\texttt{CV\_IMWRITE\_PNG\_COMPRESSION}), from 0 to 9 (the higher value means smaller size and longer compression time), 3 by default.
 730     \item In the case of PPM, PGM or PBM it can a binary format flag (\texttt{CV\_IMWRITE\_PXM\_BINARY}), 0 or 1, 1 by default.
 731 \end{itemize}
 732     }
 733 \end{description}
 734
 735 The function \texttt{imwrite} saves the image to the specified file. The image format is chosen based on the \texttt{filename} extension, see \cross{imread} for the list of extensions. Only 8-bit (or 16-bit in the case of PNG, JPEG 2000 and TIFF) 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 \cross{Mat::convertTo}, and \cross{cvtColor} to convert it before saving, or use the universal XML I/O functions to save the image to XML or YAML format.
 736
 737
 738 \cvclass{VideoCapture}
 739 Class for video capturing from video files or cameras
 740
 741 \begin{lstlisting}
 742 class VideoCapture
 743 {
 744 public:
 745     // the default constructor
 746     VideoCapture();
 747     // the constructor that opens video file
 748     VideoCapture(const string& filename);
 749     // the constructor that starts streaming from the camera
 750     VideoCapture(int device);
 751
 752     // the destructor
 753     virtual ~VideoCapture();
 754
 755     // opens the specified video file
 756     virtual bool open(const string& filename);
 757
 758     // starts streaming from the specified camera by its id
 759     virtual bool open(int device);
 760
 761     // returns true if the file was open successfully or if the camera
 762     // has been initialized succesfully
 763     virtual bool isOpened() const;
 764
 765     // closes the camera stream or the video file
 766     // (automatically called by the destructor)
 767     virtual void release();
 768
 769     // grab the next frame or a set of frames from a multi-head camera;
 770     // returns false if there are no more frames
 771     virtual bool grab();
 772     // reads the frame from the specified video stream
 773     // (non-zero channel is only valid for multi-head camera live streams)
 774     virtual bool retrieve(Mat& image, int channel=0);
 775     // equivalent to grab() + retrieve(image, 0);
 776     virtual VideoCapture& operator >> (Mat& image);
 777
 778     // sets the specified property propId to the specified value
 779     virtual bool set(int propId, double value);
 780     // retrieves value of the specified property
 781     virtual double get(int propId);
 782
 783 protected:
 784     ...
 785 };
 786 \end{lstlisting}
 787
 788 The class provides C++ video capturing API. Here is how the class can be used:
 789
 790 \begin{lstlisting}
 791 #include "cv.h"
 792 #include "highgui.h"
 793
 794 using namespace cv;
 795
 796 int main(int, char**)
 797 {
 798     VideoCapture cap(0); // open the default camera
 799     if(!cap.isOpened())  // check if we succeeded
 800         return -1;
 801
 802     Mat edges;
 803     namedWindow("edges",1);
 804     for(;;)
 805     {
 806         Mat frame;
 807         cap >> frame; // get a new frame from camera
 808         cvtColor(frame, edges, CV_BGR2GRAY);
 809         GaussianBlur(edges, edges, Size(7,7), 1.5, 1.5);
 810         Canny(edges, edges, 0, 30, 3);
 811         imshow("edges", edges);
 812         if(waitKey(30) >= 0) break;
 813     }
 814     // the camera will be deinitialized automatically in VideoCapture destructor
 815     return 0;
 816 }
 817 \end{lstlisting}
 818
 819
 820 \cvclass{VideoWriter}
 821 Video writer class
 822
 823 \begin{lstlisting}
 824 class VideoWriter
 825 {
 826 public:
 827     // default constructor
 828     VideoWriter();
 829     // constructor that calls open
 830     VideoWriter(const string& filename, int fourcc,
 831                 double fps, Size frameSize, bool isColor=true);
 832
 833     // the destructor
 834     virtual ~VideoWriter();
 835
 836     // opens the file and initializes the video writer.
 837     // filename - the output file name.
 838     // fourcc - the codec
 839     // fps - the number of frames per second
 840     // frameSize - the video frame size
 841     // isColor - specifies whether the video stream is color or grayscale
 842     virtual bool open(const string& filename, int fourcc,
 843                       double fps, Size frameSize, bool isColor=true);
 844
 845     // returns true if the writer has been initialized successfully
 846     virtual bool isOpened() const;
 847
 848     // writes the next video frame to the stream
 849     virtual VideoWriter& operator << (const Mat& image);
 850
 851 protected:
 852     ...
 853 };
 854 \end{lstlisting}
 855
 856 \fi
 857