VehicleApi 接口文档¶

简介¶

简述：该文件提供了RflySim平台群体仿真场景下无人机载具与UE地图地球模型相关的基础API类，支持对群体无人机个体状态、地图地球模型进行管理与交互。

本模块作为RflySim群体无人机仿真开发的核心基础模块，为多无人机协同任务仿真提供了底层接口支持。其中Vehicle类可用于单独管理每一架仿真无人机的状态与控制指令，UEMapServe类负责对接虚幻引擎渲染的仿真地图服务，EarthModel类则提供了大地坐标系相关的模型支持，适用于多无人机协同侦察、编队控制、集群任务规划等各类群体无人机仿真开发场景，帮助开发者快速搭建自定义的群体无人机仿真任务。

快速开始¶

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

from RflySimSDK.swarm.VehicleApi import Vehicle

# 1. 初始化四轴无人机对象，修改CopterID即可适配自己的无人机编号
uav = Vehicle(
    CopterID=1,        # 无人机ID
    Vehicletype=3,     #  vehicle type 3代表四旋翼无人机
    mapName="Grasslands", # 仿真使用的地图名称
    updatefreq=100,    # 数据更新频率
    isBroadCast=False  # 是否开启广播模式
)

# 2. 获取原始偏航角，使用yawSat方法把偏航角归一化到[-pi, pi]区间
raw_yaw = 4.5  # 原始角度，单位弧度
normalized_yaw = uav.yawSat(raw_yaw)
print(f"原始偏航角{raw_yaw:.2f} 归一化后: {normalized_yaw:.2f} 弧度")

# 3. 也可以使用yawSat1做同样的归一化
normalized_yaw2 = uav.yawSat1(raw_yaw)
print(f"原始偏航角{raw_yaw:.2f} 归一化后(yawSat1): {normalized_yaw2:.2f} 弧度")

# 4. 滚转角归一化到[-pi, pi]区间
raw_roll = -5.0
normalized_roll = uav.RollSat(raw_roll)
print(f"原始滚转角{raw_roll:.2f} 归一化后: {normalized_roll:.2f} 弧度")

环境与依赖¶

Python 环境：>= 3.8.10
依赖库：copy、cv2、math、numpy、os、pymavlink、pymavlink.dialects.v20、socket、struct、sys、threading、time
前置准备：调用此接口前，必须先完成RflySimSDK的初始化并确保 swarm 模块已正确导入。

核心接口说明¶

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

全局常量与枚举定义¶

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

独立常量¶

无

全局/独立函数¶

无

`Vehicle` 类¶

单架无人机的API接口类，用于在RflySim仿真环境中对单个无人机进行控制和状态获取。

`init(CopterID=1, Vehicletype=3, mapName="Grasslands", updatefreq=100, isBroadCast=False)`¶

功能说明：初始化单架无人机的仿真连接与API配置，创建对应无人机的控制对象。 参数列表 (Args)：

参数名	类型	默认值	说明
CopterID	int	1	无人机的ID编号，对应仿真环境中无人机的编号
Vehicletype	int	3	无人机类型，1为固定翼，3为多旋翼
mapName	str	"Grasslands"	仿真环境使用的地图名称
updatefreq	int	100	无人机状态数据更新频率，单位为Hz
isBroadCast	bool	False	是否开启状态广播，开启后会向网络广播无人机状态数据

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

`yawSat(yaw)`¶

功能说明：将偏航角限幅到 [-π, π] 区间 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
yaw	None	是	无	需要限幅的输入偏航角

返回值 (Returns)：限幅后落在 [-π, π] 区间的偏航角 异常 (Raises)：无

`yawSat1(yaw)`¶

功能说明：将偏航角限幅到 [-π, π] 区间 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
yaw	None	是	无	需要限幅的输入偏航角

返回值 (Returns)：限幅后落在 [-π, π] 区间的偏航角 异常 (Raises)：无

`RollSat(Roll)`¶

功能说明：将横滚角限幅到 [-π, π] 区间 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
Roll	None	是	无	需要限幅的输入横滚角

返回值 (Returns)：限幅后落在 [-π, π] 区间的横滚角 异常 (Raises)：无

`sat(inPwm, thres=1)`¶

功能说明：对输入值进行限幅处理：若输入值大于阈值则设为阈值，小于负阈值则设为负阈值，否则保持原值不变 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
inPwm	None	是	0	需要进行限幅的输入值
thres	None	否	1	限幅的阈值，取值范围为 `[-thres, thres]`

