Skip to content

File syn_geo.h

FileList > src > syntropic > util > syn_geo.h

Go to the source code of this file

Geodetic coordinate transformations and distance calculation library. More...

  • #include "../common/syn_defs.h"
  • #include "../proto/syn_nmea.h"
  • #include <stdbool.h>
  • #include <stdint.h>

Classes

Type Name
struct SYN_ENU
Local East-North-Up (ENU) 3D Cartesian coordinates in meters.
struct SYN_GeoPos
Structured Geographic Position with accuracy bound and fix quality.

Public Functions

Type Name
double syn_geo_3d_distance_m (const SYN_ENU * p1, const SYN_ENU * p2)
Compute 3D Euclidean Cartesian distance between two ENU points.
SYN_Status syn_geo_ecef_to_enu (double x, double y, double z, double ref_lat_deg, double ref_lon_deg, double ref_alt_m, SYN_ENU * out_enu)
Convert global ECEF coordinates to a Local East-North-Up (ENU) frame.
SYN_Status syn_geo_ecef_to_wgs84 (double x, double y, double z, double * out_lat, double * out_lon, double * out_alt)
Convert Earth-Centered Earth-Fixed (ECEF) coordinates back to WGS-84 Geodetic.
double syn_geo_haversine_m (double lat1_deg, double lon1_deg, double lat2_deg, double lon2_deg)
Compute 2D surface geodesic distance using the Haversine formula.
SYN_Status syn_geo_pos_from_gga (const SYN_NMEA_GGA * gga, SYN_GeoPos * out_pos)
Populate a SYN_GeoPos structure from a parsed NMEA GGA sentence.
SYN_Status syn_geo_wgs84_to_ecef (double lat_deg, double lon_deg, double alt_m, double * out_x, double * out_y, double * out_z)
Convert WGS-84 Geodetic coordinates to Earth-Centered Earth-Fixed (ECEF).
SYN_Status syn_geo_wgs84_to_enu (double lat_deg, double lon_deg, double alt_m, double ref_lat_deg, double ref_lon_deg, double ref_alt_m, SYN_ENU * out_enu)
Direct conversion from WGS-84 Geodetic to Local East-North-Up (ENU).

Macros

Type Name
define SYN_GEO_WGS84_A 6378137.0
define SYN_GEO_WGS84_E2 0.0066943799901413165
define SYN_GEO_WGS84_INV_F 298.257223563

Detailed Description

Provides 64-bit precision WGS-84 ellipsoid coordinate transformations between spherical GNSS coordinates (Latitude, Longitude, Altitude) and 3D metric Cartesian frames: * ECEF (Earth-Centered Earth-Fixed): Global (X, Y, Z) in meters. * ENU (East-North-Up): Local (East, North, Up) in meters relative to an origin reference station (Lat0, Lon0, Alt0).

Preserves sub-millimeter mathematical precision, fully supporting 1 cm RTK Fixed GNSS positioning data parsed from NMEA sentences.

Usage: 

SYN_GeoPos base, rover;
// ... initialize base and rover positions ...
SYN_ENU local_enu;
syn_geo_wgs84_to_enu(rover.latitude, rover.longitude, rover.altitude_m,
                     base.latitude, base.longitude, base.altitude_m,
                     &local_enu);
// local_enu.east_m, local_enu.north_m, local_enu.up_m are in meters!

Public Functions Documentation

function syn_geo_3d_distance_m

Compute 3D Euclidean Cartesian distance between two ENU points. 

double syn_geo_3d_distance_m (
    const SYN_ENU * p1,
    const SYN_ENU * p2
)

Parameters:

  • p1 Point 1 ENU coordinates in meters. Must not be NULL.
  • p2 Point 2 ENU coordinates in meters. Must not be NULL.

Returns:

3D Euclidean distance in meters.

function syn_geo_ecef_to_enu

Convert global ECEF coordinates to a Local East-North-Up (ENU) frame. 

SYN_Status syn_geo_ecef_to_enu (
    double x,
    double y,
    double z,
    double ref_lat_deg,
    double ref_lon_deg,
    double ref_alt_m,
    SYN_ENU * out_enu
)

Computes metric Cartesian offsets (East, North, Up) relative to a reference station origin (ref_lat_deg, ref_lon_deg, ref_alt_m).

Parameters:

  • x Target ECEF X in meters.
  • y Target ECEF Y in meters.
  • z Target ECEF Z in meters.
  • ref_lat_deg Reference origin Latitude in decimal degrees.
  • ref_lon_deg Reference origin Longitude in decimal degrees.
  • ref_alt_m Reference origin Altitude in meters.
  • out_enu Output ENU Cartesian coordinates. Must not be NULL.

Returns:

