简介

简述：该文件定义了与虚幻引擎4（UE4）仿真环境通信的各类数据结构，用于实现无人机状态请求、传感器数据获取、相机参数配置及 SIL 模型数据交换等功能。

在 RflySim 仿真平台中，UE4 提供高保真度的三维可视化与物理仿真环境。本模块封装了与 UE4 交互所需的全部数据协议结构，包括无人机位姿与碰撞数据请求（CoptReqData、reqVeCrashData）、物体状态查询（ObjReqData）、视觉传感器配置（VisionSensorReqNew、CameraData）以及 PX4 SIL 模型接口数据（PX4SILIntFloat）。通过这些结构体定义，开发者可在 Python 环境中精确构造与解析 UE4 通信报文，实现仿真场景中的传感器仿真、图像采集与硬件在环测试等高级功能。

CoptReqData 类

用于存储无人机状态请求数据的结构体，包含校验和、飞机ID、位置、欧拉角、四元数、几何中心、外框范围和时间戳等信息，共80字节。主要用于与UE4引擎通信时传输无人机的完整状态数据。

__init__(iv=None)

功能说明：初始化 CoptReqData 实例，可选择性传入初始值进行数据填充。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
iv	CoptReqData	否	None	用于初始化数据的源对象，若为 None 则创建空实例

返回值 (Returns)：

• CoptReqData 实例对象

异常 (Raises)：

• 无

示例：

# 创建空实例
data = CoptReqData()

# 基于现有数据创建副本
new_data = CoptReqData(existing_data)

CopyData(iv)

功能说明：从外部数据源复制完整状态数据到当前结构体实例。支持从同类实例中复制所有字段数据，用于更新当前对象状态。

参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
iv	CoptReqData	是	-	数据源对象，需为同类实例

返回值 (Returns)：

• 无

异常 (Raises)：

• 无

示例：

from RflySimSDK.ue import CoptReqData

# 创建目标对象
target_data = CoptReqData()

# 假设 source_data 是已填充的源对象
target_data.CopyData(source_data)

# 访问更新后的数据
print(f"飞机ID: {target_data.copterID}")
print(f"位置: ({target_data.pos[0]}, {target_data.pos[1]}, {target_data.pos[2]})")
print(f"欧拉角: ({target_data.euler[0]}, {target_data.euler[1]}, {target_data.euler[2]})")

CopyDataOld(iv)

功能说明：从外部数据源复制旧版本格式的状态数据到当前结构体实例。用于兼容早期版本的数据格式，自动转换并填充字段。

参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
iv	CoptReqData	是	-	数据源对象，需为同类实例（旧版本格式）

返回值 (Returns)：

• 无

异常 (Raises)：

• 无

---

CopyData(iv)

Function Description: Copies data from the source object to the current instance, used for data synchronization or backup. Arguments (Args):

Parameter Name	Type	Required	Default	Description
iv	CoptReqData	Yes	-	Source data object; all its field values will be copied to the current instance

Return Value (Returns):

• None

Exceptions (Raises):

• None

Example:

source = CoptReqData()
source.CopterID = 1
source.PosUE = [0.0, 0.0, 0.0]

target = CoptReqData()
target.CopyData(source)  # Copies data from source to target

---

CopyDataOld(iv)

Function Description: Copies data from the source object to the current instance using the legacy format, ensuring compatibility with historical data structure parsing. Arguments (Args):

Parameter Name	Type	Required	Default	Description
iv	CoptReqData	Yes	-	Source data object; fields are mapped and copied according to the legacy format

Return Value (Returns):

• None

Exceptions (Raises):

• None

ObjReqData Class

Used to store and transmit the complete state information of objects in a UE4 scene, including position, orientation, geometric properties, and metadata. This class corresponds to the memory layout of a C struct and is commonly used for data exchange between the RflySim simulation system and the UE4 engine.

__init__(iv=None)

Function Description: Initializes an ObjReqData instance; optionally initializes from existing data. Arguments (Args):

Parameter Name	Type	Required	Default	Description
iv	ObjReqData / None	No	None	Source data object; if None, creates an empty instance

Return Value (Returns):

• ObjReqData instance object

Exceptions (Raises):

• None

---

CopyData(iv)

Function Description: Copies all field data from the source object to the current instance (new version format). Arguments (Args):

Parameter Name	Type	Required	Default	Description
iv	ObjReqData	Yes	-	Source data object

Return Value (Returns):

• None

Exceptions (Raises):

• None

---

CopyDataOld(iv)

Function Description: Copies all field data from the source object to the current instance (legacy format compatibility). Arguments (Args):

Parameter Name	Type	Required	Default	Description
iv	ObjReqData	Yes	-	Source data object

Return Value (Returns):

• None

Exceptions (Raises):

• None

Example:

# Create an empty instance and populate data
obj = ObjReqData()
obj.PosUE = [100.0, 200.0, 50.0]
obj.angEuler = [0.0, 0.0, 1.57]
obj.ObjName = b"TargetDrone\x00"

# Create a new instance by copying from an existing object
obj_copy = ObjReqData(obj)
# Or use the CopyData method
another_copy = ObjReqData()
another_copy.CopyData(obj)

### `VisionSensorReqNew` 类

该类对应 C++ 结构体 `VisionSensorReq`，用于向 UE4 发送请求并设置相机参数。包含数据校验位、内存序号、传感器类型、目标飞机绑定、图像分辨率、传输协议、相机视场角、安装位置与姿态等完整配置字段。

#### `__init__(iv=None)`

**功能说明**：初始化视觉传感器请求对象，可选择从现有对象复制数据进行初始化。  
**参数列表 (Args)**：

| 参数名 | 类型 | 是否必填 | 默认值 | 说明 |
| :--- | :--- | :---: | :--- | :--- |
| `iv` | `VisionSensorReqNew` | 否 | `None` | 用于初始化的源对象，若为 `None` 则创建默认参数的实例 |

**返回值 (Returns)**：

- `VisionSensorReqNew` 实例对象

**异常 (Raises)**：

- 无

**示例**：

```python
# 创建默认配置的视觉传感器请求
sensor_req = VisionSensorReqNew()

# 基于现有实例创建副本
existing_req = VisionSensorReqNew()
new_req = VisionSensorReqNew(existing_req)

---

CopyData(iv)

功能说明：将指定视觉传感器请求对象的数据复制到当前实例中。
参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
iv	VisionSensorReqNew	是	-	源视觉传感器请求对象，从中复制数据

返回值 (Returns)：

• 无

异常 (Raises)：

• 无

示例：

sensor1 = VisionSensorReqNew()
sensor2 = VisionSensorReqNew()
sensor2.CopyData(sensor1)  # 将sensor1的数据复制到sensor2

---

#### `CopyData(iv)`

**Function Description**: Copies the data fields from the specified visual sensor request object to the current instance.  
**Arguments (Args)**:

| Parameter Name | Type | Required | Default | Description |
| :--- | :--- | :---: | :--- | :--- |
| `iv` | `VisionSensorReqNew` | Yes | - | Source visual sensor request object from which all configuration data is copied |

**Returns**:

- None

**Raises**:

- None

**Example**:

```python
# Create two instances
source_sensor = VisionSensorReqNew()
target_sensor = VisionSensorReqNew()

