高级 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 创建一个滑块（滑块或范围控件），并指定其名称和范围，将变量 value 指定为与滑块同步的位置，并指定回调函数 onChange 在滑块位置更改时调用。创建的滑块将显示在指定的窗口 winname 中。

注意

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

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

参数

trackbarname	创建的滑块的名称。
winname	将用作创建的滑块的父级的窗口的名称。
value	可选地指向整数变量的指针，其值反映滑块的位置。在创建时，滑块的位置由该变量定义。
count	滑块的最大位置。最小位置始终为 0。
onChange	指向每次滑块位置更改时将调用的函数的指针。此函数的原型应为 void Foo(int,void*);，其中第一个参数是滑块位置，第二个参数是用户数据（请参阅下一个参数）。如果回调是 NULL 指针，则不会调用任何回调，但只会更新 value。
userdata	用户数据，以原样传递给回调。它可以用于处理滑块事件，而无需使用全局变量。

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。控制：使用 `space` 或 `enter` 完成当前选择并开始新的选择，使用 `esc` 终止多个 ROI 选择过程。

参数

windowName	将显示选择过程的窗口的名称。
img	选择 ROI 的图像。
boundingBoxes	选定的 ROI。
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 毫秒，当它为正数时。由于操作系统在切换线程之间有最短时间，因此该函数不会等待 exactly 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 等