| OpenCV 5.0.0alpha Open Source Computer Vision

Loading...
Searching...
No Matches
Topics | Typedefs | Functions
High-level GUI

## Topics
| Flags related creating and manipulating HighGUI windows and mouse events
| OpenGL support
| Qt New Functions
| WinRT support

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

- Create and manipulate windows that can display images and "remember" their content (no need to handle repaint events from OS).
- Add trackbars to the windows, handle simple mouse events as well as keyboard commands.

## Typedefs
typedef void(* | cv::ButtonCallback) (int state, void *userdata)
| Callback function for a button created by cv::createButton.
typedef void(* | cv::MouseCallback) (int event, int x, int y, int flags, void *userdata)
| Callback function for mouse events. see cv::setMouseCallback.
typedef void(* | cv::OpenGlDrawCallback) (void *userdata)
| Callback function defined to be called every frame. See cv::setOpenGlDrawCallback.
typedef void(* | cv::TrackbarCallback) (int pos, void *userdata)
| Callback function for Trackbar see cv::createTrackbar.

## 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.
const std::string | cv::currentUIFramework ()
| HighGUI backend used.
void | cv::destroyAllWindows ()
| Destroys all of the HighGUI windows.
void | cv::destroyWindow (const String &winname)
| Destroys the specified window.
int | cv::getMouseWheelDelta (int flags)
| Gets the mouse-wheel motion delta, when handling mouse-wheel events cv::EVENT_MOUSEWHEEL and cv::EVENT_MOUSEHWHEEL.
int | cv::getTrackbarPos (const String &trackbarname, const String &winname)
| Returns the trackbar position.
Rect | cv::getWindowImageRect (const String &winname)
| Provides rectangle of image in the window.
double | cv::getWindowProperty (const String &winname, int prop_id)
| Provides parameters of a window.
void | cv::imshow (const String &winname, InputArray mat)
| Displays an image in the specified window.
void | cv::moveWindow (const String &winname, int x, int y)
| Moves the window to the specified position.
void | cv::namedWindow (const String &winname, int flags=WINDOW_AUTOSIZE)
| Creates a window.
int | cv::pollKey ()
| Polls for a pressed key.
void | cv::resizeWindow (const String &winname, const cv::Size &size)
void | cv::resizeWindow (const String &winname, int width, int height)
| Resizes the window to the specified size.
Rect | cv::selectROI (const String &windowName, InputArray img, bool showCrosshair=true, bool fromCenter=false, bool printNotice=true)
| Allows users to select a ROI on the given image.
Rect | cv::selectROI (InputArray img, bool showCrosshair=true, bool fromCenter=false, bool printNotice=true)
void | cv::selectROIs (const String &windowName, InputArray img, std::vector< Rect > &boundingBoxes, bool showCrosshair=true, bool fromCenter=false, bool printNotice=true)
| Allows users to select multiple ROIs on the given image.
void | cv::setMouseCallback (const String &winname, MouseCallback onMouse, void *userdata=0)
| Sets mouse handler for the specified window.
void | cv::setTrackbarMax (const String &trackbarname, const String &winname, int maxval)
| Sets the trackbar maximum position.
void | cv::setTrackbarMin (const String &trackbarname, const String &winname, int minval)
| Sets the trackbar minimum position.
void | cv::setTrackbarPos (const String &trackbarname, const String &winname, int pos)
| Sets the trackbar position.
void | cv::setWindowProperty (const String &winname, int prop_id, double prop_value)
| Changes parameters of a window dynamically.
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.
int | cv::waitKeyEx (int delay=0)
| Similar to waitKey, but returns full key code.

## Typedef Documentation

## ◆ ButtonCallback

typedef void(* cv::ButtonCallback) (int state, void *userdata)

`#include <opencv2/highgui.hpp>`

Callback function for a button created by cv::createButton.

Parameters

  state | current state of the button. It could be -1 for a push button, 0 or 1 for a check/radio box button.
  userdata | The optional parameter.

## ◆ MouseCallback

typedef void(* cv::MouseCallback) (int event, int x, int y, int flags, void *userdata)