返回值 (Returns)：限幅后的结果值 异常 (Raises)：无

`initSimpleModel(intState=[0, 0, 0], targetIP="127.0.0.1", GPSOrigin=[40.1540302, 116.2593683, 50])`¶

功能说明：初始化并启动无人机点质量模型用于控制。初始位置和偏航角与CopterSim界面上的值保持一致，初始高度可从CopterSim或UE4中获取 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
intState	None	否	`[0, 0, 0]`	无人机初始状态，依次包含初始X坐标 (m，北东坐标系下)、初始Y坐标 (m，北东坐标系下)、初始偏航角 (度)
targetIP	None	否	`127.0.0.1`	接收无人机状态信息的目标IP地址，一般为运行Simulink的电脑IP
GPSOrigin	None	否	`[40.1540302, 116.2593683, 50]`	GPS原点坐标，依次为纬度、经度、高度，用于坐标系转换

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

`RecMavLoop()`¶

功能说明：无 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无

`EndSimpleModel()`¶

功能说明：结束点质量模型运行 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无

`enFixedWRWTO()`¶

功能说明：无 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无

`TypeMask(EnList)`¶

功能说明：根据使能列表获取离线控制消息的类型掩码，掩码定义参考MAVLink官网POSITION_TARGET_TYPEMASK文档 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
EnList	None	是	无	控制量使能列表，标记哪些控制量在离线控制中生效

返回值 (Returns)：生成的离线位置目标消息类型掩码 异常 (Raises)：无

`SimpleModelLoop()`¶

功能说明：点质量模型的死循环运行函数，维持模型持续更新 参数列表 (Args)：无参数 返回值 (Returns)：无 异常 (Raises)：无

`ModelStep(CurTime=-1)`¶

功能说明：无 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
CurTime	None	否	-1	当前仿真时间

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

`SendUavState(CurTime)`¶

功能说明：无 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
CurTime	None	是	无	当前仿真时间

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

`ProssInput(dt)`¶

功能说明：无 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
dt	None	是	无	时间步长

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

`fixedPitchFromVel(vel)`¶

功能说明：无 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
vel	None	是	无	速度输入

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

`Step(dt)`¶

功能说明：无 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
dt	None	是	无	时间步长

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

`SendOutput(CurTime)`¶

功能说明：发送输出控制指令 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
CurTime	Any	是	无	当前时间戳

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

`SendPosNED(x=0, y=0, z=0, yaw=0)`¶

功能说明：向PX4发送地理北东下(NED)坐标系下的无人机目标位置，同时控制偏航角，位置单位为米，偏航角单位为弧度；当无人机飞行在地面上方时，z值小于0。 参数列表 (Args)：

参数名	类型	是否必填	说明
x	Any	否	NED坐标系下x方向(北向)目标位置，单位m
y	Any	否	NED坐标系下y方向(东向)目标位置，单位m
z	Any	否	NED坐标系下z方向(下向)目标位置，单位m
yaw	Any	否	目标偏航角，单位rad

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

`SendPosNEDNoYaw(x=0, y=0, z=0)`¶

功能说明：向PX4发送地理北东下(NED)坐标系下的无人机目标位置，不控制偏航角，位置单位为米；当无人机飞行在地面上方时，z值小于0。 参数列表 (Args)：

参数名	类型	是否必填	说明
x	Any	否	NED坐标系下x方向(北向)目标位置，单位m
y	Any	否	NED坐标系下y方向(东向)目标位置，单位m
z	Any	否	NED坐标系下z方向(下向)目标位置，单位m

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

`SendPosFRD(x=0, y=0, z=0, yaw=0)`¶

功能说明：向PX4发送机体前右下(FRD)坐标系下的无人机目标位置，同时控制偏航角，位置单位为米，偏航角单位为弧度；当无人机飞行在地面上方时，z值小于0。 参数列表 (Args)：

参数名	类型	是否必填	说明
x	Any	否	FRD坐标系下x方向(前向)目标位置，单位m
y	Any	否	FRD坐标系下y方向(右向)目标位置，单位m
z	Any	否	FRD坐标系下z方向(下向)目标位置，单位m
yaw	Any	否	目标偏航角，单位rad

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

`SendPosFRDNoYaw(x=0, y=0, z=0)`¶

