EarthModel Interface Documentation

Introduction

Overview: This document provides a大地 model and coordinate transformation utility class based on the MAV coordinate system conventions, supporting unified coordinate conversion calculations in drone simulation scenarios.

In drone simulation and flight controller development, different application scenarios typically use varying coordinate definitions, including WGS84 latitude/longitude/altitude coordinates, ENU (East-North-Up), NED (North-East-Down), and other systems. The accuracy of coordinate transformations directly impacts the fidelity of drone positioning, navigation, and control algorithm simulations. As a foundational supporting module of the RflySimSDK control toolchain, this module adheres to the MAV coordinate system specifications used by PX4 flight controllers, enabling core functionalities such as coordinate transformation and geodetic position computation in simulation environments. It is applicable to diverse development and simulation scenarios including drone path planning, state estimation, and cross-vehicle coordinate alignment.

Quick Start

A minimal runnable example; copy and modify only minimal configuration to run.

from RflySimSDK.ctrl import EarthModel

# Initialize the Earth coordinate transformation model
earth = EarthModel()

# Define home point latitude, longitude, and altitude (units: radians, meters respectively); example uses approximate Beijing coordinates
lat0 = 39.9 * 3.1415926 / 180  # latitude in radians
lon0 = 116.3 * 3.1415926 / 180 # longitude in radians
h0 = 50  # origin altitude in meters

# Target point latitude, longitude, and altitude to be transformed
lat = 39.901 * 3.1415926 / 180
lon = 116.301 * 3.1415926 / 180
h = 100

# Step 1: Convert latitude/longitude/altitude (LLA) to Earth-Centered, Earth-Fixed (ECEF) coordinates
x_ecef, y_ecef, z_ecef = earth.lla2ecef(lat, lon, h)
print(f"Target point ECEF coordinates: X={x_ecef:.2f} Y={y_ecef:.2f} Z={z_ecef:.2f} meters")

# Step 2: Convert ECEF coordinates to ENU (East-North-Up) relative to the origin
x_enu, y_enu, z_enu = earth.ecef2enu(x_ecef, y_ecef, z_ecef, lat0, lon0, h0)
print(f"Target point ENU coordinates relative to origin: East={x_enu:.2f} North={y_enu:.2f} Up={z_enu:.2f} meters")

# Reverse transformation: ENU back to ECEF for verification
x_ecef_rev, y_ecef_rev, z_ecef_rev = earth.enu2ecef(x_enu, y_enu, z_enu, lat0, lon0, h0)
print(f"Reverse-transformed ECEF coordinates: X={x_ecef_rev:.2f} Y={y_ecef_rev:.2f} Z={z_ecef_rev:.2f} meters")

Environment & Dependencies

• Python Environment: >= 3.8.10
• Dependencies: copy, cv2, math, numpy, os, socket, struct, sys, threading, time
• Prerequisites: Before calling this interface, ensure the RflySimSDK module has been correctly imported and the basic environment has been configured.

Core Interface Description

The module EarthModel.py contains configuration variables, helper functions, and core business classes.

Global Constants and Enumerations

This section lists all globally accessible constants and enumeration definitions that can be directly referenced.

Standalone Constants

None

---

Enumerations

Coordinate

Reference: MAV_FRAME

Name	Type	Value	Description
LOCAL_NED	int	1	-
GLOBAL_INT	int	5	-
NED_BODY	int	8	-

---

Global/Standalone Functions

None

---

EarthModel Class

Provides coordinate transformation capabilities among Earth coordinate systems, supporting conversions among latitude/longitude/altitude (LLA), Earth-Centered Earth-Fixed (ECEF), East-North-Up (ENU), and North-East-Down (NED) coordinate systems. Commonly used in drone simulation for coordinate positioning and navigation calculations.

__init__()

Function Description: Initializes an instance of the EarthModel class.
Parameters (Args):

None
Returns:

• An EarthModel instance object

Raises:

• None

---

lla2ecef(lat, lon, h)

Function Description: Converts latitude/longitude/altitude coordinates (LLA, WGS84) to Earth-Centered Earth-Fixed (ECEF) coordinates.
Parameters (Args):

Parameter	Type	Required	Default	Description
lat	float	Yes	-	Latitude, in degrees
lon	float	Yes	-	Longitude, in degrees
h	float	Yes	-	Altitude, in meters

Returns:

• tuple[float, float, float]: ECEF coordinates (x, y, z), in meters

