高级GUI

主题
	与创建和操作HighGUI窗口及鼠标事件相关的标志
	OpenGL支持
	Qt新函数
	WinRT支持

详细描述

OpenCV旨在用于完整的应用程序，并且可以在功能丰富的UI框架（如Qt*、WinForms*或Cocoa*）中使用，或者完全不使用任何UI。然而，有时需要快速试用功能并可视化结果。HighGUI模块正是为此目的而设计的。

它提供了方便的接口以

• 创建和操作可显示图像并“记住”其内容的窗口（无需处理来自操作系统的重绘事件）。
• 向窗口添加滑动条，处理简单的鼠标事件以及键盘命令。

类型定义
typedef void(*	cv::ButtonCallback) (int state, void *userdata)
	由cv::createButton创建的按钮的回调函数。
typedef void(*	cv::MouseCallback) (int event, int x, int y, int flags, void *userdata)
	鼠标事件的回调函数。参见cv::setMouseCallback。
typedef void(*	cv::OpenGlDrawCallback) (void *userdata)
	定义为每帧调用的回调函数。参见cv::setOpenGlDrawCallback。
typedef void(*	cv::TrackbarCallback) (int pos, void *userdata)
	滑动条的回调函数，参见cv::createTrackbar。

函数
int	cv::createTrackbar (const String &trackbarname, const String &winname, int *value, int count, TrackbarCallback onChange=0, void *userdata=0)
	创建滑动条并将其附加到指定窗口。
const std::string	cv::currentUIFramework ()
	使用的HighGUI后端。
void	cv::destroyAllWindows ()
	销毁所有HighGUI窗口。
void	cv::destroyWindow (const String &winname)
	销毁指定窗口。
int	cv::getMouseWheelDelta (int flags)
	处理鼠标滚轮事件cv::EVENT_MOUSEWHEEL和cv::EVENT_MOUSEHWHEEL时，获取鼠标滚轮的运动增量。
int	cv::getTrackbarPos (const String &trackbarname, const String &winname)
	返回滑动条位置。
Rect	cv::getWindowImageRect (const String &winname)
	提供窗口中图像的矩形区域。
double	cv::getWindowProperty (const String &winname, int prop_id)
	提供窗口参数。
void	cv::imshow (const String &winname, InputArray mat)
	在指定窗口中显示图像。
void	cv::moveWindow (const String &winname, int x, int y)
	将窗口移动到指定位置。
void	cv::namedWindow (const String &winname, int flags=WINDOW_AUTOSIZE)
	创建窗口。
int	cv::pollKey ()
	轮询按下的键。
void	cv::resizeWindow (const String &winname, const cv::Size &size)
void	cv::resizeWindow (const String &winname, int width, int height)
	将窗口调整到指定大小。
Rect	cv::selectROI (const String &windowName, InputArray img, bool showCrosshair=true, bool fromCenter=false, bool printNotice=true)
	允许用户在给定图像上选择一个ROI。
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)
	允许用户在给定图像上选择多个ROI。
void	cv::setMouseCallback (const String &winname, MouseCallback onMouse, void *userdata=0)
	为指定窗口设置鼠标处理程序。
void	cv::setTrackbarMax (const String &trackbarname, const String &winname, int maxval)
	设置滑动条最大位置。
void	cv::setTrackbarMin (const String &trackbarname, const String &winname, int minval)
	设置滑动条最小位置。
void	cv::setTrackbarPos (const String &trackbarname, const String &winname, int pos)
	设置滑动条位置。
void	cv::setWindowProperty (const String &winname, int prop_id, double prop_value)
	动态更改窗口参数。
void	cv::setWindowTitle (const String &winname, const String &title)
	更新窗口标题。
int	cv::startWindowThread ()
int	cv::waitKey (int delay=0)
	等待按键按下。
int	cv::waitKeyEx (int delay=0)
	与waitKey类似，但返回完整键码。

类型定义文档

ButtonCallback

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

#include <opencv2/highgui.hpp>

由cv::createButton创建的按钮的回调函数。

参数

状态	按钮的当前状态。对于按钮可以是-1，对于复选框/单选框按钮可以是0或1。
用户数据	可选参数。

MouseCallback

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

#include <opencv2/highgui.hpp>

鼠标事件的回调函数。参见cv::setMouseCallback。

参数

event	其中一个cv::MouseEventTypes常量。
x	鼠标事件的x坐标。
y	鼠标事件的y坐标。
flags	其中一个cv::MouseEventFlags常量。
用户数据	可选参数。

OpenGlDrawCallback

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