功能说明：向PX4发送机体前右下(FRD)坐标系下的无人机目标位置，不控制偏航角，位置单位为米；当无人机飞行在地面上方时，z值小于0。 参数列表 (Args)：

参数名	类型	是否必填	说明
x	Any	否	FRD坐标系下x方向(前向)目标位置，单位m
y	Any	否	FRD坐标系下y方向(右向)目标位置，单位m
z	Any	否	FRD坐标系下z方向(下向)目标位置，单位m

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

`SendVelNED(vx=0, vy=0, vz=0, yawrate=0)`¶

功能说明：向PX4发送地理北东下(NED)坐标系下的无人机目标速度，同时控制偏航角速度，速度单位为m/s，偏航角速度单位为rad/s；当无人机向上飞行时，vz值小于0。 参数列表 (Args)：

参数名	类型	是否必填	说明
vx	Any	否	NED坐标系下x方向(北向)目标速度，单位m/s
vy	Any	否	NED坐标系下y方向(东向)目标速度，单位m/s
vz	Any	否	NED坐标系下z方向(下向)目标速度，单位m/s
yawrate	Any	否	目标偏航角速度，单位rad/s

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

`SendVelNEDNoYaw(vx, vy, vz)`¶

功能说明：向PX4发送地理北东下(NED)坐标系下的无人机目标速度，不控制偏航，速度单位为m/s；当无人机向上飞行时，vz值小于0。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
vx	Any	是	无	NED坐标系下x方向(北向)目标速度，单位m/s
vy	Any	是	无	NED坐标系下y方向(东向)目标速度，单位m/s
vz	Any	是	无	NED坐标系下z方向(下向)目标速度，单位m/s

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

`SendVelFRD(vx=0, vy=0, vz=0, yawrate=0)`¶

功能说明：向PX4发送机体前右下(FRD)坐标系下的无人机目标速度，同时控制偏航角速度，速度单位为m/s，偏航角速度单位为rad/s；当无人机向上飞行时，vz值小于0。 参数列表 (Args)：

参数名	类型	是否必填	说明
vx	Any	否	FRD坐标系下x方向(前向)目标速度，单位m/s
vy	Any	否	FRD坐标系下y方向(右向)目标速度，单位m/s
vz	Any	否	FRD坐标系下z方向(下向)目标速度，单位m/s
yawrate	Any	否	目标偏航角速度，单位rad/s

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

`SendVelNoYaw(vx, vy, vz)`¶

功能说明：向PX4发送机体前右下(FRD)坐标系下的无人机目标速度，不控制偏航角速度，速度单位为m/s；当无人机向上飞行时，vz值小于0。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
vx	Any	是	无	FRD坐标系下x方向(前向)目标速度，单位m/s
vy	Any	是	无	FRD坐标系下y方向(右向)目标速度，单位m/s
vz	Any	是	无	FRD坐标系下z方向(下向)目标速度，单位m/s

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

`sendBuf(buf, windowID=-1)`¶

功能说明：发送自定义缓冲区数据 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
buf	Any	是	无	待发送的缓冲区数据
windowID	Any	否	-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模型或更新已有模型的状态，发送的数据包含校验和、无人机ID、类型、PWM输出、速度、欧拉角、位置和时间戳信息。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
copterID	Any	否	1	无人机ID
vehicleType	Any	否	3	无人机类型
PosE	Any	否	[0, 0, 0]	地理NED坐标系下的位置，单位m
AngEuler	Any	否	[0, 0, 0]	滚转角、俯仰角、偏航角组成的欧拉角，单位rad
VelE	Any	否	[0, 0, 0]	地理坐标系下的速度，单位m/s
PWMs	Any	否	[0] * 8	8路PWM输出值
runnedTime	Any	否	-1	当前时间戳，单位s，-1表示使用内部计时
windowID	Any	否	-1	目标RflySim3D窗口ID，-1表示默认窗口

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

`SendCruiseSpeed(Speed=10)`¶

功能说明：发送指令修改飞行器的巡航速度，单位为m/s。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
Speed	Any	否	10	目标巡航速度，单位m/s

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

`SendCopterSpeed(Speed=5)`¶

功能说明：发送指令设置多旋翼飞行器的最大速度，单位为m/s。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
Speed	Any	否	5	多旋翼目标最大速度，单位m/s

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