# Copy data from source_sensor to target_sensor
target_sensor.CopyData(source_sensor)

CameraData Class

Represents a camera data structure used to store metadata of a camera, including camera sequence ID, type ID, resolution, field of view, pose (position and orientation), timestamp, and other information. The total size of this structure is 72 bytes.

---

__init__(iv=None)

Function Description: Initializes a camera data object.
Arguments (Args):

Parameter Name	Type	Required	Default	Description
iv	CameraData	No	None	Source object for data copying; if None, default values are initialized

Returns:

• Instance of CameraData

Raises:

• None

---

CopyData(iv)

Function Description: Copies data from the source object to the current object.
Arguments (Args):

Parameter Name	Type	Required	Default	Description
iv	CameraData	Yes	-	Source data object whose field values will be copied to the current object

Returns:

• None

Raises:

• None

Example:

```python cam1 = CameraData() cam1.SeqID = 1 cam1.TypeID = 0 cam1.DataHeight = 480 cam1.DataWidth = 640

cam2 = CameraData() cam2.CopyData(cam1) # cam2's field values are identical to cam1's

---

CopyDataOld(iv)

Function Description: Copies data from the source object to the current object using the old version format.
Arguments (Args):

Parameter Name	Type	Required	Default Value	Description
iv	CameraData	Yes	-	Source data object; data is copied using the old version format

Return Value (Returns):

• None

Exceptions (Raises):

• None

UE4CtrlAPI Class

RflySim3D scene control and communication interface class. This class provides UDP communication capabilities with the UE4/UE5 simulation environment, supporting transmission and reception of aircraft data, object data, and camera data, as well as sending scene control commands.

__init__(ip="127.0.0.1")

Function Description: Initializes a UE4CtrlAPI instance and establishes a communication connection with RflySim3D. Creates a UDP socket, initializes data storage vectors, sets control flags, and prepares event mechanisms for multithreaded message processing.

Arguments (Args):

Parameter Name	Type	Default Value	Description
ip	str	"127.0.0.1"	IP address of the target PC, used to establish a UDP communication connection with RflySim3D

Return Value (Returns): None
Exceptions (Raises): None

sendUE4Cmd(cmd, windowID=-1)

Function Description: Sends a command to control the display style of RflySim3D. Available command strings take the form 'RflyShowTextTime "txt" time', supporting various display control functions including text display, map switching, camera control, and vehicle model operations.

Arguments (Args):

Parameter Name	Type	Required	Default Value	Description
cmd	Any	Yes	None	Command string; for detailed command formats, refer to the function description
windowID	Any	No	-1	Target window ID; -1 indicates all windows

Return Value (Returns): None
Exceptions (Raises): None

---

fillList(data, inLen)

Function Description: Internal helper method for populating list data. (No detailed documentation available.)

Arguments (Args):

Parameter Name	Type	Required	Default Value	Description
data	Any	Yes	None	Data to be filled
inLen	Any	Yes	None	Target length

Return Value (Returns): None
Exceptions (Raises): None

---

sendUE4CmdNet(cmd)

Function Description: Sends control commands to all RflySim3D instances over the local network using multicast address 224.0.0.10:20009, supporting up to 92 bytes of command data. Command types are automatically checked and converted: strings are encoded into byte sequences, and those exceeding 91 bytes are truncated. After sending the command, if it is a "RflyChangeMap" command, an additional 0.5-second wait is performed to ensure scene switching completes.

Arguments (Args):

Parameter Name	Type	Required	Default Value	Description
cmd	Any	Yes	None	Command string or byte sequence; maximum length is 91 bytes

Return Value (Returns): None
Exceptions (Raises): None

---

sendUE4LabelID(CopterID=0, Txt='', fontSize=30, RGB=[255, 0, 0], windowID=-1)

Function Description: Sends a label ID display command to RflySim3D to display a text label on a specified aircraft.

Arguments (Args):

Parameter Name	Type	Required	Default Value	Description
CopterID	Any	No	0	Target aircraft ID
Txt	Any	No	""	Text content to display
fontSize	Any	No	30	Font size
RGB	Any	No	[255, 0, 0]	Text color in [R, G, B] format, range 0–255
windowID	Any	No	-1	Target window ID; -1 indicates all windows

Return Value (Returns): None
Exceptions (Raises): None

---

sendUE4LabelMsg(CopterID=0, Txt='', fontSize=30, RGB=[255, 0, 0], dispTime=0, dispFlag=-1, windowID=-1)

Function Description: Sends a label message display command to RflySim3D, supporting a more sophisticated message management mechanism. Message display behavior is jointly controlled by dispFlag and dispTime:
- When dispFlag < 0 and dispTime >= 0, additive mode is used;
- When dispFlag < 0 and dispTime < 0, all messages are cleared;
- When dispFlag = 0 and dispTime >= 0, row 0 is updated;
- When 1 <= dispFlag < 5, the corresponding row is updated; if dispTime < 0, the message is deleted;
- If dispFlag exceeds the current number of messages, additive mode is automatically activated.

Arguments (Args):

Parameter Name	Type	Required	Default Value	Description
CopterID	Any	No	0	Target aircraft ID; ≤0 indicates all aircraft
Txt	Any	No	""	Text content to display, maximum 120 bytes
fontSize	Any	No	30	Font size
RGB	Any	No	[255, 0, 0]	Text color in [R, G, B] format, range 0–255
dispTime	Any	No	0	Display duration in seconds; <0 for immediate disappearance, =0 for permanent display, >0 for disappearance after specified seconds
dispFlag	Any	No	-1	Display flag controlling message update mode
windowID	Any	No	-1	Target window ID; -1 indicates all windows

Return Value (Returns): None
Exceptions (Raises): None

sendUE4Attatch(CopterIDs, AttatchIDs, AttatchTypes, windowID=-1)

Function Description: Sends a message to RflySim3D to attach one or more aircraft to other objects (supports up to 25 aircraft). Accepts three list-type arguments, each with a maximum length of 25. Attachment types include: 0—Normal mode, 1—Relative position but not relative attitude, 2—Relative position + yaw (not relative to pitch and roll), 3—Relative position + full attitude (pitch, roll, and yaw).

Arguments (Args):

Parameter Name	Type	Required	Default	Description
CopterIDs	Any	Yes	None	List of aircraft IDs, max length 25
AttatchIDs	Any	Yes	None	List of target object IDs to attach to, max length 25
AttatchTypes	Any	Yes	None	List of attachment types, values 0–3, max length 25
windowID	Any	No	-1	Target window ID; -1 indicates all windows

Returns: None

Raises: None

---

circle_traj(t, center=(0.0, 0.0), radius=1.0, W=5.0)

Function Description: Generates a point on a circular trajectory; computes the coordinates on the circle based on the time parameter.

Arguments (Args):

Parameter Name	Type	Required	Default	Description
t	float	Yes	None	Time (seconds)
center	Any	No	(0.0, 0.0)	Center coordinates of the circle (x_c, y_c)
radius	float	No	1.0	Radius (meters)
W	float	No	5.0	Trajectory period (seconds); default is 5 seconds per circle

Returns: Tuple (x, y), coordinates of the point on the circle

Raises: None

---

sendUE4Pos(copterID=1, vehicleType=3, MotorRPMSMean=0, PosE=[0, 0, 0], AngEuler=[0, 0, 0], windowID=-1)

Function Description: Sends position and attitude information to RflySim3D to create a new 3D model or update the state of an existing one.

Arguments (Args):

Parameter Name	Type	Required	Default	Description
copterID	Any	No	1	Aircraft ID
vehicleType	Any	No	3	Vehicle type
MotorRPMSMean	Any	No	0	Mean motor RPM
PosE	Any	No	[0, 0, 0]	Position in Earth-fixed frame [x, y, z] (meters, NED)
AngEuler	Any	No	[0, 0, 0]	Euler angles [roll, pitch, yaw] (radians)
windowID	Any	No	-1	Target window ID; -1 indicates all windows

Returns: None

Raises: None

---

sendUE4Pos2Ground(copterID=1, vehicleType=3, MotorRPMSMean=0, PosE=[0, 0, 0], AngEuler=[0, 0, 0], windowID=-1)

Function Description: Sends position and attitude information to RflySim3D to create or update a 3D model, ensuring the model remains always grounded. Uses checksum = 1234567891 to notify UE4 to generate an object that always conforms to the ground.

Arguments (Args):

Parameter Name	Type	Required	Default	Description
copterID	Any	No	1	Aircraft ID
vehicleType	Any	No	3	Vehicle type
MotorRPMSMean	Any	No	0	Mean motor RPM
PosE	Any	No	[0, 0, 0]	Position in Earth-fixed frame [x, y, z] (meters, NED)
AngEuler	Any	No	[0, 0, 0]	Euler angles [roll, pitch, yaw] (radians)
windowID	Any	No	-1	Target window ID; -1 indicates all windows

Returns: None

Raises: None

---

sendUE4Destroy(copterID, windowID=-1)

Function Description: Sends a command to RflySim3D to destroy a specified aircraft. When vehicleType == -3, deletes the corresponding Copter based on the specified ID. Uses the same sending logic as sendUE4PosNew.

Arguments (Args):

Parameter Name	Type	Required	Default	Description
copterID	Any	Yes	None	ID of the aircraft to destroy
windowID	Any	No	-1	Target window ID; -1 indicates all windows

Returns: None

Raises: None

---

sendUE4PosScale(copterID=1, vehicleType=3, MotorRPMSMean=0, PosE=[0, 0, 0], AngEuler=[0, 0, 0], Scale=[1, 1, 1], windowID=-1)

Function Description: Sends position, attitude, and scaling information to RflySim3D to create or update a 3D model, supporting modification of the model’s scale.

Arguments (Args):

Parameter Name	Type	Required	Default Value	Description
copterID	Any	No	1	Aircraft ID
vehicleType	Any	No	3	Vehicle type
MotorRPMSMean	Any	No	0	Mean motor RPM
PosE	Any	No	[0, 0, 0]	Position in Earth coordinate frame [x, y, z] (meters, NED)
AngEuler	Any	No	[0, 0, 0]	Euler angles [roll, pitch, yaw] (radians)
Scale	Any	No	[1, 1, 1]	Scale factor [x, y, z]
windowID	Any	No	-1	Target window ID; -1 indicates all windows

Returns: None

Raises: None

---

sendUE4PosScale2Ground(copterID=1, vehicleType=3, MotorRPMSMean=0, PosE=[0, 0, 0], AngEuler=[0, 0, 0], Scale=[1, 1, 1], windowID=-1)

Function Description: Sends position, attitude, and scale information to RflySim3D to create or update a 3D model, supporting modification of the model’s scale factor while ensuring the model remains grounded. Uses checksum = 1234567891 to notify UE4 to generate objects that always conform to the ground surface.

Arguments:

Parameter Name	Type	Required	Default Value	Description
copterID	Any	No	1	Aircraft ID
vehicleType	Any	No	3	Vehicle type
MotorRPMSMean	Any	No	0	Mean motor RPM
PosE	Any	No	[0, 0, 0]	Position in Earth coordinate frame [x, y, z] (meters, NED)
AngEuler	Any	No	[0, 0, 0]	Euler angles [roll, pitch, yaw] (radians)
Scale	Any	No	[1, 1, 1]	Scale factor [x, y, z]
windowID	Any	No	-1	Target window ID; -1 indicates all windows

Returns: None

Raises: None

---

sendUE4PosFull(copterID, vehicleType, MotorRPMS=[0] * 8, VelE=[0, 0, 0], PosE=[0, 0, 0], RateB=[0, 0, 0], AngEuler=[0, 0, 0], windowID=-1)

Function Description: Sends complete position, attitude, and motion state information to RflySim3D for creating new 3D models or updating existing models with full state data. Includes full state information such as velocity, angular velocity, and motor RPMs.

Arguments:

Parameter Name	Type	Required	Default Value	Description
copterID	Any	Yes	None	Aircraft ID
vehicleType	Any	Yes	None	Vehicle type
MotorRPMS	Any	No	[0,0,0,0,0,0,0,0]	RPMs of 8 motors
VelE	Any	No	[0, 0, 0]	Velocity in Earth coordinate frame [Vx, Vy, Vz] (m/s, NED)
PosE	Any	No	[0, 0, 0]	Position in Earth coordinate frame [x, y, z] (m, NED)
RateB	Any	No	[0, 0, 0]	Angular rate in body frame [p, q, r] (rad/s)
AngEuler	Any	No	[0, 0, 0]	Euler angles [roll, pitch, yaw] (radians)
windowID	Any	No	-1	Target window ID; -1 indicates all windows

Returns: None

Raises: None

---

sendUE4ExtAct(copterID=1, ActExt=[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], windowID=-1)

Function Description: Sends extended actuation data to RflySim3D to control 16 additional floating-point parameters of the aircraft. Uses checksum = 1234567894 and includes a runtime timestamp along with 16 extended parameters.

Arguments:

Parameter Name	Type	Required	Default Value	Description
copterID	Any	No	1	Aircraft ID
ActExt	Any	No	[0,...0] (16 zeros)	16 extended actuation parameters
windowID	Any	No	-1	Target window ID; -1 indicates all windows

Returns: None

Raises: None

---

sendUE4PosSimple(copterID, vehicleType, PWMs, VelE, PosE, AngEuler, runnedTime=-1, windowID=-1)

Function Description: Sends simplified position and attitude information to RflySim3D, including a timestamp and PWM control signals. Used for creating new 3D models or updating existing models; fewer parameters than the full version, resulting in lower communication overhead.

Parameter Name	Type	Required	Default Value	Description
copterID	Any	Yes	None	Aircraft ID
vehicleType	Any	Yes	None	Vehicle type
PWMs	Any	Yes	None	8 PWM control signals
VelE	Any	Yes	None	Velocity in Earth coordinate system [Vx, Vy, Vz] (m/s, NED)
PosE	Any	Yes	None	Position in Earth coordinate system [x, y, z] (m, NED)
AngEuler	Any	Yes	None	Euler angles [roll, pitch, yaw] (radians)
runnedTime	Any	No	-1	Timestamp of elapsed time (seconds); -1 indicates using current time
windowID	Any	No	-1	Target window ID; -1 indicates broadcasting to all windows

Returns: None

Raises: None

sendUE4PosNew(copterID=1, vehicleType=3, PosE=[0, 0, 0], AngEuler=[0, 0, 0], VelE=[0, 0, 0], PWMs=[0] * 8, runnedTime=-1, windowID=-1)

Function Description: Sends position, attitude, and other information to RflySim3D to create new 3D models or update existing ones. This function constructs an SOut2SimulatorSimpleTime structure and transmits it via UDP to UE4.

Arguments:

Parameter Name	Type	Required	Default Value	Description
copterID	int	No	1	Aircraft/object ID
vehicleType	int	No	3	Vehicle type; 3 for quadcopter
PosE	list[float]	No	[0, 0, 0]	Position [x, y, z] in ENU coordinate system (meters)
AngEuler	list[float]	No	[0, 0, 0]	Euler angles [roll, pitch, yaw] (radians)
VelE	list[float]	No	[0, 0, 0]	Velocity [vx, vy, vz] in ENU coordinate system (m/s)
PWMs	list[float]	No	[0] * 8	Motor speeds / PWM values (up to 8 values)
runnedTime	float	No	-1	Current timestamp (seconds); -1 indicates using system current time
windowID	int	No	-1	Target RflySim3D window ID; -1 indicates broadcasting to all windows

Returns: None

Raises: None

---

sendUE4PosScale100(copterID, vehicleType, PosE, AngEuler, MotorRPMSMean, Scale, isFitGround=False, windowID=-1)

Function Description: Sends position, attitude, scaling, and other information for up to 100 aircraft to RflySim3D in a single batch, enabling simultaneous creation or update of 100 3D models. This function constructs a Multi3DData100New structure and transmits it via UDP.

Arguments:

Parameter Name	Type	Required	Default Value	Description
copterID	list[int]	Yes	None	Array of 100 aircraft IDs (1–100); 0 indicates the model should not be displayed
vehicleType	list[int]	Yes	None	Array of 100 vehicle types; 3 for quadcopters
PosE	list[float]	Yes	None	300-element position array [x1,y1,z1,x2,y2,z2,...] (meters)
AngEuler	list[float]	Yes	None	300-element Euler angle array [r1,p1,y1,r2,p2,y2,...] (radians)
MotorRPMSMean	list[float]	Yes	None	100-element array of average motor speeds (RPM)
Scale	list[int]	Yes	None	300-element scaling array [sx1,sy1,sz1,sx2,sy2,sz2,...]; values equal actual dimensions × 100
isFitGround	bool	No	False	Whether to force aircraft to conform to ground level; when True, validation flag is set to 1234567891
windowID	int	No	-1	Target RflySim3D window ID; -1 indicates broadcasting to all windows

Returns: None

Raises: None

---

sendUE4PosScalePwm20(copterID, vehicleType, PosE, AngEuler, Scale, PWMs, isFitGround=False, windowID=-1)

Function Description: Sends position, attitude, scaling, and PWM information for up to 20 aircraft to RflySim3D in a single batch, enabling simultaneous creation or update of 20 3D models. This function constructs a Multi3DData2New structure and transmits it via UDP.

Arguments:

Parameter Name	Type	Required	Default Value	Description
copterID	list[int]	Yes	None	20-element aircraft ID array, ranging from 1 to 20; 0 indicates the aircraft is not displayed
vehicleType	list[int]	Yes	None	20-element aircraft type array; quadcopters are represented by 3
PosE	list[float]	Yes	None	60-element position array [x1,y1,z1,x2,y2,z2,...], unit: meters (m)
AngEuler	list[float]	Yes	None	60-element Euler angle array [r1,p1,y1,r2,p2,y2,...], unit: radians (rad)
Scale	list[int]	Yes	None	60-element scaling array [sx1,sy1,sz1,sx2,sy2,sz2,...]; values equal actual dimensions multiplied by 100
PWMs	list[float]	Yes	None	160-element PWM/motor speed array; corresponds to 20 aircraft, each with 8 motors; unit: RPM
isFitGround	bool	No	False	Whether to keep aircraft始终贴合地面 (always grounded). When True, the verification value is 1234567891
windowID	int	No	-1	Target RflySim3D window ID; -1 indicates broadcasting to all windows

Returns: None

Raises: None

---

getUE4Pos(CopterID=1)

Function Description: Retrieves position data of a specified aircraft within UE4. This method queries and returns the position information of the aircraft identified by the given CopterID from internal data caches.

Arguments:

Parameter Name	Type	Required	Default Value	Description
CopterID	int	No	1	Target aircraft ID

Returns: Position data of the specified aircraft; the exact format depends on the internal data structure definition.

Raises: None

---

getUE4Data(CopterID=1)

Function Description: Retrieves complete data of a specified aircraft within UE4. This method queries and returns all relevant data associated with the aircraft identified by the given CopterID from internal data caches, providing more comprehensive information than getUE4Pos.

Arguments:

Parameter Name	Type	Required	Default Value	Description
CopterID	int	No	1	Target aircraft ID

Returns: Complete data of the specified aircraft; the exact format depends on the internal data structure definition.

Raises: None

---

initUE4MsgRec()

Function Description: Initializes the UDP data reception mechanism for messages from UE4. Currently, this is primarily used to listen for crash data; it creates a UDP reception thread and begins listening on a designated port.

Arguments: None

Returns: None

Raises: None

---

endUE4MsgRec()

Function Description: Terminates UE4 message reception. Stops the UDP reception thread, cleans up related resources, and terminates the message reception mechanism initiated by initUE4MsgRec.

Arguments: None

Returns: None

Raises: None

---

UE4MsgRecLoop()

Function Description: A blocking loop function handling UE4 message reception. Listens on 224.0.0.10:20006 and local port 20006, processing messages returned by RflySim3D or CopterSim. It supports six message types:

1. CopterSimCrash (12 bytes): Collision detection data; returned by RflySim3D upon collision occurrence after collision detection mode is enabled via key 'P'.
2. PX4SILIntFloat (120 bytes): A composite data structure containing checksum, CopterID, integer array, and float array.
3. reqVeCrashData (160 bytes): Complete aircraft state data, including position, velocity, attitude, collision information, etc.
4. CameraData (56 bytes): Camera data; stored in self.CamDataVect upon reception.
5. CoptReqData (64 bytes): Target data associated with a copter_id; stored in self.CoptDataVect upon reception.
6. ObjReqData (96 bytes): Data for built-in scene objects; stored in self.ObjDataVect upon reception.

Received data can be retrieved using the getCamCoptObj function.

Arguments: None

Returns: None

Raises: None

---

getCamCoptObj(type_id=1, objName=1)

Function Description: Retrieves camera, target, or object data based on type and name. The meaning of objName varies depending on type_id:

• type=0: Camera; objName corresponds to the camera's seqID
• type=1: Manually created target with copter_id; objName corresponds to CopterID
• type=2: Built-in scene object; objName corresponds to the object's name (string)

Arguments:

Parameter Name	Type	Required	Default Value	Description
type_id	int	No	1	Request type: 0=Camera, 1=Target with copter_id, 2=Built-in scene object
objName	int/str	No	1	Target identifier: seqID for camera, CopterID for target, or name string for object

Returns: Data object corresponding to the specified type; the exact format depends on type_id.

Raises: None

---

sendRflyShowTextTime(txt, time)

Function Description: Sends a command to RflySim3D to display a specified text message for a given duration within the simulation environment.

Arguments:

Parameter Name	Type	Required	Default Value	Description
txt	str	Yes	None	Text content to be displayed
time	float	Yes	None	Duration for text display, in seconds

Returns: None

Raises:

Exception Type	Description
TypeError	Raised when argument types are incorrect
ValueError	Raised when argument values are invalid

---

reqCamCoptObj(type_id=1, objName=1, windowID=0)

Function Description: Requests data for cameras, targets with copter_id, or scene-embedded objects from RflySim3D. The meaning of objName varies depending on type_id:

• type=0: Camera; objName corresponds to the camera’s seqID
• type=1: Manually created target with copter_id; objName corresponds to CopterID
• type=2: Scene-embedded object; objName corresponds to the object’s name (string)

Internally invokes the RflyReqObjData(int opFlag, FString objName, FString colorflag) function command, where opFlag: 0=create camera, 1=create target corresponding to copter_id, 2=create object.

Args:

Parameter Name	Type	Required	Default Value	Description
type_id	int	No	1	Request type: 0=Camera, 1=Target with copter_id, 2=Scene-embedded object
objName	int/str	No	1	Target identifier: seqID for camera, CopterID for target, or object name string
windowID	int	No	0	Target RflySim3D window ID; default is window 0

Returns: None

Raises: None

---

reqCam(SeqIDList=[0], windowID=0)

Function Description: Requests data for specified cameras from RflySim3D. After sending the request, RflySim3D periodically returns CameraData structures, which are stored in self.CamDataVect upon receipt and can be retrieved using getCamCoptObj.

Args:

Parameter Name	Type	Required	Default Value	Description
SeqIDList	list[int]	No	[0]	List of camera sequence IDs
windowID	int	No	0	Target RflySim3D window ID; default is window 0

Returns: None

Raises: None

---

reqCopt(CopterIDList=[0], windowID=0)

Function Description: Requests data for specified targets with copter_id from RflySim3D. After sending the request, RflySim3D periodically returns CoptReqData structures, which are stored in self.CoptDataVect upon receipt and can be retrieved using getCamCoptObj.

Args:

Parameter Name	Type	Required	Default Value	Description
CopterIDList	list[int]	No	[0]	List of copter_id IDs
windowID	int	No	0	Target RflySim3D window ID; default is window 0

Returns: None

Raises: None

---

reqObj(ObjNameList=[''], windowID=0)

Function Description: Requests data for scene-embedded objects from RflySim3D. After sending the request, RflySim3D periodically returns ObjReqData structures, which are stored in self.ObjDataVect upon receipt and can be retrieved using getCamCoptObj.

Args:

Parameter Name	Type	Required	Default Value	Description
ObjNameList	list[str]	No	['']	List of object names
windowID	int	No	0	Target RflySim3D window ID; default is window 0

Returns: None

Raises: None

---

SetUE4RadianceValue(UEObjectName, windows=-1)

Function Description: Sets the radiance/luminance value of a specified object in UE4, used to adjust lighting or emissive effects of objects in the scene.

Args:

Parameter Name	Type	Required	Default Value	Description
UEObjectName	str	Yes	None	Name of the object in the UE4 scene
windows	int	No	-1	Target RflySim3D window ID; -1 indicates broadcasting to all windows

Returns: None

Raises: None

SetUE4RadianceValue__All(windows=-1)

Function Description: Sets the radiance/luminance value for all windows.

Args:

Parameter Name	Type	Required	Default Value	Description
windows	int	No	-1	Window ID; -1 indicates all windows

Returns: None

Raises: None

---

sendUE4SetStencilValueByActorName(Actorname, StencilValue, is_name_regex=False, windowID=-1)

Function Description: Sets the stencil value (template buffer value) of the scene via Actor name, used for masking or contour extraction in post-processing.

Parameter List (Args):

Parameter Name	Type	Required	Default Value	Description
Actorname	str	Yes	None	Actor name
StencilValue	int	Yes	None	Stencil value (0–255)
is_name_regex	bool	No	False	Whether to use regex for name matching
windowID	int	No	-1	Window ID; -1 indicates all windows

Return Value (Returns): None

Exceptions (Raises): None

---

sendUE4SetStencilValueByMeshComponentName(Meshname, StencilValue, is_name_regex=False, windowID=-1)

Function Description: Sets the Stencil value of the scene by mesh component name, used for masking or outline extraction in post-processing.

Parameter List (Args):

Parameter Name	Type	Required	Default Value	Description
Meshname	str	Yes	None	Mesh component name
StencilValue	int	Yes	None	Stencil value (0–255)
is_name_regex	bool	No	False	Whether to use regex for name matching
windowID	int	No	-1	Window ID; -1 indicates all windows

Return Value (Returns): None

Exceptions (Raises): None

---

sendUE4SetStencilValueByCopterID(CopterID, StencilValue, windowID=-1)

Function Description: Sets the Stencil value of the corresponding Actor by CopterID (UAV ID), used for masking or outline extraction in post-processing.

Parameter List (Args):

Parameter Name	Type	Required	Default Value	Description
CopterID	int	Yes	None	UAV ID
StencilValue	int	Yes	None	Stencil value (0–255)
windowID	int	No	-1	Window ID; -1 indicates all windows

Return Value (Returns): None

Exceptions (Raises): None

---

sendUE4VariableMessage(copterID, vehicleType, settingType, pointIndex, vehicleSetting, messageType, messageDatas, windowID=-1)

Function Description: Sends a variable-length pipeline/tube message to create or modify pipeline/tube visualization objects in UE4. Supports operations such as creation, modification, and deletion; allows setting attributes like pipeline radius, opacity, emissive intensity, and color.

Parameter List (Args):

Parameter Name	Type	Required	Default Value	Description
copterID	int	Yes	None	Object ID, used to uniquely identify a pipeline/tube object
vehicleType	int	Yes	None	Object type (ClassID)
settingType	int	Yes	None	Edit type: 0 = add, 1 = modify, 2 = delete
pointIndex	list	Yes	None	Array of point indices; -1 = all points, 0 = no modification, other values = specific point indices
vehicleSetting	list	Yes	None	Parameter settings array (16 elements): [radius (m), opacity, emissive intensity, color R, G, B, A, UI visibility flag, ...]; -1 = retain original data, -2 = use default data
messageType	int	Yes	None	Message type: 0 = unknown, 1 = int32, 2 = float, 3 = string, 4 = Vector2D, 5 = Vector3D
messageDatas	list	Yes	None	Message content array; coordinate units are meters
windowID	int	No	-1	Window ID; -1 indicates all windows

Return Value (Returns): None

Exceptions (Raises): None

---

sendUE4CreatePipelineMsg(copterID, settingParam, messageDatas)

Function Description: Sends a pipeline creation message to create a new pipeline/tube object in UE4.

Parameter List (Args):

Parameter Name	Type	Required	Default Value	Description
copterID	int	Yes	None	Pipeline object ID
settingParam	list	Yes	None	Pipeline parameter settings array
messageDatas	list	Yes	None	Pipeline point coordinate data

Return Value (Returns): None

Exceptions (Raises): None

---

sendUE4CoverPipelineMsg(copterID, settingParam, messageDatas)

Function Description: Sends a pipeline overwrite message to completely replace an existing pipeline/tube object with new data.

Parameter List (Args):

Parameter Name	Type	Required	Default Value	Description
copterID	int	Yes	None	Pipeline object ID
settingParam	list	Yes	None	Pipeline parameter settings array
messageDatas	list	Yes	None	Pipeline point coordinate data

Return Value (Returns): None

Exceptions (Raises): None

---

sendUE4AddPointToPipelineMsg(copterID, messageDatas)

Function Description: Sends a message to append new points to an existing pipeline/tube object.

Parameter Name	Type	Required	Default Value	Description
copterID	int	Yes	None	Pipeline object ID
messageDatas	list	Yes	None	Point coordinate data to be appended

Returns: None
Raises: None

---

sendUE4DeletePointMsg(copterID, pointIndexs)

Function Description: Sends a message to delete specific points from a pipeline.

Arguments:

Parameter Name	Type	Required	Default Value	Description
copterID	int	Yes	None	Pipeline object ID
pointIndexs	list	Yes	None	Array of indices of points to be deleted

Returns: None
Raises: None

---

sendUE4SetPipelineScaleMsg(copterID, pointIndexs, size)

Function Description: Sends a message to set the pipeline thickness, modifying the radius/thickness of specified points.

Arguments:

Parameter Name	Type	Required	Default Value	Description
copterID	int	Yes	None	Pipeline object ID
pointIndexs	list	Yes	None	Array of point indices to be modified; -1 indicates all points
size	float	Yes	None	Pipeline radius in meters

Returns: None
Raises: None

---

sendUE4SetPipelineDiaphaneityMsg(copterID, pointIndexs, diaphaneity)

Function Description: Sends a message to set the pipeline transparency, modifying the material transparency of specified points.

Arguments:

Parameter Name	Type	Required	Default Value	Description
copterID	int	Yes	None	Pipeline object ID
pointIndexs	list	Yes	None	Array of point indices to be modified; -1 indicates all points
diaphaneity	float	Yes	None	Transparency value, typically in the range [0, 1]

Returns: None
Raises: None

---

sendUE4SetPipelineLightMsg(copterID, pointIndexs, light)

Function Description: Sends a message to set the pipeline emissive intensity, modifying the self-illumination effect of specified points.

Arguments:

Parameter Name	Type	Required	Default Value	Description
copterID	int	Yes	None	Pipeline object ID
pointIndexs	list	Yes	None	Array of point indices to be modified; -1 indicates all points
light	float	Yes	None	Emissive intensity value

Returns: None
Raises: None

---

sendUE4SetPipelineColorMsg(copterID, pointIndexs, Color_R, Color_G, Color_B, Color_A)

Function Description: Sends a message to set the pipeline color, modifying the material color (RGBA) of specified points.

Arguments:

Parameter Name	Type	Required	Default Value	Description
copterID	int	Yes	None	Pipeline object ID
pointIndexs	list	Yes	None	Array of point indices to be modified; -1 indicates all points
Color_R	float	Yes	None	Red channel value (0–1 or 0–255)
Color_G	float	Yes	None	Green channel value (0–1 or 0–255)
Color_B	float	Yes	None	Blue channel value (0–1 or 0–255)
Color_A	float	Yes	None	Alpha channel value (0–1 or 0–255)

Returns: None
Raises: None

---

sendUE4SetPipelinePosMsg(copterID, pointIndexs, messageDatas)

Function Description: Sends a message to set the position of pipeline points, modifying the spatial coordinates of specified points.

Arguments:

Parameter Name	Type	Required	Default Value	Description
copterID	int	Yes	None	Pipeline object ID
pointIndexs	list	Yes	None	Array of point indices to be modified
messageDatas	list	Yes	None	New point coordinate data in meters

Returns: None
Raises: None

---

sendUE4SetWidgetVisble(copterID, isShowUI)

Function Description: Sends a message to set widget visibility, controlling the display or hiding of UI widgets related to pipelines/lines.

Arguments:

Parameter Name	Type	Required	Default Value	Description
copterID	int	Yes	None	Pipeline/widget object ID
isShowUI	bool	Yes	None	Whether to show the UI widget; True to show, False to hide

Returns: None
Raises: None

sendUE4RobotExtAct(copterID=1, ActExt=[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], windowID=-1)

Function Description: Sends an extended action control command for the quadruped robot (robot dog) to the UE4 simulation environment. Control item activation is managed via a TypeMask bitmask, supporting multiple control modes including action commands, obstacle avoidance settings, target position, attitude control, and velocity vectors.

Arguments (Args):

Parameter Name	Type	Required	Default	Description
copterID	int	No	1	CopterID identifier of the robot dog
ActExt	list[float]	No	[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]	Extended action parameter array, consisting of 16 elements: 0. TypeMask (bitmask) 1. Robot dog action command (1: stand up, 2: jump, etc.) 2. Obstacle avoidance radius 3–5. Destination position x, y, z 6–8. Robot dog’s Roll, Pitch, Yaw 9–11. Robot dog’s forward vector X, Y, Z 12. Robot dog speed setting 13. Coordinate system used (1: NED, 2: FRD)
windowID	int	No	-1	Target window ID; -1 indicates sending to all windows

Returns: None

Raises: None

---

sendUE4MassMovement(robotDogID, childUAVID, isCombined)

Function Description: Sends combined/separated control commands for the robot dog and drone, enabling coordinated motion control for scenarios where the drone is carried by the robot dog.

Arguments (Args):

Parameter Name	Type	Required	Default	Description
robotDogID	int	Yes	-	ID identifier of the robot dog
childUAVID	int	Yes	-	ID identifier of the child drone (the one being carried)
isCombined	bool/int	Yes	-	Combined state flag: True/1 indicates combined, False/0 indicates separated

Returns: None

Raises: None

---

sendDogPosENoAltYaw(copterID, pos_x, pos_y, yaw)

Function Description: Sends control commands for the robot dog’s horizontal position (XY plane) and yaw angle, while maintaining constant altitude.

Arguments (Args):

Parameter Name	Type	Required	Default	Description
copterID	int	Yes	-	CopterID of the robot dog
pos_x	float	Yes	-	Target X coordinate (ENU coordinate system, unit: meters)
pos_y	float	Yes	-	Target Y coordinate (ENU coordinate system, unit: meters)
yaw	float	Yes	-	Target yaw angle (unit: radians)

Returns: None

Raises: None

---

sendDogPosENoAlt(copterID, pos_x, pos_y)

Function Description: Sends control commands for the robot dog’s horizontal position (XY plane), while maintaining constant altitude and yaw angle.

Arguments (Args):

Parameter Name	Type	Required	Default	Description
copterID	int	Yes	-	CopterID of the robot dog
pos_x	float	Yes	-	Target X coordinate (ENU coordinate system, unit: meters)
pos_y	float	Yes	-	Target Y coordinate (ENU coordinate system, unit: meters)

Returns: None

Raises: None

---

sendDogRateNoAltYaw(copterID, yaw_rate, speed_x, speed_y, axis)

Function Description: Sends rate control commands for the robot dog (yaw rate + horizontal velocity), while maintaining constant altitude.

Arguments (Args):

Parameter Name	Type	Required	Default	Description
copterID	int	Yes	-	CopterID of the robot dog
yaw_rate	float	Yes	-	Yaw rate (unit: radians/second)
speed_x	float	Yes	-	Velocity in X direction (unit: meters/second)
speed_y	float	Yes	-	Velocity in Y direction (unit: meters/second)
axis	int	Yes	-	Coordinate system selection (1: NED, 2: FRD/body-fixed frame)

Returns: None

Raises: None

---

sendDogVelENoAltYaw(copterID, yaw, speed_x, speed_y, axis)

Function Description: Sends velocity and feedforward yaw angle control commands for the robot dog, while maintaining constant altitude.

Arguments (Args):

Parameter Name	Type	Required	Default	Description
copterID	int	Yes	-	CopterID of the robot dog
yaw	float	Yes	-	Target yaw angle (unit: radians)
speed_x	float	Yes	-	Velocity in X direction (unit: meters/second)
speed_y	float	Yes	-	Velocity in Y direction (unit: meters/second)
axis	int	Yes	-	Coordinate system selection (1: NED, 2: FRD/body-fixed frame)

Returns: None

Raises: None

---

sendDogVelENoAlt(copterID, speed_x, speed_y, axis)

Function Description: Sends horizontal velocity control commands for the robot dog, while maintaining constant altitude and yaw angle.

Arguments (Args):

Parameter Name	Type	Required	Default Value	Description
copterID	int	Yes	-	CopterID of the robot dog
speed_x	float	Yes	-	Velocity in X direction (unit: m/s)
speed_y	float	Yes	-	Velocity in Y direction (unit: m/s)
axis	int	Yes	-	Coordinate system selection (1: NED, 2: FRD/body-fixed frame)

Returns: None

Raises: None

---

sendUE4DogSpeed(copterID, speed)

Description: Sends a command to set the scalar motion speed of the robot dog.

Args:

Parameter Name	Type	Required	Default Value	Description
copterID	int	Yes	-	CopterID of the robot dog
speed	float	Yes	-	Target speed value (unit: m/s)

Returns: None

Raises: None

---

sendUE4DogObstacleAvoidance(copterID, radius)

Description: Sends a command to set the obstacle avoidance radius of the robot dog, enabling or disabling autonomous obstacle avoidance.

Args:

Parameter Name	Type	Required	Default Value	Description
copterID	int	Yes	-	CopterID of the robot dog
radius	float	Yes	-	Obstacle avoidance radius (unit: m); obstacle avoidance is disabled when radius < 0; default is 0.05

Returns: None

Raises: None

---

sendUE4DogPlayAction(copterID, actionNum)

Description: Sends a command to play a predefined action of the robot dog, triggering a specific behavioral motion.

Args:

Parameter Name	Type	Required	Default Value	Description
copterID	int	Yes	-	CopterID of the robot dog
actionNum	int	Yes	-	Action number; valid values: 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: None

Raises: None

---

startMulticastListener()

Description: Starts the multicast listener to receive multicast data from the UE4 simulation environment.

Args: None

Returns: None

Raises: None

---

stopMulticastListener()

Description: Stops the multicast listener, terminating the reception of multicast data from the UE4 simulation environment.

Args: None

Returns: None

Raises: None

---

getRflyStatusMap()

Description: Retrieves the RflySim simulation status map, containing the current simulation runtime status and related information.

Args: None

Returns: Returns a dictionary storing various status information in key-value pairs.

Raises: None

---

getRflyIP(user)

Description: Retrieves the RflySim simulation IP address for a specified user.

Args:

Parameter Name	Type	Required	Default Value	Description
user	str	Yes	-	User identifier

Returns: Returns the IP address string corresponding to the specified user.

Raises: None

---

getRflyStartTime(user)

Description: Retrieves the RflySim simulation start time for a specified user.

Args:

Parameter Name	Type	Required	Default Value	Description
user	str	Yes	-	User identifier

Returns: Returns the simulation start timestamp (unit: seconds).

Raises: None

---

getRflyMapName(user)

Description: Retrieves the RflySim map name for a specified user.

Args:

Parameter Name	Type	Required	Default Value	Description
user	Any	Yes	-	Target user identifier

Returns: Map name

Raises: None

---

getRflyHeartbeat(user)

Description: Retrieves the RflySim heartbeat status for a specified user.

Args:

Parameter Name	Type	Required	Default Value	Description
user	Any	Yes	-	Target user identifier

Returns: Heartbeat status

Raises: None

---

getLocalUserName()

Function Description: Retrieves the local username.
Parameters (Args): None
Returns: Local username
Raises: None

---

getCurIP()

Function Description: Retrieves the current IP address.
Parameters (Args): None
Returns: Current IP address
Raises: None

---

getCurMapName()

Function Description: Retrieves the name of the current map.
Parameters (Args): None
Returns: Current map name
Raises: None

---

getCurStartTime()

Function Description: Retrieves the current startup time.
Parameters (Args): None
Returns: Current startup time
Raises: None

---

getCurHeartbeat()

Function Description: Retrieves the current heartbeat status.
Parameters (Args): None
Returns: Current heartbeat status
Raises: None

---

getAllIPAndUserName()

Function Description: Retrieves all IP addresses and their corresponding usernames.
Parameters (Args): None
Returns: Mapping of IP addresses to usernames
Raises: None

---

getAllUEMaps(is_ue5=False)

Function Description: Retrieves all valid map names (.umap files) from the specified UE project’s Content directory. Automatically excludes maps whose names start with _ or contain LogicMap.
Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
is_ue5	bool	No	False	Whether the project is UE5

Returns: List of valid map names
Raises: None

---

getAllUEItems(is_ue5=False)

Function Description: Traverses .xml files under the project’s Content directory and plugin Content directories, extracts MeshClass and Name, maps MeshClass to Chinese categories according to predefined rules, and returns a dictionary of names grouped by category.
Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
is_ue5	bool	No	False	Whether the project is UE5

Returns: Dictionary of names grouped by Chinese category
Raises: None

Advanced Usage Examples

Demonstrates complex composite scenarios (e.g., multi-class collaboration, asynchronous control, batch operations)

```python from RflySimSDK.ue import UE4CtrlAPI, VisionSensorReqNew, CameraData import time import threading

