cppmap3d Documentation

https://github.com/ClancyWalters/cppmap3d

Implementation details and examples

This library was written as a baseline for 3D coordinate conversions. It’s primarily a direct adaptation of pymap3d and so will share performance characteristics of that libraries’ choice of algorithms. It’s intended to have high compatability, even with old compilers, and avoids sacrificing performance where possible.

The library is intended to be minimally invasive pulling in only <cmath> from the STL and using no data structures. Compatability and avoiding the STL result in the heavy use of out paramters, if this is undesirable, I recommend writing a wrapper using structs or std::tuple<>.

#import "cppmap3d.hh"

double x, y, z;
double lat, lon, alt;
double az, el, range;
cppmap3d::ecef2aer(x, y, z, lat, lon, alt, az, el, range);

One concession to performance is a #define exists for using a significantly faster ecef2geodetic. This breaks parity with pymap3d.

#define CPPMAP3D_ECEF2GEODETIC_OLSON
#import "cppmap3d.hh"

double x, y, z;
double lat, lon, alt;
cppmap3d::ecef2geodetic(x, y, z, lat, lon, alt); //roughly 2x speed of You (2000)

Development / Running DocTest & Nanobench

Clone the project recursively

git clone --recursive https://github.com/ClancyWalters/cppmap3d.git

Setup vcpkg

.\vcpkg\bootstrap-vcpkg.bat
.\vcpkg\vcpkg.exe install
.\vcpkg\vcpkg.exe integrate install

Build the project, tests, and Docs. Obviously choose an appropriate present.

cmake --build --preset=windows-x64-debug

Run the tests

.\out\build\windows-x64-debug\cppmap3d_tests.exe

Run the benchmarking (should be done in release)

.\out\build\windows-x64-release\cppmap3d_benchmarks.exe

documentation is compiled locally at out/build/windows-x64-release/docs/sphinx/index.html

Docs

namespace cppmap3d

C++ 3D geographic coordinate conversions

Enums

enum class Ellipsoid

Ellipsoids used to approximate the shape of the earth.

See also

pymap3d ellipsoid source

Values:

enumerator Maupertuis
enumerator Plessis
enumerator Everest1830
enumerator Everest1830Modified
enumerator Everest1967
enumerator Airy
enumerator Bessel
enumerator Clarke1866
enumerator Clarke1878
enumerator Clarke1860
enumerator Helmert
enumerator Hayford
enumerator International1924
enumerator Krassovsky1940
enumerator WGS66
enumerator Australian
enumerator International1967
enumerator GRS67
enumerator SA1969
enumerator WGS72
enumerator GRS80
enumerator WGS84
enumerator WGS84Mean
enumerator IERS1989
enumerator PZ9011
enumerator IERS2003
enumerator GSK2011
enumerator Mercury
enumerator Venus
enumerator Moon
enumerator Mars
enumerator Jupyter
enumerator Io
enumerator Saturn
enumerator Uranus
enumerator Neptune
enumerator Pluto

Functions

inline void ecef2geodetic(double x, double y, double z, double &out_lat, double &out_lon, double &out_alt, Ellipsoid ellipsoid = Ellipsoid::WGS84)

Converts Earth-Centered, Earth-Fixed (ECEF) coordinates to geodetic coordinates.

Note

Defaults to pymap3d’s algorithm from you (2000). Olson (1996) algorithm is selected at compile time by defining the ‘CPPMAP3D_ECEF2GEODETIC_OLSON’ macro.

Parameters:

  • x – The ECEF x-coordinate, in meters.

  • y – The ECEF y-coordinate, in meters.

  • z – The ECEF z-coordinate, in meters.

  • out_lat – [out] The latitude, in radians (output parameter).

  • out_lon – [out] The longitude, in radians (output parameter).

  • out_alt – [out] The altitude, in meters (output parameter).

  • ellipsoid – The ellipsoid model used for the conversion (default is WGS84).

Throws:

std::domain_error – if the ECEF coordinates are close to the center of the Earth and CPPMAP3D_ECEF2GEODETIC_OLSON is defined.

inline void aer2enu(double az, double el, double range, double &out_e, double &out_n, double &out_u)

Converts Azimuth, Elevation, and Range (AER) coordinates to East, North, Up (ENU) coordinates.

Parameters:

  • az – The azimuth angle, in radians.

  • el – The elevation angle, in radians.

  • range – The range distance, in meters.

  • out_e – [out] The East coordinate, in meters (output parameter).

  • out_n – [out] The North coordinate, in meters (output parameter).

  • out_u – [out] The Up coordinate, in meters (output parameter).

Throws:

std::domain_error – if range is negative

inline void enu2aer(double east, double north, double up, double &out_az, double &out_el, double &out_range)

Converts East, North, Up (ENU) coordinates to Azimuth, Elevation, and Range (AER) coordinates.

Parameters:

  • east – The East coordinate, in meters.

  • north – The North coordinate, in meters.

  • up – The Up coordinate, in meters.

  • out_az – [out] The azimuth angle, in radians (output parameter).

  • out_el – [out] The elevation angle, in radians (output parameter).

  • out_range – [out] The range distance, in meters (output parameter).

inline void aer2ned(double az, double el, double range, double &out_north, double &out_east, double &out_down)

Converts Azimuth, Elevation, and Range (AER) coordinates to North, East, Down (NED) coordinates.

Parameters:

  • az – The azimuth angle, in radians.

  • el – The elevation angle, in radians.

  • range – The range distance, in meters.

  • out_north – [out] The North coordinate, in meters (output parameter).

  • out_east – [out] The East coordinate, in meters (output parameter).

  • out_down – [out] The Down coordinate, in meters (output parameter).

inline void geodetic2ecef(double lat, double lon, double alt, double &out_x, double &out_y, double &out_z, Ellipsoid ellipsoid = Ellipsoid::WGS84)

Converts geodetic coordinates to Earth-Centered, Earth-Fixed (ECEF) coordinates.

Parameters:

  • lat – The latitude, in radians.

  • lon – The longitude, in radians.

  • alt – The altitude, in meters.

  • out_x – [out] The ECEF x-coordinate, in meters (output parameter).

  • out_y – [out] The ECEF y-coordinate, in meters (output parameter).

  • out_z – [out] The ECEF z-coordinate, in meters (output parameter).

  • ellipsoid – The ellipsoid model used for the conversion (default is WGS84).

Throws:

std::domain_error – if latitude is not within -pi/2 and pi/2 inclusive

inline void ecef2enu(double x, double y, double z, double lat, double lon, double alt, double &out_east, double &out_north, double &out_up, Ellipsoid ellipsoid = Ellipsoid::WGS84)

Converts Earth-Centered, Earth-Fixed (ECEF) coordinates to East, North, Up (ENU) coordinates.

Parameters:

  • x – The ECEF x-coordinate, in meters.

  • y – The ECEF y-coordinate, in meters.

  • z – The ECEF z-coordinate, in meters.

  • lat – The latitude, in radians.

  • lon – The longitude, in radians.

  • alt – The altitude, in meters.

  • out_east – [out] The East coordinate, in meters (output parameter).

  • out_north – [out] The North coordinate, in meters (output parameter).

  • out_up – [out] The Up coordinate, in meters (output parameter).

  • ellipsoid – The ellipsoid model used for the conversion (default is WGS84).

inline void ecef2aer(double x, double y, double z, double lat, double lon, double alt, double &out_az, double &out_el, double &out_range, Ellipsoid ellipsoid = Ellipsoid::WGS84)

Converts Earth-Centered, Earth-Fixed (ECEF) coordinates to Azimuth, Elevation, and Range (AER) coordinates.