`SendGroundSpeed(Speed=15)`¶

功能说明：发送指令修改飞行器的地面速度，单位为m/s。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
Speed	Any	否	15	目标地面速度，单位m/s

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

`SendCruiseRadius(rad=20)`¶

功能说明：发送指令修改飞行器的巡航转弯半径，单位为米。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
rad	Any	否	20	目标巡航转弯半径，单位m

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

`SendMavArm(isArm=0)`¶

功能说明：发送MAVLink解锁/上锁指令控制飞行器动力状态 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
isArm	Any	否	0	0代表上锁停机，非0代表解锁启动动力

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

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

功能说明：向RflySim3D（UE4引擎）发送控制指令，用于修改场景显示、相机参数、载具状态等，支持的指令格式如下：

b'RflyShowTextTime txt time'：让UE4显示指定文本，持续time秒
b'RflyShowText txt'：让UE4显示指定文本，持续5秒
RflyChangeMapbyID id：根据ID切换场景地图
RflyChangeMapbyName txt：根据名称切换场景地图
RflyChangeViewKeyCmd key num：等效于在UE4中按下按键+num的快捷键操作
RflyCameraPosAngAdd x y z roll pitch yaw：基于当前相机位置，增量偏移x-y-z(单位：米)和滚转-俯仰-偏航(单位：度)
RflyCameraPosAng x y z roll pitch yaw：直接设置相机相对于UE原点的x-y-z(单位：米)和滚转-俯仰-偏航(单位：度)
RflyCameraFovDegrees degrees：修改相机视场角(单位：度)
RflyChange3DModel CopterID veTypes=0：修改指定载具编号的3D模型ID
RflyChangeVehicleSize CopterID size=0：修改指定载具编号的尺寸大小
RflyMoveVehiclePosAng CopterID isFitGround x y z roll pitch yaw：基于当前位置增量移动载具到指定x-y-z(单位：米)和滚转-俯仰-偏航(单位：度)，isFitGround表示是否贴合地形
RflySetVehiclePosAng CopterID isFitGround x y z roll pitch yaw：直接设置载具相对于UE原点的x-y-z(单位：米)和滚转-俯仰-偏航(单位：度)，isFitGround表示是否贴合地形
RflyScanTerrainH xLeftBottom yLeftBottom xRightTop yRightTop scanHeight scanInterval：让UE4扫描指定范围地形，生成高度图png和高程数据txt文件，参数单位均为米
RflyCesiumOriPos lat lon Alt：修改Cesium地图原点的纬度、经度、高度(单位：度、米)
RflyClearCapture：清空图像捕获缓存

参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
cmd	bytes	是	无	要发送的控制指令字节流
windowID	int	否	-1	RflySim3D窗口ID，默认-1表示发送到主窗口

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

`SendVelYawAlt(vel=10, alt=-100, yaw=6.28)`¶

功能说明：向PX4发送期望速度、高度、偏航角控制指令，坐标系为地球北东下(NED)坐标系，NED坐标系下高度高于地面时z值为负 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
vel	数组[float]	否	10	期望北东方向速度，格式为[v_north, v_east]，单位：m/s
alt	float	否	-100	期望高度，NED坐标系下单位：m
yaw	float	否	6.28	期望偏航角，单位：rad

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

`sendMavTakeOff(xM=0, yM=0, zM=0, YawRad=0, PitchRad=20 / 180.0 * math.pi)`¶

功能说明：发送起飞指令，让飞行器起飞到指定的局部坐标系目标位置 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
xM	float	否	0	目标位置x坐标，单位：m
yM	float	否	0	目标位置y坐标，单位：m
zM	float	否	0	目标位置z坐标（高度），单位：m
YawRad	float	否	0	目标偏航角，单位：rad
PitchRad	float	否	20 / 180.0 * math.pi	起飞俯仰角，单位：rad

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

`sendMavTakeOffGPS(lat, lon, alt, yawDeg=0, pitchDeg=15)`¶

功能说明：发送起飞指令，让飞行器起飞到指定的GPS全球坐标系目标位置 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
lat	float	是	无	目标纬度，单位：度
lon	float	是	无	目标经度，单位：度
alt	float	是	无	目标高度，单位：m
yawDeg	float	否	0	目标偏航角，单位：度
pitchDeg	float	否	15	起飞俯仰角，单位：度

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

`UEMapServe` 类¶