Initialize UE4 control API

ue = UE4CtrlAPI()

Batch create multiple drones and assign circular formation trajectories

def batch_create_drones(count, center_pos, radius, height): """Batch create drones and assign circular formation trajectories""" drones = [] for i in range(count): angle = (2 * 3.14159 * i) / count drone_id = 100 + i # Starting ID

    # Compute target position
    target_x = center_pos[0] + radius * __import__('math').cos(angle)
    target_y = center_pos[1] + radius * __import__('math').sin(angle)

    # Send initial position to ground
    ue.sendUE4Pos2Ground(drone_id, 1, 
                       [target_x, target_y, height, 0, 0, 0])
    drones.append({
        'id': drone_id,
        'angle': angle,
        'radius': radius
    })
return drones

Asynchronous vision sensor data acquisition

def async_vision_sensor(sensor_id, callback): """Asynchronously fetch vision sensor data""" sensor = VisionSensorReqNew()

def fetch_data():
    while True:
        # Copy latest data
        sensor.CopyData()
        callback(sensor_id, sensor)
        time.sleep(0.033)  # 30Hz refresh rate

thread = threading.Thread(target=fetch_data)
thread.daemon = True
thread.start()
return thread

Complex Scenario: Formation Flight + Dynamic Obstacle Avoidance + Visual Tracking