`#include <opencv2/highgui.hpp>`

Callback function for mouse events. see cv::setMouseCallback.

Parameters

  event | one of the cv::MouseEventTypes constants.
  x | The x-coordinate of the mouse event.
  y | The y-coordinate of the mouse event.
  flags | one of the cv::MouseEventFlags constants.
  userdata | The optional parameter.

## ◆ OpenGlDrawCallback

typedef void(* cv::OpenGlDrawCallback) (void *userdata)

`#include <opencv2/highgui.hpp>`

Callback function defined to be called every frame. See cv::setOpenGlDrawCallback.

Parameters

  userdata | The optional parameter.

## ◆ TrackbarCallback

typedef void(* cv::TrackbarCallback) (int pos, void *userdata)

`#include <opencv2/highgui.hpp>`

Callback function for Trackbar see cv::createTrackbar.

Parameters

  pos | current position of the specified trackbar.
  userdata | The optional parameter.

## Function Documentation

## ◆ createTrackbar()

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

`#include <opencv2/highgui.hpp>`

Creates a trackbar and attaches it to the specified window.

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 if the trackbar should be attached to the control panel.

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

Parameters

  trackbarname | Name of the created trackbar.
  winname | Name of the window that will be used as a parent of the created trackbar.
  value | Optional pointer to an integer variable whose value reflects the position of the slider. Upon creation, the slider position is defined by this variable.
  count | Maximal position of the slider. The minimal position is always 0.
  onChange | Pointer 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.
  userdata | User data that is passed as is to the callback. It can be used to handle trackbar events without using global variables.

## ◆ currentUIFramework()

const std::string cv::currentUIFramework | ( |  | ) |

Python:
| cv.currentUIFramework( |  | ) -> | retval

`#include <opencv2/highgui.hpp>`

HighGUI backend used.

The function returns HighGUI backend name used: could be COCOA, GTK2/3, QT, WAYLAND or WIN32. Returns empty string if there is no available UI backend.

## ◆ destroyAllWindows()

void cv::destroyAllWindows | ( |  | ) |

Python:
| cv.destroyAllWindows( |  | ) -> | None

`#include <opencv2/highgui.hpp>`

Destroys all of the HighGUI windows.

The function destroyAllWindows destroys all of the opened HighGUI windows.

## ◆ destroyWindow()

void cv::destroyWindow | ( | const String & | winname | ) |

Python:
| cv.destroyWindow( | winname | ) -> | None

`#include <opencv2/highgui.hpp>`

Destroys the specified window.

The function destroyWindow destroys the window with the given name.

Parameters

  winname | Name of the window to be destroyed.

## ◆ getMouseWheelDelta()

int cv::getMouseWheelDelta | ( | int | flags | ) |

`#include <opencv2/highgui.hpp>`

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

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 cv::EVENT_MOUSEWHEEL positive and negative values mean forward and backward scrolling, respectively. For cv::EVENT_MOUSEHWHEEL, where available, positive and negative values mean right and left scrolling, respectively.

Note
  Mouse-wheel events are currently supported only on Windows and Cocoa.

Parameters

  flags | The mouse callback flags parameter.

## ◆ getTrackbarPos()

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

Python:
| cv.getTrackbarPos( | trackbarname, winname | ) -> | retval

`#include <opencv2/highgui.hpp>`

Returns the trackbar position.

The function returns the current position of the specified trackbar.

Note
  [Qt Backend Only] winname can be empty if the trackbar is attached to the control panel.

Parameters

  trackbarname | Name of the trackbar.
  winname | Name of the window that is the parent of the trackbar.

## ◆ getWindowImageRect()

Rect cv::getWindowImageRect | ( | const String & | winname | ) |

Python:
| cv.getWindowImageRect( | winname | ) -> | retval

`#include <opencv2/highgui.hpp>`

Provides rectangle of image in the window.

The function getWindowImageRect returns the client screen coordinates, width and height of the image rendering area.

Parameters

  winname | Name of the window.

See also
  resizeWindow moveWindow