用于在RflySim仿真环境中管理UE（虚幻引擎）地图高程数据，提供地图加载和地形高度查询功能，常用于无人机航迹规划、地形避障等需要获取地形高度信息的仿真场景。

`init(name="")`¶

功能说明：初始化UEMapServe类实例，创建地图服务对象 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`name`	`str`	否	`""`	要加载的地图文件名称

返回值 (Returns)：

UEMapServe 实例对象

异常 (Raises)：

无

`LoadPngData(name)`¶

功能说明：加载PNG格式的地形高程数据文件，解析并存储地形高度信息 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`name`	`str`	是	-	PNG高程数据文件的路径或名称

返回值 (Returns)：

无

异常 (Raises)：

无

示例：

from RflySimSDK.swarm import UEMapServe
map_serve = UEMapServe()
# 加载地形高程PNG文件
map_serve.LoadPngData("terrain_map.png")

`getTerrainAltData(xin, yin)`¶

功能说明：根据输入的坐标查询对应位置的地形高度数据 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`xin`	`float`/`np.ndarray`	是	-	查询点的东向坐标，支持单个坐标或批量坐标数组
`yin`	`float`/`np.ndarray`	是	-	查询点的北向坐标，维度需与`xin`保持一致

返回值 (Returns)：

float/np.ndarray: 对应坐标点的地形高度值，输入为数组时返回同维度数组

异常 (Raises)：

无

示例：

from RflySimSDK.swarm import UEMapServe
import numpy as np

map_serve = UEMapServe()
map_serve.LoadPngData("terrain_map.png")
# 查询单个点的地形高度
alt = map_serve.getTerrainAltData(100.5, 200.3)
# 批量查询多个点的地形高度
x_coords = np.array([100, 101, 102])
y_coords = np.array([200, 201, 202])
alts = map_serve.getTerrainAltData(x_coords, y_coords)

`EarthModel` 类¶

提供WGS84地球模型下多种坐标系之间的转换，用于无人机仿真中地理坐标与局部导航坐标的相互变换。

`init()`¶

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

EarthModel 实例对象

异常 (Raises)：

无

`lla2ecef(lat, lon, h)`¶

功能说明：将经纬度高度（LLA地理坐标）转换为地心地固（ECEF）直角坐标 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`lat`	`float`	是	-	纬度，单位：度
`lon`	`float`	是	-	经度，单位：度
`h`	`float`	是	-	海拔高度，单位：米

返回值 (Returns)：

tuple[float, float, float]: ECEF坐标系下的(x, y, z)坐标，单位：米

异常 (Raises)：

无

`ecef2enu(x, y, z, lat0, lon0, h0)`¶

功能说明：将地心地固（ECEF）坐标转换为原点在参考点的东向北向上（ENU）局部坐标 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`x`	`float`	是	-	ECEF坐标系下的X坐标，单位：米
`y`	`float`	是	-	ECEF坐标系下的Y坐标，单位：米
`z`	`float`	是	-	ECEF坐标系下的Z坐标，单位：米
`lat0`	`float`	是	-	参考点纬度，单位：度
`lon0`	`float`	是	-	参考点经度，单位：度
`h0`	`float`	是	-	参考点海拔高度，单位：米

返回值 (Returns)：

tuple[float, float, float]: ENU坐标系下的(xEast, yNorth, zUp)坐标，单位：米

异常 (Raises)：

无

`enu2ecef(xEast, yNorth, zUp, lat0, lon0, h0)`¶

功能说明：将原点在参考点的东向北向上（ENU）局部坐标转换为地心地固（ECEF）坐标 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`xEast`	`float`	是	-	ENU坐标系下的东向坐标，单位：米
`yNorth`	`float`	是	-	ENU坐标系下的北向坐标，单位：米
`zUp`	`float`	是	-	ENU坐标系下的天向坐标，单位：米
`lat0`	`float`	是	-	参考点纬度，单位：度
`lon0`	`float`	是	-	参考点经度，单位：度
`h0`	`float`	是	-	参考点海拔高度，单位：米

返回值 (Returns)：

tuple[float, float, float]: ECEF坐标系下的(x, y, z)坐标，单位：米

异常 (Raises)：

无

`ecef2lla(x, y, z)`¶

