VisionCaptureApi 接口文档¶

简介¶

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

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

快速开始¶

以下示例从 Config.json 加载传感器配置，向 RflySim3D 发送取图请求，并显示收到的各路图像。

参考例程：[RflySim安装路径]\RflySimAPIs\8.RflySimVision\0.ApiExps\1-UsageAPI\0.ConfigJsonAPI

import sys

import cv2
import VisionCaptureApi


vis = VisionCaptureApi.VisionCaptureApi()
vis.jsonLoad()

for sensor in vis.VisSensor:
    print("SeqID:", sensor.SeqID)
    print("SendProtocol:", sensor.SendProtocol)

if not vis.sendReqToUE4():
    sys.exit(0)
vis.startImgCap()

while True:
    for index in range(len(vis.hasData)):
        if vis.hasData[index]:
            cv2.imshow("Img" + str(index), vis.Img[index])
    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

环境与依赖¶

Python 环境：>= 3.8.10
依赖库：copy、ctrl.IpManager、cv2、email、ipaddress、json、math、mmap、numpy、os、platform、psutil、re、socket、struct、subprocess、sys、threading、time、warnings
可选依赖：Open3DShow 仅在 Windows 或 WSL 下尝试导入；不可用时仍可接收点云，但 SensorPreview() 不创建点云显示窗口。
前置准备：调用此接口前，需要确保已经正确导入RflySimSDK的vision模块。

核心接口说明¶

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

全局常量与枚举定义¶

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

独立常量¶

名称	默认值	说明
`SENSOR_REQ_STRUCT`	`<4H4B6f`	CopterSim 传感器请求的小端无填充协议，共 36 字节。
`IMU_DATA_STRUCT`	`<iid6f`	IMU 返回协议，共 40 字节。
`ODOM_DATA_STRUCT`	`<IIdIHH3d4f3f3f`	Odom 返回协议，共 88 字节，四元数顺序为 `w, x, y, z`。
`IMU_DATA_CHECKSUM`	`1234567898`	IMU 包校验码。
`ODOM_DATA_CHECKSUM`	`1234567888`	Odom 包校验码。
`ODOM_FRAME_NED_FRD`	`1`	Odom 线数据采用 NED/FRD 坐标约定。
`ODOM_POSITION_VALID`	`1 << 0`	位置字段有效位。
`ODOM_ORIENTATION_VALID`	`1 << 1`	姿态字段有效位。
`ODOM_LINEAR_VELOCITY_VALID`	`1 << 2`	线速度字段有效位。
`ODOM_ANGULAR_VELOCITY_VALID`	`1 << 3`	角速度字段有效位。
`ODOM_DISCONTINUITY`	`1 << 5`	Odom 不连续标志；置位时重置该飞机的初始变换。
`udpDecodeMode`	`2`	`1` 为收包与解码同线程，`2` 为收包、解码双线程。
`isPrintUdpStat`	`0`	是否打印 UDP 收包与丢帧统计。
`isUseRawUdpTimestamp`	`False`	ROS 消息是否直接使用 UDP 包内的仿真相对时间戳。
`publishCopterSimClock`	`False`	是否由单个 ROS1 仿真发布 CopterSim `/clock`；启用时要求 `isUseRawUdpTimestamp=True`。

全局/独立函数¶

无

`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)

`imuDataCopterSnapshot` 类¶

按飞机保存的一帧 IMU 数据副本。实例包含 checksum、seq、仿真相对时间 timestmp、三轴加速度 acc、三轴角速度 rate、对齐后的 imuStmp 和时间基准 rflyStartStmp。getImuData() 返回该对象的深拷贝，调用方修改它不会影响接收线程中的缓存。

`init()`¶

功能说明：将数值字段初始化为 0，数组初始化为三个浮点 0，校验码初始化为 IMU_DATA_CHECKSUM。

参数列表 (Args)：无

返回值 (Returns)：imuDataCopterSnapshot 实例

`odomDataCopter` 类¶

按飞机保存的一帧 CopterSim Odom 数据，保持线协议的 NED/FRD 坐标约定。主要字段包括 seq、timestmp、copterID、frameType、flags、position[3]、quaternion[4]（w, x, y, z）、linearVelocity[3]、angularVelocity[3]、odomStmp 和 rflyStartStmp。

`init()`¶

功能说明：以单位四元数和零位置、零速度初始化 Odom 快照，默认 frameType=ODOM_FRAME_NED_FRD、checksum=ODOM_DATA_CHECKSUM。

参数列表 (Args)：无

返回值 (Returns)：odomDataCopter 实例

`DistanceSensor` 类¶

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

`init()`¶

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

DistanceSensor 实例对象

异常 (Raises)：无

`OpticalFlowSensor` 类¶

TypeID 10 光流数据容器，保存 time_usec、sensor_id、原始光流 flow_x/flow_y、角速度补偿后的 flow_comp_m_x/flow_comp_m_y、质量 quality、地面距离 ground_distance 以及 flow_rate_x/flow_rate_y。

`init()`¶

功能说明：将全部光流数据字段初始化为 0。quality 的协议范围为 0（不可用）至 255（最高质量），ground_distance 为负值时表示距离未知。

参数列表 (Args)：无

返回值 (Returns)：OpticalFlowSensor 实例

`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)：无