def complex_scenario(): # 1. Batch create 6 drones in a circular formation formation = batch_create_drones( count=6, center_pos=[0, 0, 0], radius=50, height=30 )

# 2. Add dynamic circular trajectories to the formation
for drone in formation:
    ue.circle_traj(
        drone['id'], 
        center=[0, 0, 30], 
        radius=drone['radius'], 
        speed=10, 
        height=30
    )

# 3. Asynchronously start visual sensor for target tracking
def on_vision_data(sensor_id, data):
    # Process vision data and dynamically adjust the formation
    print(f"Sensor {sensor_id} captured frame")

async_vision_sensor(201, on_vision_data)

# 4. Dynamic destruction and reconstruction (simulating fault recovery)
time.sleep(10)
ue.sendUE4Destroy(102)  # Destroy drone #2
time.sleep(2)
ue.sendUE4Pos2Ground(102, 1, [30, 30, 30, 0, 0, 0])  # Reconstruct

Notes and Pitfall Avoidance Guide

• ID Conflict Management: The copID parameter in methods such as sendUE4Pos and sendUE4Pos2Ground must be globally unique. Reusing the same ID for different positions will cause object flickering or abnormal control in UE4. It is recommended to establish an ID allocation table (e.g., 100–199 for multirotors, 200–299 for fixed-wing aircraft).

