跳转至

UEMapServe 接口文档

简介

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

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

快速开始

以下示例加载 Grasslands 地图数据，并查询地图坐标 (1, 1) 处的地形高度。

参考例程：[RflySim安装路径]\RflySimAPIs\3.RflySim3DUE\0.ApiExps\e6_RflySim3DCtrlAPI\4.TrajDemo

import UEMapServe


mapServe = UEMapServe.UEMapServe("Grasslands")
x = 1
y = 1
z = mapServe.getTerrainAltData(x, y)
print("地形高度:", z)

环境与依赖

  • 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()

进阶用法示例

以下示例读取 OldFactory 的全部地形点，并使用 Open3D 将点云保存为当前脚本目录下的 terrain_points.ply。

参考例程：[RflySim安装路径]\RflySimAPIs\3.RflySim3DUE\1.BasicExps\e3_RflySim3DTerrainPcd

import os

import open3d as o3d
import UEMapServe


mapServe = UEMapServe.UEMapServe("OldFactory")
terrainPoints = mapServe.outTerrainPoint()

pointCloud = o3d.geometry.PointCloud()
pointCloud.points = o3d.utility.Vector3dVector(terrainPoints)

outputPath = os.path.join(
    os.path.dirname(__file__),
    "terrain_points.ply",
)
o3d.io.write_point_cloud(outputPath, pointCloud)
print("文件已保存到", outputPath)

注意事项与避坑指南

  • 高程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: 重构公共库文件夹