SYN_OK on success, SYN_INVALID_PARAM if out_enu is NULL.

function syn_geo_ecef_to_wgs84

Convert Earth-Centered Earth-Fixed (ECEF) coordinates back to WGS-84 Geodetic. 

SYN_Status syn_geo_ecef_to_wgs84 (
    double x,
    double y,
    double z,
    double * out_lat,
    double * out_lon,
    double * out_alt
)

Uses Bowring's closed-form algorithm for high precision.

Parameters:

  • x ECEF X coordinate in meters.
  • y ECEF Y coordinate in meters.
  • z ECEF Z coordinate in meters.
  • out_lat Output Latitude in decimal degrees. Must not be NULL.
  • out_lon Output Longitude in decimal degrees. Must not be NULL.
  • out_alt Output Altitude in meters. Must not be NULL.

Returns:

SYN_OK on success, SYN_INVALID_PARAM if outputs are NULL.

function syn_geo_haversine_m

Compute 2D surface geodesic distance using the Haversine formula. 

double syn_geo_haversine_m (
    double lat1_deg,
    double lon1_deg,
    double lat2_deg,
    double lon2_deg
)

Parameters:

  • lat1_deg Point 1 Latitude in decimal degrees.
  • lon1_deg Point 1 Longitude in decimal degrees.
  • lat2_deg Point 2 Latitude in decimal degrees.
  • lon2_deg Point 2 Longitude in decimal degrees.

Returns:

2D Surface distance in meters.

function syn_geo_pos_from_gga

Populate a SYN_GeoPos structure from a parsed NMEA GGA sentence. 

SYN_Status syn_geo_pos_from_gga (
    const SYN_NMEA_GGA * gga,
    SYN_GeoPos * out_pos
)

Assigns automatic accuracy estimate based on fix quality: * RTK_FIXED: 0.01 m (1 cm) * RTK_FLOAT: 0.20 m (20 cm) * DGPS: 1.00 m * GPS: 2.50 m * INVALID/EST: 50.0 m

Parameters:

  • gga Parsed NMEA GGA sentence. Must not be NULL.
  • out_pos Output SYN_GeoPos struct. Must not be NULL.

Returns:

SYN_OK on success, SYN_INVALID_PARAM if args are NULL.

function syn_geo_wgs84_to_ecef

Convert WGS-84 Geodetic coordinates to Earth-Centered Earth-Fixed (ECEF). 

SYN_Status syn_geo_wgs84_to_ecef (
    double lat_deg,
    double lon_deg,
    double alt_m,
    double * out_x,
    double * out_y,
    double * out_z
)

Parameters:

  • lat_deg Latitude in decimal degrees (-90 to +90).
  • lon_deg Longitude in decimal degrees (-180 to +180).
  • alt_m Altitude above ellipsoid/MSL in meters.
  • out_x Output ECEF X coordinate in meters. Must not be NULL.
  • out_y Output ECEF Y coordinate in meters. Must not be NULL.
  • out_z Output ECEF Z coordinate in meters. Must not be NULL.

Returns:

SYN_OK on success, SYN_INVALID_PARAM if outputs are NULL.

function syn_geo_wgs84_to_enu

Direct conversion from WGS-84 Geodetic to Local East-North-Up (ENU). 

SYN_Status syn_geo_wgs84_to_enu (
    double lat_deg,
    double lon_deg,
    double alt_m,
    double ref_lat_deg,
    double ref_lon_deg,
    double ref_alt_m,
    SYN_ENU * out_enu
)

Convenience function combining WGS84->ECEF and ECEF->ENU.

Parameters:

  • lat_deg Target Latitude in decimal degrees.
  • lon_deg Target Longitude in decimal degrees.
  • alt_m Target Altitude in meters.
  • ref_lat_deg Reference origin Latitude in decimal degrees.
  • ref_lon_deg Reference origin Longitude in decimal degrees.
  • ref_alt_m Reference origin Altitude in meters.
  • out_enu Output ENU Cartesian coordinates in meters.

Returns:

SYN_OK on success, SYN_INVALID_PARAM if out_enu is NULL.

Macro Definition Documentation

define SYN_GEO_WGS84_A

#define SYN_GEO_WGS84_A `6378137.0`

WGS-84 Semi-major axis in meters (a).

define SYN_GEO_WGS84_E2

#define SYN_GEO_WGS84_E2 `0.0066943799901413165`

WGS-84 First eccentricity squared (e^2 = 2f - f^2).

define SYN_GEO_WGS84_INV_F

#define SYN_GEO_WGS84_INV_F `298.257223563`

WGS-84 Inverse flattening (1/f).

The documentation for this class was generated from the following file src/syntropic/util/syn_geo.h