OpenCV  3.0.0-rc1
Open Source Computer Vision
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Groups Pages
Modules | Typedefs | Enumerations | Functions
High-level GUI

Modules

 OpenGL support
 
 Qt New Functions
 
 C API
 

Typedefs

typedef void(* cv::ButtonCallback )(int state, void *userdata)
 
typedef void(* cv::MouseCallback )(int event, int x, int y, int flags, void *userdata)
 
typedef void(* cv::OpenGlDrawCallback )(void *userdata)
 
typedef void(* cv::TrackbarCallback )(int pos, void *userdata)
 

Enumerations

enum  {
  cv::WINDOW_NORMAL = 0x00000000,
  cv::WINDOW_AUTOSIZE = 0x00000001,
  cv::WINDOW_OPENGL = 0x00001000,
  cv::WINDOW_FULLSCREEN = 1,
  cv::WINDOW_FREERATIO = 0x00000100,
  cv::WINDOW_KEEPRATIO = 0x00000000
}
 
enum  {
  cv::WND_PROP_FULLSCREEN = 0,
  cv::WND_PROP_AUTOSIZE = 1,
  cv::WND_PROP_ASPECT_RATIO = 2,
  cv::WND_PROP_OPENGL = 3
}
 
enum  {
  cv::EVENT_MOUSEMOVE = 0,
  cv::EVENT_LBUTTONDOWN = 1,
  cv::EVENT_RBUTTONDOWN = 2,
  cv::EVENT_MBUTTONDOWN = 3,
  cv::EVENT_LBUTTONUP = 4,
  cv::EVENT_RBUTTONUP = 5,
  cv::EVENT_MBUTTONUP = 6,
  cv::EVENT_LBUTTONDBLCLK = 7,
  cv::EVENT_RBUTTONDBLCLK = 8,
  cv::EVENT_MBUTTONDBLCLK = 9,
  cv::EVENT_MOUSEWHEEL = 10,
  cv::EVENT_MOUSEHWHEEL = 11
}
 
enum  {
  cv::EVENT_FLAG_LBUTTON = 1,
  cv::EVENT_FLAG_RBUTTON = 2,
  cv::EVENT_FLAG_MBUTTON = 4,
  cv::EVENT_FLAG_CTRLKEY = 8,
  cv::EVENT_FLAG_SHIFTKEY = 16,
  cv::EVENT_FLAG_ALTKEY = 32
}
 
enum  {
  cv::QT_FONT_LIGHT = 25,
  cv::QT_FONT_NORMAL = 50,
  cv::QT_FONT_DEMIBOLD = 63,
  cv::QT_FONT_BOLD = 75,
  cv::QT_FONT_BLACK = 87
}
 
enum  {
  cv::QT_STYLE_NORMAL = 0,
  cv::QT_STYLE_ITALIC = 1,
  cv::QT_STYLE_OBLIQUE = 2
}
 
enum  {
  cv::QT_PUSH_BUTTON = 0,
  cv::QT_CHECKBOX = 1,
  cv::QT_RADIOBOX = 2
}
 

Functions

int cv::createTrackbar (const String &trackbarname, const String &winname, int *value, int count, TrackbarCallback onChange=0, void *userdata=0)
 Creates a trackbar and attaches it to the specified window. More...
 
void cv::destroyAllWindows ()
 Destroys all of the HighGUI windows. More...
 
void cv::destroyWindow (const String &winname)
 Destroys a window. More...
 
int cv::getMouseWheelDelta (int flags)
 Gets the mouse-wheel motion delta, when handling mouse-wheel events EVENT_MOUSEWHEEL and EVENT_MOUSEHWHEEL. More...
 
int cv::getTrackbarPos (const String &trackbarname, const String &winname)
 Returns the trackbar position. More...
 
double cv::getWindowProperty (const String &winname, int prop_id)
 Provides parameters of a window. More...
 
void cv::imshow (const String &winname, InputArray mat)
 Displays an image in the specified window. More...
 