`sendOdomReqCopterSim(copterID=1, IP="127.0.0.1", freq=100, port=None)`¶

功能说明：启动或复用指定飞机的 IMU/Odom 共用 UDP 接收线程，将该飞机标记为独立 Odom 数据源，然后向 CopterSim 发送 sensorType=1 的 Odom 请求。

参数名	类型	默认值	说明
copterID	`int`	`1`	目标飞机 ID，必须大于等于 1。
IP	`str`	`127.0.0.1`	CopterSim 所在主机地址。
freq	`int`	`100`	请求频率，允许范围 1 至 1000 Hz。
port	`int \| None`	`None`	本地返回端口；默认使用 `31000 + copterID - 1`。

返回值 (Returns)：无

异常 (Raises)：参数越界或 RemotSendIP 不是有效 IPv4 地址时抛出 ValueError；端口绑定失败时由 socket 抛出 OSError。

`sendOdomReqClient(copterID=1, IP="127.0.0.1", freq=100, port=None)`¶

功能说明：只发送 Odom 请求，不创建接收线程。返回地址取 RemotSendIP；未设置时使用 127.0.0.1。调用方需要自行调用 startCopterSensorReceiver() 或管理接收端口。

参数含义、默认端口和校验范围与 sendOdomReqCopterSim() 相同。

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

功能说明：启动或复用指定飞机的共用接收线程，再向 CopterSim 发送 sensorType=0 的 IMU 请求。同一接收端口可同时识别 40 字节 IMU 包和 88 字节 Odom 包。

参数名	类型	默认值	说明
copterID	`int`	`1`	目标飞机 ID，必须大于等于 1。
IP	`str`	`127.0.0.1`	CopterSim 所在主机地址。
freq	`int`	`200`	请求频率，允许范围 1 至 1000 Hz。
port	`int \| None`	`None`	本地返回端口；默认使用 `31000 + copterID - 1`。

返回值 (Returns)：无

异常 (Raises)：参数越界或返回 IP 非法时抛出 ValueError；端口绑定失败时由 socket 抛出 OSError。

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

功能说明：只发送 IMU 请求，不创建接收线程。port、频率和返回 IP 的处理规则与 sendImuReqCopterSim() 相同。

返回值 (Returns)：无

`sendImuReqServe(copterID=1, port=None)`¶

功能说明：兼容旧调用的别名，直接转调 startCopterSensorReceiver(copterID, port)；它只启动接收端，不发送请求。

返回值 (Returns)：无

`startCopterSensorReceiver(copterID=1, port=None)`¶

功能说明：为 (copterID, port) 创建守护接收线程，或复用仍在运行的同键线程。接收 socket 绑定到 0.0.0.0，超时为 0.2 秒，并由 getIMUDataLoop() 同时分派 IMU 与 Odom 数据。

参数名	类型	默认值	说明
copterID	`int`	`1`	接收数据所属飞机 ID。
port	`int \| None`	`None`	监听端口，必须在 1 至 65535；默认按飞机 ID 计算。

返回值 (Returns)：无；相同接收器已运行时直接返回。

`getIMUDataLoop(copterID, udp_sensor=None, stop_event=None)`¶

功能说明：IMU/Odom 接收线程的内部循环。40 字节包按 IMU_DATA_STRUCT 解码，88 字节且校验码正确的包按 ODOM_DATA_STRUCT 解码；无效校验码、非有限数值、飞机 ID 或坐标类型不匹配的数据会被丢弃。

参数名	类型	默认值	说明
copterID	`int`	-	该接收线程对应的飞机 ID。
udp_sensor	`socket \| None`	`None`	接收 socket；为空时兼容使用 `self.udp_imu`。
stop_event	`threading.Event \| None`	`None`	单个接收线程的停止事件。