功能说明：将地心地固（ECEF）直角坐标转换为经纬度高度（LLA地理坐标） 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`x`	`float`	是	-	ECEF坐标系下的X坐标，单位：米
`y`	`float`	是	-	ECEF坐标系下的Y坐标，单位：米
`z`	`float`	是	-	ECEF坐标系下的Z坐标，单位：米

返回值 (Returns)：

tuple[float, float, float]: LLA坐标系下的(lat, lon, h)坐标，纬度经度单位为度，高度单位为米

异常 (Raises)：

无

`lla2enu(lat, lon, h, lat_ref, lon_ref, h_ref)`¶

功能说明：直接将经纬度高度（LLA）坐标转换为参考点对应ENU局部坐标 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`lat`	`float`	是	-	目标点纬度，单位：度
`lon`	`float`	是	-	目标点经度，单位：度
`h`	`float`	是	-	目标点海拔高度，单位：米
`lat_ref`	`float`	是	-	参考点纬度，单位：度
`lon_ref`	`float`	是	-	参考点经度，单位：度
`h_ref`	`float`	是	-	参考点海拔高度，单位：米

返回值 (Returns)：

tuple[float, float, float]: ENU坐标系下的(xEast, yNorth, zUp)坐标，单位：米

异常 (Raises)：

无

`enu2lla(xEast, yNorth, zUp, lat_ref, lon_ref, h_ref)`¶

功能说明：直接将参考点对应ENU局部坐标转换为经纬度高度（LLA）坐标 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`xEast`	`float`	是	-	ENU坐标系下的东向坐标，单位：米
`yNorth`	`float`	是	-	ENU坐标系下的北向坐标，单位：米
`zUp`	`float`	是	-	ENU坐标系下的天向坐标，单位：米
`lat_ref`	`float`	是	-	参考点纬度，单位：度
`lon_ref`	`float`	是	-	参考点经度，单位：度
`h_ref`	`float`	是	-	参考点海拔高度，单位：米

返回值 (Returns)：

tuple[float, float, float]: LLA坐标系下的(lat, lon, h)坐标，纬度经度单位为度，高度单位为米

异常 (Raises)：

无

`lla2ned(lla, lla0)`¶

功能说明：将经纬度高度（LLA）坐标转换为原点在参考点的北东下（NED）局部坐标 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`lla`	`tuple[float, float, float]`	是	-	目标点经纬度高度，格式为(lat, lon, h)，纬度经度单位为度，高度单位为米
`lla0`	`tuple[float, float, float]`	是	-	参考点经纬度高度，格式为(lat0, lon0, h0)，纬度经度单位为度，高度单位为米

返回值 (Returns)：

tuple[float, float, float]: NED坐标系下的(north, east, down)坐标，单位：米

异常 (Raises)：

无

`ned2lla(ned, lla0)`¶

功能说明：将原点在参考点的北东下（NED）局部坐标转换为经纬度高度（LLA）坐标 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`ned`	`tuple[float, float, float]`	是	-	NED坐标系下坐标，格式为(north, east, down)，单位：米
`lla0`	`tuple[float, float, float]`	是	-	参考点经纬度高度，格式为(lat0, lon0, h0)，纬度经度单位为度，高度单位为米

返回值 (Returns)：

tuple[float, float, float]: LLA坐标系下的(lat, lon, h)坐标，纬度经度单位为度，高度单位为米

异常 (Raises)：

无

示例：

from RflySimSDK.swarm import EarthModel
# 初始化坐标转换模型
em = EarthModel()
# LLA转ENU：以起点(30.5度, 114.2度, 10米)为参考，计算目标点的局部坐标
lat, lon, h = 30.501, 114.201, 15
lat_ref, lon_ref, h_ref = 30.5, 114.2, 10
xEast, yNorth, zUp = em.lla2enu(lat, lon, h, lat_ref, lon_ref, h_ref)
print(f"ENU坐标：东向{xEast:.2f}m，北向{yNorth:.2f}m，天向{zUp:.2f}m")
# ENU转回LLA验证
new_lat, new_lon, new_h = em.enu2lla(xEast, yNorth, zUp, lat_ref, lon_ref, h_ref)
print(f"转回LLA：纬度{new_lat:.4f}度，经度{new_lon:.4f}度，高度{new_h:.2f}m")

进阶用法示例¶

展示复杂组合场景（如多类协作、异步控制、批量操作）