void cv::moveWindow (const String &winname, int x, int y)
 Moves window to the specified position. More...
 
void cv::namedWindow (const String &winname, int flags=WINDOW_AUTOSIZE)
 Creates a window. More...
 
void cv::resizeWindow (const String &winname, int width, int height)
 Resizes window to the specified size. More...
 
void cv::setMouseCallback (const String &winname, MouseCallback onMouse, void *userdata=0)
 Sets mouse handler for the specified window. More...
 
void cv::setTrackbarMax (const String &trackbarname, const String &winname, int maxval)
 Sets the trackbar maximum position. More...
 
void cv::setTrackbarPos (const String &trackbarname, const String &winname, int pos)
 Sets the trackbar position. More...
 
void cv::setWindowProperty (const String &winname, int prop_id, double prop_value)
 Changes parameters of a window dynamically. More...
 
void cv::setWindowTitle (const String &winname, const String &title)
 Updates window title. More...
 
int cv::startWindowThread ()
 
int cv::waitKey (int delay=0)
 Waits for a pressed key. More...
 

Detailed Description

While OpenCV was designed for use in full-scale applications and can be used within functionally rich UI frameworks (such as Qt*, WinForms*, or Cocoa*) or without any UI at all, sometimes there it is required to try functionality quickly and visualize the results. This is what the HighGUI module has been designed for.

It provides easy interface to:

Typedef Documentation

typedef void(* cv::ButtonCallback)(int state, void *userdata)
typedef void(* cv::MouseCallback)(int event, int x, int y, int flags, void *userdata)
typedef void(* cv::OpenGlDrawCallback)(void *userdata)
typedef void(* cv::TrackbarCallback)(int pos, void *userdata)

Enumeration Type Documentation

anonymous enum
Enumerator
WINDOW_NORMAL 
WINDOW_AUTOSIZE 
WINDOW_OPENGL 
WINDOW_FULLSCREEN 
WINDOW_FREERATIO 
WINDOW_KEEPRATIO 
anonymous enum
Enumerator
WND_PROP_FULLSCREEN 
WND_PROP_AUTOSIZE 
WND_PROP_ASPECT_RATIO 
WND_PROP_OPENGL 
anonymous enum
Enumerator
EVENT_MOUSEMOVE 
EVENT_LBUTTONDOWN 
EVENT_RBUTTONDOWN 
EVENT_MBUTTONDOWN 
EVENT_LBUTTONUP 
EVENT_RBUTTONUP 
EVENT_MBUTTONUP 
EVENT_LBUTTONDBLCLK 
EVENT_RBUTTONDBLCLK 
EVENT_MBUTTONDBLCLK 
EVENT_MOUSEWHEEL 
EVENT_MOUSEHWHEEL 
anonymous enum
Enumerator
EVENT_FLAG_LBUTTON 
EVENT_FLAG_RBUTTON 
EVENT_FLAG_MBUTTON 
EVENT_FLAG_CTRLKEY 
EVENT_FLAG_SHIFTKEY 
EVENT_FLAG_ALTKEY 
anonymous enum
Enumerator
QT_FONT_LIGHT 
QT_FONT_NORMAL 
QT_FONT_DEMIBOLD 
QT_FONT_BOLD 
QT_FONT_BLACK 
anonymous enum
Enumerator
QT_STYLE_NORMAL 
QT_STYLE_ITALIC 
QT_STYLE_OBLIQUE 
anonymous enum
Enumerator
QT_PUSH_BUTTON 
QT_CHECKBOX 
QT_RADIOBOX 

Function Documentation

int cv::createTrackbar ( const String &  trackbarname,
const String &  winname,
int *  value,
int  count,
TrackbarCallback  onChange = 0,
void *  userdata = 0 
)

Creates a trackbar and attaches it to the specified window.