Note
  [Wayland Backend Only] This function is not supported by the Wayland protocol limitation.

## ◆ getWindowProperty()

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

Python:
| cv.getWindowProperty( | winname, prop_id | ) -> | retval

`#include <opencv2/highgui.hpp>`

Provides parameters of a window.

The function getWindowProperty returns properties of a window.

Parameters

  winname | Name of the window.
  prop_id | Window property to retrieve. The following operation flags are available: (cv::WindowPropertyFlags)

See also
  setWindowProperty

Note
  [Wayland Backend Only] This function is not supported.

## ◆ imshow()

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

Python:
| cv.imshow( | winname, mat | ) -> | None

`#include <opencv2/highgui.hpp>`

Displays an image in the specified window.

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, 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 or 64-bit floating-point, the pixel values are multiplied by 255. That is, the value range [0,1] is mapped to [0,255].
- 32-bit integer images are not processed anymore due to ambiguouty of required transform. Convert to 8-bit unsigned matrix using a custom preprocessing specific to image's context.

If window was created with OpenGL support, cv::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 a call to cv::waitKey or cv::pollKey to perform GUI housekeeping tasks that are necessary to actually show the given image and make the window respond to mouse and keyboard events. Otherwise, it won't display the image and the window might lock up. For example, waitKey(0) will display the window infinitely until any keypress (it is suitable for image display). waitKey(25) will display a frame and wait approximately 25 ms for a key press (suitable for displaying a video frame-by-frame). To remove the window, use cv::destroyWindow.
  [Windows Backend Only] Pressing Ctrl+C will copy the image to the clipboard. Pressing Ctrl+S will show a dialog to save the image.
  [Wayland Backend Only] Supoorting format is extended.
  - If the image is 8-bit signed, the pixels are biased by 128. That is, the value range [-128,127] is mapped to [0,255].
  - If the image is 16-bit signed, the pixels are divided by 256 and biased by 128. That is, the value range [-32768,32767] is mapped to [0,255].

Parameters

  winname | Name of the window.
  mat | Image to be shown.

## ◆ moveWindow()

void cv::moveWindow | ( | const String & | winname,
|  | int | x,
|  | int | y )

Python:
| cv.moveWindow( | winname, x, y | ) -> | None

`#include <opencv2/highgui.hpp>`

Moves the window to the specified position.

Parameters

  winname | Name of the window.
  x | The new x-coordinate of the window.
  y | The new y-coordinate of the window.

Note
  [Wayland Backend Only] This function is not supported by the Wayland protocol limitation.

## ◆ namedWindow()

void cv::namedWindow | ( | const String & | winname,
|  | int | flags = WINDOW_AUTOSIZE )

Python:
| cv.namedWindow( | winname[, flags] | ) -> | None

`#include <opencv2/highgui.hpp>`

Creates a window.

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 cv::destroyWindow or cv::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:
  - WINDOW_NORMAL or WINDOW_AUTOSIZE: WINDOW_NORMAL enables you to resize the window, whereas WINDOW_AUTOSIZE adjusts automatically the window size to fit the displayed image (see imshow ), and you cannot change the window size manually.
  - WINDOW_FREERATIO or WINDOW_KEEPRATIO: WINDOW_FREERATIO adjusts the image with no respect to its ratio, whereas WINDOW_KEEPRATIO keeps the image ratio.
  - WINDOW_GUI_NORMAL or WINDOW_GUI_EXPANDED: WINDOW_GUI_NORMAL is the old way to draw the window without statusbar and toolbar, whereas WINDOW_GUI_EXPANDED is a new enhanced GUI. By default, flags == WINDOW_AUTOSIZE | WINDOW_KEEPRATIO | WINDOW_GUI_EXPANDED

Parameters

  winname | Name of the window in the window caption that may be used as a window identifier.
  flags | Flags of the window. The supported flags are: (cv::WindowFlags)

## ◆ pollKey()

int cv::pollKey | ( |  | ) |

Python:
| cv.pollKey( |  | ) -> | retval

`#include <opencv2/highgui.hpp>`

Polls for a pressed key.

