高级GUI

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

详细说明

OpenCV设计用于在完整的应用程序中使用，并且可以在功能丰富的UI框架（如Qt*、WinForms*或Cocoa*）中或完全不使用UI的情况下使用。但有时需要快速尝试功能并可视化结果。这就是HighGUI模块的设计目的。

它提供了简单的接口来

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

类型定义 (Typedefs)
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 ()
	正在使用的高级GUI后端。
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，但返回完整的按键代码。

类型定义文档 (Typedef Documentation)

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。

参数

事件	是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	可选参数。

函数文档 (Function Documentation)

createTrackbar()

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

#include <opencv2/highgui.hpp>

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

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

注意

[仅限Qt后端] 如果滑块应附加到控件面板，则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>

正在使用的高级GUI后端。

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

destroyAllWindows()

void cv::destroyAllWindows

(

)

Python
	cv.destroyAllWindows(		) ->	None

#include <opencv2/highgui.hpp>

销毁所有 HighGUI 窗口。

destroyAllWindows函数销毁所有已打开的高级GUI窗口。

destroyWindow()

void cv::destroyWindow

(

const String &

窗口名称

)

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

#include <opencv2/highgui.hpp>

销毁指定窗口。

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

参数

窗口名称	要销毁的窗口的名称。

getMouseWheelDelta()

int cv::getMouseWheelDelta

(

int

flags (标志)

)

#include <opencv2/highgui.hpp>

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

对于普通的鼠标滚轮，增量将是120的倍数。值为120对应于滚轮的一个刻度旋转或操作的阈值，并且每次增量应发生一次此类操作。一些具有更高分辨率自由旋转滚轮的高精度鼠标可能会生成较小的值。

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

注意

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

参数

flags (标志)

鼠标回调标志参数。

getTrackbarPos()

int cv::getTrackbarPos	(	const String &	滑块名称,
		const String &	窗口名称 )

Python
	cv.getTrackbarPos(	滑块名称, 窗口名称	) ->	retval

#include <opencv2/highgui.hpp>

返回跟踪条位置。

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

注意

[仅限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	属性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	) ->	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]。

参数

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

moveWindow()

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

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

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

参数

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

pollKey()

int cv::pollKey

(

)

Python
	cv.pollKey(		) ->	retval

#include <opencv2/highgui.hpp>

轮询按下的键。

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

注意

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

该函数仅在至少创建一个高级GUI窗口且该窗口处于活动状态时才有效。如果有多个高级GUI窗口，任何一个都可以是活动的。

resizeWindow() [1/2]

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

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

#include <opencv2/highgui.hpp>

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

参数

窗口名称	窗口名称。
size (大小)	新的窗口大小。

resizeWindow() [2/2]

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

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

#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。控件：使用space或enter完成选择，使用键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。控件：使用space或enter完成当前选择并开始新的选择，使用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示例，了解如何指定和使用回调。
userdata	传递给回调的可选参数。

setTrackbarMax()

void cv::setTrackbarMax	(	const String &	滑块名称,
		const String &	窗口名称,
		int	最大值 (maxval) )

Python
	cv.setTrackbarMax(	滑块名称, 窗口名称, 最大值	) ->	None

#include <opencv2/highgui.hpp>

设置滑块的最大位置。

setTrackbarMax函数设置指定窗口中指定滑块的最大位置。

注意

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

参数

滑块名称	滑块的名称。
窗口名称	滑块父窗口的名称。
最大值 (maxval)	新的最大位置。

setTrackbarMin()

void cv::setTrackbarMin	(	const String &	滑块名称,
		const String &	窗口名称,
		int	最小值 )

Python
	cv.setTrackbarMin(	滑块名称, 窗口名称, 最小值	) ->	None

#include <opencv2/highgui.hpp>

设置滑块的最小位置。

setTrackbarMin函数设置指定窗口中指定滑块的最小位置。

注意

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

参数

滑块名称	滑块的名称。
窗口名称	滑块父窗口的名称。
最小值	新的最小位置。

setTrackbarPos()

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

Python
	cv.setTrackbarPos(	滑块名称, 窗口名称, 位置	) ->	None

#include <opencv2/highgui.hpp>

设置轨迹条位置。

setTrackbarPos函数设置指定窗口中指定滑块的位置。

注意

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

参数

滑块名称	滑块的名称。
窗口名称	滑块父窗口的名称。
pos	新位置。

setWindowProperty()

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

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

#include <opencv2/highgui.hpp>

动态更改窗口的参数。

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

参数

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

注意

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

setWindowTitle()

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

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

#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毫秒，具体取决于当时您的计算机上正在运行的其他任务。它返回按下键的代码，如果指定的时限内没有按键按下，则返回-1。要检查按键但不要等待，请使用pollKey。

注意

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

该函数仅在至少创建一个高级GUI窗口且该窗口处于活动状态时才有效。如果有多个高级GUI窗口，任何一个都可以是活动的。

参数

延迟	延迟（以毫秒为单位）。0是特殊值，表示“永远”。

waitKeyEx()

int cv::waitKeyEx

(

int

delay=0

)

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

#include <opencv2/highgui.hpp>

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

注意

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