Parameters
trackbarnameName of the created trackbar.
winnameName of the window that will be used as a parent of the created trackbar.
valueOptional pointer to an integer variable whose value reflects the position of the slider. Upon creation, the slider position is defined by this variable.
countMaximal position of the slider. The minimal position is always 0.
onChangePointer to the function to be called every time the slider changes position. This function should be prototyped as 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 the NULL pointer, no callbacks are called, but only value is updated.
userdataUser data that is passed as is to the callback. It can be used to handle trackbar events without using global variables.

The function createTrackbar creates a trackbar (a slider or range control) with the specified name and range, assigns a variable value to be a position synchronized with the trackbar and specifies the callback function onChange to be called on the trackbar position change. The created trackbar is displayed in the specified window winname.

Note

[Qt Backend Only]** winname can be empty (or NULL) if the trackbar should be attached to the control panel.

Clicking the label of each trackbar enables editing the trackbar values manually.

Note
  • An example of using the trackbar functionality can be found at opencv_source_code/samples/cpp/connected_components.cpp
Examples:
contours2.cpp, demhist.cpp, distrans.cpp, edge.cpp, ffilldemo.cpp, fitellipse.cpp, laplace.cpp, morphology2.cpp, and pca.cpp.
void cv::destroyAllWindows ( )

Destroys all of the HighGUI windows.

The function destroyAllWindows destroys all of the opened HighGUI windows.

void cv::destroyWindow ( const String &  winname)

Destroys a window.

Parameters
winnameName of the window to be destroyed.

The function destroyWindow destroys the window with the given name.

Examples:
ffilldemo.cpp, and grabcut.cpp.
int cv::getMouseWheelDelta ( int  flags)

Gets the mouse-wheel motion delta, when handling mouse-wheel events EVENT_MOUSEWHEEL and EVENT_MOUSEHWHEEL.

Parameters
flagsThe mouse callback flags parameter.

For regular mice with a scroll-wheel, delta will be a multiple of 120. The value 120 corresponds to a one notch rotation of the wheel or the threshold for action to be taken and one such action should occur for each delta. Some high-precision mice with higher-resolution freely-rotating wheels may generate smaller values.

For EVENT_MOUSEWHEEL positive and negative values mean forward and backward scrolling, respectively. For EVENT_MOUSEHWHEEL, where available, positive and negative values mean right and left scrolling, respectively.

With the C API, the macro CV_GET_WHEEL_DELTA(flags) can be used alternatively.

Note

Mouse-wheel events are currently supported only on Windows.

int cv::getTrackbarPos ( const String &  trackbarname,
const String &  winname 
)

Returns the trackbar position.

Parameters
trackbarnameName of the trackbar.
winnameName of the window that is the parent of the trackbar.

The function returns the current position of the specified trackbar.

Note

[Qt Backend Only]** winname can be empty (or NULL) if the trackbar is attached to the control panel.

double cv::getWindowProperty ( const String &  winname,
int  prop_id 
)

Provides parameters of a window.

Parameters
winnameName of the window.
prop_idWindow property to retrieve. The following operation flags are available:
  • CV_WND_PROP_FULLSCREEN Change if the window is fullscreen ( CV_WINDOW_NORMAL or CV_WINDOW_FULLSCREEN ).
  • CV_WND_PROP_AUTOSIZE Change if the window is resizable (CV_WINDOW_NORMAL or CV_WINDOW_AUTOSIZE ).
  • CV_WND_PROP_ASPECTRATIO Change if the aspect ratio of the image is preserved (CV_WINDOW_FREERATIO or CV_WINDOW_KEEPRATIO ).

See setWindowProperty to know the meaning of the returned values.

The function getWindowProperty returns properties of a window.

void cv::imshow ( const String &  winname,
InputArray  mat 
)

Displays an image in the specified window.

Parameters
winnameName of the window.
matImage to be shown.

