ScreenCapApiV4 接口文档¶

简介¶

简述：该模块提供Windows平台下多窗口捕获与操作的Python接口，支持获取窗口句柄、提取窗口画面为OpenCV格式图像、移动指定窗口位置，可满足多窗口的屏幕内容采集需求。

在RflySim无人机仿真任务中，仿真可视化窗口、各类任务调试窗口通常同时存在，很多基于机器视觉的无人机自主任务开发需要直接从仿真窗口获取实时画面，而非通过相机传感器通道采集。该模块适配Windows系统的窗口机制，支持同时枚举采集多个目标窗口的画面，输出符合OpenCV处理标准的图像格式，方便开发人员直接对接各类视觉检测、识别算法，适用于多窗口仿真场景下的屏幕视觉抓取、仿真演示窗口布局调整等任务，是RflySim平台计算机视觉开发流程中获取仿真画面的常用工具模块。

快速开始¶

以下示例获取第一个 RflySim3D 窗口的句柄和窗口信息，然后持续抓取并显示其画面。

参考例程：[RflySim安装路径]\RflySimAPIs\8.RflySimVision\1.BasicExps\1-VisionCtrlDemos\e5_ScreenCapAPI\1-ShootBall

import cv2
import ScreenCapApiV4 as sca


windowHandles = sca.getWndHandls()
if not windowHandles:
    raise RuntimeError("未找到 RflySim3D 窗口")

windowInfo = sca.getHwndInfo(windowHandles[0])

while True:
    imageBgr = sca.getCVImg(windowInfo)
    cv2.imshow("RflySim3D", imageBgr)
    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

环境与依赖¶

Python 环境：>= 3.8.10
依赖库：ctypes、cv2、d3dshot、numpy、re、sys、warnings、win32con、win32gui、win32ui
前置准备：调用此接口前，需要确保系统支持屏幕捕获功能，且已正确导入RflySimSDK.vision模块。

核心接口说明¶

该模块 ScreenCapApiV4.py 包含了配置变量、辅助函数及核心业务类。

全局常量与枚举定义¶

本节列出模块中所有可直接引用的全局常量和枚举定义。

独立常量¶

变量名	类型	值	说明
`_RFLYSIM3D_WINDOW_TITLE`	`re.Pattern`	`^RflySim3D(?:\s.*)?-(\d+)$`	匹配 `RflySim3D-0` 和 `RflySim3D UE4 Full v5.01-0` 等标题，并提取末尾窗口编号。

全局/独立函数¶

`window_enumeration_handler(hwnd, window_entries)`¶

功能说明：Windows 窗口枚举回调函数。仅收集类名为 UnrealWindow、当前可见且标题符合 _RFLYSIM3D_WINDOW_TITLE 规则的 RflySim3D 窗口。 参数列表：

hwnd: 当前枚举到的窗口句柄
window_entries: 结果列表；每个元素为 (窗口编号, 窗口句柄, 窗口标题) 元组

返回值：

无（返回非零值表示继续枚举窗口）

异常：无

`getWndHandls()`¶

功能说明：枚举当前可见的 RflySim3D 窗口，按标题末尾的数字编号升序排列，并返回对应句柄。若多个窗口使用相同编号，函数会发出 RuntimeWarning；相同编号之间保留 EnumWindows 的原始顺序，调用方应自行核对窗口身份。 参数列表：无 返回值：

list[int]: 按数字编号排序后的 RflySim3D 窗口句柄列表

异常：无

`getHwndInfo(hWnd)`¶

功能说明：根据指定窗口句柄，获取该窗口的位置、尺寸等基础信息，用于后续窗口截图操作 参数列表：

hWnd: 目标窗口的句柄

返回值：

dict: 包含窗口句柄、位置坐标、尺寸大小的窗口信息字典

异常：无

`getCVImg(wInfo)`¶

功能说明：对指定信息的窗口进行截图，将截图转换为OpenCV格式的BGR图像 参数列表：

wInfo: 包含窗口句柄、位置、尺寸的窗口信息字典，由getHwndInfo获取

返回值：

numpy.ndarray: OpenCV格式的BGR窗口截图数组

异常：无

`getCVImgList(wInfoList)`¶

功能说明：批量对多个窗口进行截图，批量转换为OpenCV格式图像 参数列表：

wInfoList: 多个窗口信息组成的列表，每个元素为单窗口信息字典

返回值：

list[numpy.ndarray]: 对应每个窗口的OpenCV格式截图组成的列表

异常：无

`moveWd(hwd, x=0, y=0, topMost=False)`¶

功能说明：移动指定窗口到屏幕指定坐标位置，可选择将窗口设置为顶层置顶显示 参数列表：