#include <opencv2/highgui.hpp>

定义为每帧调用的回调函数。参见cv::setOpenGlDrawCallback。

参数

用户数据

可选参数。

TrackbarCallback

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

#include <opencv2/highgui.hpp>

滑动条的回调函数，参见cv::createTrackbar。

参数

pos	指定滑动条的当前位置。
用户数据	可选参数。

函数文档

createTrackbar()

int cv::createTrackbar	(	const String &	滑动条名称,
		const String &	窗口名称,
		int *	值,
		int	count,
		TrackbarCallback	onChange = 0,
		void *	userdata = 0 )

#include <opencv2/highgui.hpp>

创建滑动条并将其附加到指定窗口。

函数createTrackbar创建一个具有指定名称和范围的滑动条（滑块或范围控件），将一个变量值指定为与滑动条同步的位置，并指定回调函数onChange以在滑动条位置改变时调用。创建的滑动条显示在指定的窗口winname中。

注意

[仅Qt后端] 如果滑动条应附加到控制面板，则winname可以为空。

点击每个滑动条的标签可以手动编辑滑动条的值。

参数

滑动条名称	创建的滑动条的名称。
窗口名称	将包含滑动条的窗口的名称。
值	指向将被滑动条改变的整数值的指针。如果未使用值指针，则传递nullptr。在这种情况下，请在回调函数中手动处理滑动条位置。
count	滑动条的最大位置。
onChange	指向每当滑块位置改变时要调用的函数的指针。此函数应具有原型void Foo(int, void*);，其中第一个参数是滑动条位置，第二个参数是用户数据（参见下一个参数）。如果回调是nullptr，则不会调用任何回调，但滑动条的值仍将自动更新。
用户数据	传递给回调的可选用户数据。

注意

如果value指针是nullptr，则滑动条位置必须手动管理。请手动调用回调函数并传入所需的初始值，以避免运行时警告。

另请参见

向我们的应用程序添加滑动条！

currentUIFramework()

const std::string cv::currentUIFramework

(

)

Python
	cv.currentUIFramework(		) ->	retval

#include <opencv2/highgui.hpp>

使用的HighGUI后端。

该函数返回使用的HighGUI后端名称：可以是COCOA、GTK2/3、QT、WAYLAND或WIN32。如果没有可用的UI后端，则返回空字符串。

destroyAllWindows()

void cv::destroyAllWindows

(

)

Python
	cv.destroyAllWindows(		) ->	无

#include <opencv2/highgui.hpp>

销毁所有HighGUI窗口。

函数destroyAllWindows销毁所有已打开的HighGUI窗口。

destroyWindow()

void cv::destroyWindow

(

const String &

窗口名称

)

Python
	cv.destroyWindow(	窗口名称	) ->	无

#include <opencv2/highgui.hpp>

销毁指定窗口。

函数destroyWindow销毁具有给定名称的窗口。

参数

窗口名称

要销毁的窗口名称。

getMouseWheelDelta()

int cv::getMouseWheelDelta

(

int

flags

)

#include <opencv2/highgui.hpp>

处理鼠标滚轮事件cv::EVENT_MOUSEWHEEL和cv::EVENT_MOUSEHWHEEL时，获取鼠标滚轮的运动增量。

对于带有滚轮的普通鼠标，delta将是120的倍数。值120对应于滚轮的一个刻度旋转，或需要采取行动的阈值，并且每个delta都应该发生一次此类行动。一些具有更高分辨率自由旋转滚轮的高精度鼠标可能会生成较小的值。

对于cv::EVENT_MOUSEWHEEL，正值和负值分别表示向前和向后滚动。对于cv::EVENT_MOUSEHWHEEL（如果可用），正值和负值分别表示向右和向左滚动。

注意

鼠标滚轮事件目前仅在Windows和Cocoa上受支持。

参数

flags

鼠标回调标志参数。

getTrackbarPos()

int cv::getTrackbarPos	(	const String &	滑动条名称,
		const String &	winname )

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

#include <opencv2/highgui.hpp>

返回滑动条位置。

该函数返回指定滑动条的当前位置。

注意

[仅Qt后端] 如果滑动条附加到控制面板，则winname可以为空。

参数

滑动条名称	滑动条的名称。
窗口名称	作为滑动条父窗口的名称。

getWindowImageRect()

Rect cv::getWindowImageRect

(

const String &

窗口名称

)

Python
	cv.getWindowImageRect(	窗口名称	) ->	retval

#include <opencv2/highgui.hpp>

提供窗口中图像的矩形区域。

