UEMapServe 接口文档

简介

简述：该文件提供了用于对接虚幻引擎地图服务的UEMapServe类，实现RflySim仿真环境与虚幻引擎高清地形地图的通信交互。

该模块是RflySimSDK连接虚幻引擎仿真环境的核心交互组件，主要用于为无人机仿真任务提供可视化的三维地图环境支撑。它负责处理虚幻引擎端地图资源的调用、仿真状态的同步，支持开发者在RflySim中调用虚幻引擎生成的高精度地理地图、自定义场景地图，适用于大规模地形巡检、城市无人机任务仿真等需要高清可视化三维环境的仿真开发场景，能够将仿真运算逻辑与逼真的可视化渲染分离，保证仿真运行效率的同时提供优质的视觉仿真效果。

快速开始

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

import sys
import os
from RflySimSDK.ue import UEMapServe

if __name__ == "__main__":
    # 初始化UE地图服务，传入要加载的地图名称（无需后缀，示例使用默认地图example）
    map_serve = UEMapServe(name="example")
    # 加载PNG高程地图数据，自动查找文件位置
    elev_array, map_info = map_serve.LoadPngData(name="example")

    # 打印地图信息供验证
    print("地图范围信息：", map_info)
    print("高程数据形状：", elev_array.shape)
    print("加载完成，可使用elev_array进行后续路径规划等任务")

环境与依赖

• Python 环境：>= 3.8.10
• 依赖库：copy、cv2、numpy、os、socket、struct、sys、threading、time
• 前置准备：调用此接口前，必须确保UE仿真环境已就绪且RflySimSDK已完成初始化。

核心接口说明

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

全局常量与枚举定义

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

独立常量

无

---

全局/独立函数

无

---

UEMapServe 类

用于加载并解析Unreal Engine仿真环境中的地形高程数据，支持通过坐标查询指定位置地形高度、生成全地形点数据，常用于无人机地形仿真、路径规划等场景。

---

__init__(name="")

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

参数名	类型	是否必填	默认值	说明
name	str	否	""	待加载的地形数据文件名前缀（不含后缀）

返回值 (Returns)：

• UEMapServe 实例对象

异常 (Raises)：

• 无

---

LoadPngData(name)

功能说明：加载并解析指定名称的地形PNG高程数据和参数配置文件，自动搜索当前工作目录与PX4PSP默认地形目录，完成坐标缩放、偏移参数的计算，将结果保存为类属性。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
name	str	是	-	地形数据文件名前缀（不含.png/.txt后缀）

返回值 (Returns)：

• 无

异常 (Raises)：

• 无

示例：

from RflySimSDK.ue import UEMapServe
map_serve = UEMapServe()
# 加载名为terrain_sample的地形数据
map_serve.LoadPngData("terrain_sample")

---

getTerrainAltData(xin, yin)

功能说明：根据输入的平面坐标，通过双线性插值计算得到该位置对应的地形高度值。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
xin	float	是	-	待查询点的X方向平面坐标（单位：米）
yin	float	是	-	待查询点的Y方向平面坐标（单位：米）

返回值 (Returns)：

• float: 输入坐标对应的地形高度值（单位：米）

异常 (Raises)：

• 无

示例：

# 查询坐标(10, 20)处的地形高度
altitude = map_serve.getTerrainAltData(10, 20)
print(f"坐标(10, 20)处地形高度为: {altitude}米")

---

outTerrainPoint()

功能说明：遍历整个地形网格的所有单元格，计算每个单元格对应的实际坐标与地形高度，生成包含所有地形点坐标和高度的列表。 参数列表 (Args)： 无 返回值 (Returns)：

• list[tuple[float, float, float]]: 包含所有地形点信息的列表，每个元素为(x, y, h)元组，x、y为平面坐标，h为地形高度

异常 (Raises)：

• 无

示例：

# 获取整个地形所有点的坐标和高度数据
terrain_points = map_serve.outTerrainPoint()

---

进阶用法示例

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

import RflySimSDK.ue as rfly_ue
import numpy as np
from concurrent.futures import ThreadPoolExecutor

# 多线程批量提取多区域高程点的进阶场景：批量规划航测覆盖区的地形采样
map_server = rfly_ue.UEMapServe()
# 加载高清地形PNG高程数据
map_server.LoadPngData("terrain_highres.png")

# 定义多区域批量采样函数
def batch_sample_region(region_bounds):
    lon_min, lon_max, lat_min, lat_max, grid_size = region_bounds
    # 生成均匀分布的采样格网
    lon_grid = np.linspace(lon_min, lon_max, grid_size)
    lat_grid = np.linspace(lat_min, lat_max, grid_size)
    region_alt = []
    for lon in lon_grid:
        for lat in lat_grid:
            alt = map_server.outTerrainPoint(lon, lat)
            region_alt.append((lon, lat, alt))
    # 获取区域整体地形起伏统计
    _, mean_alt, std_alt = map_server.getTerrainAltData(lon_min, lon_max, lat_min, lat_max)
    return {"region_bounds": region_bounds, "samples": region_alt, "mean_alt": mean_alt, "std_alt": std_alt}

# 分区域异步处理，提升大场景地形采样效率
task_regions = [
    (116.0, 116.2, 40.0, 40.2, 50),
    (116.2, 116.4, 40.0, 40.2, 50),
    (116.0, 116.2, 40.2, 40.4, 50),
    (116.2, 116.4, 40.2, 40.4, 50)
]

with ThreadPoolExecutor(max_workers=4) as executor:
    all_region_result = list(executor.map(batch_sample_region, task_regions))

# 合并所有区域结果用于后续航迹规划地形适配
print(f"完成{len(all_region_result)}个区域地形采样，最大地形标准差为{max([res['std_alt'] for res in all_region_result])}")

注意事项与避坑指南

• 高程PNG坐标系适配：LoadPngData加载的高程PNG需与当前仿真场景的地理坐标系保持一致，若使用WGS84以外的坐标系需提前完成坐标转换，否则outTerrainPoint提取的高程会出现整体偏移。
• 边界坐标参数范围：调用getTerrainAltData时需保证输入的经纬度范围落在加载PNG对应的有效地理范围内，若输入范围超出边界，会返回错误的默认高程值，需提前对输入边界做裁剪处理。
• 批量操作的线程安全：UEMapServe对象本身不支持多线程同时修改内部高程缓存，多线程批量采样时仅可调用outTerrainPoint、getTerrainAltData这类只读方法，不可同时调用LoadPngData切换高程数据。
• 大尺寸PNG性能优化：加载超过4K分辨率的高程PNG时会占用较多内存，若仅需要单点高程提取，可提前对PNG做降采样处理，避免不必要的内存占用。

更新日志

• 2025-08-07: fix: 修复Python312兼容性问题
• 2024-09-06: fix:更新API
• 2024-08-29: fix:更新API页面
• 2024-08-29: fix: 增加自动检索CopterSim的Map路径
• 2024-06-13: fix:更新例程索引
• 2024-06-12: fix:更新接口注释
• 2024-06-04: fix：更新接口注释
• 2024-03-22: fix：增加outTerrainPoint接口
• 2023-11-15: fix:修复UEMapServe库文件
• 2023-10-24: feat: 重构公共库文件夹