hwd: 目标窗口的句柄
x: 窗口左上角在屏幕中的目标X坐标，默认为0
y: 窗口左上角在屏幕中的目标Y坐标，默认为0
topMost: 是否将窗口设置为顶层置顶，默认为False不置顶

返回值：

无

异常：无

`clearHWND(wInfo)`¶

功能说明：释放窗口截图操作中占用的GDI资源，避免资源泄漏 参数列表：

wInfo: 已完成截图操作的窗口信息字典，内部存储了GDI资源句柄需要释放

返回值：

无

异常：无

`WinInfo` 类¶

用于存储Windows窗口截图相关的资源与尺寸信息，为屏幕捕获功能提供基础数据结构。

`init(hWnd, width, height, saveDC, saveBitMap, mfcDC, hWndDC)`¶

功能说明：初始化窗口信息对象，存储窗口截图所需的各类资源句柄与尺寸参数 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`hWnd`	`int`	是	-	目标窗口的句柄
`width`	`int`	是	-	捕获区域的宽度（像素）
`height`	`int`	是	-	捕获区域的高度（像素）
`saveDC`	`int`	是	-	兼容设备上下文的句柄
`saveBitMap`	`int`	是	-	位图对象的句柄
`mfcDC`	`int`	是	-	MFC设备上下文的句柄
`hWndDC`	`int`	是	-	目标窗口的设备上下文句柄

返回值 (Returns)：

WinInfo 实例对象

异常 (Raises)：

无

进阶用法示例¶

以下示例获取两个 RflySim3D 窗口，调整其屏幕位置，并通过 getCVImgList 批量抓取两个窗口的图像。

参考例程：[RflySim安装路径]\RflySimAPIs\8.RflySimVision\1.BasicExps\1-VisionCtrlDemos\e5_ScreenCapAPI\2-CrossRing

import cv2
import ScreenCapApiV4 as sca


windowHandles = sca.getWndHandls()
if len(windowHandles) < 2:
    raise RuntimeError("该示例需要两个 RflySim3D 窗口")

# 将两个窗口并排放置
nextX, nextY = sca.moveWd(windowHandles[0], 0, 0, True)
sca.moveWd(windowHandles[1], nextX, 0, False)

windowInfoList = [
    sca.getHwndInfo(windowHandles[0]),
    sca.getHwndInfo(windowHandles[1]),
]

while True:
    imageList = sca.getCVImgList(windowInfoList)
    for index, imageBgr in enumerate(imageList):
        cv2.imshow("RflySim3D-" + str(index), imageBgr)
    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

注意事项与避坑指南¶

窗口状态：getHwndInfo() 遇到客户区宽高同时为 0 的最小化窗口会直接退出；getCVImg() 和 getCVImgList() 在句柄失效时也会退出。采集期间不要最小化或关闭目标窗口。
窗口标题规则：getWndHandls() 只接受以 RflySim3D 开头、以 -数字编号 结尾的可见 UnrealWindow，其他 UE 窗口不会出现在返回列表中。
重复编号：多个可见窗口共用同一编号时会触发 RuntimeWarning，此时排序不能区分主视角和观察者窗口，应结合窗口标题和句柄人工确认。
资源释放：当前默认 isNewUE=True，使用 d3dshot 捕获；clearHWND() 只在旧版 Windows GDI 捕获路径中释放 DC 和位图资源。

更新日志¶

2026-09-11: 🐛 fix: 修复 RflySim3D 窗口识别与排序 [P2]
2024-08-05: fix：增加HTML版API注释
2024-07-17: fix：更新VisionCaptureApi接口API
2023-10-23: feat: Add all Python common labs

ScreenCapApiV4 接口文档¶

简介¶

快速开始¶

环境与依赖¶

核心接口说明¶

全局常量与枚举定义¶

独立常量¶

全局/独立函数¶

window_enumeration_handler(hwnd, window_entries)¶

getWndHandls()¶

getHwndInfo(hWnd)¶

getCVImg(wInfo)¶

getCVImgList(wInfoList)¶

moveWd(hwd, x=0, y=0, topMost=False)¶

clearHWND(wInfo)¶

WinInfo 类¶

__init__(hWnd, width, height, saveDC, saveBitMap, mfcDC, hWndDC)¶

进阶用法示例¶

注意事项与避坑指南¶

更新日志¶

`window_enumeration_handler(hwnd, window_entries)`¶

`getWndHandls()`¶

`getHwndInfo(hWnd)`¶

`getCVImg(wInfo)`¶

`getCVImgList(wInfoList)`¶

`moveWd(hwd, x=0, y=0, topMost=False)`¶

`clearHWND(wInfo)`¶

`WinInfo` 类¶

`init(hWnd, width, height, saveDC, saveBitMap, mfcDC, hWndDC)`¶