函数getWindowImageRect返回图像渲染区域的客户端屏幕坐标、宽度和高度。

参数

窗口名称

窗口名称。

另请参见

resizeWindow moveWindow

注意

[仅Wayland后端] 此函数受Wayland协议限制不支持。

getWindowProperty()

double cv::getWindowProperty	(	const String &	窗口名称,
		int	prop_id )

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

#include <opencv2/highgui.hpp>

提供窗口参数。

函数getWindowProperty返回窗口的属性。

参数

窗口名称	窗口名称。
属性ID	要检索的窗口属性。可用的操作标志如下：(cv::WindowPropertyFlags)

另请参见

setWindowProperty

注意

[仅Wayland后端] 此函数不支持。

imshow()

void cv::imshow	(	const String &	窗口名称,
		InputArray	mat )

Python
	cv.imshow(	winname, mat	) ->	无

#include <opencv2/highgui.hpp>

在指定窗口中显示图像。

函数imshow在指定窗口中显示图像。如果窗口是使用cv::WINDOW_AUTOSIZE标志创建的，则图像将以其原始大小显示，但仍受限于屏幕分辨率。否则，图像将被缩放以适应窗口。该函数可能会根据图像的深度缩放图像。

• 如果图像是8位无符号的，则按原样显示。
• 如果图像是16位无符号的，则像素值除以256。也就是说，值范围[0,255*256]映射到[0,255]。
• 如果图像是32位或64位浮点型，则像素值乘以255。也就是说，值范围[0,1]映射到[0,255]。
• 由于所需变换的模糊性，32位整数图像不再被处理。请使用特定于图像上下文的自定义预处理将其转换为8位无符号矩阵。

如果窗口是使用OpenGL支持创建的，则cv::imshow也支持ogl::Buffer、ogl::Texture2D和cuda::GpuMat作为输入。

如果在此函数之前未创建窗口，则假定创建了一个使用cv::WINDOW_AUTOSIZE的窗口。

如果您需要显示大于屏幕分辨率的图像，则需要在imshow之前调用namedWindow("", WINDOW_NORMAL)。

注意

此函数后应调用cv::waitKey或cv::pollKey以执行必要的GUI内务管理任务，以实际显示给定图像并使窗口响应鼠标和键盘事件。否则，它将不显示图像，窗口可能会锁定。例如，waitKey(0)将无限期地显示窗口，直到按下任何键（适用于图像显示）。waitKey(25)将显示一帧并等待大约25毫秒的按键（适用于逐帧显示视频）。要删除窗口，请使用cv::destroyWindow。

[仅Windows后端] 按Ctrl+C将图像复制到剪贴板。按Ctrl+S将显示一个对话框来保存图像。

[仅Wayland后端] 支持的格式已扩展。

• 如果图像是8位有符号的，则像素值偏移128。也就是说，值范围[-128,127]映射到[0,255]。
• 如果图像是16位有符号的，则像素值除以256并偏移128。也就是说，值范围[-32768,32767]映射到[0,255]。

参数

窗口名称	窗口名称。
mat	要显示的图像。

moveWindow()

void cv::moveWindow	(	const String &	窗口名称,
		int	x,
		int	y )

Python
	cv.moveWindow(	winname, x, y	) ->	无

#include <opencv2/highgui.hpp>

将窗口移动到指定位置。

参数

窗口名称	窗口名称。
x	窗口新的x坐标。
y	窗口新的y坐标。

注意

[仅Wayland后端] 此函数受Wayland协议限制不支持。

namedWindow()

void cv::namedWindow	(	const String &	窗口名称,
		int	flags = WINDOW_AUTOSIZE )

Python
	cv.namedWindow(	winname[, flags]	) ->	无

#include <opencv2/highgui.hpp>

创建窗口。

函数namedWindow创建一个窗口，可用作图像和滑动条的占位符。创建的窗口通过其名称引用。

如果同名窗口已存在，则该函数不执行任何操作。

您可以调用cv::destroyWindow或cv::destroyAllWindows来关闭窗口并释放所有相关内存使用。对于一个简单的程序，您实际上不必调用这些函数，因为应用程序的所有资源和窗口在退出时都会由操作系统自动关闭。

注意

Qt后端支持额外的标志