Parameters:

  • x – The ECEF x-coordinate, in meters.

  • y – The ECEF y-coordinate, in meters.

  • z – The ECEF z-coordinate, in meters.

  • lat – The latitude, in radians.

  • lon – The longitude, in radians.

  • alt – The altitude, in meters.

  • out_az – [out] The azimuth angle, in radians (output parameter).

  • out_el – [out] The elevation angle, in radians (output parameter).

  • out_range – [out] The range distance, in meters (output parameter).

  • ellipsoid – The ellipsoid model used for the conversion (default is WGS84).

inline void ecef2ned(double x, double y, double z, double lat, double lon, double alt, double &out_north, double &out_east, double &out_down, Ellipsoid ellipsoid = Ellipsoid::WGS84)

Converts Earth-Centered, Earth-Fixed (ECEF) coordinates to North, East, Down (NED) coordinates.

Parameters:

  • x – The ECEF x-coordinate, in meters.

  • y – The ECEF y-coordinate, in meters.

  • z – The ECEF z-coordinate, in meters.

  • lat – The latitude, in radians.

  • lon – The longitude, in radians.

  • alt – The altitude, in meters.

  • out_north – [out] The North coordinate, in meters (output parameter).

  • out_east – [out] The East coordinate, in meters (output parameter).

  • out_down – [out] The Down coordinate, in meters (output parameter).

  • ellipsoid – The ellipsoid model used for the conversion (default is WGS84).

inline void enu2ecef(double east, double north, double up, double lat, double lon, double alt, double &out_x, double &out_y, double &out_z, Ellipsoid ellipsoid = Ellipsoid::WGS84)

Converts East, North, Up (ENU) coordinates to Earth-Centered, Earth-Fixed (ECEF) coordinates.

Parameters:

  • east – The East coordinate, in meters.

  • north – The North coordinate, in meters.

  • up – The Up coordinate, in meters.

  • lat – The latitude, in radians.

  • lon – The longitude, in radians.

  • alt – The altitude, in meters.

  • out_x – [out] The ECEF x-coordinate, in meters (output parameter).

  • out_y – [out] The ECEF y-coordinate, in meters (output parameter).

  • out_z – [out] The ECEF z-coordinate, in meters (output parameter).

  • ellipsoid – The ellipsoid model used for the conversion (default is WGS84).

inline void enu2geodetic(double east, double north, double up, double lat, double lon, double alt, double &out_lat, double &out_lon, double &out_alt, Ellipsoid ellipsoid = Ellipsoid::WGS84)

Converts East, North, Up (ENU) coordinates to geodetic coordinates.

Parameters:

  • east – The East coordinate, in meters.

  • north – The North coordinate, in meters.

  • up – The Up coordinate, in meters.

  • lat – The latitude, in radians.

  • lon – The longitude, in radians.

  • alt – The altitude, in meters.

  • out_lat – [out] The latitude, in radians (output parameter).

  • out_lon – [out] The longitude, in radians (output parameter).

  • out_alt – [out] The altitude, in meters (output parameter).

  • ellipsoid – The ellipsoid model used for the conversion (default is WGS84).

inline void geodetic2enu(double lat, double lon, double alt, double lat0, double lon0, double alt0, double &out_east, double &out_north, double &out_up, Ellipsoid ellipsoid = Ellipsoid::WGS84)

Converts geodetic coordinates to East, North, Up (ENU) coordinates relative to a reference point.

Parameters:

  • lat – The latitude in radians of the target.

  • lon – The longitude in radians of the target.

  • alt – The altitude in meters of the target.

  • lat0 – The latitude in radians of the observer.

  • lon0 – The longitude in radians of the observer.

  • alt0 – The altitude in meters of the observer.

  • out_east – [out] The East coordinate, in meters (output parameter).

  • out_north – [out] The North coordinate, in meters (output parameter).

  • out_up – [out] The Up coordinate, in meters (output parameter).

  • ellipsoid – The ellipsoid model used for the conversion (default is WGS84).

inline void geodetic2aer(double lat, double lon, double alt, double lat0, double lon0, double alt0, double &out_az, double &out_el, double &out_range, Ellipsoid ellipsoid = Ellipsoid::WGS84)

