高级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创建的按钮的回调函数。

参数

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

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 常量。
userdata	可选参数。

OpenGlDrawCallback

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

#include <opencv2/highgui.hpp>

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

参数

userdata

可选参数。

TrackbarCallback

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

#include <opencv2/highgui.hpp>

轨迹条的回调函数，参见cv::createTrackbar。

参数

pos	指定滑块条的当前位置。
userdata	可选参数。

函数文档

createTrackbar()

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

#include <opencv2/highgui.hpp>

创建一个轨迹条并将其附加到指定的窗口。

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

注意

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

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

参数

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

注意

如果 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(		) ->	None

#include <opencv2/highgui.hpp>

销毁所有HighGUI窗口。

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

destroyWindow()

void cv::destroyWindow

(

const String &

winname

)

Python
	cv.destroyWindow(	winname	) ->	None

#include <opencv2/highgui.hpp>

销毁指定的窗口。

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

参数

winname

要销毁的窗口的名称。

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 &	trackbarname,
		const String &	winname )

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

#include <opencv2/highgui.hpp>

返回轨迹条的位置。

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

注意

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

参数

trackbarname	滑块条的名称。
winname	作为滑块条父级的窗口的名称。

getWindowImageRect()

Rect cv::getWindowImageRect

(

const String &

winname

)

Python
	cv.getWindowImageRect(	winname	) ->	retval

#include <opencv2/highgui.hpp>

提供窗口中图像的矩形。

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

参数

winname

窗口名称。

另请参见

resizeWindow moveWindow

注意

[**仅限 Wayland 后端**] 由于 Wayland 协议的限制，此函数不受支持。

getWindowProperty()

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

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

#include <opencv2/highgui.hpp>

提供窗口的参数。

函数 `getWindowProperty` 返回窗口的属性。

参数

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

另请参见

setWindowProperty

注意

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

imshow()

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

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

#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]。

参数

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

moveWindow()

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

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

#include <opencv2/highgui.hpp>

将窗口移动到指定位置。

参数

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

注意

[**仅限 Wayland 后端**] 由于 Wayland 协议的限制，此函数不受支持。

namedWindow()

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

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

#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

参数

winname	窗口标题栏中窗口的名称，可用作窗口标识符。
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 &	winname,
		const cv::Size &	size )

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

#include <opencv2/highgui.hpp>

这是一个重载的成员函数，为了方便使用。它与上面的函数唯一的区别在于它接受的参数。

参数

winname	窗口名称。
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>

将窗口调整为指定大小。

注意

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

参数

winname	窗口名称。
width	新的窗口宽度。
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>

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

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

参数

windowName	显示选择过程的窗口名称。
img	用于选择ROI的图像。
showCrosshair	如果为真，则显示选择矩形的十字准星。
fromCenter	如果为真，则选择的中心将与初始鼠标位置匹配。反之，选择矩形的一个角将对应于初始鼠标位置。
printNotice	如果为真，则会在控制台中打印选择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 &	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>

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

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

参数

windowName	显示选择过程的窗口名称。
img	用于选择ROI的图像。
boundingBoxes	选定的ROIs。
showCrosshair	如果为真，则显示选择矩形的十字准星。
fromCenter	如果为真，则选择的中心将与初始鼠标位置匹配。反之，选择矩形的一个角将对应于初始鼠标位置。
printNotice	如果为真，则会在控制台中打印选择ROI或取消选择的提示。

注意

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

setMouseCallback()

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

#include <opencv2/highgui.hpp>

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

参数

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

setTrackbarMax()

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

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

#include <opencv2/highgui.hpp>

设置轨迹条的最大位置。

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

注意

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

参数

trackbarname	滑块条的名称。
winname	作为轨迹条父级的窗口名称。
maxval	新的最大位置。

setTrackbarMin()

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

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

#include <opencv2/highgui.hpp>

设置滑块条的最小位置。

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

注意

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

参数

trackbarname	滑块条的名称。
winname	作为轨迹条父级的窗口名称。
minval	新的最小位置。

setTrackbarPos()

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

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

#include <opencv2/highgui.hpp>

设置滑块条的位置。

该函数设置指定窗口中指定轨迹条的位置。

注意

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

参数

trackbarname	滑块条的名称。
winname	作为轨迹条父级的窗口名称。
pos	新的位置。

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>

动态更改窗口参数。

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

参数

winname	窗口名称。
prop_id	要编辑的窗口属性。支持的操作标志为：（cv::WindowPropertyFlags）
prop_value	窗口属性的新值。支持的标志为：（cv::WindowFlags）

注意

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

setWindowTitle()

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

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

#include <opencv2/highgui.hpp>

更新窗口标题。

参数

winname	窗口名称。
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>

等待按键按下。

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

注意

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

只有在至少创建了一个 HighGUI 窗口并且窗口处于活动状态时，此函数才有效。如果有多个 HighGUI 窗口，则任何一个窗口都可以处于活动状态。

参数

delay

以毫秒为单位的延迟。0 是表示“无限期”的特殊值。

waitKeyEx()

int cv::waitKeyEx

(

int

delay = 0

)

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

#include <opencv2/highgui.hpp>

类似于 waitKey，但返回完整的按键码。

注意

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