VisionCaptureApi 接口文档¶

简介¶

简述：本文件定义了RflySim无人机仿真平台视觉感知模块所需的数据结构与API类，为Python端向UE4仿真环境请求相机图像、各类传感器数据提供了基础交互支撑。

在RflySim仿真中，视觉任务是无人机自主导航、目标检测等智能算法开发的核心场景，需要Python端与UE4端完成参数交互与数据传输。本模块定义了用于向UE4发送相机参数设置、图像请求请求的结构体，以及来自CopterSim的IMU数据、距离传感器数据等各类感知数据的封装结构，同时提供了核心的VisionCaptureApi类实现Python端从UE4仿真环境获取仿真图像。它适用于开发基于视觉的无人机仿真算法，为仿真环境的视觉感知数据交互提供了统一的规范接口，可支持单目、多目相机仿真数据获取，结合IMU、距离传感器信息可完成多传感器融合仿真任务。

快速开始¶

最简可用示例，复制后修改最少配置即可运行。

from RflySimSDK.vision.VisionCaptureApi import VisionCaptureApi, VisionSensorReqNew

# 1. 初始化视觉捕获API，默认连接本地RflySim仿真环境
vision_api = VisionCaptureApi(ip="127.0.0.1")

# 2. 创建一个新的视觉传感器请求对象，默认请求RGB图像和位姿数据
sensor_req = VisionSensorReqNew()

# 3. 将视觉传感器请求添加到捕获列表
try:
    vision_api.addVisSensor(sensor_req)
except Exception as e:
    print(f"添加视觉传感器失败: {e}")

# 4. 欧拉角转四元数示例：滚转0度，俯仰0度，偏航90度，转换为四元数
roll = 0
pitch = 0
yaw = 90
quat = vision_api.euler2quat(roll, pitch, yaw, copter="iris", coordinate_frame="global")
print(f"转换得到的四元数: {quat}")

环境与依赖¶

Python 环境：>= 3.8.10
依赖库：Open3DShow、copy、ctrl.IpManager、cv2、email、json、math、mmap、numpy、os、platform、psutil、re、socket、struct、subprocess、sys、threading、time、warnings
前置准备：调用此接口前，需要确保已经正确导入RflySimSDK的vision模块。

核心接口说明¶

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

全局常量与枚举定义¶

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

独立常量¶

无

全局/独立函数¶

无

`Queue` 类¶

提供基础队列数据结构，用于先进先出（FIFO）形式的元素存储与管理。

`init()`¶

功能说明：初始化空队列实例 参数列表 (Args)：无参数 返回值 (Returns)：

Queue 实例对象

异常 (Raises)：无

`enqueue(item)`¶

功能说明：将元素添加到队列尾部 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`item`	`任意类型`	是	-	待添加到队列的元素

返回值 (Returns)：

无

异常 (Raises)：无

`dequeue()`¶

功能说明：移除并返回队列头部元素 参数列表 (Args)：无参数 返回值 (Returns)：

队列头部元素

异常 (Raises)：无

`is_empty()`¶

功能说明：判断当前队列是否为空 参数列表 (Args)：无参数 返回值 (Returns)：

bool: 队列为空返回True，否则返回False

异常 (Raises)：无

`size()`¶

功能说明：获取队列中当前存储的元素数量 参数列表 (Args)：无参数 返回值 (Returns)：

int: 队列元素数量

异常 (Raises)：无

示例：

from RflySimSDK.vision import Queue

# 创建队列并添加元素
q = Queue()
q.enqueue("first frame")
q.enqueue("second frame")

# 查看队列大小
print(q.size())  # 输出 2

# 取出队列元素
item = q.dequeue()
print(item)  # 输出 first frame

# 判断是否为空
print(q.is_empty())  # 输出 False

`RflyTimeStmp` 类¶

用于管理无人机视觉数据时间戳的工具类，可存储和更新时间戳数值，配合视觉捕获模块使用。

`init(iv)`¶

功能说明：初始化 RflyTimeStmp 实例，设置初始时间戳数值 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`iv`	任意数值类型	是	-	初始时间戳数值

返回值 (Returns)：

RflyTimeStmp 实例对象

异常 (Raises)：无

`Update(iv)`¶

功能说明：更新存储的时间戳数值为新的输入值 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`iv`	任意数值类型	是	-	待更新的新时间戳数值

返回值 (Returns)：无 异常 (Raises)：无

示例：

from RflySimSDK.vision import RflyTimeStmp
# 初始化时间戳为0
ts = RflyTimeStmp(0)
# 更新时间戳为当前仿真时间12.34
ts.Update(12.34)

`VisionSensorReq` 类¶

