核心函数

1. cv2.namedWindow(windowName, flags)

功能：创建一个窗口，可指定窗口属性（是否可调整大小、是否为全屏等）。
语法：

cv2.namedWindow(winname, flags)

参数说明：

参数	类型	说明
winname	str	窗口的名称（字符串），用于唯一标识该窗口
flags	int	窗口标志，用于控制窗口属性（见下表）

flags 可选值：

标志	含义
cv2.WINDOW_NORMAL	创建一个可调整大小的窗口
cv2.WINDOW_AUTOSIZE	（默认）窗口大小自动适应图像，不能改变
cv2.WINDOW_FULLSCREEN	全屏显示窗口
cv2.WINDOW_FREERATIO	允许自由缩放图像显示比例
cv2.WINDOW_KEEPRATIO	保持图像宽高比缩放（默认）
cv2.WINDOW_GUI_EXPANDED	启用带状态栏的 GUI
cv2.WINDOW_GUI_NORMAL	经典窗口（无状态栏）

2. cv2.imshow(windowName, image)

功能：在指定的窗口中显示图像。
语法：

cv2.imshow(winname, mat)

参数说明：

参数	类型	说明
winname	str	已创建的窗口名称
mat	ndarray	图像矩阵（例如通过 cv2.imread() 读取）

注意：

• 图像必须是 numpy.ndarray 类型。
• imshow 只是将图像传递给窗口缓冲区，不会立即显示，需要调用 cv2.waitKey() 来刷新。

3. cv2.waitKey(delay=0)

功能：等待键盘事件；窗口刷新依赖于该函数。
语法：

key = cv2.waitKey(delay)

参数说明：

参数	类型	说明
delay	int	等待时间（毫秒）。0 表示无限等待直到按键。

返回值：

• 返回按键的 ASCII 值，可用于判断退出条件。
  例如：

if cv2.waitKey(0) & 0xFF == ord('q'):
    break

4. cv2.destroyWindow(windowName)

功能：销毁指定窗口。

cv2.destroyWindow(winname)

5. cv2.destroyAllWindows()

功能：销毁所有由 OpenCV 创建的窗口。

cv2.destroyAllWindows()

6. cv2.resizeWindow(windowName, width, height)

功能：修改已创建窗口的大小（仅 WINDOW_NORMAL 类型窗口可调整）。

cv2.resizeWindow(winname, width, height)

7. cv2.moveWindow(windowName, x, y)

功能：移动窗口位置到指定屏幕坐标。

cv2.moveWindow(winname, x, y)

8. cv2.setWindowProperty(windowName, prop_id, prop_value)

功能：设置窗口的特性，如是否全屏显示。

cv2.setWindowProperty(winname, prop_id, prop_value)

常用属性：

属性ID	说明	可选值
cv2.WND_PROP_FULLSCREEN	全屏显示属性	cv2.WINDOW_FULLSCREEN / cv2.WINDOW_NORMAL
cv2.WND_PROP_AUTOSIZE	自动调整大小	0（禁用）/1（启用）
cv2.WND_PROP_ASPECT_RATIO	是否保持宽高比	0/1

示例

示例 1：最简单的图像显示

import cv2

# 读取图像
img = cv2.imread("test.jpg")

# 显示图像（自动创建窗口）
cv2.imshow("Simple Display", img)

# 等待按键并关闭
cv2.waitKey(0)
cv2.destroyAllWindows()

示例 2：创建可调整大小的窗口

import cv2

img = cv2.imread("test.jpg")

# 创建可调整窗口
cv2.namedWindow("Adjustable Window", cv2.WINDOW_NORMAL)
cv2.imshow("Adjustable Window", img)

# 改变窗口大小
cv2.resizeWindow("Adjustable Window", 800, 600)
cv2.waitKey(0)
cv2.destroyAllWindows()

示例 3：全屏显示图像

import cv2

img = cv2.imread("test.jpg")

cv2.namedWindow("FullScreen", cv2.WINDOW_NORMAL)
cv2.setWindowProperty("FullScreen", cv2.WND_PROP_FULLSCREEN, cv2.WINDOW_FULLSCREEN)
cv2.imshow("FullScreen", img)

cv2.waitKey(0)
cv2.destroyAllWindows()

示例 4：循环显示与退出条件

import cv2

img = cv2.imread("test.jpg")
cv2.namedWindow("Loop Display", cv2.WINDOW_AUTOSIZE)

while True:
    cv2.imshow("Loop Display", img)
    key = cv2.waitKey(10) & 0xFF
    if key == ord('q'):  # 按下 q 键退出
        break

cv2.destroyAllWindows()

示例 5：多个窗口显示

import cv2

img = cv2.imread("test.jpg")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)

cv2.imshow("Original", img)
cv2.imshow("Gray", gray)

cv2.moveWindow("Original", 100, 100)
cv2.moveWindow("Gray", 600, 100)

cv2.waitKey(0)
cv2.destroyAllWindows()

总结

功能	函数	注意事项
创建窗口	cv2.namedWindow()	在 imshow() 前创建才能设置类型
调整大小	cv2.resizeWindow()	仅对 WINDOW_NORMAL 有效
移动窗口	cv2.moveWindow()	可用于多窗口排版
设置全屏	cv2.setWindowProperty()	可切换全屏与普通模式
键盘交互	cv2.waitKey()	必须调用才能刷新界面
关闭窗口	cv2.destroyWindow() / destroyAllWindows()	释放资源