The function pollKey polls for a key event without waiting. It returns the code of the pressed key or -1 if no key was pressed since the last invocation. To wait until a key was pressed, use waitKey.

Note
  The functions waitKey and pollKey are the only methods in HighGUI that can fetch and handle GUI events, so one of them needs to be called periodically for normal event processing unless HighGUI is used within an environment that takes care of event processing.
  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.

## ◆ resizeWindow() [1/2]

void cv::resizeWindow | ( | const String & | winname,
|  | const cv::Size & | size )

Python:
| cv.resizeWindow( | winname, width, height | ) -> | None
| cv.resizeWindow( | winname, size | ) -> | None

`#include <opencv2/highgui.hpp>`

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

  winname | Window name.
  size | The new window size.

## ◆ resizeWindow() [2/2]

void cv::resizeWindow | ( | const String & | winname,
|  | int | width,
|  | int | height )

Python:
| cv.resizeWindow( | winname, width, height | ) -> | None
| cv.resizeWindow( | winname, size | ) -> | None

`#include <opencv2/highgui.hpp>`

Resizes the window to the specified size.

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.

Parameters

  winname | Window name.
  width | The new window width.
  height | The new window height.

## ◆ selectROI() [1/2]

Rect cv::selectROI | ( | const String & | windowName,
|  | InputArray | img,
|  | bool | showCrosshair = true,
|  | bool | fromCenter = false,
|  | bool | printNotice = true )

Python:
| cv.selectROI( | windowName, img[, showCrosshair[, fromCenter[, printNotice]]] | ) -> | retval
| cv.selectROI( | img[, showCrosshair[, fromCenter[, printNotice]]] | ) -> | retval

`#include <opencv2/highgui.hpp>`

Allows users to select a ROI on the given image.

The function creates a window and allows users to select a ROI using the mouse. Controls: use `space` or `enter` to finish selection, use key `c` to cancel selection (function will return the zero cv::Rect).

Parameters

  windowName | name of the window where selection process will be shown.
  img | image to select a ROI.
  showCrosshair | if true crosshair of selection rectangle will be shown.
  fromCenter | if true center of selection will match initial mouse position. In opposite case a corner of selection rectangle will correspont to the initial mouse position.
  printNotice | if true a notice to select ROI or cancel selection will be printed in console.

Returns
  selected ROI or empty rect if selection canceled.

Note
  The function sets it's own mouse callback for specified window using cv::setMouseCallback(windowName, ...). After finish of work an empty callback will be set for the used window.

## ◆ selectROI() [2/2]

Rect cv::selectROI | ( | InputArray | img,
|  | bool | showCrosshair = true,
|  | bool | fromCenter = false,
|  | bool | printNotice = true )

Python:
| cv.selectROI( | windowName, img[, showCrosshair[, fromCenter[, printNotice]]] | ) -> | retval
| cv.selectROI( | img[, showCrosshair[, fromCenter[, printNotice]]] | ) -> | retval

`#include <opencv2/highgui.hpp>`

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

## ◆ selectROIs()

void cv::selectROIs | ( | const String & | windowName,
|  | InputArray | img,
|  | std::vector< Rect > & | boundingBoxes,
|  | bool | showCrosshair = true,
|  | bool | fromCenter = false,
|  | bool | printNotice = true )

Python:
| cv.selectROIs( | windowName, img[, showCrosshair[, fromCenter[, printNotice]]] | ) -> | boundingBoxes

`#include <opencv2/highgui.hpp>`

Allows users to select multiple ROIs on the given image.

The function creates a window and allows users to select multiple ROIs using the mouse. Controls: use `space` or `enter` to finish current selection and start a new one, use `esc` to terminate multiple ROI selection process.

Parameters

  windowName | name of the window where selection process will be shown.
  img | image to select a ROI.
  boundingBoxes | selected ROIs.
  showCrosshair | if true crosshair of selection rectangle will be shown.
  fromCenter | if true center of selection will match initial mouse position. In opposite case a corner of selection rectangle will correspont to the initial mouse position.
  printNotice | if true a notice to select ROI or cancel selection will be printed in console.