用于向UE4仿真环境请求并设置相机参数的C++结构体对应Python类，可在RflySim无人机视觉仿真中配置视觉传感器参数。

`init()`¶

功能说明：初始化VisionSensorReq类实例，所有参数成员按照结构体默认定义创建 参数列表 (Args)：无参数 返回值 (Returns)：

VisionSensorReq 实例对象

异常 (Raises)：无

示例：

from RflySimSDK.vision import VisionSensorReq
# 创建视觉传感器参数请求对象
sensor_req = VisionSensorReq()
# 配置目标飞机ID
sensor_req.TargetCopter = 1
# 设置相机安装位置
sensor_req.SensorPosXYZ = [0, 0, 0.1]

`VisionSensorReqNew` 类¶

该类是用于向UE4仿真环境发送请求、设置视觉传感器参数的C++风格结构体，在RflySim无人机视觉仿真中用于定义视觉传感器的配置信息。

`init()`¶

功能说明：初始化VisionSensorReqNew实例对象 参数列表 (Args)：无参数 返回值 (Returns)：

VisionSensorReqNew 实例对象

异常 (Raises)：无

`imuDataCopter` 类¶

用于从CopterSim接收无人机IMU传感器数据的数据结构体，存储校验位、消息序号、时间戳、加速度计数据和陀螺仪数据。

`init(imu_name, node=None)`¶

功能说明：初始化imuDataCopter实例，设置IMU数据话题名称和ROS节点 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`imu_name`	`str`	否	`"/rflysim/imu"`	IMU数据的ROS话题名称
`node`	`Any`	否	`None`	用于发布IMU数据的ROS节点对象

返回值 (Returns)：

imuDataCopter 实例对象

异常 (Raises)：

无

`AlignTime(img_time)`¶

功能说明：将IMU数据时间戳与图像时间戳进行时间对齐，匹配对应时刻的IMU数据 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`img_time`	`double`	是	-	需要对齐的图像时间戳

返回值 (Returns)：

对齐后匹配的IMU数据

异常 (Raises)：

无

`Imu2ros(node=None)`¶

功能说明：将当前IMU数据转换为ROS格式并发布 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`node`	`Any`	否	`None`	用于发布IMU数据的ROS节点对象，若为None则使用初始化时设置的节点

返回值 (Returns)：

无

异常 (Raises)：

无

示例：

from RflySimSDK.vision import imuDataCopter
# 初始化IMU数据接收对象
imu = imuDataCopter()
# 对图像时间戳123.45进行时间对齐，获取对应时刻IMU
aligned_imu = imu.AlignTime(123.45)

`DistanceSensor` 类¶

测距传感器功能类，用于在RflySim无人机仿真中实现距离传感器相关的仿真逻辑。

`init()`¶

功能说明：初始化DistanceSensor类实例 参数列表 (Args)：无 返回值 (Returns)：

DistanceSensor 实例对象

异常 (Raises)：无

`SensorReqCopterSim` 类¶

这是一个用于向UE4发送传感器数据请求的结构体类，对应C++结构体定义，主要在RflySim无人机仿真中传递传感器请求配置信息。

`init()`¶

功能说明：初始化空的传感器请求结构体实例 参数列表 (Args)：无 返回值 (Returns)：

SensorReqCopterSim 实例对象

异常 (Raises)：无

`VisionCaptureApi` 类¶

这是Python端从UE4获取图像的API类。

`init(ip='127.0.0.1')`¶

功能说明：初始化视觉图像捕获API实例，建立与UE4端的图像服务连接。 参数列表 (Args)：

参数名	类型	默认值	说明
ip	`str`	`127.0.0.1`	UE4图像服务所在的IP地址，本地运行时使用默认本地回环地址即可

返回值 (Returns)：无 异常 (Raises)：无

`euler2quat(r, p, y, copter, coordinate_frame="global")`¶

功能说明：将欧拉角转换为四元数，支持不同载具和坐标系下的转换 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
r	`Any`	是	无	滚转角欧拉角分量
p	`Any`	是	无	俯仰角欧拉角分量
y	`Any`	是	无	偏航角欧拉角分量
copter	`str`	是	无	载具类型标识
coordinate_frame	`Any`	否	"global"	坐标系类型，默认为全局坐标系

返回值 (Returns)：转换后的四元数 异常 (Raises)：无

`addVisSensor(vsr=VisionSensorReq())`¶

功能说明：向视觉传感器列表中添加一个新的旧版本VisionSensorReq视觉传感器请求结构体 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
vsr	`Any`	否	`VisionSensorReq()`	待添加的旧版本视觉传感器请求结构体

返回值 (Returns)：无 异常 (Raises)：Exception - 添加失败时抛出异常

`addVisSensor(vsr=VisionSensorReqNew())`¶

