EarthModel Interface Documentation¶

Introduction¶

Overview: This document provides a geodetic 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¶

The following example converts GPS latitude/longitude/altitude coordinates to NED coordinates relative to a reference point. Latitude and longitude in the interface inputs are in degrees, altitude is in meters.

Reference example: [RflySim installation path]\RflySimAPIs\5.RflySimFlyCtrl\0.ApiExps\14.SITLVeriGenCodeFirm\3.OffboardCtrlCodeGen

import EarthModel


earth = EarthModel.EarthModel()

# Map center and drone Home point, both in format [latitude, longitude, altitude]
mapCenterLLA = [40.1540302, 116.2593683, 50.0]
homeLLA = [40.1541302, 116.2594683, 55.0]

gpsOriginOffset = earth.lla2ned(homeLLA, mapCenterLLA)
print("NED offset of Home point relative to map center:", gpsOriginOffset)

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	Type	Required	Default	Description
`lat`	`float`	Yes	-	Target point latitude, in degrees
`lon`	`float`	Yes	-	Target point longitude, in degrees
`h`	`float`	Yes	-	Target point altitude, in meters
`lat_ref`	`float`	Yes	-	Reference point latitude, in degrees
`lon_ref`	`float`	Yes	-	Reference point longitude, in degrees
`h_ref`	`float`	Yes	-	Reference point altitude, in meters

Returns:

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

Raises:

None

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

Function Description: Directly converts East-North-Up (ENU) coordinates relative to a reference point to latitude/longitude/altitude coordinates (LLA).
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
`lat_ref`	`float`	Yes	-	Reference point latitude, in degrees
`lon_ref`	`float`	Yes	-	Reference point longitude, in degrees
`h_ref`	`float`	Yes	-	Reference point altitude, in meters

Returns:

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

Raises:

None

`lla2ned(lla, lla0)`¶

Function Description: Converts latitude/longitude/altitude coordinates (LLA) to North-East-Down (NED) coordinates relative to a reference point.
Parameters (Args):

Parameter	Type	Required	Default	Description
`lla`	`list[float]`/`tuple[float]`	Yes	-	Target point latitude, longitude, and altitude, format: [latitude, longitude, altitude]; latitude and longitude in degrees, altitude in meters
`lla0`	`list[float]`/`tuple[float]`	Yes	-	Reference point latitude, longitude, and altitude, format: [latitude, longitude, altitude]; latitude and longitude in degrees, 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 relative to a reference point to latitude/longitude/altitude coordinates (LLA).
Parameters (Args):

Parameter	Type	Required	Default	Description
`ned`	`list[float]`/`tuple[float]`	Yes	-	Target point NED coordinates, format: [North, East, Down], in meters
`lla0`	`list[float]`/`tuple[float]`	Yes	-	Reference point latitude, longitude, and altitude, format: [latitude, longitude, altitude]; latitude and longitude in degrees, altitude in meters

Returns:

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

Raises:

None

Example:

from RflySimSDK.ctrl import EarthModel

# Initialize Earth model
em = EarthModel()
# Reference point latitude, longitude, and altitude (a location in Beijing)
ref_lat, ref_lon, ref_h = 39.9087, 116.4021, 50
# Target point latitude, longitude, and altitude
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¶

The following example converts multiple GPS points uniformly to a local NED coordinate system and uses ned2lla for reverse conversion verification.

Reference example: [RflySim installation path]\RflySimAPIs\5.RflySimFlyCtrl\0.ApiExps\14.SITLVeriGenCodeFirm\3.OffboardCtrlCodeGen

import EarthModel


earth = EarthModel.EarthModel()
originLLA = [40.1540302, 116.2593683, 50.0]
vehicleLLAs = [
    [40.1541302, 116.2593683, 55.0],
    [40.1540302, 116.2594683, 60.0],
    [40.1539302, 116.2593683, 45.0],
]

for vehicleLLA in vehicleLLAs:
    ned = earth.lla2ned(vehicleLLA, originLLA)
    restoredLLA = earth.ned2lla(ned, originLLA)
    print("LLA:", vehicleLLA)
    print("NED:", ned)
    print("Restored LLA:", restoredLLA)

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 file

EarthModel Interface Documentation¶

Introduction¶

Quick Start¶

Environment & Dependencies¶

Core Interface Description¶

Global Constants and Enumerations¶

Standalone Constants¶

Enumerations¶

Coordinate¶

Global/Standalone Functions¶

EarthModel Class¶

__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)¶

Advanced Usage Examples¶

Notes and Pitfall Avoidance Guide¶

Changelog¶

`Coordinate`¶

`EarthModel` Class¶

`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)`¶