The function imshow displays an image in the specified window. If the window was created with the CV_WINDOW_AUTOSIZE flag, the image is shown with its original size, however it is still limited by the screen resolution. Otherwise, the image is scaled to fit the window. The function may scale the image, depending on its depth:

  • If the image is 8-bit unsigned, it is displayed as is.
  • 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].
  • 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].

If window was created with OpenGL support, imshow also support ogl::Buffer , ogl::Texture2D and cuda::GpuMat as input.

If the window was not created before this function, it is assumed creating a window with CV_WINDOW_AUTOSIZE.

If you need to show an image that is bigger than the screen resolution, you will need to call namedWindow("", WINDOW_NORMAL) before the imshow.

Note
This function should be followed by waitKey function which displays the image for specified milliseconds. Otherwise, it won't display the image. For example, waitKey(0) will display the window infinitely until any keypress (it is suitable for image display). waitKey(25) will display a frame for 25 ms, after which display will be automatically closed. (If you put it in a loop to read videos, it will display the video frame-by-frame)

[Windows Backend Only] Pressing Ctrl+C will copy the image to the clipboard.

Examples:
contours2.cpp, convexhull.cpp, demhist.cpp, distrans.cpp, edge.cpp, ffilldemo.cpp, fitellipse.cpp, grabcut.cpp, houghcircles.cpp, houghlines.cpp, kmeans.cpp, laplace.cpp, lsd_lines.cpp, minarea.cpp, morphology2.cpp, pca.cpp, segment_objects.cpp, and watershed.cpp.
void cv::moveWindow ( const String &  winname,
int  x,
int  y 
)

Moves window to the specified position.

Parameters
winnameWindow name
xThe new x-coordinate of the window
yThe new y-coordinate of the window
void cv::namedWindow ( const String &  winname,
int  flags = WINDOW_AUTOSIZE 
)

Creates a window.

Parameters
winnameName of the window in the window caption that may be used as a window identifier.
flagsFlags of the window. The supported flags are:
  • WINDOW_NORMAL If this is set, the user can resize the window (no constraint).
  • WINDOW_AUTOSIZE If this is set, the window size is automatically adjusted to fit the displayed image (see imshow ), and you cannot change the window size manually.
  • WINDOW_OPENGL If this is set, the window will be created with OpenGL support.

The function namedWindow creates a window that can be used as a placeholder for images and trackbars. Created windows are referred to by their names.

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

You can call destroyWindow or destroyAllWindows to close the window and de-allocate any associated memory usage. For a simple program, you do not really have to call these functions because all the resources and windows of the application are closed automatically by the operating system upon exit.

Note

Qt backend supports additional flags:

  • CV_WINDOW_NORMAL or CV_WINDOW_AUTOSIZE: CV_WINDOW_NORMAL enables you to resize the window, whereas CV_WINDOW_AUTOSIZE adjusts automatically the window size to fit the displayed image (see imshow ), and you cannot change the window size manually.
  • CV_WINDOW_FREERATIO or CV_WINDOW_KEEPRATIO: CV_WINDOW_FREERATIO adjusts the image with no respect to its ratio, whereas CV_WINDOW_KEEPRATIO keeps the image ratio.
  • CV_GUI_NORMAL or CV_GUI_EXPANDED: CV_GUI_NORMAL is the old way to draw the window without statusbar and toolbar, whereas CV_GUI_EXPANDED is a new enhanced GUI. By default, flags == CV_WINDOW_AUTOSIZE | CV_WINDOW_KEEPRATIO | CV_GUI_EXPANDED
Examples:
contours2.cpp, demhist.cpp, distrans.cpp, edge.cpp, ffilldemo.cpp, fitellipse.cpp, grabcut.cpp, laplace.cpp, morphology2.cpp, pca.cpp, segment_objects.cpp, and watershed.cpp.
void cv::resizeWindow ( const String &  winname,
int  width,
int  height 
)

Resizes window to the specified size.

Parameters
winnameWindow name
widthThe new window width
heightThe new window height
Note
  • The specified window size is for the image area. Toolbars are not counted.
  • Only windows created without CV_WINDOW_AUTOSIZE flag can be resized.