本示例实现了多无人机集群编队的地形适配位置计算+异步姿态饱和控制的组合场景，结合了swarm模块下 Vehicle 集群控制、UEMapServe 地形读取与 EarthModel 坐标转换三类功能的协作，可以批量根据实际地形调整无人机目标位置，并异步给每架无人机下发符合舵面限位要求的姿态指令：

import RflySimSDK.swarm as rs
import numpy as np

# 初始化多无人机集群控制对象
drone_swarm = [rs.Vehicle() for i in range(5)]
# 开启仿真简单模型循环
for drone in drone_swarm:
    drone.initSimpleModel()
drone.RecMavLoop()
drone.SimpleModelLoop()

# 加载UE地形高程数据，获取目标航点区域的地形高度
map_serve = rs.UEMapServe()
map_serve.LoadPngData()
coord_trans = rs.EarthModel()

# 批量计算适配地形的ENU目标坐标
target_lonlat = [(116.397, 39.908) for _ in range(5)]
target_lla = []
for lon, lat in target_lonlat:
    alt = map_serve.getTerrainAltData(lon, lat)
    # 无人机在地形上方100m飞行
    target_lla.append([lon, lat, alt + 100])

# 异步对每架无人机执行坐标转换+姿态饱和控制
for idx, drone in enumerate(drone_swarm):
    lla = target_lla[idx]
    # 转换为相对于原点的ENU坐标
    origin_lla = [116.397, 39.908, 100]
    enu_pos = coord_trans.lla2enu(lla, origin_lla)
    # 对偏航角做饱和限制，输出符合物理限制的控制量
    limited_yaw = drone.yawSat(enu_pos[0] * 0.1)
    # 应用类型掩码后下发控制指令
    masked_yaw = drone.TypeMask(limited_yaw, mask=0x04)

# 结束仿真时释放资源
drone.EndSimpleModel()

注意事项与避坑指南¶

坐标转换输入顺序一致性：EarthModel类中经纬度高度转换方法均采用(经度,纬度,高度)的输入顺序，若颠倒经纬度顺序会产生百米级的坐标偏差，使用前需要核对输入参数顺序。
仿真模型生命周期管理：调用Vehicle类的initSimpleModel开启简单模型后，必须在任务结束时调用EndSimpleModel释放资源，重复初始化未释放的模型会导致端口占用、仿真进程崩溃。
地形数据加载前置要求：调用UEMapServe的getTerrainAltData获取地形高程前，必须先调用LoadPngData完成高程地图数据加载，未加载数据时获取到的高度为默认的0值，会导致飞行高度计算错误。
饱和控制方法匹配场景：Vehicle类提供了yawSat、yawSat1、RollSat等多个分通道饱和限制方法，需要对应控制通道选择对应方法，混用会导致姿态控制量溢出超出无人机舵面行程限制。

更新日志¶

2024-12-10: fix:更新集群控制接口注释
2024-07-18: fix:更新API主页索引
2023-11-10: 移动VehicleApi.py 的位置

VehicleApi 接口文档¶

简介¶

快速开始¶

环境与依赖¶

核心接口说明¶

全局常量与枚举定义¶

独立常量¶

全局/独立函数¶

Vehicle 类¶

__init__(CopterID=1, Vehicletype=3, mapName="Grasslands", updatefreq=100, isBroadCast=False)¶

yawSat(yaw)¶

yawSat1(yaw)¶

RollSat(Roll)¶

sat(inPwm, thres=1)¶

initSimpleModel(intState=[0, 0, 0], targetIP="127.0.0.1", GPSOrigin=[40.1540302, 116.2593683, 50])¶

RecMavLoop()¶

EndSimpleModel()¶

enFixedWRWTO()¶

TypeMask(EnList)¶

SimpleModelLoop()¶

ModelStep(CurTime=-1)¶

SendUavState(CurTime)¶

ProssInput(dt)¶

fixedPitchFromVel(vel)¶

Step(dt)¶

SendOutput(CurTime)¶

SendPosNED(x=0, y=0, z=0, yaw=0)¶

SendPosNEDNoYaw(x=0, y=0, z=0)¶

SendPosFRD(x=0, y=0, z=0, yaw=0)¶

SendPosFRDNoYaw(x=0, y=0, z=0)¶

SendVelNED(vx=0, vy=0, vz=0, yawrate=0)¶

SendVelNEDNoYaw(vx, vy, vz)¶

SendVelFRD(vx=0, vy=0, vz=0, yawrate=0)¶

