UE4CtrlAPI 引擎控制
简介¶
简述：该文件定义了与 RflySim3D（UE4/UE5）通信的数据结构和控制接口，用于载具/物体状态查询、场景与相机控制、组件特效创建、攻防反馈及 SIL 数据交换。
在 RflySim 仿真平台中，UE4 提供高保真度的三维可视化与物理仿真环境。本模块封装了与 UE4 交互所需的全部数据协议结构，包括无人机位姿与碰撞数据请求（CoptReqData、reqVeCrashData）、物体状态查询（ObjReqData）、视觉传感器配置（VisionSensorReqNew、CameraData）以及 PX4 SIL 模型接口数据（PX4SILIntFloat）。通过这些结构体定义，开发者可在 Python 环境中精确构造与解析 UE4 通信报文，实现仿真场景中的传感器仿真、图像采集与硬件在环测试等高级功能。
快速开始¶
以下示例创建 UE 控制接口，将所有已打开的 RflySim3D 窗口切换到
Grasslands地图，并等待地图加载完成。
参考例程：[RflySim安装路径]\RflySimAPIs\3.RflySim3DUE\0.ApiExps\e6_RflySim3DCtrlAPI\1.UECtrlPy
import UE4CtrlAPI as UE4CtrlAPI
ue = UE4CtrlAPI.UE4CtrlAPI()
ue.sendUE4Cmd("RflyChangeMapbyName Grasslands")
ue.waitForMapLoaded("Grasslands")
print("Grasslands 地图已加载")
环境与依赖¶
- Python 环境：
>= 3.8.10 - 依赖库：
atexit、contextlib、copy、ctrl.IpManager、ctypes、cv2、math、numpy、os、platform、select、socket、struct、subprocess、sys、threading、time、typing、xml.etree.ElementTree - 前置准备：调用此接口前，必须先启动 Unreal Engine 仿真环境并确保 RflySim3D 或 UE4 应用程序正在运行。
核心接口说明¶
该模块 UE4CtrlAPI.py 包含了配置变量、辅助函数及核心业务类。
全局常量与枚举定义¶
本节列出模块中所有可直接引用的全局常量和枚举定义。
独立常量¶
| 名称 | 值 | 说明 |
|---|---|---|
UE4CtrlAPI.UE4_COMPONENT_OFF |
0 |
关闭组件。 |
UE4CtrlAPI.UE4_COMPONENT_ON |
1 |
开启或创建组件。 |
UE4CtrlAPI.UE4_LASER_COMPONENT_TYPE |
103 |
激光组件类型。 |
UE4CtrlAPI.UE4_LASER_MODE_TARGET_COPTER |
1 |
锁定目标飞机的激光模式。 |
UE4CtrlAPI.UE4_LASER_MODE_FORWARD |
2 |
向前发射的激光模式。 |
全局/独立函数¶
无
PX4SILIntFloat 类¶
输出到CopterSim DLL模型的SILints和SILFloats数据。该类封装了PX4仿真接口的整数和浮点数据传输结构，用于与CopterSim进行SIL（Software In the Loop）仿真数据交互。
数据结构定义：
struct PX4SILIntFloat{
int checksum; // 1234567897
int CopterID;
int inSILInts[8]; // 8个整数输入
float inSILFLoats[20]; // 20个浮点数输入
};
__init__(iv=None)¶
功能说明：初始化PX4SILIntFloat实例，设置校验码、CopterID及整数/浮点数组数据。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
iv |
any |
否 | None |
输入数据，用于初始化整数和浮点数组。若提供iterable，则前8个元素映射到inSILInts，接下来20个元素映射到inSILFLoats |
返回值 (Returns)：
PX4SILIntFloat实例对象
异常 (Raises)：
- 无
reqVeCrashData 类¶
UE4 中无人机碰撞检测数据结构体，用于接收和存储来自 Unreal Engine 4 仿真环境的碰撞事件信息。该结构体包含了碰撞时刻的飞机状态、碰撞对象信息以及空间位置等完整数据，适用于碰撞分析、事故回放和安全验证等场景。
__init__(iv=None)¶
功能说明：初始化碰撞数据结构体实例。可根据传入的字节数据或同类实例进行初始化，若未提供参数则创建空结构体。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
iv |
bytes | reqVeCrashData |
否 | None |
初始化数据，可为字节串或同类实例 |
返回值 (Returns)：
reqVeCrashData实例对象
异常 (Raises)：
- 无
CopyData(iv)¶
功能说明：从外部数据源复制碰撞数据到当前结构体实例。支持从字节串或同类实例中解析并复制所有字段数据。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
iv |
bytes | reqVeCrashData |
是 | - | 数据源，可为字节串或同类实例 |
返回值 (Returns)：
- 无
异常 (Raises)：
- 无
示例：
from RflySimSDK.ue import reqVeCrashData
# 创建空结构体
crash_data = reqVeCrashData()
# 假设 raw_bytes 是从 UDP 接收到的原始数据
raw_bytes = b'...' # 来自 UE4 的碰撞数据包
crash_data.CopyData(raw_bytes)
# 访问碰撞信息
print(f"碰撞飞机ID: {crash_data.copterID}")
print(f"碰撞类型: {crash_data.CrashType}") # -2=地面, -1=静态物体, 0=无碰撞, >0=被碰飞机ID
print(f"碰撞位置: ({crash_data.CrashPos[0]}, {crash_data.CrashPos[1]}, {crash_data.CrashPos[2]})")
CoptReqData 类¶
用于存储无人机状态请求数据的结构体，包含飞机ID、位置、姿态、几何外框等信息，共80字节。主要用于与UE4引擎通信时传输无人机的完整状态数据。
__init__(iv=None)¶
功能说明：初始化 CoptReqData 实例，可选择性传入初始值进行数据填充。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
iv |
CoptReqData |
否 | None |
用于初始化数据的源对象，若为 None 则创建空实例 |
返回值 (Returns)：
CoptReqData实例对象
异常 (Raises)：
- 无
示例：
CopyData(iv)¶
功能说明：将源对象的数据复制到当前实例，用于数据同步或备份。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
iv |
CoptReqData |
是 | - | 数据源对象，其所有字段值将被复制到当前实例 |
返回值 (Returns)：
- 无
异常 (Raises)：
- 无
示例：
source = CoptReqData()
source.CopterID = 1
source.PosUE = [0.0, 0.0, 0.0]
target = CoptReqData()
target.CopyData(source) # 将source的数据复制到target
CopyDataOld(iv)¶
功能说明：使用旧版格式将源对象的数据复制到当前实例，兼容历史版本的数据结构解析。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
iv |
CoptReqData |
是 | - | 数据源对象，使用旧版格式进行字段映射和复制 |
返回值 (Returns)：
- 无
异常 (Raises)：
- 无
CombatReqData 类¶
固定长度的攻防状态快照，对应 296 字节 6i2d48i8d UDP 数据。一个数据包描述一架飞机及最多 8 个组件，不重复携带 CoptReqData 的位姿字段。
主要字段包括 CopterID、TeamID、ComponentCount、FriendlyFire、MaxHealth、CurrentHealth，以及按组件索引对齐的 ComponentID、ComponentTypeID、DamagePerHit、AttackFrequency、AttackRangeM、TargetCopterID 和 DamageCaused 数组。
__init__(iv=None)¶
功能说明：创建空攻防快照；传入已解包序列时立即调用 CopyData() 填充字段。校验码默认值为 1234567888，最大组件数为 8。
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| iv | Sequence | None |
否 | None |
struct.unpack() 得到的 64 字段序列。 |
返回值 (Returns)：CombatReqData 实例
异常 (Raises)：iv 字段数不是 64 时抛出 ValueError。
CopyData(iv)¶
功能说明：从 64 字段序列更新快照，并将 ComponentCount 限制在 0 至 8。所有组件数组均按固定 8 项复制，只有前 ComponentCount 项代表有效组件。
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| iv | Sequence |
是 | - | 按 6i2d48i8d 解包后的字段序列。 |
返回值 (Returns)：无
异常 (Raises)：字段数不是 64 时抛出 ValueError。
ObjReqData 类¶
用于存储和传输 UE4 场景中物体的完整状态信息，包括位置、姿态、几何属性及元数据。该类对应 C 结构体的内存布局，常用于 RflySim 仿真系统中与 UE4 引擎的数据交互场景。
__init__(iv=None)¶
功能说明：初始化 ObjReqData 实例，可选择从现有数据复制初始化
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
iv |
ObjReqData / None |
否 | None |
源数据对象，若为 None 则创建空实例 |
返回值 (Returns)：
ObjReqData实例对象
异常 (Raises)：
- 无
CopyData(iv)¶
功能说明：从源对象复制所有字段数据到当前实例（新版本格式） 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
iv |
ObjReqData |
是 | - | 源数据对象 |
返回值 (Returns)：
- 无
异常 (Raises)：
- 无
CopyDataOld(iv)¶
功能说明：从源对象复制所有字段数据到当前实例（旧版本兼容格式） 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
iv |
ObjReqData |
是 | - | 源数据对象 |
返回值 (Returns)：
- 无
异常 (Raises)：
- 无
示例：
# 创建空实例并填充数据
obj = ObjReqData()
obj.PosUE = [100.0, 200.0, 50.0]
obj.angEuler = [0.0, 0.0, 1.57]
obj.ObjName = b"TargetDrone\x00"
# 从现有对象复制创建新实例
obj_copy = ObjReqData(obj)
# 或使用 CopyData 方法
another_copy = ObjReqData()
another_copy.CopyData(obj)
VisionSensorReqNew 类¶
该类对应 C++ 结构体 VisionSensorReq，用于向 UE4 发送请求并设置相机参数。包含数据校验位、内存序号、传感器类型、目标飞机绑定、图像分辨率、传输协议、相机视场角、安装位置与姿态等完整配置字段。
__init__(iv=None)¶
功能说明：初始化视觉传感器请求对象，可选择从现有对象复制数据进行初始化。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
iv |
VisionSensorReqNew |
否 | None |
用于初始化的源对象，若为 None 则创建默认参数的实例 |
返回值 (Returns)：
VisionSensorReqNew实例对象
异常 (Raises)：
- 无
示例：
# 创建默认配置的视觉传感器请求
sensor_req = VisionSensorReqNew()
# 基于现有实例创建副本
existing_req = VisionSensorReqNew()
new_req = VisionSensorReqNew(existing_req)
CopyData(iv)¶
功能说明：将指定视觉传感器请求对象的数据字段复制到当前实例。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
iv |
VisionSensorReqNew |
是 | - | 源视觉传感器请求对象，从中复制所有配置数据 |
返回值 (Returns)：
- 无
异常 (Raises)：
- 无
示例：
# 创建两个实例
source_sensor = VisionSensorReqNew()
target_sensor = VisionSensorReqNew()
# 将 source_sensor 的数据复制到 target_sensor
target_sensor.CopyData(source_sensor)
CameraData 类¶
表示相机数据结构体，用于存储相机的元数据信息，包括相机序号、类型、分辨率、视场角、位置姿态、时间戳等信息。该结构体总大小为 72 字节。
__init__(iv=None)¶
功能说明：初始化相机数据对象 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
iv |
CameraData |
否 | None |
用于拷贝数据的源对象，若为 None 则初始化默认值 |
返回值 (Returns)：
CameraData实例对象
异常 (Raises)：
- 无
CopyData(iv)¶
功能说明：从源对象拷贝数据到当前对象 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
iv |
CameraData |
是 | - | 源数据对象，其字段值将被拷贝到当前对象 |
返回值 (Returns)：
- 无
异常 (Raises)：
- 无
示例：
cam1 = CameraData()
cam1.SeqID = 1
cam1.TypeID = 0
cam1.DataHeight = 480
cam1.DataWidth = 640
cam2 = CameraData()
cam2.CopyData(cam1) # cam2 的字段值与 cam1 相同
CopyDataOld(iv)¶
功能说明：使用旧版本格式从源对象拷贝数据到当前对象 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
iv |
CameraData |
是 | - | 源数据对象，使用旧版本格式进行数据拷贝 |
返回值 (Returns)：
- 无
异常 (Raises)：
- 无
UE4CtrlAPI 类¶
RflySim3D 场景控制与通信接口类。该类提供与 UE4/UE5 仿真环境的 UDP 通信能力，支持飞行器数据、对象数据、相机数据的传输与接收，以及场景控制指令的发送。
__init__(ip="127.0.0.1")¶
功能说明：初始化 UE4CtrlAPI 实例，建立与 RflySim3D 的通信连接。创建 UDP 套接字、初始化数据存储向量、设置控制标志，并为多线程消息处理准备事件机制。
参数列表 (Args)：
| 参数名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| ip | str | "127.0.0.1" | 目标 PC 的 IP 地址，用于建立与 RflySim3D 的 UDP 通信连接 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4Cmd(cmd, windowID=-1)¶
功能说明：发送命令以控制 RflySim3D 的显示样式。可用的命令字符串形如 'RflyShowTextTime "txt" time'，支持多种显示控制功能包括文本显示、地图切换、相机控制、车辆模型操作等。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| cmd | 任意 | 是 | 无 | 命令字符串，详细命令格式见功能说明 |
| windowID | 任意 | 否 | -1 | 目标窗口ID，-1表示所有窗口 |
返回值 (Returns)：无
异常 (Raises)：无
fillList(data, inLen)¶
功能说明：内部辅助方法，用于填充列表数据。（无详细文档说明）
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| data | 任意 | 是 | 无 | 待填充的数据 |
| inLen | 任意 | 是 | 无 | 目标长度 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4CmdNet(cmd)¶
功能说明：通过局域网向所有 RflySim3D 实例发送控制命令。使用多播地址 224.0.0.10:20009 进行网络广播，支持最多92字节的命令数据。命令类型会自动检查与转换：字符串会被编码为字节串，长度超过91字节会被截断。发送命令后，如果是 "RflyChangeMap" 命令会额外等待0.5秒以确保场景切换完成。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| cmd | 任意 | 是 | 无 | 命令字符串或字节串，最大长度91字节 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4LabelID(CopterID=0, Txt='', fontSize=30, RGB=[255, 0, 0], windowID=-1)¶
功能说明：向 RflySim3D 发送标签ID显示命令，在指定飞机上显示文本标签。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| CopterID | 任意 | 否 | 0 | 目标飞机ID |
| Txt | 任意 | 否 | "" | 显示的文本内容 |
| fontSize | 任意 | 否 | 30 | 字体大小 |
| RGB | 任意 | 否 | [255, 0, 0] | 文本颜色 [R, G, B]，范围0-255 |
| windowID | 任意 | 否 | -1 | 目标窗口ID，-1表示所有窗口 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4LabelMsg(CopterID=0, Txt='', fontSize=30, RGB=[255, 0, 0], dispTime=0, dispFlag=-1, windowID=-1)¶
功能说明：向 RflySim3D 发送标签消息显示命令，支持更复杂的消息管理机制。消息显示行为由 dispFlag 和 dispTime 共同控制：当 dispFlag < 0 且 dispTime >= 0 时采用累加模式；dispFlag < 0 且 dispTime < 0 时清空所有消息；dispFlag = 0 且 dispTime >= 0 时更新第0行；1 <= dispFlag < 5 时更新对应行，dispTime < 0 会删除该消息；dispFlag 大于当前消息数时切换到累加模式。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| CopterID | 任意 | 否 | 0 | 目标飞机ID，≤0表示所有飞机 |
| Txt | 任意 | 否 | "" | 显示的文本内容，最大120字节 |
| fontSize | 任意 | 否 | 30 | 字体大小 |
| RGB | 任意 | 否 | [255, 0, 0] | 文本颜色 [R, G, B]，范围0-255 |
| dispTime | 任意 | 否 | 0 | 显示时间（秒），<0立刻消失，=0永久显示，>0指定秒后消失 |
| dispFlag | 任意 | 否 | -1 | 显示标志，控制消息更新模式 |
| windowID | 任意 | 否 | -1 | 目标窗口ID，-1表示所有窗口 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4Attatch(CopterIDs, AttatchIDs, AttatchTypes, windowID=-1)¶
功能说明：发送消息到 RflySim3D，将一个或多个飞机附加到其他物体上（最多支持25个飞机）。支持三种列表参数，每个列表最大长度为25。附加类型包括：0-正常模式，1-相对位置不相对姿态，2-相对位置+偏航（不相对俯仰和滚转），3-相对位置+全姿态（俯仰滚转偏航）。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| CopterIDs | 任意 | 是 | 无 | 飞机ID列表，最大长度25 |
| AttatchIDs | 任意 | 是 | 无 | 目标附加对象ID列表，最大长度25 |
| AttatchTypes | 任意 | 是 | 无 | 附加类型列表，0-3，最大长度25 |
| windowID | 任意 | 否 | -1 | 目标窗口ID，-1表示所有窗口 |
返回值 (Returns)：无
异常 (Raises)：无
circle_traj(t, center=(0.0, 0.0), radius=1.0, W=5.0)¶
功能说明：生成圆形轨迹点，根据时间参数计算圆上的坐标位置。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| t | float | 是 | 无 | 时间（秒） |
| center | 任意 | 否 | (0.0, 0.0) | 圆心坐标 (x_c, y_c) |
| radius | float | 否 | 1.0 | 半径（米） |
| W | float | 否 | 5.0 | 轨迹周期（秒），默认5秒一圈 |
返回值 (Returns)：元组 (x, y)，圆上的坐标点
异常 (Raises)：无
sendUE4Pos(copterID=1, vehicleType=3, MotorRPMSMean=0, PosE=[0, 0, 0], AngEuler=[0, 0, 0], windowID=-1)¶
功能说明：向 RflySim3D 发送位置和姿态信息，用于创建新的3D模型或更新现有模型的状态。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | 任意 | 否 | 1 | 飞机ID |
| vehicleType | 任意 | 否 | 3 | 载具类型 |
| MotorRPMSMean | 任意 | 否 | 0 | 电机平均转速 |
| PosE | 任意 | 否 | [0, 0, 0] | 地球坐标系位置 [x, y, z]（米，NED） |
| AngEuler | 任意 | 否 | [0, 0, 0] | 欧拉角 [roll, pitch, yaw]（弧度） |
| windowID | 任意 | 否 | -1 | 目标窗口ID，-1表示所有窗口 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4Pos2Ground(copterID=1, vehicleType=3, MotorRPMSMean=0, PosE=[0, 0, 0], AngEuler=[0, 0, 0], windowID=-1)¶
功能说明：向 RflySim3D 发送位置和姿态信息，创建或更新3D模型，并确保模型始终贴合地面。使用 checksum = 1234567891 通知 UE4 生成始终贴合地面的物体。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | 任意 | 否 | 1 | 飞机ID |
| vehicleType | 任意 | 否 | 3 | 载具类型 |
| MotorRPMSMean | 任意 | 否 | 0 | 电机平均转速 |
| PosE | 任意 | 否 | [0, 0, 0] | 地球坐标系位置 [x, y, z]（米，NED） |
| AngEuler | 任意 | 否 | [0, 0, 0] | 欧拉角 [roll, pitch, yaw]（弧度） |
| windowID | 任意 | 否 | -1 | 目标窗口ID，-1表示所有窗口 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4Destroy(copterID, windowID=-1)¶
功能说明：向 RflySim3D 发送销毁指定飞机的命令。当 vehicleType == -3 时，根据指定 ID 删除对应的 Copter。使用 sendUE4PosNew 的发送逻辑。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | 任意 | 是 | 无 | 要销毁的飞机ID |
| windowID | 任意 | 否 | -1 | 目标窗口ID，-1表示所有窗口 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4PosScale(copterID=1, vehicleType=3, MotorRPMSMean=0, PosE=[0, 0, 0], AngEuler=[0, 0, 0], Scale=[1, 1, 1], windowID=-1)¶
功能说明：向 RflySim3D 发送位置、姿态和缩放信息，创建或更新3D模型，并支持修改模型缩放比例。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | 任意 | 否 | 1 | 飞机ID |
| vehicleType | 任意 | 否 | 3 | 载具类型 |
| MotorRPMSMean | 任意 | 否 | 0 | 电机平均转速 |
| PosE | 任意 | 否 | [0, 0, 0] | 地球坐标系位置 [x, y, z]（米，NED） |
| AngEuler | 任意 | 否 | [0, 0, 0] | 欧拉角 [roll, pitch, yaw]（弧度） |
| Scale | 任意 | 否 | [1, 1, 1] | 缩放比例 [x, y, z] |
| windowID | 任意 | 否 | -1 | 目标窗口ID，-1表示所有窗口 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4PosScale2Ground(copterID=1, vehicleType=3, MotorRPMSMean=0, PosE=[0, 0, 0], AngEuler=[0, 0, 0], Scale=[1, 1, 1], windowID=-1)¶
功能说明：向 RflySim3D 发送位置、姿态和缩放信息，创建或更新3D模型，支持修改模型缩放比例，并确保模型始终贴合地面。使用 checksum = 1234567891 通知 UE4 生成始终贴合地面的物体。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | 任意 | 否 | 1 | 飞机ID |
| vehicleType | 任意 | 否 | 3 | 载具类型 |
| MotorRPMSMean | 任意 | 否 | 0 | 电机平均转速 |
| PosE | 任意 | 否 | [0, 0, 0] | 地球坐标系位置 [x, y, z]（米，NED） |
| AngEuler | 任意 | 否 | [0, 0, 0] | 欧拉角 [roll, pitch, yaw]（弧度） |
| Scale | 任意 | 否 | [1, 1, 1] | 缩放比例 [x, y, z] |
| windowID | 任意 | 否 | -1 | 目标窗口ID，-1表示所有窗口 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4PosFull(copterID, vehicleType, MotorRPMS=[0] * 8, VelE=[0, 0, 0], PosE=[0, 0, 0], RateB=[0, 0, 0], AngEuler=[0, 0, 0], windowID=-1)¶
功能说明：向 RflySim3D 发送完整的位置、姿态和运动状态信息，用于创建新的3D模型或更新现有模型的完整状态。包含速度、角速度、电机转速等完整状态信息。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | 任意 | 是 | 无 | 飞机ID |
| vehicleType | 任意 | 是 | 无 | 载具类型 |
| MotorRPMS | 任意 | 否 | [0,0,0,0,0,0,0,0] | 8个电机的转速（RPM） |
| VelE | 任意 | 否 | [0, 0, 0] | 地球坐标系速度 [Vx, Vy, Vz]（m/s，NED） |
| PosE | 任意 | 否 | [0, 0, 0] | 地球坐标系位置 [x, y, z]（m，NED） |
| RateB | 任意 | 否 | [0, 0, 0] | 机体坐标系角速度 [p, q, r]（rad/s） |
| AngEuler | 任意 | 否 | [0, 0, 0] | 欧拉角 [roll, pitch, yaw]（弧度） |
| windowID | 任意 | 否 | -1 | 目标窗口ID，-1表示所有窗口 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4ExtAct(copterID=1, ActExt=[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], windowID=-1)¶
功能说明：向 RflySim3D 发送扩展动作数据，用于控制飞机的额外16个浮点参数。校验位为1234567894，包含运行时间戳和16个扩展参数。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | 任意 | 否 | 1 | 飞机ID |
| ActExt | 任意 | 否 | [0,...0]（16个0） | 16个扩展动作参数 |
| windowID | 任意 | 否 | -1 | 目标窗口ID，-1表示所有窗口 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4PosSimple(copterID, vehicleType, PWMs, VelE, PosE, AngEuler, runnedTime=-1, windowID=-1)¶
功能说明：向 RflySim3D 发送简化的位置和姿态信息，包含时间戳和PWM控制信号。用于创建新的3D模型或更新现有模型的状态，相比完整版本参数更少，通信开销更小。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | 任意 | 是 | 无 | 飞机ID |
| vehicleType | 任意 | 是 | 无 | 载具类型 |
| PWMs | 任意 | 是 | 无 | 8个PWM控制信号 |
| VelE | 任意 | 是 | 无 | 地球坐标系速度 [Vx, Vy, Vz]（m/s，NED） |
| PosE | 任意 | 是 | 无 | 地球坐标系位置 [x, y, z]（m，NED） |
| AngEuler | 任意 | 是 | 无 | 欧拉角 [roll, pitch, yaw]（弧度） |
| runnedTime | 任意 | 否 | -1 | 运行时间戳（秒），-1表示使用当前时间 |
| windowID | 任意 | 否 | -1 | 目标窗口ID，-1表示所有窗口 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4PosNew(copterID=1, vehicleType=3, PosE=[0, 0, 0], AngEuler=[0, 0, 0], VelE=[0, 0, 0], PWMs=[0] * 8, runnedTime=-1, windowID=-1)¶
功能说明：向 RflySim3D 发送位置、姿态等信息，用于创建新的 3D 模型或更新已有模型的状态。该函数构造 SOut2SimulatorSimpleTime 结构体数据并通过 UDP 发送给 UE4。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | int | 否 | 1 | 飞机/物体 ID |
| vehicleType | int | 否 | 3 | 载具类型，四旋翼为 3 |
| PosE | list[float] | 否 | [0, 0, 0] | 东北天坐标系下的位置 [x, y, z]，单位 m |
| AngEuler | list[float] | 否 | [0, 0, 0] | 欧拉角 [roll, pitch, yaw]，单位 rad |
| VelE | list[float] | 否 | [0, 0, 0] | 东北天坐标系下的速度 [vx, vy, vz]，单位 m/s |
| PWMs | list[float] | 否 | [0] * 8 | 电机转速/ PWM 值，最多 8 个 |
| runnedTime | float | 否 | -1 | 当前时间戳，单位 s，-1 表示使用系统当前时间 |
| windowID | int | 否 | -1 | 目标 RflySim3D 窗口 ID，-1 表示广播到所有窗口 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4PosScale100(copterID, vehicleType, PosE, AngEuler, MotorRPMSMean, Scale, isFitGround=False, windowID=-1)¶
功能说明：向 RflySim3D 批量发送 100 架飞机的位置、姿态、缩放等信息，用于一次性创建或更新 100 个 3D 模型。该函数构造 Multi3DData100New 结构体数据并通过 UDP 发送。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | list[int] | 是 | 无 | 100 维飞机 ID 数组，从 1 到 100，0 表示不显示 |
| vehicleType | list[int] | 是 | 无 | 100 维飞机类型数组，四旋翼为 3 |
| PosE | list[float] | 是 | 无 | 300 维位置数组 [x1,y1,z1,x2,y2,z2,...]，单位 m |
| AngEuler | list[float] | 是 | 无 | 300 维欧拉角数组 [r1,p1,y1,r2,p2,y2,...]，单位 rad |
| MotorRPMSMean | list[float] | 是 | 无 | 100 维平均电机转速数组，单位 RPM |
| Scale | list[int] | 是 | 无 | 300 维缩放数组 [sx1,sy1,sz1,sx2,sy2,sz2,...]，值为实际尺寸*100 |
| isFitGround | bool | 否 | False | 是否使飞机始终贴合地面，True 时校验位为 1234567891 |
| windowID | int | 否 | -1 | 目标 RflySim3D 窗口 ID，-1 表示广播到所有窗口 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4PosScalePwm20(copterID, vehicleType, PosE, AngEuler, Scale, PWMs, isFitGround=False, windowID=-1)¶
功能说明：向 RflySim3D 批量发送 20 架飞机的位置、姿态、缩放及 PWM 等信息，用于一次性创建或更新 20 个 3D 模型。该函数构造 Multi3DData2New 结构体数据并通过 UDP 发送。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | list[int] | 是 | 无 | 20 维飞机 ID 数组，从 1 到 20，0 表示不显示 |
| vehicleType | list[int] | 是 | 无 | 20 维飞机类型数组，四旋翼为 3 |
| PosE | list[float] | 是 | 无 | 60 维位置数组 [x1,y1,z1,x2,y2,z2,...]，单位 m |
| AngEuler | list[float] | 是 | 无 | 60 维欧拉角数组 [r1,p1,y1,r2,p2,y2,...]，单位 rad |
| Scale | list[int] | 是 | 无 | 60 维缩放数组 [sx1,sy1,sz1,sx2,sy2,sz2,...]，值为实际尺寸*100 |
| PWMs | list[float] | 是 | 无 | 160 维 PWM/电机转速数组，对应 20 个飞机各 8 个电机，单位 RPM |
| isFitGround | bool | 否 | False | 是否使飞机始终贴合地面，True 时校验位为 1234567891 |
| windowID | int | 否 | -1 | 目标 RflySim3D 窗口 ID，-1 表示广播到所有窗口 |
返回值 (Returns)：无
异常 (Raises)：无
getUE4Pos(CopterID=1)¶
功能说明：获取指定飞机在 UE4 中的位置数据。该方法从内部数据缓存中查询并返回指定 CopterID 的位置信息。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| CopterID | int | 否 | 1 | 目标飞机 ID |
返回值 (Returns)：指定飞机的位置数据，具体格式取决于内部数据结构的定义
异常 (Raises)：无
getUE4Data(CopterID=1)¶
功能说明：获取指定飞机在 UE4 中的完整数据。该方法从内部数据缓存中查询并返回指定 CopterID 的所有相关数据，比 getUE4Pos 返回更完整的信息。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| CopterID | int | 否 | 1 | 目标飞机 ID |
返回值 (Returns)：指定飞机的完整数据，具体格式取决于内部数据结构的定义
异常 (Raises)：无
initUE4MsgRec()¶
功能说明：初始化从 UE4 接收 UDP 数据的监听机制。当前主要用于监听碰撞数据（crash data），创建 UDP 接收线程并开始监听指定端口的数据。
参数列表 (Args)：无参数
返回值 (Returns)：无
异常 (Raises)：无
endUE4MsgRec()¶
功能说明：结束 UE4 消息监听。停止 UDP 接收线程，清理相关资源，终止 initUE4MsgRec 启动的消息监听机制。
参数列表 (Args)：无参数
返回值 (Returns)：无
异常 (Raises)：无
UE4MsgRecLoop()¶
功能说明：UE4 消息监听死循环处理函数。监听 224.0.0.10:20006 以及本地 20006 端口，处理 RflySim3D 或 CopterSim 返回的消息。共支持 6 种消息类型：
- CopterSimCrash（12 字节）：碰撞检测数据，RflySim3D 按 P 键开启碰撞检测模式后，发生碰撞时返回
- PX4SILIntFloat（120 字节）：包含 checksum、CopterID、整型数组和浮点数组的复合数据结构
- reqVeCrashData（160 字节）：完整的飞机状态数据，包含位置、速度、姿态、碰撞信息等
- CameraData（56 字节）：相机数据，接收后存放在
self.CamDataVect中 - CoptReqData（64 字节）：带 copter_id 的目标数据，接收后存放在
self.CoptDataVect中 - ObjReqData（96 字节）：场景中自带物体的数据，接收后存放在
self.ObjDataVect中
接收到的数据可使用 getCamCoptObj 函数进行获取。
参数列表 (Args)：无参数
返回值 (Returns)：无
异常 (Raises)：无
getCamCoptObj(type_id=1, objName=1)¶
功能说明：根据类型和名称获取相机、目标或物体的数据。根据 type_id 不同，objName 的含义也不同：
type=0表示相机，objName对应相机的seqIDtype=1表示手动创建带copter_id的目标，objName对应CopterIDtype=2表示场景中自带的物体，objName对应物体名称（字符串）
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| type_id | int | 否 | 1 | 请求类型：0=相机，1=带copter_id的目标，2=场景自带物体 |
| objName | int/str | 否 | 1 | 目标标识：相机时为seqID，目标时为CopterID，物体时为名称字符串 |
返回值 (Returns)：对应类型的数据对象，具体格式取决于 type_id
异常 (Raises)：无
sendRflyShowTextTime(txt, time)¶
功能说明：向 RflySim3D 发送显示文本和时间的指令，用于在仿真环境中显示特定文本信息并指定显示时长。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| txt | str | 是 | 无 | 需要显示的文本内容 |
| time | float | 是 | 无 | 文本显示持续时间，单位秒 |
返回值 (Returns)：无
异常 (Raises)：
| 异常类型 | 说明 |
|---|---|
| TypeError | 参数类型错误时抛出 |
| ValueError | 参数值不合法时抛出 |
reqCamCoptObj(type_id=1, objName=1, windowID=0)¶
功能说明：向 RflySim3D 请求相机、带 copter_id 的目标或场景中自带物体的数据。根据 type_id 不同，objName 的含义不同：
type=0表示相机，objName对应相机的seqIDtype=1表示手动创建带copter_id的目标，objName对应CopterIDtype=2表示场景中自带的物体，objName对应物体名称（字符串）
内部调用 RflyReqObjData(int opFlag, FString objName, FString colorflag) 函数命令，其中 opFlag：0=创建相机，1=创建 copter_id 对应的目标，2=创建物体。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| type_id | int | 否 | 1 | 请求类型：0=相机，1=带copter_id的目标，2=场景自带物体 |
| objName | int/str | 否 | 1 | 目标标识：相机时为seqID，目标时为CopterID，物体时为名称字符串 |
| windowID | int | 否 | 0 | 目标 RflySim3D 窗口 ID，默认 0 号窗口 |
返回值 (Returns)：无
异常 (Raises)：无
reqCam(SeqIDList=[0], windowID=0)¶
功能说明：向 RflySim3D 请求指定相机的数据。发送请求后，RflySim3D 会定时返回 CameraData 结构体数据，接收后存放在 self.CamDataVect 中，可使用 getCamCoptObj 获取。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| SeqIDList | list[int] | 否 | [0] | 相机的序列 ID 列表 |
| windowID | int | 否 | 0 | 目标 RflySim3D 窗口 ID，默认 0 号窗口 |
返回值 (Returns)：无
异常 (Raises)：无
reqCopt(CopterIDList=[0], windowID=0)¶
功能说明：向 RflySim3D 请求指定带 copter_id 目标的数据。发送请求后，RflySim3D 会定时返回 CoptReqData 结构体数据，接收后存放在 self.CoptDataVect 中，可使用 getCamCoptObj 获取。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| CopterIDList | list[int] | 否 | [0] | copter_id 的 ID 列表 |
| windowID | int | 否 | 0 | 目标 RflySim3D 窗口 ID，默认 0 号窗口 |
返回值 (Returns)：无
异常 (Raises)：无
reqObj(ObjNameList=[''], windowID=0)¶
功能说明：向 RflySim3D 请求场景中自带物体的数据。发送请求后，RflySim3D 会定时返回 ObjReqData 结构体数据，接收后存放在 self.ObjDataVect 中，可使用 getCamCoptObj 获取。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| ObjNameList | list[str] | 否 | [''] | 物体名称的列表 |
| windowID | int | 否 | 0 | 目标 RflySim3D 窗口 ID，默认 0 号窗口 |
返回值 (Returns)：无
异常 (Raises)：无
SetUE4RadianceValue(UEObjectName, windows=-1)¶
功能说明：设置 UE4 中指定物体的辐射度/亮度值。用于调整场景中物体的光照或发光效果。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| UEObjectName | str | 是 | 无 | UE4 场景中物体的名称 |
| windows | int | 否 | -1 | 目标 RflySim3D 窗口 ID，-1 表示广播到所有窗口 |
返回值 (Returns)：无
异常 (Raises)：无
SetUE4RadianceValue__All(windows=-1)¶
功能说明：设置所有窗口的辐射值/亮度值
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| windows | int | 否 | -1 | 窗口ID，-1表示所有窗口 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4SetStencilValueByActorName(Actorname, StencilValue, is_name_regex=False, windowID=-1)¶
功能说明：通过Actor名称设置场景的Stencil值（模板缓冲区值），用于后期处理中的遮罩或轮廓提取
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| Actorname | str | 是 | None | Actor名称 |
| StencilValue | int | 是 | None | Stencil值（0-255） |
| is_name_regex | bool | 否 | False | 是否使用正则表达式匹配名称 |
| windowID | int | 否 | -1 | 窗口ID，-1表示所有窗口 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4SetStencilValueByMeshComponentName(Meshname, StencilValue, is_name_regex=False, windowID=-1)¶
功能说明：通过网格组件名称设置场景的Stencil值，用于后期处理中的遮罩或轮廓提取
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| Meshname | str | 是 | None | 网格组件名称 |
| StencilValue | int | 是 | None | Stencil值（0-255） |
| is_name_regex | bool | 否 | False | 是否使用正则表达式匹配名称 |
| windowID | int | 否 | -1 | 窗口ID，-1表示所有窗口 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4SetStencilValueByCopterID(CopterID, StencilValue, windowID=-1)¶
功能说明：通过CopterID（无人机ID）设置对应Actor的Stencil值，用于后期处理中的遮罩或轮廓提取
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| CopterID | int | 是 | None | 无人机ID |
| StencilValue | int | 是 | None | Stencil值（0-255） |
| windowID | int | 否 | -1 | 窗口ID，-1表示所有窗口 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4VariableMessage(copterID, vehicleType, settingType, pointIndex, vehicleSetting, messageType, messageDatas, windowID=-1)¶
功能说明：发送可变长度的管道/线路消息，用于在UE4中创建或修改管道、线路等可视化对象。支持创建、修改、删除等操作类型，可设置管道半径、透明度、颜色等属性。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | int | 是 | None | 对象ID，用于标识唯一的管道/线路对象 |
| vehicleType | int | 是 | None | 对象类型（ClassID） |
| settingType | int | 是 | None | 编辑类型：0=新增，1=修改，2=删除 |
| pointIndex | list | 是 | None | 点位编号数组，-1表示全部，0表示不修改，其他表示对应点位 |
| vehicleSetting | list | 是 | None | 参数设置，16位数组：[半径(m), 透明度, 自发光强度, 颜色R, G, B, A, 是否显示UI, ...]，-1表示沿用原数据，-2表示使用默认数据 |
| messageType | int | 是 | None | 消息类型：0=unknown, 1=int32, 2=Float, 3=String, 4=Vector2D, 5=Vector3D |
| messageDatas | list | 是 | None | 消息内容数组，坐标信息单位为米 |
| windowID | int | 否 | -1 | 窗口ID，-1表示所有窗口 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4CreatePipelineMsg(copterID, settingParam, messageDatas)¶
功能说明：发送创建管道消息，在UE4中创建新的管道/线路对象
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | int | 是 | None | 管道对象ID |
| settingParam | list | 是 | None | 管道参数设置数组 |
| messageDatas | list | 是 | None | 管道点位坐标数据 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4CoverPipelineMsg(copterID, settingParam, messageDatas)¶
功能说明：发送覆盖管道消息，用新的数据完全覆盖已有的管道/线路对象
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | int | 是 | None | 管道对象ID |
| settingParam | list | 是 | None | 管道参数设置数组 |
| messageDatas | list | 是 | None | 管道点位坐标数据 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4AddPointToPipelineMsg(copterID, messageDatas)¶
功能说明：发送添加点位到管道消息，向已有的管道/线路追加新的点位
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | int | 是 | None | 管道对象ID |
| messageDatas | list | 是 | None | 要追加的点位坐标数据 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4DeletePointMsg(copterID, pointIndexs)¶
功能说明：发送删除管道点位消息，删除指定管道中的特定点位
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | int | 是 | None | 管道对象ID |
| pointIndexs | list | 是 | None | 要删除的点位索引数组 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4SetPipelineScaleMsg(copterID, pointIndexs, size)¶
功能说明：发送设置管道粗细消息，修改指定点位的管道半径/粗细
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | int | 是 | None | 管道对象ID |
| pointIndexs | list | 是 | None | 要设置的点位索引数组，-1表示全部 |
| size | float | 是 | None | 管道半径，单位为米 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4SetPipelineDiaphaneityMsg(copterID, pointIndexs, diaphaneity)¶
功能说明：发送设置管道透明度消息，修改指定点位的管道材质透明度
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | int | 是 | None | 管道对象ID |
| pointIndexs | list | 是 | None | 要设置的点位索引数组，-1表示全部 |
| diaphaneity | float | 是 | None | 透明度值，范围通常为0-1 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4SetPipelineLightMsg(copterID, pointIndexs, light)¶
功能说明：发送设置管道自发光强度消息，修改指定点位的管道自发光效果
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | int | 是 | None | 管道对象ID |
| pointIndexs | list | 是 | None | 要设置的点位索引数组，-1表示全部 |
| light | float | 是 | None | 自发光强度值 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4SetPipelineColorMsg(copterID, pointIndexs, Color_R, Color_G, Color_B, Color_A)¶
功能说明：发送设置管道颜色消息，修改指定点位的管道材质颜色（RGBA）
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | int | 是 | None | 管道对象ID |
| pointIndexs | list | 是 | None | 要设置的点位索引数组，-1表示全部 |
| Color_R | float | 是 | None | 红色通道值（0-1或0-255） |
| Color_G | float | 是 | None | 绿色通道值（0-1或0-255） |
| Color_B | float | 是 | None | 蓝色通道值（0-1或0-255） |
| Color_A | float | 是 | None | Alpha通道值（0-1或0-255） |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4SetPipelinePosMsg(copterID, pointIndexs, messageDatas)¶
功能说明：发送设置管道点位位置消息，修改指定点位的空间坐标位置
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | int | 是 | None | 管道对象ID |
| pointIndexs | list | 是 | None | 要设置的点位索引数组 |
| messageDatas | list | 是 | None | 新的点位坐标数据，单位为米 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4SetWidgetVisble(copterID, isShowUI)¶
功能说明：发送设置控件可见性消息，控制管道/线路相关的UI控件显示或隐藏
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | int | 是 | None | 管道/控件对象ID |
| isShowUI | bool | 是 | None | 是否显示UI控件，True为显示，False为隐藏 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4RobotExtAct(copterID=1, ActExt=[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], windowID=-1)¶
功能说明：向 UE4 仿真环境发送机器狗（机器人）扩展动作控制指令。通过 TypeMask 位掩码控制各控制项的启用状态，支持动作命令、避障设置、目标位置、姿态控制、速度向量等多种控制模式。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | int | 否 | 1 | 机器狗的 CopterID 标识 |
| ActExt | list[float] | 否 | [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0] | 扩展动作参数数组，共16个元素： 0.TypeMask（位掩码） 1.机器狗动作命令（1起立，2跳跃等） 2.避障半径 3-5.目的地位置x,y,z 6-8.机器狗自身Roll,Pitch,Yaw 9-11.机器狗前进向量X,Y,Z 12.机器狗速度设置 13.使用的坐标系（1:NED，2:FRD） |
| windowID | int | 否 | -1 | 目标窗口ID，-1表示发送到所有窗口 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4MassMovement(robotDogID, childUAVID, isCombined)¶
功能说明：发送机器狗与无人机的组合/分离控制指令，用于实现机器狗搭载无人机的协同运动控制。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| robotDogID | int | 是 | - | 机器狗的ID标识 |
| childUAVID | int | 是 | - | 子无人机（被搭载）的ID标识 |
| isCombined | bool/int | 是 | - | 是否组合状态，True/1表示组合，False/0表示分离 |
返回值 (Returns)：无
异常 (Raises)：无
sendDogPosENoAltYaw(copterID, pos_x, pos_y, yaw)¶
功能说明：发送机器狗的水平位置（XY平面）和偏航角控制指令，高度保持不变。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | int | 是 | - | 机器狗的CopterID |
| pos_x | float | 是 | - | 目标位置X坐标（ENU坐标系，单位：米） |
| pos_y | float | 是 | - | 目标位置Y坐标（ENU坐标系，单位：米） |
| yaw | float | 是 | - | 目标偏航角（单位：弧度） |
返回值 (Returns)：无
异常 (Raises)：无
sendDogPosENoAlt(copterID, pos_x, pos_y)¶
功能说明：发送机器狗的水平位置（XY平面）控制指令，高度和偏航角保持不变。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | int | 是 | - | 机器狗的CopterID |
| pos_x | float | 是 | - | 目标位置X坐标（ENU坐标系，单位：米） |
| pos_y | float | 是 | - | 目标位置Y坐标（ENU坐标系，单位：米） |
返回值 (Returns)：无
异常 (Raises)：无
sendDogRateNoAltYaw(copterID, yaw_rate, speed_x, speed_y, axis)¶
功能说明：发送机器狗的速率控制指令（偏航角速率 + 水平速度），高度保持不变。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | int | 是 | - | 机器狗的CopterID |
| yaw_rate | float | 是 | - | 偏航角速率（单位：弧度/秒） |
| speed_x | float | 是 | - | X方向速度（单位：米/秒） |
| speed_y | float | 是 | - | Y方向速度（单位：米/秒） |
| axis | int | 是 | - | 坐标系选择（1: NED, 2: FRD/机体坐标系） |
返回值 (Returns)：无
异常 (Raises)：无
sendDogVelENoAltYaw(copterID, yaw, speed_x, speed_y, axis)¶
功能说明：发送机器狗的速度和前馈偏航角控制指令，高度保持不变。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | int | 是 | - | 机器狗的CopterID |
| yaw | float | 是 | - | 目标偏航角（单位：弧度） |
| speed_x | float | 是 | - | X方向速度（单位：米/秒） |
| speed_y | float | 是 | - | Y方向速度（单位：米/秒） |
| axis | int | 是 | - | 坐标系选择（1: NED, 2: FRD/机体坐标系） |
返回值 (Returns)：无
异常 (Raises)：无
sendDogVelENoAlt(copterID, speed_x, speed_y, axis)¶
功能说明：发送机器狗的水平速度控制指令，高度和偏航角保持不变。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | int | 是 | - | 机器狗的CopterID |
| speed_x | float | 是 | - | X方向速度（单位：米/秒） |
| speed_y | float | 是 | - | Y方向速度（单位：米/秒） |
| axis | int | 是 | - | 坐标系选择（1: NED, 2: FRD/机体坐标系） |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4DogSpeed(copterID, speed)¶
功能说明：发送机器狗的运动速度标量设置指令。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | int | 是 | - | 机器狗的CopterID |
| speed | float | 是 | - | 目标速度值（单位：米/秒） |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4DogObstacleAvoidance(copterID, radius)¶
功能说明：发送机器狗的避障半径设置指令，启用或禁用自主避障功能。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | int | 是 | - | 机器狗的CopterID |
| radius | float | 是 | - | 避障半径（单位：米），小于0时关闭避障，默认0.05 |
返回值 (Returns)：无
异常 (Raises)：无
sendUE4DogPlayAction(copterID, actionNum)¶
功能说明：发送机器狗的预设动作播放指令，触发特定的行为动作。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| copterID | int | 是 | - | 机器狗的CopterID |
| actionNum | int | 是 | - | 动作编号，可选值： 1:Damp, 2:BalanceStand, 3:StopMove, 4:PStandUp, 5:StandDown, 6:RecoveryStand, 7:Sit, 8:RiseSit, 9:SwitchGait, 10:BodyHeight, 11:FootRaiseHeight, 12:SpeedLevel, 13:Hello, 14:Stretch, 15:SwitchJoystick, 16:ContinuousGait, 17:Wallow, 18:Pose, 19:Scrape, 20:FrontFlip, 21:FrontJump, 22:FrontPounce, 23:Dance |
返回值 (Returns)：无
异常 (Raises)：无
startMulticastListener()¶
功能说明：启动组播监听器，用于接收来自 UE4 仿真环境的组播数据。
参数列表 (Args)：无参数
返回值 (Returns)：无
异常 (Raises)：无
stopMulticastListener()¶
功能说明：停止组播监听器，终止接收来自 UE4 仿真环境的组播数据。
参数列表 (Args)：无参数
返回值 (Returns)：无
异常 (Raises)：无
getRflyStatusMap()¶
功能说明：获取 RflySim 仿真状态映射表，包含当前仿真的运行状态和相关信息。
参数列表 (Args)：无参数
返回值 (Returns)：返回仿真状态映射字典，键值对形式存储各类状态信息。
异常 (Raises)：无
getRflyIP(user)¶
功能说明：获取指定用户的 RflySim 仿真 IP 地址信息。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| user | str | 是 | - | 用户名标识 |
返回值 (Returns)：返回指定用户对应的 IP 地址字符串。
异常 (Raises)：无
getRflyStartTime(user)¶
功能说明：获取指定用户的 RflySim 仿真启动时间。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| user | str | 是 | - | 用户名标识 |
返回值 (Returns)：返回仿真启动时间戳（单位：秒）。
异常 (Raises)：无
getRflyMapName(user)¶
功能说明：获取指定用户的RflySim地图名称。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| user | Any | 是 | - | 目标用户标识 |
返回值 (Returns)：地图名称 异常 (Raises)：无
getRflyHeartbeat(user)¶
功能说明：获取指定用户的RflySim心跳状态。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| user | Any | 是 | - | 目标用户标识 |
返回值 (Returns)：心跳状态 异常 (Raises)：无
getLocalUserName()¶
功能说明：获取本地用户名。 参数列表 (Args)：无参数 返回值 (Returns)：本地用户名 异常 (Raises)：无
getCurIP()¶
功能说明：获取当前IP地址。 参数列表 (Args)：无参数 返回值 (Returns)：当前IP地址 异常 (Raises)：无
getCurMapName()¶
功能说明：获取当前地图名称。 参数列表 (Args)：无参数 返回值 (Returns)：当前地图名称 异常 (Raises)：无
waitForMapLoaded(target_map, timeout_s=60, poll_s=0.5, stable_count=3)¶
功能说明：轮询本机最新组播状态，等待 CurrentMap 等于目标地图且 UdpRecvState == 4。只有收到不同心跳计数的连续就绪状态才累加稳定次数，达到 stable_count 后返回。
| 参数名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| target_map | str |
- | 期望加载完成的地图名称。 |
| timeout_s | float |
60 |
最长等待时间，单位为秒。 |
| poll_s | float |
0.5 |
轮询间隔，单位为秒。 |
| stable_count | int |
3 |
连续不同心跳满足地图和 UDP 就绪条件的次数。 |
返回值 (Returns)：加载稳定后返回 True。
异常 (Raises)：超时时抛出 TimeoutError，异常文本包含最后地图和 UDP 状态。
wait_for_map_loaded(target_map, timeout_s=60, poll_s=0.5, stable_count=3)¶
功能说明：waitForMapLoaded() 的蛇形命名别名，参数、返回值和异常行为完全相同。
getCurStartTime()¶
功能说明：获取当前启动时间。 参数列表 (Args)：无参数 返回值 (Returns)：当前启动时间 异常 (Raises)：无
getCurHeartbeat()¶
功能说明：获取当前心跳状态。 参数列表 (Args)：无参数 返回值 (Returns)：当前心跳状态 异常 (Raises)：无
getAllIPAndUserName()¶
功能说明：获取所有IP地址和对应的用户名。 参数列表 (Args)：无参数 返回值 (Returns)：所有IP地址和用户名的映射 异常 (Raises)：无
getAllUEMaps(is_ue5=False, sort_by_custom=True)¶
功能说明：获取指定 UE 项目 Content 目录下所有有效的地图名称（.umap 文件）。自动排除首字母为 '_' 以及名称中包含 'LogicMap' 的地图。 参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| is_ue5 | bool | 否 | False | 是否为UE5项目 |
| sort_by_custom | bool | 否 | True | 为 True 时按内置地图顺序排列，否则按地图名称排序 |
返回值 (Returns)：有效地图名称列表 异常 (Raises)：无
getAllUECopters(is_ue5=False, sort_by_custom=True)¶
功能说明：获取当前 UE/UE5 项目中所有可放置的 Copter 条目。该接口遍历项目 Content 和插件 Content 下的 XML 资源，提取 MeshClass、Name 等字段，并按规则处理后返回。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| is_ue5 | bool | 否 | False | 是否按 UE5 项目路径和资源规则读取 |
| sort_by_custom | bool | 否 | True | 是否按定制规则排序；为 False 时按 ClassID 排序 |
返回值 (Returns)：可放置 Copter 条目列表，元素通常为包含名称、类别、类 ID 等信息的字典。
异常 (Raises)：无
getAllUEVehicles(is_ue5=False, sort_by_custom=True)¶
功能说明：获取当前 UE/UE5 项目中的所有载具条目。该接口会先读取载具名称列表，再从原始资源列表中过滤出载具相关 XML 项。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| is_ue5 | bool | 否 | False | 是否按 UE5 项目路径和资源规则读取 |
| sort_by_custom | bool | 否 | True | 是否按定制规则排序；为 False 时按 ClassID 排序 |
返回值 (Returns)：载具条目列表，元素通常为包含名称、类别、类 ID 等信息的字典。
异常 (Raises)：无
getAllUEItems(is_ue5=False, sort_by_custom=True)¶
功能说明：获取当前 UE/UE5 项目中载具外的其他可放置物品。该接口遍历项目 Content 及插件 Content 下的 .xml 文件，排除载具名称列表中的项目，再根据预定义规则处理类别和排序。
参数列表 (Args)：
| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| is_ue5 | bool | 否 | False | 是否为UE5项目 |
| sort_by_custom | bool | 否 | True | 是否按定制规则排序；为 False 时按 ClassID 排序 |
返回值 (Returns)：载具外可放置物品列表，元素通常为包含名称、类别、类 ID 等信息的字典。 异常 (Raises)：无
sendUE4Component(copterID, parentComponentID, componentID, componentTypeID, switchCommand, params=None, windowID=-1, sequence=None)¶
功能说明：发送 144 字节 2i1d16d 组件协议。params 最多 12 项，不足部分补 0；未指定 sequence 时在线程锁保护下生成递增序列。windowID < 0 时发送到窗口端口 20010 至 20012，否则只发送到 20010 + windowID。
| 参数名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| copterID | int |
- | 绑定组件的飞机 ID。 |
| parentComponentID | int |
- | 父组件 ID；直接绑定飞机时填 0。 |
| componentID | int |
- | 调用方分配的组件 ID。 |
| componentTypeID | int |
- | 蓝图组件类型 ID。 |
| switchCommand | int |
- | 0=Off、1=On、2=UpdateOnly。 |
| params | Sequence | None |
None |
最多 12 个蓝图扩展参数。 |
| windowID | int |
-1 |
目标窗口；负数表示前三个窗口。 |
| sequence | float | None |
None |
可复用的命令序列号。 |
返回值 (Returns)：本次使用的 sequence。
异常 (Raises)：params 超过 12 项时抛出 ValueError。
startUE4CombatFeedback(copterIDs, windowID=0)¶
功能说明：启动 20006 端口接收线程，清除指定飞机的旧攻防缓存并调用 reqCopt() 请求新数据。等待最多 1 秒后返回各飞机当前快照；输入 ID 会去重但保留顺序。
| 参数名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| copterIDs | int | Iterable[int] |
- | 一个或多个正整数飞机 ID。 |
| windowID | int |
0 |
发送请求的 RflySim3D 窗口编号。 |
返回值 (Returns)：dict[int, CombatReqData | None]。
异常 (Raises)：列表为空、布尔值、非整数或非正数 ID 会触发 ValueError。
getUE4CombatSnapshot(copterID)¶
功能说明：在线程锁保护下查找指定飞机最新的攻防数据。
返回值 (Returns)：存在时返回 CombatReqData 深拷贝，否则返回 None。
异常 (Raises)：飞机 ID 不是正整数时抛出 ValueError。
getUE4CopterHealthRate(copterID)¶
功能说明：返回 CurrentHealth / MaxHealth。未收到数据或 MaxHealth <= 0 时返回 None。
getUE4CombatComponents(copterID)¶
功能说明：将有效组件区间 [0, ComponentCount) 转为字典列表。每项包含组件索引、ID、类型、单次伤害、攻击频率、攻击距离、目标飞机和累计实际伤害。
返回值 (Returns)：list[dict]；没有快照时返回空列表。
getCombatData(CopterID=1)¶
功能说明：兼容旧接口。必要时启动 UE4 消息接收线程并等待 1 秒，然后返回缓存中的原始 CombatReqData 对象。
返回值 (Returns)：找到时返回缓存对象，未找到时返回整数 0。需要隔离调用方修改时优先使用 getUE4CombatSnapshot()。
sendUE4Explosion(copterID, componentID, effectType, isOn=True)¶
功能说明：以组件类型 100 创建、重播或关闭爆炸特效，effectType 写入首个扩展参数。
sendUE4Fire(copterID, componentID, effectType, isOn=True)¶
功能说明：以组件类型 101 创建、重播或关闭起火特效。
sendUE4Smoke(copterID, componentID, effectType, isOn=True)¶
功能说明：以组件类型 102 创建、重播或关闭烟雾特效。
上述三个接口均要求 copterID、componentID、effectType 为正整数；命令使用同一序列号发送三次并间隔 0.01 秒，返回该序列号。
sendUE4LaserForward(copterID, componentID, effectType, attackRange, isOn=True)¶
功能说明：创建或关闭向前攻击激光。组件类型固定为 103，目标飞机 ID 为 0，线协议中的攻击模式值为 2。
sendUE4LaserToCopter(copterID, componentID, targetCopterID, effectType, attackRange, isOn=True)¶
功能说明：创建或关闭锁定指定飞机的激光。组件类型固定为 103，线协议中的攻击模式值为 1。
两个激光接口均要求 effectType 为正整数、attackRange 为有限非负数；锁定模式还要求 targetCopterID 为正整数。参数不合法时抛出 ValueError，成功时返回组件命令序列号。
进阶用法示例¶
以下示例请求 RflySim3D 回传载具数据，创建两个场景物体，并分别通过
getUE4Pos和getUE4Data查询位置及完整状态。
参考例程：[RflySim安装路径]\RflySimAPIs\3.RflySim3DUE\0.ApiExps\e6_RflySim3DCtrlAPI\9.RflySim3DPosGet
import math
import time
import UE4CtrlAPI as UE4CtrlAPI
ue = UE4CtrlAPI.UE4CtrlAPI()
# 请求 RflySim3D 将载具状态回传到组播端口
ue.sendUE4Cmd("RflyReqVehicleData 1")
time.sleep(0.5)
ue.initUE4MsgRec()
time.sleep(2)
# 创建两个场景物体
ue.sendUE4Pos(100, 30, 0, [2.5, 0, -8.086], [0, 0, math.pi])
ue.sendUE4PosScale(
101,
200030,
0,
[10.5, 0, -8.086],
[0, 0, math.pi],
[10, 10, 10],
)
time.sleep(0.5)
# getUE4Pos 返回 [x, y, z, isExist]
for copterID in [1, 100, 101, 102]:
posWithFlag = ue.getUE4Pos(copterID)
if posWithFlag[3]:
print("位置:", copterID, posWithFlag[0:3])
else:
print("未收到载具数据:", copterID)
# getUE4Data 返回完整的 reqVeCrashData 状态对象
vehicleState = ue.getUE4Data(1)
if isinstance(vehicleState, UE4CtrlAPI.reqVeCrashData):
print("完整状态:", vehicleState.copterID, vehicleState.PosE)
注意事项与避坑指南¶
-
ID 冲突管理：
sendUE4Pos、sendUE4Pos2Ground等方法的copID参数必须全局唯一。若重复发送相同 ID 到不同位置会导致 UE4 中对象闪烁或控制异常，建议建立 ID 分配表（如 100-199 多旋翼、200-299 固定翼）。 -
坐标系混淆：
sendUE4Pos使用 NED（北东下）坐标系，而sendUE4Pos2Ground会将高度强制归零到地面。若在circle_traj中混合使用两者，会出现高度计算错误，建议全程统一使用sendUE4Pos并手动处理地面碰撞检测。 -
异步数据竞争：
VisionSensorReqNew.CopyData()和CameraData.CopyData()非线程安全，若在多线程中同时调用会导致内存对齐错误。必须使用互斥锁保护，或改用CopyDataOld获取上一帧缓存数据作为降级方案。 -
对象生命周期失控：
sendUE4Destroy仅销毁 UE4 视觉对象，不会清理 Python 端残留的CoptReqData或ObjReqData实例。长期运行仿真后会出现内存泄漏，建议建立对象池并显式调用del或重建UE4CtrlAPI实例。 -
网络超时盲区：
sendUE4CmdNet依赖 UDP 发送无确认机制，若 UE4 端未启动或防火墙拦截，调用会静默失败。生产环境必须配合reqVeCrashData或自定义心跳检测，超时后触发重连逻辑而非继续堆积指令。
更新日志¶
2026-08-28: 组件加载和攻防消息相关例程接口2026-04-10: 增加获取UE地图和可放置物品列表的接口2026-03-06: 添加覆盖创建管道的接口2026-03-03: feat：SDK增加IP处理机制，兼容本地版上云2026-03-02: 添加根据ID删除对应的Copter的接口2026-02-28: 增加显示隐藏点位编号UI的API2026-01-20: UE4CtrlAPI组播接口和WSL环境下bug修复2026-01-14: 修改组播端口2026-01-06: 新增组播获取IP和RflySim打开的地图等接口2025-12-18: 新增UE控制接口2025-09-11: fix: 增加Linux端口复用的支持2025-08-19: fix: 更新视觉和UE接口2025-07-14: fix2025-07-11: fix2024-07-30: 补充了吊舱接口内容2024-07-10: 融合吊舱程序所用接口内容