Raises:

• None

---

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

Function Description: Converts Earth-Centered Earth-Fixed (ECEF) coordinates to East-North-Up (ENU) coordinates relative to a reference point.
Parameters (Args):

Parameter	Type	Required	Default	Description
x	float	Yes	-	ECEF X-coordinate, in meters
y	float	Yes	-	ECEF Y-coordinate, in meters
z	float	Yes	-	ECEF Z-coordinate, in meters
lat0	float	Yes	-	Reference point latitude, in degrees
lon0	float	Yes	-	Reference point longitude, in degrees
h0	float	Yes	-	Reference point altitude, in meters

Returns:

• tuple[float, float, float]: ENU coordinates (East, North, Up), in meters

Raises:

• None

---

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

Function Description: Converts East-North-Up (ENU) coordinates relative to a reference point to Earth-Centered Earth-Fixed (ECEF) coordinates.
Parameters (Args):

Parameter	Type	Required	Default	Description
xEast	float	Yes	-	East component in ENU, in meters
yNorth	float	Yes	-	North component in ENU, in meters
zUp	float	Yes	-	Up component in ENU, in meters
lat0	float	Yes	-	Reference point latitude, in degrees
lon0	float	Yes	-	Reference point longitude, in degrees
h0	float	Yes	-	Reference point altitude, in meters

Returns:

• tuple[float, float, float]: ECEF coordinates (x, y, z), in meters

Raises:

• None

---

ecef2lla(x, y, z)

Function Description: Converts Earth-Centered Earth-Fixed (ECEF) coordinates to latitude/longitude/altitude coordinates (LLA, WGS84).
Parameters (Args):

Parameter	Type	Required	Default	Description
x	float	Yes	-	ECEF X-coordinate, in meters
y	float	Yes	-	ECEF Y-coordinate, in meters
z	float	Yes	-	ECEF Z-coordinate, in meters

Returns:

• tuple[float, float, float]: LLA coordinates (latitude, longitude, altitude); latitude and longitude in degrees, altitude in meters

Raises:

• None

---

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

Function Description: Directly converts latitude/longitude/altitude coordinates (LLA) to East-North-Up (ENU) coordinates relative to a reference point.
Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
lat	float	Yes	-	Latitude of the target point, in degrees
lon	float	Yes	-	Longitude of the target point, in degrees
h	float	Yes	-	Height of the target point, in meters
lat_ref	float	Yes	-	Latitude of the reference point, in degrees
lon_ref	float	Yes	-	Longitude of the reference point, in degrees
h_ref	float	Yes	-	Height of the reference point, in meters

Returns:

• tuple[float, float, float]: (East, North, Up) coordinates in the East-North-Up (ENU) frame, in meters

Raises:

• None

---

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

Function Description: Directly converts East-North-Up (ENU) coordinates, with the reference point as the origin, into Latitude-Longitude-Altitude (LLA) coordinates.

Args:

Parameter Name	Type	Required	Default Value	Description
xEast	float	Yes	-	East component of the ENU coordinate, in meters
yNorth	float	Yes	-	North component of the ENU coordinate, in meters
zUp	float	Yes	-	Up component of the ENU coordinate, in meters
lat_ref	float	Yes	-	Latitude of the reference point, in degrees
lon_ref	float	Yes	-	Longitude of the reference point, in degrees
h_ref	float	Yes	-	Height of the reference point, in meters

Returns:

• tuple[float, float, float]: LLA coordinates (latitude, longitude, altitude), with latitude and longitude in degrees and altitude in meters

Raises:

• None

---

lla2ned(lla, lla0)

Function Description: Converts Latitude-Longitude-Altitude (LLA) coordinates into North-East-Down (NED) coordinates, with the reference point as the origin.

Args:

Parameter Name	Type	Required	Default Value	Description
lla	list[float]/tuple[float]	Yes	-	Target point LLA coordinates, formatted as [latitude, longitude, altitude], with latitude and longitude in degrees and altitude in meters
lla0	list[float]/tuple[float]	Yes	-	Reference point LLA coordinates, formatted as [latitude, longitude, altitude], with latitude and longitude in degrees and altitude in meters

Returns:

• list[float]: NED coordinates [North, East, Down], in meters

Raises:

• None

---

ned2lla(ned, lla0)

Function Description: Converts North-East-Down (NED) coordinates, with the reference point as the origin, into Latitude-Longitude-Altitude (LLA) coordinates.