Converts geodetic coordinates to Azimuth, Elevation, and Range (AER) coordinates relative to a reference point.

Parameters:

  • lat – The latitude in radians of the target.

  • lon – The longitude in radians of the target.

  • alt – The altitude in meters of the target.

  • lat0 – The latitude in radians of the observer.

  • lon0 – The longitude in radians of the observer.

  • alt0 – The altitude in meters of the observer.

  • out_az – [out] The azimuth angle, in radians (output parameter).

  • out_el – [out] The elevation angle, in radians (output parameter).

  • out_range – [out] The range distance, in meters (output parameter).

  • ellipsoid – The ellipsoid model used for the conversion (default is WGS84).

inline void geodetic2ned(double lat, double lon, double alt, double lat0, double lon0, double alt0, double &out_north, double &out_east, double &out_down, Ellipsoid ellipsoid = Ellipsoid::WGS84)

Converts geodetic coordinates to North, East, Down (NED) coordinates relative to a reference point.

Parameters:

  • lat – The latitude in radians of the target.

  • lon – The longitude in radians of the target.

  • alt – The altitude in meters of the target.

  • lat0 – The latitude in radians of the observer.

  • lon0 – The longitude in radians of the observer.

  • alt0 – The altitude in meters of the observer.

  • out_north – [out] The North coordinate, in meters (output parameter).

  • out_east – [out] The East coordinate, in meters (output parameter).

  • out_down – [out] The Down coordinate, in meters (output parameter).

  • ellipsoid – The ellipsoid model used for the conversion (default is WGS84).

inline void aer2ecef(double az, double el, double range, double lat, double lon, double alt, double &out_x, double &out_y, double &out_z, Ellipsoid ellipsoid = Ellipsoid::WGS84)

Converts Azimuth, Elevation, and Range (AER) coordinates to Earth-Centered, Earth-Fixed (ECEF) coordinates.

Parameters:

  • az – The azimuth angle, in radians.

  • el – The elevation angle, in radians.

  • range – The range distance, in meters.

  • lat – The latitude, in radians.

  • lon – The longitude, in radians.

  • alt – The altitude, in meters.

  • out_x – [out] The ECEF x-coordinate, in meters (output parameter).

  • out_y – [out] The ECEF y-coordinate, in meters (output parameter).

  • out_z – [out] The ECEF z-coordinate, in meters (output parameter).

  • ellipsoid – The ellipsoid model used for the conversion (default is WGS84).

inline void aer2geodetic(double az, double el, double range, double lat, double lon, double alt, double &out_lat, double &out_lon, double &out_alt, Ellipsoid ellipsoid = Ellipsoid::WGS84)

Converts Azimuth, Elevation, and Range (AER) coordinates to geodetic coordinates.

Parameters:

  • az – The azimuth angle, in radians.

  • el – The elevation angle, in radians.

  • range – The range distance, in meters.

  • lat – The latitude, in radians.

  • lon – The longitude, in radians.

  • alt – The altitude, in meters.

  • out_lat – [out] The latitude, in radians (output parameter).

  • out_lon – [out] The longitude, in radians (output parameter).

  • out_alt – [out] The altitude, in meters (output parameter).

  • ellipsoid – The ellipsoid model used for the conversion (default is WGS84).

inline void ned2ecef(double north, double east, double down, double lat, double lon, double alt, double &out_x, double &out_y, double &out_z, Ellipsoid ellipsoid = Ellipsoid::WGS84)

Converts North, East, Down (NED) coordinates to Earth-Centered, Earth-Fixed (ECEF) coordinates.

Parameters:

  • north – The North coordinate, in meters.

  • east – The East coordinate, in meters.

  • down – The Down coordinate, in meters.

  • lat – The latitude, in radians.

  • lon – The longitude, in radians.

  • alt – The altitude, in meters.

  • out_x – [out] The ECEF x-coordinate, in meters (output parameter).

  • out_y – [out] The ECEF y-coordinate, in meters (output parameter).

  • out_z – [out] The ECEF z-coordinate, in meters (output parameter).

  • ellipsoid – The ellipsoid model used for the conversion (default is WGS84).