SendVelNoYaw(vx, vy, vz)¶

sendBuf(buf, windowID=-1)¶

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

SendCruiseSpeed(Speed=10)¶

SendCopterSpeed(Speed=5)¶

SendGroundSpeed(Speed=15)¶

SendCruiseRadius(rad=20)¶

SendMavArm(isArm=0)¶

sendUE4Cmd(cmd, windowID=-1)¶

SendVelYawAlt(vel=10, alt=-100, yaw=6.28)¶

sendMavTakeOff(xM=0, yM=0, zM=0, YawRad=0, PitchRad=20 / 180.0 * math.pi)¶

sendMavTakeOffGPS(lat, lon, alt, yawDeg=0, pitchDeg=15)¶

UEMapServe 类¶

__init__(name="")¶

LoadPngData(name)¶

getTerrainAltData(xin, yin)¶

EarthModel 类¶

__init__()¶

lla2ecef(lat, lon, h)¶

ecef2enu(x, y, z, lat0, lon0, h0)¶

enu2ecef(xEast, yNorth, zUp, lat0, lon0, h0)¶

ecef2lla(x, y, z)¶

lla2enu(lat, lon, h, lat_ref, lon_ref, h_ref)¶

enu2lla(xEast, yNorth, zUp, lat_ref, lon_ref, h_ref)¶

lla2ned(lla, lla0)¶

ned2lla(ned, lla0)¶

进阶用法示例¶

注意事项与避坑指南¶

更新日志¶

`Vehicle` 类¶

`init(CopterID=1, Vehicletype=3, mapName="Grasslands", updatefreq=100, isBroadCast=False)`¶

`yawSat(yaw)`¶

`yawSat1(yaw)`¶

`RollSat(Roll)`¶

`sat(inPwm, thres=1)`¶

`initSimpleModel(intState=[0, 0, 0], targetIP="127.0.0.1", GPSOrigin=[40.1540302, 116.2593683, 50])`¶

`RecMavLoop()`¶

`EndSimpleModel()`¶

`enFixedWRWTO()`¶

`TypeMask(EnList)`¶

`SimpleModelLoop()`¶

`ModelStep(CurTime=-1)`¶

`SendUavState(CurTime)`¶

`ProssInput(dt)`¶

`fixedPitchFromVel(vel)`¶

`Step(dt)`¶

`SendOutput(CurTime)`¶

`SendPosNED(x=0, y=0, z=0, yaw=0)`¶

`SendPosNEDNoYaw(x=0, y=0, z=0)`¶

`SendPosFRD(x=0, y=0, z=0, yaw=0)`¶

`SendPosFRDNoYaw(x=0, y=0, z=0)`¶

`SendVelNED(vx=0, vy=0, vz=0, yawrate=0)`¶

`SendVelNEDNoYaw(vx, vy, vz)`¶

`SendVelFRD(vx=0, vy=0, vz=0, yawrate=0)`¶

`SendVelNoYaw(vx, vy, vz)`¶

`sendBuf(buf, windowID=-1)`¶

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

`SendCruiseSpeed(Speed=10)`¶

`SendCopterSpeed(Speed=5)`¶

`SendGroundSpeed(Speed=15)`¶

`SendCruiseRadius(rad=20)`¶

`SendMavArm(isArm=0)`¶

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

`SendVelYawAlt(vel=10, alt=-100, yaw=6.28)`¶

`sendMavTakeOff(xM=0, yM=0, zM=0, YawRad=0, PitchRad=20 / 180.0 * math.pi)`¶

`sendMavTakeOffGPS(lat, lon, alt, yawDeg=0, pitchDeg=15)`¶

`UEMapServe` 类¶

`init(name="")`¶

`LoadPngData(name)`¶

`getTerrainAltData(xin, yin)`¶

`EarthModel` 类¶

`init()`¶

`lla2ecef(lat, lon, h)`¶

`ecef2enu(x, y, z, lat0, lon0, h0)`¶

`enu2ecef(xEast, yNorth, zUp, lat0, lon0, h0)`¶

`ecef2lla(x, y, z)`¶

`lla2enu(lat, lon, h, lat_ref, lon_ref, h_ref)`¶

`enu2lla(xEast, yNorth, zUp, lat_ref, lon_ref, h_ref)`¶

`lla2ned(lla, lla0)`¶

`ned2lla(ned, lla0)`¶