`getImuData(copterID=1)`¶

功能说明：线程安全地读取指定飞机最新的 IMU 快照。

返回值 (Returns)：已收到数据时返回 imuDataCopterSnapshot 的深拷贝，否则返回 None。

`getOdomData(copterID=1)`¶

功能说明：线程安全地读取指定飞机最新的 Odom 快照。接收端会拒绝重复、倒序和无不连续标记的回退帧，并对有效四元数归一化。

返回值 (Returns)：已收到数据时返回 odomDataCopter 的深拷贝，否则返回 None。

`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 - 发送过程出错时抛出

`sendUE4Cmd(cmd, windowID=-1)`¶

功能说明：向UE4发送自定义命令 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
cmd	-	是	无	要发送的命令内容
windowID	-	否	`-1`	目标RflySim3D窗口索引，-1表示发送给所有窗口

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

`sendReqToUE4(windID=0, IP="")`¶

功能说明：发送视觉传感器列表到RflySim3D，请求获取对应图像，通过windID指定发送请求的RflySim3D窗口索引 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
windID	-	否	`0`	RflySim3D目标窗口索引
IP	-	否	`""`	目标IP地址，为空使用默认地址

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

`setUdpDecodeMode(mode=2)`¶

功能说明：设置模块级 UDP 解码方式。mode=1 时由一个线程顺序收包和解码；mode=2 时接收线程负责重组完整帧，并通过有界队列交给独立解码线程，默认使用该模式。

参数名	类型	默认值	说明
mode	`int`	`2`	只允许 `1` 或 `2`。

返回值 (Returns)：无

异常 (Raises)：传入其他值时抛出 ValueError。

`img_udp_thrdNew(udpSok, idx, typeID)`¶

功能说明：UDP接收图像的线程工作函数，用于处理指定视觉传感器的图像UDP接收 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
udpSok	-	是	无	UDP套接字对象
idx	-	是	无	视觉传感器索引
typeID	-	是	无	传感器类型ID

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

`img_mem_thrd(idxList)`¶

功能说明：共享内存方式接收图像的线程工作函数，处理指定索引列表视觉传感器的图像接收 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
idxList	-	是	无	需要接收的视觉传感器索引列表

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

`startImgCap(isRemoteSend=False)`¶

功能说明：启动循环，从UE4接收图像。当isRemoteSend为True时，会将从内存获取的图像转发到UDP端口 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
isRemoteSend	-	否	`False`	是否开启图像远程转发，开启后会将图像从共享内存转发到UDP端口

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

`sendImgUDPNew(idx)`¶

功能说明：将指定索引视觉传感器的图像通过新UDP协议发送 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
idx	-	是	无	视觉传感器索引

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

`sendImgBuffer(idx, data)`¶

功能说明：发送指定索引视觉传感器的图像缓冲区数据 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
idx	-	是	无	视觉传感器索引
data	-	是	无	要发送的图像数据缓冲区

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

`jsonLoad(ChangeMode=-1, jsonPath="")`¶

功能说明：加载配置JSON文件，创建用于图像采集的相机列表。如果ChangeMode>=0，会将发送协议的第一项SendProtocol[0]设置为ChangeMode以修改图像传输方式 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
ChangeMode	-	否	`-1`	传输模式修改值，大于等于0时会覆盖配置中的传输模式
jsonPath	-	否	`""`	配置JSON文件的路径，为空使用默认路径

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

`dictLoad(jsData, ChangeMode=-1)`¶

功能说明：jsonLoad方法的封装，提供直接从内存中读取dict类型的传感器数据，数据组织方式和jsonLoad方法中JSON文件的组织方式一致 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
jsData	-	是	无	内存中存储的传感器配置字典数据
ChangeMode	-	否	`-1`	传输模式修改值，大于等于0时会覆盖配置中的传输模式

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

`stopRun()`¶

功能说明：设置全局停止标志，关闭所有 CopterSim IMU/Odom 接收 socket，并等待相关线程结束。 参数列表 (Args)：无参数 返回值 (Returns)：无返回值 异常 (Raises)：无

`stopCopterSensorReceiver(copterID=None, port=None)`¶

功能说明：按飞机 ID、端口或二者组合停止接收器；两个参数都为空时停止全部 CopterSim IMU/Odom 接收器。方法先从注册表移除匹配项，再设置停止事件、关闭 socket，并等待非当前线程最多 1 秒。

参数名	类型	默认值	说明
copterID	`int \| None`	`None`	仅停止该飞机的接收器。
port	`int \| None`	`None`	仅停止该端口的接收器。

返回值 (Returns)：无

`SensorPreview(seq_id=-1)`¶

功能说明：预览指定序号的视觉传感器采集的图像 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
seq_id	-	否	`-1`	要预览的视觉传感器序号，-1表示预览所有传感器

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

进阶用法示例¶

以下示例请求激光雷达点云数据，并将 vis.Img[0] 中的新点云持续更新到 Open3D 窗口。

参考例程：[RflySim安装路径]\RflySimAPIs\8.RflySimVision\0.ApiExps\1-UsageAPI\3.PointCloudAPI\2.LidarAPIPointCloudDemo

import sys
import time

import Open3DShow
import VisionCaptureApi


show3d = Open3DShow.Open3DShow()
vis = VisionCaptureApi.VisionCaptureApi()

vis.jsonLoad()
if not vis.sendReqToUE4():
    sys.exit(0)
vis.startImgCap()
show3d.CreatShow(0)

lastTime = time.time()
while True:
    lastTime += 1 / 10.0
    sleepTime = lastTime - time.time()
    if sleepTime > 0:
        time.sleep(sleepTime)
    else:
        lastTime = time.time()

    if vis.hasData[0]:
        show3d.UpdateShow(vis.Img[0])
        vis.hasData[0] = False

注意事项与避坑指南¶

重复添加视觉传感器问题：多次调用addVisSensor时需保证输入的sensor_id全局唯一，重复ID会导致仿真端传感器覆盖，最终获取到的视觉数据会出现错乱。
异步数据缓存溢出：使用自定义队列缓存IMU或视觉数据时，需要定期清理旧数据，长时间运行会导致队列累积占用大量内存，可以通过判断队列大小，超出阈值后弹出队首旧数据。
跨主机连接IP检测：调用isIpLocal检测IP属性后再建立连接，如果仿真端运行在非本地主机，需要确认IP端口权限开放，默认端口会被远程防火墙拦截导致请求超时。
时间对齐前提条件：调用imuDataCopter.AlignTime之前需要先完成时间戳初始化，未调用RflyTimeStmp.Update更新参考时间戳会导致对齐结果偏差，引发SLAM位姿跳变。

更新日志¶

2026-09-11: 🐛 fix: 修复视觉帧与里程计时间不同步问题 [P0]
2026-08-06: 时间基准初始化和 imgStmp 更新移入“解码成功”分支，每帧执行
2026-03-03: feat：SDK增加IP处理机制，兼容本地版上云
2026-02-02: 增加深度转点云的odom发布
2026-02-02: fix：优化协议
2026-02-01: fix：注释路径打印
2026-01-31: fix: 更新深度转点云协议
2026-01-31: fix: 更新深度转点云的通信协议
2026-01-23: 对话题/Depth_Cloud 添加对齐时间戳
2026-01-22: Merge branch 'master' of http://rflysim.synology.me:8418/FeisiLab/RflySimSDK
2026-01-22: 更改ROS 输出的IMU坐标系方向，使接口输出的始终为FLU坐标系，更改前按照FRD—> FLU 转换，但是平台的IMU 角速度符合FRD系，但是线加速度不符合FRD系，而是BLD
2025-12-12: fix: 优化图像时间戳同步机制，解决Windows下的图像时间戳不同步bug
2025-12-08: 更改平台odom数据在0模式下 local 系下平移从FRD->FLU 变更
2025-12-07: fix: 新增激光雷达的相对位置传输数据
2025-12-04: fix: 修复点云传感器问题
2025-09-30: 解决鱼眼相机在UDP模模式下的bug
2025-09-29: ROS2 深度转点云的seq 变量已经被取消，接口需要适配

VisionCaptureApi 接口文档¶

简介¶

快速开始¶

环境与依赖¶

核心接口说明¶

全局常量与枚举定义¶

独立常量¶

全局/独立函数¶

Queue 类¶

__init__()¶

enqueue(item)¶

dequeue()¶

is_empty()¶

size()¶

RflyTimeStmp 类¶

__init__(iv)¶

Update(iv)¶

VisionSensorReq 类¶

__init__()¶

VisionSensorReqNew 类¶

__init__()¶

imuDataCopter 类¶

__init__(imu_name, node=None)¶

AlignTime(img_time)¶

Imu2ros(node=None)¶

imuDataCopterSnapshot 类¶

__init__()¶

odomDataCopter 类¶

__init__()¶

DistanceSensor 类¶

__init__()¶

OpticalFlowSensor 类¶

__init__()¶

SensorReqCopterSim 类¶

__init__()¶

VisionCaptureApi 类¶

__init__(ip='127.0.0.1')¶

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

addVisSensor(vsr=VisionSensorReq())¶

addVisSensor(vsr=VisionSensorReqNew())¶

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

sendOdomReqCopterSim(copterID=1, IP="127.0.0.1", freq=100, port=None)¶

sendOdomReqClient(copterID=1, IP="127.0.0.1", freq=100, port=None)¶

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

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

sendImuReqServe(copterID=1, port=None)¶

startCopterSensorReceiver(copterID=1, port=None)¶

getIMUDataLoop(copterID, udp_sensor=None, stop_event=None)¶

getImuData(copterID=1)¶

getOdomData(copterID=1)¶

get_all_ip()¶

isIpLocal(IP)¶

StartTimeStmplisten()¶

getTimeStmp(CopterID=1)¶

endTimeStmplisten()¶

TimeStmploop()¶

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

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

sendUE4Cmd(cmd, windowID=-1)¶

sendReqToUE4(windID=0, IP="")¶

setUdpDecodeMode(mode=2)¶

img_udp_thrdNew(udpSok, idx, typeID)¶

img_mem_thrd(idxList)¶

startImgCap(isRemoteSend=False)¶

sendImgUDPNew(idx)¶

sendImgBuffer(idx, data)¶

jsonLoad(ChangeMode=-1, jsonPath="")¶

dictLoad(jsData, ChangeMode=-1)¶

stopRun()¶

stopCopterSensorReceiver(copterID=None, port=None)¶

SensorPreview(seq_id=-1)¶

进阶用法示例¶

注意事项与避坑指南¶

更新日志¶

`Queue` 类¶

`init()`¶

`enqueue(item)`¶

`dequeue()`¶

`is_empty()`¶

`size()`¶

`RflyTimeStmp` 类¶

`init(iv)`¶

`Update(iv)`¶

`VisionSensorReq` 类¶

`init()`¶

`VisionSensorReqNew` 类¶

`init()`¶

`imuDataCopter` 类¶

`init(imu_name, node=None)`¶

`AlignTime(img_time)`¶

`Imu2ros(node=None)`¶

`imuDataCopterSnapshot` 类¶

`init()`¶

`odomDataCopter` 类¶

`init()`¶

`DistanceSensor` 类¶

`init()`¶

`OpticalFlowSensor` 类¶

`init()`¶

`SensorReqCopterSim` 类¶

`init()`¶

`VisionCaptureApi` 类¶

`init(ip='127.0.0.1')`¶

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

`addVisSensor(vsr=VisionSensorReq())`¶

`addVisSensor(vsr=VisionSensorReqNew())`¶

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

`sendOdomReqCopterSim(copterID=1, IP="127.0.0.1", freq=100, port=None)`¶

`sendOdomReqClient(copterID=1, IP="127.0.0.1", freq=100, port=None)`¶

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

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

`sendImuReqServe(copterID=1, port=None)`¶

`startCopterSensorReceiver(copterID=1, port=None)`¶

`getIMUDataLoop(copterID, udp_sensor=None, stop_event=None)`¶

`getImuData(copterID=1)`¶

`getOdomData(copterID=1)`¶

`get_all_ip()`¶

`isIpLocal(IP)`¶

`StartTimeStmplisten()`¶

`getTimeStmp(CopterID=1)`¶

`endTimeStmplisten()`¶

`TimeStmploop()`¶

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

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

`sendUE4Cmd(cmd, windowID=-1)`¶

`sendReqToUE4(windID=0, IP="")`¶

`setUdpDecodeMode(mode=2)`¶

`img_udp_thrdNew(udpSok, idx, typeID)`¶

`img_mem_thrd(idxList)`¶

`startImgCap(isRemoteSend=False)`¶

`sendImgUDPNew(idx)`¶

`sendImgBuffer(idx, data)`¶

`jsonLoad(ChangeMode=-1, jsonPath="")`¶

`dictLoad(jsData, ChangeMode=-1)`¶

`stopRun()`¶

`stopCopterSensorReceiver(copterID=None, port=None)`¶

`SensorPreview(seq_id=-1)`¶