inline void ned2geodetic(double north, double east, double down, double lat, double lon, double alt, double &out_lat, double &out_lon, double &out_alt, Ellipsoid ellipsoid = Ellipsoid::WGS84)

Converts North, East, Down (NED) coordinates to geodetic coordinates.

Parameters:

  • north – The North coordinate, in meters.

  • east – The East coordinate, in meters.

  • down – The Down coordinate, in meters.

  • lat – The latitude, in radians.

  • lon – The longitude, in radians.

  • alt – The altitude, in meters.

  • out_lat – [out] The latitude, in radians (output parameter).

  • out_lon – [out] The longitude, in radians (output parameter).

  • out_alt – [out] The altitude, in meters (output parameter).

  • ellipsoid – The ellipsoid model used for the conversion (default is WGS84).

inline void ned2aer(double north, double east, double down, double &out_az, double &out_el, double &out_range)

Converts North, East, Down (NED) coordinates to Azimuth, Elevation, and Range (AER) coordinates.

Parameters:

  • north – The North coordinate, in meters.

  • east – The East coordinate, in meters.

  • down – The Down coordinate, in meters.

  • out_az – [out] The azimuth angle, in radians (output parameter).

  • out_el – [out] The elevation angle, in radians (output parameter).

  • out_range – [out] The range distance, in meters (output parameter).

inline void ecef2enuv(double u, double v, double w, double lat0, double lon0, double &out_east, double &out_north, double &out_up)

Converts Earth-Centered, Earth-Fixed (ECEF) VECTOR to East, North, Up (ENU) VECTOR.

Parameters:

  • x – The ECEF x-vector, in meters.

  • y – The ECEF y-vector, in meters.

  • z – The ECEF z-vector, in meters.

  • lat – The latitude, in radians.

  • lon – The longitude, in radians.

  • out_east – [out] The East vector, in meters (output parameter).

  • out_north – [out] The North vector, in meters (output parameter).

  • out_up – [out] The Up vector, in meters (output parameter).

  • ellipsoid – The ellipsoid model used for the conversion (default is WGS84).

inline void ecef2nedv(double x, double y, double z, double lat0, double lon0, double &out_north, double &out_east, double &out_down)

Converts Earth-Centered, Earth-Fixed (ECEF) VECTOR to North, East, Down (NED) VECTOR.

Parameters:

  • x – The ECEF x-vector, in meters.

  • y – The ECEF y-vector, in meters.

  • z – The ECEF z-vector, in meters.

  • lat – The latitude, in radians.

  • lon – The longitude, in radians.

  • out_north – [out] The North vector, in meters (output parameter).

  • out_east – [out] The East vector, in meters (output parameter).

  • out_down – [out] The Down vector, in meters (output parameter).

  • ellipsoid – The ellipsoid model used for the conversion (default is WGS84).

inline void enu2ecefv(double east, double north, double up, double lat0, double lon0, double &out_x, double &out_y, double &out_z)

Converts East, North, Up (ENU) VECTOR to Earth-Centered, Earth-Fixed (ECEF) VECTOR.

Parameters:

  • east – The East coordinate, in meters.

  • north – The North coordinate, in meters.

  • up – The Up coordinate, in meters.

  • lat – The latitude, in radians.

  • lon – The longitude, in radians.

  • out_x – [out] The ECEF x-vector, in meters (output parameter).

  • out_y – [out] The ECEF y-vector, in meters (output parameter).

  • out_z – [out] The ECEF z-vector, in meters (output parameter).

  • ellipsoid – The ellipsoid model used for the conversion (default is WGS84).

inline void wrapGeodetic(double lat, double lon, double &out_lat, double &out_lon)
namespace internal

Functions

inline constexpr double getMajor(Ellipsoid ellipsoid)