• Coordinate System Confusion: sendUE4Pos uses the NED (North-East-Down) coordinate system, whereas sendUE4Pos2Ground forces the height to zero relative to the ground. Mixing these two within circle_traj will result in incorrect height calculations. It is recommended to consistently use sendUE4Pos throughout and manually implement ground collision detection.

• Asynchronous Data Race: VisionSensorReqNew.CopyData() and CameraData.CopyData() are not thread-safe. Concurrent calls across threads may cause memory alignment errors. Mutex locks must be used for protection, or CopyDataOld can be used as a fallback to retrieve cached data from the previous frame.

• Uncontrolled Object Lifecycle: sendUE4Destroy only destroys the UE4 visual object and does not clean up lingering CoptReqData or ObjReqData instances on the Python side. Long-running simulations will suffer from memory leaks. It is recommended to implement an object pool and explicitly call del or reconstruct the UE4CtrlAPI instance.

• Network Timeout Blind Spot: sendUE4CmdNet relies on UDP transmission without acknowledgment. If the UE4 side is not running or firewall rules block the traffic, the call will fail silently. In production environments, this must be paired with reqVeCrashData or a custom heartbeat detection mechanism. Upon timeout, a reconnection logic should be triggered instead of continuing to queue commands.

Changelog

• 2026-04-10: Added interfaces for retrieving the UE map and list of placeable items.
• 2026-03-06: Added interface for overriding pipe creation.
• 2026-03-03: feat: SDK added IP handling mechanism to support local deployment on cloud.
• 2026-03-02: Added interface to delete a copter by ID.
• 2026-02-28: Added API to toggle visibility of waypoint ID labels in the UI.
• 2026-01-20: Fixed multicast interface and WSL environment bugs in UE4CtrlAPI.
• 2026-01-14: Modified multicast port.
• 2026-01-06: Added new interfaces for multicast-based IP retrieval and retrieving the RflySim-opened map.
• 2025-12-18: Added new UE control interfaces.
• 2025-09-11: fix: Added support for port reuse on Linux.
• 2025-08-19: fix: Updated vision and UE interfaces.
• 2025-07-14: fix
• 2025-07-11: fix
• 2024-07-30: Added gimbal interface documentation.
• 2024-07-10: Integrated interface content used by the gimbal program.