• WINDOW_NORMAL或WINDOW_AUTOSIZE： WINDOW_NORMAL允许您调整窗口大小，而WINDOW_AUTOSIZE会自动调整窗口大小以适应显示的图像（参见imshow），并且您无法手动更改窗口大小。
• WINDOW_FREERATIO或WINDOW_KEEPRATIO： WINDOW_FREERATIO调整图像时不考虑其宽高比，而WINDOW_KEEPRATIO保持图像宽高比。
• WINDOW_GUI_NORMAL或WINDOW_GUI_EXPANDED： WINDOW_GUI_NORMAL是绘制不带状态栏和工具栏的窗口的旧方式，而WINDOW_GUI_EXPANDED是一种新的增强型GUI。默认情况下，flags == WINDOW_AUTOSIZE | WINDOW_KEEPRATIO | WINDOW_GUI_EXPANDED

参数

窗口名称	窗口标题中可作为窗口标识符的窗口名称。
flags	窗口的标志。支持的标志是：(cv::WindowFlags)

pollKey()

int cv::pollKey

(

)

Python
	cv.pollKey(		) ->	retval

#include <opencv2/highgui.hpp>

轮询按下的键。

函数pollKey轮询按键事件而不等待。它返回按下的键的代码，如果自上次调用以来没有按下任何键，则返回-1。要等到按键被按下，请使用waitKey。

注意

函数waitKey和pollKey是HighGUI中唯一可以获取和处理GUI事件的方法，因此除非HighGUI在负责事件处理的环境中使用，否则需要定期调用其中一个以进行正常的事件处理。

该函数仅在至少创建一个HighGUI窗口且该窗口处于活动状态时才有效。如果存在多个HighGUI窗口，则其中任何一个都可以处于活动状态。

resizeWindow() [1/2]

void cv::resizeWindow	(	const String &	窗口名称,
		const cv::Size &	size )

Python
	cv.resizeWindow(	winname, width, height	) ->	无
	cv.resizeWindow(	winname, size	) ->	无

#include <opencv2/highgui.hpp>

这是一个重载成员函数，为方便起见而提供。它与上述函数的区别仅在于其接受的参数。

参数

窗口名称	窗口名称。
size	新窗口大小。

resizeWindow() [2/2]

void cv::resizeWindow	(	const String &	窗口名称,
		int	width,
		int	height )

Python
	cv.resizeWindow(	winname, width, height	) ->	无
	cv.resizeWindow(	winname, size	) ->	无

#include <opencv2/highgui.hpp>

将窗口调整到指定大小。

注意

指定的窗口大小是针对图像区域的。工具栏不计算在内。只有没有使用cv::WINDOW_AUTOSIZE标志创建的窗口才能调整大小。

参数

窗口名称	窗口名称。
width	新窗口宽度。
height	新窗口高度。

selectROI() [1/2]