void cv::setMouseCallback ( const String &  winname,
MouseCallback  onMouse,
void *  userdata = 0 
)

Sets mouse handler for the specified window.

Parameters
winnameWindow name
onMouseMouse callback. See OpenCV samples, such as https://github.com/Itseez/opencv/tree/master/samples/cpp/ffilldemo.cpp, on how to specify and use the callback.
userdataThe optional parameter passed to the callback.
Examples:
ffilldemo.cpp, grabcut.cpp, and watershed.cpp.
void cv::setTrackbarMax ( const String &  trackbarname,
const String &  winname,
int  maxval 
)

Sets the trackbar maximum position.

Parameters
trackbarnameName of the trackbar.
winnameName of the window that is the parent of trackbar.
maxvalNew maximum position.

The function sets the maximum position of the specified trackbar in the specified window.

Note

[Qt Backend Only]** winname can be empty (or NULL) if the trackbar is attached to the control panel.

void cv::setTrackbarPos ( const String &  trackbarname,
const String &  winname,
int  pos 
)

Sets the trackbar position.

Parameters
trackbarnameName of the trackbar.
winnameName of the window that is the parent of trackbar.
posNew position.

The function sets the position of the specified trackbar in the specified window.

Note

[Qt Backend Only]** winname can be empty (or NULL) if the trackbar is attached to the control panel.

void cv::setWindowProperty ( const String &  winname,
int  prop_id,
double  prop_value 
)

Changes parameters of a window dynamically.

Parameters
winnameName of the window.
prop_idWindow property to edit. The following operation flags are available:
  • CV_WND_PROP_FULLSCREEN Change if the window is fullscreen ( CV_WINDOW_NORMAL or CV_WINDOW_FULLSCREEN ).
  • CV_WND_PROP_AUTOSIZE Change if the window is resizable (CV_WINDOW_NORMAL or CV_WINDOW_AUTOSIZE ).
  • CV_WND_PROP_ASPECTRATIO Change if the aspect ratio of the image is preserved ( CV_WINDOW_FREERATIO or CV_WINDOW_KEEPRATIO ).
prop_valueNew value of the window property. The following operation flags are available:
  • CV_WINDOW_NORMAL Change the window to normal size or make the window resizable.
  • CV_WINDOW_AUTOSIZE Constrain the size by the displayed image. The window is not resizable.
  • CV_WINDOW_FULLSCREEN Change the window to fullscreen.
  • CV_WINDOW_FREERATIO Make the window resizable without any ratio constraints.
  • CV_WINDOW_KEEPRATIO Make the window resizable, but preserve the proportions of the displayed image.

The function setWindowProperty enables changing properties of a window.

void cv::setWindowTitle ( const String &  winname,
const String &  title 
)

Updates window title.

int cv::startWindowThread ( )
int cv::waitKey ( int  delay = 0)

Waits for a pressed key.

Parameters
delayDelay in milliseconds. 0 is the special value that means "forever".

The function waitKey waits for a key event infinitely (when \(\texttt{delay}\leq 0\) ) or for delay milliseconds, when it is positive. Since the OS has a minimum time between switching threads, the function will not wait exactly delay ms, it will wait at least delay ms, depending on what else is running on your computer at that time. It returns the code of the pressed key or -1 if no key was pressed before the specified time had elapsed.

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 an environment that takes care of event processing.

Note

The function only works if there is at least one HighGUI window created and the window is active. If there are several HighGUI windows, any of them can be active.

Examples:
contours2.cpp, convexhull.cpp, demhist.cpp, distrans.cpp, edge.cpp, ffilldemo.cpp, fitellipse.cpp, grabcut.cpp, houghcircles.cpp, houghlines.cpp, kmeans.cpp, laplace.cpp, lsd_lines.cpp, minarea.cpp, morphology2.cpp, pca.cpp, segment_objects.cpp, and watershed.cpp.