Returns the semi-major axis length of the specified ellipsoid.

Note

The semi-major axis represents half of the longest diameter of the ellipsoid.

Parameters:

ellipsoid – The ellipsoid for which the semi-major axis length is requested.

Returns:

The semi-major axis length of the specified ellipsoid in meters.

inline constexpr double getMinor(Ellipsoid ellipsoid)

Returns the semi-minor axis length of the specified ellipsoid.

Note

The semi-minor axis represents half of the shortest diameter of the ellipsoid.

Parameters:

ellipsoid – The ellipsoid for which the semi-minor axis length is requested.

Returns:

The semi-minor axis length of the specified ellipsoid in meters.

inline constexpr double getFlattening(Ellipsoid ellipsoid)

Returns the flattening factor of the specified ellipsoid.

Note

Flattening is calculated as (a - b) / a, where ‘a’ is the semi-major axis and ‘b’ is the semi-minor axis.

Parameters:

ellipsoid – The ellipsoid for which the flattening factor is requested.

Returns:

The flattening factor, a dimensionless quantity representing the ellipsoid’s deviation from a perfect sphere.

inline constexpr double getSquaredEccentricity(Ellipsoid ellipsoid)

Returns the squared eccentricity of the specified ellipsoid.

Note

Squared eccentricity is calculated as (a^2 - b^2) / a^2, where ‘a’ is the semi-major axis and ‘b’ is the semi-minor axis.

Parameters:

ellipsoid – The ellipsoid for which the squared eccentricity is requested.

Returns:

The squared eccentricity, a dimensionless quantity expressing the ellipsoid’s deviation from a perfect sphere.

inline void enu2uvw(double et, double nt, double up, double lat, double lon, double &out_u, double &out_v, double &out_w)

Internal function used in conversions certain coordinate conversions.

inline void uvw2enu(double u, double v, double w, double lat, double lon, double &out_east, double &out_north, double &out_up)

Internal function used in conversions certain coordinate conversions.

inline void ecef2geodetic_you(double x, double y, double z, double &out_lat, double &out_lon, double &out_alt, Ellipsoid ellipsoid = Ellipsoid::WGS84)

Converts Earth-Centered, Earth-Fixed (ECEF) coordinates to geodetic coordinates.

Note

This implementation is ported from pymap3d and is based on: You, Rey-Jer. (2000). Transformation of Cartesian to Geodetic Coordinates without Iterations. Journal of Surveying Engineering. doi: 10.1061/(ASCE)0733-9453.

Note

The latitude and longitude are returned in radians, and the altitude is provided in meters.

Parameters:

  • x – The ECEF x-coordinate, in meters.

  • y – The ECEF y-coordinate, in meters.

  • z – The ECEF z-coordinate, in meters.

  • out_lat – [out] The latitude, in radians (output parameter).

  • out_lon – [out] The longitude, in radians (output parameter).

  • out_alt – [out] The altitude, in meters (output parameter).

  • ellipsoid – The ellipsoid model used for the conversion (default is WGS84).

inline void ecef2geodetic_olson(double x, double y, double z, double &out_lat, double &out_lon, double &out_alt, Ellipsoid ellipsoid = Ellipsoid::WGS84)

Converts Earth-Centered, Earth-Fixed (ECEF) coordinates to geodetic coordinates using the Olson (1996) algorithm.

Note

This function implements the Olson (1996) algorithm, sourced from this algorithm comparison

Parameters:

  • x – The ECEF x-coordinate, in meters.

  • y – The ECEF y-coordinate, in meters.

  • z – The ECEF z-coordinate, in meters.

  • out_lat – [out] The latitude, in radians (output parameter).

  • out_lon – [out] The longitude, in radians (output parameter).

  • out_alt – [out] The altitude, in meters (output parameter).

  • ellipsoid – The ellipsoid model used for the conversion (default is WGS84).

Throws:

std::domain_error – if the ECEF coordinates are close to the center of the Earth.