Rect cv::selectROI	(	const String &	窗口名称,
		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>

允许用户在给定图像上选择一个ROI。

该函数创建一个窗口，允许用户使用鼠标选择一个ROI。控件：使用空格键或回车键完成选择，使用c键取消选择（函数将返回零cv::Rect）。

参数

窗口名称	将显示选择过程的窗口名称。
img	用于选择ROI的图像。
显示十字线	如果为true，则会显示选择矩形的十字线。
从中心	如果为true，则选择中心将与初始鼠标位置匹配。否则，选择矩形的角将对应于初始鼠标位置。
打印通知	如果为true，则会在控制台中打印选择ROI或取消选择的通知。

返回

选定的ROI，如果选择取消则为空矩形。

注意

该函数使用cv::setMouseCallback(windowName, ...)为指定窗口设置其自己的鼠标回调。工作完成后，将为使用的窗口设置一个空的回调。

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>

这是一个重载成员函数，为方便起见而提供。它与上述函数的区别仅在于其接受的参数。

selectROIs()

void cv::selectROIs	(	const String &	窗口名称,
		InputArray	img,
		std::vector< Rect > &	边界框,
		bool	showCrosshair = true,
		bool	fromCenter = false,
		bool	printNotice = true )

Python
	cv.selectROIs(	windowName, img[, showCrosshair[, fromCenter[, printNotice]]]	) ->	边界框

#include <opencv2/highgui.hpp>

允许用户在给定图像上选择多个ROI。

该函数创建一个窗口，允许用户使用鼠标选择多个ROI。控件：使用空格键或回车键完成当前选择并开始新的选择，使用esc终止多ROI选择过程。

参数

窗口名称	将显示选择过程的窗口名称。
img	用于选择ROI的图像。
边界框	选定的ROI。
显示十字线	如果为true，则会显示选择矩形的十字线。
从中心	如果为true，则选择中心将与初始鼠标位置匹配。否则，选择矩形的角将对应于初始鼠标位置。
打印通知	如果为true，则会在控制台中打印选择ROI或取消选择的通知。

注意

该函数使用cv::setMouseCallback(windowName, ...)为指定窗口设置其自己的鼠标回调。工作完成后，将为使用的窗口设置一个空的回调。

setMouseCallback()

void cv::setMouseCallback	(	const String &	窗口名称,
		MouseCallback	onMouse,
		void *	userdata = 0 )

#include <opencv2/highgui.hpp>

为指定窗口设置鼠标处理程序。

参数

窗口名称	窗口名称。
onMouse	鼠标事件的回调函数。有关如何指定和使用回调，请参阅OpenCV示例。
用户数据	传递给回调的可选参数。

setTrackbarMax()

void cv::setTrackbarMax	(	const String &	滑动条名称,
		const String &	窗口名称,
		int	maxval )

Python
	cv.setTrackbarMax(	trackbarname, winname, maxval	) ->	无

#include <opencv2/highgui.hpp>

设置滑动条最大位置。

该函数设置指定窗口中指定滑动条的最大位置。

注意

[仅Qt后端] 如果滑动条附加到控制面板，则winname可以为空。

参数

滑动条名称	滑动条的名称。
窗口名称	作为滑动条父窗口的名称。
最大值	新的最大位置。

setTrackbarMin()

void cv::setTrackbarMin	(	const String &	滑动条名称,
		const String &	窗口名称,
		int	minval )

Python
	cv.setTrackbarMin(	trackbarname, winname, minval	) ->	无

#include <opencv2/highgui.hpp>

设置滑动条最小位置。

该函数设置指定窗口中指定滑动条的最小位置。

注意

[仅Qt后端] 如果滑动条附加到控制面板，则winname可以为空。

参数

滑动条名称	滑动条的名称。
窗口名称	作为滑动条父窗口的名称。
最小值	新的最小位置。

setTrackbarPos()

void cv::setTrackbarPos	(	const String &	滑动条名称,
		const String &	窗口名称,
		int	pos )

Python
	cv.setTrackbarPos(	trackbarname, winname, pos	) ->	无

#include <opencv2/highgui.hpp>

设置滑动条位置。

该函数设置指定窗口中指定滑动条的位置。

注意

[仅Qt后端] 如果滑动条附加到控制面板，则winname可以为空。

参数

滑动条名称	滑动条的名称。
窗口名称	作为滑动条父窗口的名称。
pos	新位置。

setWindowProperty()

void cv::setWindowProperty	(	const String &	窗口名称,
		int	属性ID,
		double	prop_value )

Python
	cv.setWindowProperty(	winname, prop_id, prop_value	) ->	无

#include <opencv2/highgui.hpp>

动态更改窗口参数。

函数setWindowProperty允许动态更改窗口的属性。

参数

窗口名称	窗口名称。
属性ID	要编辑的窗口属性。支持的操作标志是：(cv::WindowPropertyFlags)
属性值	窗口属性的新值。支持的标志是：(cv::WindowFlags)

注意

[仅Wayland后端] 此函数不支持。

setWindowTitle()

void cv::setWindowTitle	(	const String &	窗口名称,
		const String &	title )

Python
	cv.setWindowTitle(	winname, title	) ->	无

#include <opencv2/highgui.hpp>

更新窗口标题。

参数

窗口名称	窗口名称。
标题	新标题。

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>

等待按键按下。

函数waitKey会无限期（当\(\texttt{delay}\leq 0\)时）或在delay毫秒内（当其为正值时）等待按键事件。由于操作系统在切换线程之间存在最短时间，因此该函数不会精确等待delay毫秒，而是至少等待delay毫秒，具体取决于当时计算机上运行的其他程序。如果未在指定时间过去之前按下任何键，则返回按下键的代码，否则返回-1。要检查按键是否按下但不等待，请使用pollKey。

注意

函数waitKey和pollKey是HighGUI中唯一可以获取和处理GUI事件的方法，因此除非HighGUI在负责事件处理的环境中使用，否则需要定期调用其中一个以进行正常的事件处理。

该函数仅在至少创建一个HighGUI窗口且该窗口处于活动状态时才有效。如果存在多个HighGUI窗口，则其中任何一个都可以处于活动状态。

参数

延迟	延迟毫秒数。0是一个特殊值，表示“永远”。

waitKeyEx()

int cv::waitKeyEx

(

int

delay = 0

)

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

#include <opencv2/highgui.hpp>

与waitKey类似，但返回完整键码。

注意

键码是特定于实现的，取决于所使用的后端：QT/GTK/Win32等。