Note
  The function sets it's own mouse callback for specified window using cv::setMouseCallback(windowName, ...). After finish of work an empty callback will be set for the used window.

## ◆ setMouseCallback()

void cv::setMouseCallback | ( | const String & | winname,
|  | MouseCallback | onMouse,
|  | void * | userdata = 0 )

`#include <opencv2/highgui.hpp>`

Sets mouse handler for the specified window.

Parameters

  winname | Name of the window.
  onMouse | Callback function for mouse events. See OpenCV samples on how to specify and use the callback.
  userdata | The optional parameter passed to the callback.

## ◆ setTrackbarMax()

void cv::setTrackbarMax | ( | const String & | trackbarname,
|  | const String & | winname,
|  | int | maxval )

Python:
| cv.setTrackbarMax( | trackbarname, winname, maxval | ) -> | None

`#include <opencv2/highgui.hpp>`

Sets the trackbar maximum position.

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

Note
  [Qt Backend Only] winname can be empty if the trackbar is attached to the control panel.

Parameters

  trackbarname | Name of the trackbar.
  winname | Name of the window that is the parent of trackbar.
  maxval | New maximum position.

## ◆ setTrackbarMin()

void cv::setTrackbarMin | ( | const String & | trackbarname,
|  | const String & | winname,
|  | int | minval )

Python:
| cv.setTrackbarMin( | trackbarname, winname, minval | ) -> | None

`#include <opencv2/highgui.hpp>`

Sets the trackbar minimum position.

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

Note
  [Qt Backend Only] winname can be empty if the trackbar is attached to the control panel.

Parameters

  trackbarname | Name of the trackbar.
  winname | Name of the window that is the parent of trackbar.
  minval | New minimum position.

## ◆ setTrackbarPos()

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

Python:
| cv.setTrackbarPos( | trackbarname, winname, pos | ) -> | None

`#include <opencv2/highgui.hpp>`

Sets the trackbar position.

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

Note
  [Qt Backend Only] winname can be empty if the trackbar is attached to the control panel.

Parameters

  trackbarname | Name of the trackbar.
  winname | Name of the window that is the parent of trackbar.
  pos | New position.

## ◆ setWindowProperty()

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

Python:
| cv.setWindowProperty( | winname, prop_id, prop_value | ) -> | None

`#include <opencv2/highgui.hpp>`

Changes parameters of a window dynamically.

The function setWindowProperty enables changing properties of a window.

Parameters

  winname | Name of the window.
  prop_id | Window property to edit. The supported operation flags are: (cv::WindowPropertyFlags)
  prop_value | New value of the window property. The supported flags are: (cv::WindowFlags)

Note
  [Wayland Backend Only] This function is not supported.

## ◆ setWindowTitle()

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

Python:
| cv.setWindowTitle( | winname, title | ) -> | None

`#include <opencv2/highgui.hpp>`

Updates window title.

Parameters

  winname | Name of the window.
  title | New title.

## ◆ startWindowThread()

int cv::startWindowThread | ( |  | ) |

Python:
| cv.startWindowThread( |  | ) -> | retval

`#include <opencv2/highgui.hpp>`

## ◆ waitKey()

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

Python:
| cv.waitKey( | [, delay] | ) -> | retval

`#include <opencv2/highgui.hpp>`

Waits for a pressed key.

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. To check for a key press but not wait for it, use pollKey.

Note
  The functions waitKey and pollKey are the only methods in HighGUI that can fetch and handle GUI events, so one of them needs to be called periodically for normal event processing unless HighGUI is used within an environment that takes care of event processing.
  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.

Parameters

  delay | Delay in milliseconds. 0 is the special value that means "forever".

## ◆ waitKeyEx()

int cv::waitKeyEx | ( | int | delay = 0 | ) |

Python:
| cv.waitKeyEx( | [, delay] | ) -> | retval

`#include <opencv2/highgui.hpp>`

Similar to waitKey, but returns full key code.

Note
  Key code is implementation specific and depends on used backend: QT/GTK/Win32/etc