功能说明：向视觉传感器列表中添加一个新的新版本VisionSensorReqNew视觉传感器请求结构体 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
vsr	`Any`	否	`VisionSensorReqNew()`	待添加的新版本视觉传感器请求结构体

返回值 (Returns)：无 异常 (Raises)：Exception - 添加失败时抛出异常

`sendReqToCopterSim(srcs=SensorReqCopterSim(), copterID=1, IP="127.0.0.1")`¶

功能说明：向CopterSim发送SensorReqCopterSim类型UDP请求消息，请求获取传感器数据，通过copterID指定请求的目标CopterSim实例索引 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
srcs	`Any`	否	`SensorReqCopterSim()`	传感器请求结构体
copterID	`Any`	否	1	目标载具的ID，指定请求的CopterSim实例索引
IP	`Any`	否	"127.0.0.1"	目标CopterSim所在主机的IP地址

返回值 (Returns)：无 异常 (Raises)：无

`sendImuReqCopterSim(copterID=1, IP="127.0.0.1", freq=200)`¶

功能说明：向CopterSim发送IMU数据请求指令，该函数会初始化一个线程用于监听接收IMU数据其中实际端口 = 基础端口 + 载具ID - 1 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
copterID	`Any`	否	1	目标载具的ID
IP	`Any`	否	"127.0.0.1"	请求发送目标主机的IP地址
freq	`Any`	否	200	请求的IMU数据发送频率

返回值 (Returns)：无 异常 (Raises)：无

`sendImuReqClient(copterID=1, IP="127.0.0.1", freq=200)`¶

功能说明：向CopterSim发送IMU数据请求指令，实际端口 = 基础端口 + 载具ID - 1 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
copterID	`Any`	否	1	目标载具的ID
IP	`Any`	否	"127.0.0.1"	请求发送目标主机的IP地址
freq	`Any`	否	200	请求的IMU数据发送频率

返回值 (Returns)：无 异常 (Raises)：无

`sendImuReqServe(copterID=1)`¶

功能说明：向CopterSim发送IMU数据请求指令，该函数会初始化一个线程用于监听接收IMU数据，其中实际端口 = 基础端口 + 载具ID - 1 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
copterID	`Any`	否	1	目标载具的ID

返回值 (Returns)：无 异常 (Raises)：无

`getIMUDataLoop(copterID)`¶

功能说明：循环获取指定载具的IMU数据，作为IMU监听线程的工作函数 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
copterID	`Any`	是	无	目标获取数据的载具ID

返回值 (Returns)：无 异常 (Raises)：无

`get_all_ip()`¶

功能说明：获取本机所有可用的网络接口IP地址 参数列表 (Args)：无参数 返回值 (Returns)：本机所有IP地址组成的列表 异常 (Raises)：无

`isIpLocal(IP)`¶

功能说明：判断给定IP地址是否为本机IP地址 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
IP	`Any`	是	无	待判断的IP地址

返回值 (Returns)：bool，如果是本机IP返回True，否则返回False 异常 (Raises)：无

`StartTimeStmplisten()`¶

功能说明：启动监听线程，监听20005端口以获取各个载具ID对应的Rfly时间戳 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无

`getTimeStmp(CopterID=1)`¶

功能说明：获取指定载具ID对应的最新Rfly时间戳 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
CopterID	`Any`	否	1	目标载具ID

返回值 (Returns)：指定载具对应的最新Rfly时间戳 异常 (Raises)：无

`endTimeStmplisten()`¶

功能说明：结束时间戳监听线程，停止监听时间戳数据 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无

`TimeStmploop()`¶

功能说明：时间戳监听线程的循环工作函数，持续接收处理CopterSim发送的时间戳数据 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无

`sendUpdateUEImage(vs=VisionSensorReq(), windID=0, IP="")`¶

功能说明：向UE4发送视觉传感器图像更新请求 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
vs	`Any`	否	`VisionSensorReq()`	视觉传感器请求结构体
windID	`Any`	否	0	窗口ID标识
IP	`Any`	否	""	目标UE4所在主机的IP地址，为空则自动判断

返回值 (Returns)：无 异常 (Raises)：Exception - 请求发送失败时抛出异常

`sendUpdateUEImaged(vs=VisionSensorReqNew(), windID=0, IP="")`¶

功能说明：向指定窗口的RflySim3D更新视觉传感器配置 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
vs	-	否	`VisionSensorReqNew()`	视觉传感器请求配置对象
windID	-	否	`0`	RflySim3D窗口索引
IP	-	否	`""`	目标IP地址，为空使用默认地址

返回值 (Returns)：无返回值 异常 (Raises)：Exception - 发送过程出错时抛出