Args:

Parameter Name	Type	Required	Default Value	Description
ned	list[float]/tuple[float]	Yes	-	Target point NED coordinates, formatted as [North, East, Down], in meters
lla0	list[float]/tuple[float]	Yes	-	Reference point LLA coordinates, formatted as [latitude, longitude, altitude], with latitude and longitude in degrees and altitude in meters

Returns:

• list[float]: LLA coordinates [latitude, longitude, altitude], with latitude and longitude in degrees and altitude in meters

Raises:

• None

Example:

from RflySimSDK.ctrl import EarthModel

# Initialize Earth model
em = EarthModel()
# Reference point LLA (a location in Beijing)
ref_lat, ref_lon, ref_h = 39.9087, 116.4021, 50
# Target point LLA
tar_lat, tar_lon, tar_h = 39.9097, 116.4031, 100

# Convert LLA to ENU coordinates
enu = em.lla2enu(tar_lat, tar_lon, tar_h, ref_lat, ref_lon, ref_h)
print(f"ENU coordinates: {enu}")

# Convert ENU back to LLA coordinates
lla = em.enu2lla(enu[0], enu[1], enu[2], ref_lat, ref_lon, ref_h)
print(f"LLA coordinates: {lla}")

---

## Advanced Usage Examples  
> Demonstrates complex composite scenarios (e.g., multi-agent collaboration, asynchronous control, batch operations).

This example demonstrates batch conversion of position coordinates for multiple drones, enabling coordinate system transformations across various reference frames in multi-drone mission planning scenarios. Specifically, it first imports the coordinate transformation module from RflySimSDK, then reads pre-stored GPS latitude, longitude, and altitude arrays for multiple drones. It performs batch conversion of LLA (Latitude, Longitude, Altitude) coordinates to ENU (East-North-Up) coordinates relative to the takeoff point, followed by reverse conversion back to LLA coordinates to verify transformation accuracy—fulfilling the requirement for unified coordinate computation in multi-drone collaborative missions.

```python
import numpy as np
from RflySimSDK.ctrl.EarthModel import EarthModel

# Initialize Earth model parameters
em = EarthModel()
# Simulate LLA measurements (latitude, longitude, altitude) for 5 drones: [lat, lon, alt]
multi_uav_lla = np.array([
    [31.2304, 121.4737, 100],
    [31.2310, 121.4745, 120],
    [31.2298, 121.4729, 90],
    [31.2308, 121.4752, 110],
    [31.2295, 121.4720, 85]
])
# Use the first drone as the origin; batch convert all drones' LLA coordinates to ENU
origin_lla = multi_uav_lla[0]
multi_uav_enu = em.lla2enu(multi_uav_lla, origin_lla)
# Reverse conversion to verify transformation accuracy; obtain restored LLA coordinates
restore_lla = em.enu2lla(multi_uav_enu, origin_lla)
# Output coordinate restoration error
print(f"Maximum LLA restoration error: {np.max(np.abs(multi_uav_lla - restore_lla)):.8f}")

Notes and Pitfall Avoidance Guide

• Coordinate Unit Standards: When inputting LLA coordinates, latitude and longitude must be in degrees. Inputting values in radians directly will result in coordinate offsets of thousands of kilometers.
• Array Input Dimension Requirements: For batch coordinate conversion, the input array must have each row representing a single coordinate set. If a one-dimensional array (single coordinate set) is provided, it will be automatically reshaped; when defining custom batch inputs, ensure dimension alignment.
• Origin Parameter Requirement: When converting between LLA, ENU, and NED coordinate systems, the origin coordinate parameter must be provided. Omitting the origin will trigger a missing-parameter error.
• Ellipsoid Parameter Defaults: EarthModel uses WGS84 ellipsoid parameters by default. If the mission requires another ellipsoid model, reinitialize the model and update the corresponding parameters before performing conversions.

Changelog

• 2024-06-18: fix: API format adjustment
• 2024-06-13: fix: Update example index
• 2024-06-12: fix: Update interface comments
• 2024-06-12: fix: Update interface comments in earthmodel.py
• 2024-06-11: fix: Update interface comments
• 2023-11-09: feat: Add cloud-compatible interfaces
• 2023-10-24: feat: Fix several bugs
• 2023-10-23: fix: Remove UE4 control-related code from PX4MavCtrlV4.py; add EarthModel.py