UEMapServe Interface Documentation

Introduction

Overview: This file provides the UEMapServe class for interfacing with Unreal Engine map services, enabling communication and interaction between the RflySim simulation environment and Unreal Engine’s high-definition terrain maps.

This module serves as the core interactive component of the RflySimSDK for connecting to the Unreal Engine simulation environment. It primarily supports visualization of 3D map environments for drone simulation missions. It handles the invocation of map resources on the Unreal Engine side, synchronization of simulation states, and supports developers in RflySim to utilize high-precision geographic maps and custom scene maps generated by Unreal Engine. It is suitable for simulation development scenarios requiring high-definition visual 3D environments, such as large-scale terrain inspection and urban drone mission simulation. It decouples simulation computation logic from realistic visual rendering, ensuring simulation runtime efficiency while delivering high-quality visual simulation effects.

Quick Start

The following example loads the Grasslands map data and queries the terrain height at map coordinates (1, 1).

Reference example: [RflySim installation path]\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("Terrain height:", z)

Environment and Dependencies

• Python Environment: >= 3.8.10
• Dependencies: copy, cv2, numpy, os, socket, struct, sys, threading, time
• Prerequisites: Before calling this interface, ensure the UE simulation environment is ready and RflySimSDK has been initialized.

Core Interface Description

The module UEMapServe.py includes configuration variables, helper functions, and the core business class.

Global Constants and Enumerations

This section lists all globally accessible constants and enumerations defined in the module.

Standalone Constants

None

---

Global/Standalone Functions

None

---

UEMapServe Class

Used to load and parse terrain elevation data from the Unreal Engine simulation environment. Supports querying terrain height at specified coordinates and generating full terrain point data. Commonly used in drone terrain simulation and path planning scenarios.

---

__init__(name="")

Function Description: Initializes an instance of the UEMapServe map service class.
Arguments (Args):

Parameter Name	Type	Required	Default	Description
name	str	No	""	Prefix of the terrain data file name to load (excluding file extension)

Return Value (Returns):

• UEMapServe instance object

Exceptions (Raises):

• None

---

LoadPngData(name)

Function Description: Loads and parses the specified terrain PNG elevation data and parameter configuration file. Automatically searches the current working directory and the default PX4PSP terrain directory, computes coordinate scaling and offset parameters, and stores results as class attributes.
Arguments (Args):

Parameter Name	Type	Required	Default	Description
name	str	Yes	—	Prefix of the terrain data file name (excluding .png/.txt extensions)

Return Value (Returns):

• None

Exceptions (Raises):

• None

Example:

from RflySimSDK.ue import UEMapServe
map_serve = UEMapServe()
# Load terrain data named "terrain_sample"
map_serve.LoadPngData("terrain_sample")

---

getTerrainAltData(xin, yin)

Function Description: Computes the terrain height at the given planar coordinates using bilinear interpolation.
Arguments (Args):

Parameter Name	Type	Required	Default	Description
xin	float	Yes	—	X-coordinate (in meters) of the query point
yin	float	Yes	—	Y-coordinate (in meters) of the query point

Return Value (Returns):

• float: Terrain height (in meters) corresponding to the input coordinates

Exceptions (Raises):

• None

Example:

# Query terrain altitude at coordinate (10, 20)
altitude = map_serve.getTerrainAltData(10, 20)
print(f"Terrain altitude at (10, 20): {altitude} meters")

---

outTerrainPoint()

Function Description: Iterates through all grid cells of the entire terrain mesh, computes the actual coordinates and terrain height for each cell, and generates a list containing all terrain point coordinates and heights.
Arguments (Args):
None
Return Value (Returns):

• list[tuple[float, float, float]]: List of all terrain points; each element is an (x, y, h) tuple, where x and y are planar coordinates and h is terrain height.

Exceptions (Raises):

• None

Example:

# Retrieve coordinates and altitude data for all terrain points
terrain_points = map_serve.outTerrainPoint()

---

Advanced Usage Examples

The following example reads all terrain points of OldFactory and uses Open3D to save the point cloud as terrain_points.ply in the current script directory.

Reference example: [RflySim installation path]\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("File saved to", outputPath)

Notes and Pitfall Avoidance Guide

• Elevation PNG Coordinate System Compatibility: The elevation PNG loaded via LoadPngData must match the geographic coordinate system of the current simulation scene. If a coordinate system other than WGS84 is used, coordinate transformation must be performed beforehand; otherwise, elevation values extracted via outTerrainPoint will exhibit systematic offsets.
• Boundary Coordinate Parameter Range: When calling getTerrainAltData, ensure the input longitude and latitude range falls within the valid geographic extent corresponding to the loaded PNG. If the input range exceeds the boundary, erroneous default elevation values will be returned; thus, input boundaries should be clipped in advance.
• Thread Safety in Batch Operations: The UEMapServe object itself does not support concurrent modification of its internal elevation cache. During multithreaded batch sampling, only read-only methods such as outTerrainPoint and getTerrainAltData may be invoked; methods like LoadPngData, which modify internal state, must not be called concurrently.
• Performance Optimization for Large PNGs: Loading elevation PNGs exceeding 4K resolution consumes significant memory. If only single-point elevation extraction is required, consider downsampling the PNG in advance to avoid unnecessary memory overhead.

Changelog

• 2025-08-07: fix: Resolve Python 3.12 compatibility issue
• 2024-09-06: fix: Update API
• 2024-08-29: fix: Update API page
• 2024-08-29: fix: Add automatic retrieval of CopterSim Map path
• 2024-06-13: fix: Update example index
• 2024-06-12: fix: Update interface comments
• 2024-06-04: fix: Update interface comments
• 2024-03-22: fix: Add outTerrainPoint interface
• 2023-11-15: fix: Fix UEMapServe library file
• 2023-10-24: feat: Restructure public library folder