[mrpt-topography]

Overview

Topographic functions, geoid transformations.

Library mrpt-topography

This C++ library is part of MRPT and can be installed in Debian-based systems with:

sudo apt install libmrpt-topography-dev

Conversion and useful data structures to handle topographic data, perform geoid transformations, geocentric coordinates, etc…

See mrpt::topography

Library contents

// typedefs

typedef mrpt::math::TPoint3D mrpt::topography::TUTMCoords;
typedef mrpt::math::TPoint3D mrpt::topography::TGeocentricCoords;

// structs

struct mrpt::topography::TCoords;
struct mrpt::topography::TDatum10Params;
struct mrpt::topography::TDatum1DTransf;
struct mrpt::topography::TDatum7Params;
struct mrpt::topography::TDatum7Params_TOPCON;
struct mrpt::topography::TDatumHelmert2D;
struct mrpt::topography::TDatumHelmert2D_TOPCON;
struct mrpt::topography::TDatumHelmert3D;
struct mrpt::topography::TDatumHelmert3D_TOPCON;
struct mrpt::topography::TDatumTransfInterpolation;
struct mrpt::topography::TEllipsoid;
struct mrpt::topography::TGeodeticCoords;

// global functions

bool mrpt::topography::operator == (
    const TCoords& a,
    const TCoords& o
    );

bool mrpt::topography::operator != (
    const TCoords& a,
    const TCoords& o
    );

std::ostream& mrpt::topography::operator << (
    std::ostream& out,
    const TCoords& o
    );

bool mrpt::topography::operator == (
    const TGeodeticCoords& a,
    const TGeodeticCoords& o
    );

bool mrpt::topography::operator != (
    const TGeodeticCoords& a,
    const TGeodeticCoords& o
    );

void mrpt::topography::geodeticToENU_WGS84(const TGeodeticCoords& in_coords, mrpt::math::TPoint3D& out_ENU_point, const TGeodeticCoords& in_coords_origin);

void mrpt::topography::ENUToGeocentric(
    const mrpt::math::TPoint3D& in_ENU_point,
    const TGeodeticCoords& in_coords_origin,
    TGeocentricCoords& out_coords,
    const TEllipsoid& ellip
    );

void mrpt::topography::ENUToGeodetic_WGS84(const mrpt::math::TPoint3D& in_ENU_point, TGeodeticCoords& out_coords, const TGeodeticCoords& in_coords_origin);
void mrpt::topography::geocentricToENU_WGS84(const mrpt::math::TPoint3D& in_geocentric_point, mrpt::math::TPoint3D& out_ENU_point, const TGeodeticCoords& in_coords_origin);

void mrpt::topography::geocentricToENU_WGS84(
    const std::vector<mrpt::math::TPoint3D>& in_geocentric_points,
    std::vector<mrpt::math::TPoint3D>& out_ENU_points,
    const TGeodeticCoords& in_coords_origin
    );

void mrpt::topography::geodeticToGeocentric_WGS84(const TGeodeticCoords& in_coords, mrpt::math::TPoint3D& out_point);
void mrpt::topography::geodeticToGeocentric(const TGeodeticCoords& in_coords, TGeocentricCoords& out_point, const TEllipsoid& ellip);
void mrpt::topography::geocentricToGeodetic(const TGeocentricCoords& in_point, TGeodeticCoords& out_coords, const TEllipsoid& ellip = TEllipsoid::Ellipsoid_WGS84());
void mrpt::topography::transform7params(const mrpt::math::TPoint3D& in_point, const TDatum7Params& in_datum, mrpt::math::TPoint3D& out_point);
void mrpt::topography::transform7params_TOPCON(const mrpt::math::TPoint3D& in_point, const TDatum7Params_TOPCON& in_datum, mrpt::math::TPoint3D& out_point);
void mrpt::topography::transform10params(const mrpt::math::TPoint3D& in_point, const TDatum10Params& in_datum, mrpt::math::TPoint3D& out_point);
void mrpt::topography::transformHelmert2D(const mrpt::math::TPoint2D& p, const TDatumHelmert2D& d, mrpt::math::TPoint2D& o);
void mrpt::topography::transformHelmert2D_TOPCON(const mrpt::math::TPoint2D& p, const TDatumHelmert2D_TOPCON& d, mrpt::math::TPoint2D& o);
void mrpt::topography::transformHelmert3D(const mrpt::math::TPoint3D& p, const TDatumHelmert3D& d, mrpt::math::TPoint3D& o);
void mrpt::topography::transformHelmert3D_TOPCON(const mrpt::math::TPoint3D& p, const TDatumHelmert3D_TOPCON& d, mrpt::math::TPoint3D& o);
void mrpt::topography::transform1D(const mrpt::math::TPoint3D& p, const TDatum1DTransf& d, mrpt::math::TPoint3D& o);
void mrpt::topography::transfInterpolation(const mrpt::math::TPoint3D& p, const TDatumTransfInterpolation& d, mrpt::math::TPoint3D& o);

void mrpt::topography::UTMToGeodetic(
    double X,
    double Y,
    int zone,
    char hem,
    double& out_lon,
    double& out_lat,
    const TEllipsoid& ellip = TEllipsoid::Ellipsoid_WGS84()
    );

void mrpt::topography::UTMToGeodetic(
    const TUTMCoords& UTMCoords,
    int zone,
    char hem,
    TGeodeticCoords& GeodeticCoords,
    const TEllipsoid& ellip = TEllipsoid::Ellipsoid_WGS84()
    );

void mrpt::topography::GeodeticToUTM(
    double in_latitude_degrees,
    double in_longitude_degrees,
    double& out_UTM_x,
    double& out_UTM_y,
    int& out_UTM_zone,
    char& out_UTM_latitude_band,
    const TEllipsoid& ellip = TEllipsoid::Ellipsoid_WGS84()
    );

void mrpt::topography::geodeticToUTM(
    const TGeodeticCoords& GeodeticCoords,
    TUTMCoords& UTMCoords,
    int& UTMZone,
    char& UTMLatitudeBand,
    const TEllipsoid& ellip = TEllipsoid::Ellipsoid_WGS84()
    );

void mrpt::topography::GeodeticToUTM(
    const TGeodeticCoords& GeodeticCoords,
    TUTMCoords& UTMCoords,
    int& UTMZone,
    char& UTMLatitudeBand,
    const TEllipsoid& ellip = TEllipsoid::Ellipsoid_WGS84()
    );

void mrpt::topography::ENU_axes_from_WGS84(
    double in_longitude_reference_degrees,
    double in_latitude_reference_degrees,
    double in_height_reference_meters,
    mrpt::math::TPose3D& out_ENU,
    bool only_angles = false
    );

void mrpt::topography::ENU_axes_from_WGS84(const TGeodeticCoords& in_coords, mrpt::math::TPose3D& out_ENU, bool only_angles = false);
void mrpt::topography::registerAllClasses_mrpt_topography();

Global Functions

void mrpt::topography::geodeticToENU_WGS84(
    const TGeodeticCoords& in_coords,
    mrpt::math::TPoint3D& out_ENU_point,
    const TGeodeticCoords& in_coords_origin
    )

Coordinates transformation from longitude/latitude/height to ENU (East-North-Up) X/Y/Z coordinates The WGS84 ellipsoid is used for the transformation.

The coordinates are in 3D relative to some user-provided point, with local X axis being east-ward, Y north-ward, Z up-ward. For an explanation, refer to http://en.wikipedia.org/wiki/Reference_ellipsoid The “Up” (Z) direction in ENU is the normal to the ellipsoid, which coincides with the direction of an increasing geodetic height.

void mrpt::topography::ENUToGeocentric(
    const mrpt::math::TPoint3D& in_ENU_point,
    const TGeodeticCoords& in_coords_origin,
    TGeocentricCoords& out_coords,
    const TEllipsoid& ellip
    )

ENU to geocentric coordinates.

The “Up” (Z) direction of the input ENU point is the normal to the ellipsoid at in_coords_origin, the same convention used by geodeticToENU_WGS84(), so that both functions are exact inverses of each other.

See also:

geodeticToENU_WGS84

void mrpt::topography::ENUToGeodetic_WGS84(
    const mrpt::math::TPoint3D& in_ENU_point,
    TGeodeticCoords& out_coords,
    const TGeodeticCoords& in_coords_origin
    )

ENU to longitude/latitude/height (WGS84) coordinates, relative to the given origin.

This is the exact inverse of geodeticToENU_WGS84(). The “Up” (Z) direction of the input ENU point is the normal to the ellipsoid at in_coords_origin.

See also:

geodeticToENU_WGS84, ENUToGeocentric

void mrpt::topography::geocentricToENU_WGS84(
    const mrpt::math::TPoint3D& in_geocentric_point,
    mrpt::math::TPoint3D& out_ENU_point,
    const TGeodeticCoords& in_coords_origin
    )

Geocentric (ECEF) to ENU (East-North-Up) coordinates, relative to the given origin (WGS84 ellipsoid).

Its inverse is ENUToGeocentric().

See also:

ENUToGeocentric, geodeticToENU_WGS84

void mrpt::topography::geodeticToGeocentric_WGS84(
    const TGeodeticCoords& in_coords,
    mrpt::math::TPoint3D& out_point
    )

Coordinates transformation from longitude/latitude/height to geocentric X/Y/Z coordinates (WGS84 ellipsoid).

The WGS84 ellipsoid is used for the transformation. The coordinates are in 3D where the reference is the center of the Earth. For an explanation, refer to http://en.wikipedia.org/wiki/Reference_ellipsoid

See also:

geodeticToENU_WGS84

void mrpt::topography::geodeticToGeocentric(
    const TGeodeticCoords& in_coords,
    TGeocentricCoords& out_point,
    const TEllipsoid& ellip
    )

Coordinates transformation from longitude/latitude/height to geocentric X/Y/Z coordinates (with an specified geoid).

See also:

geocentricToGeodetic

void mrpt::topography::geocentricToGeodetic(
    const TGeocentricCoords& in_point,
    TGeodeticCoords& out_coords,
    const TEllipsoid& ellip = TEllipsoid::Ellipsoid_WGS84()
    )

Coordinates transformation from geocentric X/Y/Z coordinates to longitude/latitude/height.

It uses Bowring’s closed-form approximation, accurate to better than 0.1 mm for heights below 100 km (the error grows with height, to a few mm at 1000 km).

See also:

geodeticToGeocentric

void mrpt::topography::transform7params(
    const mrpt::math::TPoint3D& in_point,
    const TDatum7Params& in_datum,
    mrpt::math::TPoint3D& out_point
    )

7-parameter Bursa-Wolf transformation: [ X Y Z ]_WGS84 = [ dX dY dZ ] + ( 1 + dS ) [ 1 RZ -RY; -RZ 1 RX; RY -RX 1 ] [ X Y Z ]_local This is the “coordinate frame rotation” sign convention (EPSG:9607).

7-parameter Bursa-Wolf transformation: [ X Y Z ]_WGS84 = [ dX dY dZ ] + ( 1 + dS ) [ 1 RZ -RY; -RZ 1 RX; RY -RX 1 ] [ X Y Z ]_local

For the “position vector” convention (EPSG:9606), see transformHelmert3D().

See also:

transform10params

void mrpt::topography::transform7params_TOPCON(
    const mrpt::math::TPoint3D& in_point,
    const TDatum7Params_TOPCON& in_datum,
    mrpt::math::TPoint3D& out_point
    )

Same as transform7params(), but taking the rotation matrix elements directly (as used by TOPCON equipment/software) instead of small-angle rotation parameters.

7-parameter transformation, TOPCON convention: [ X Y Z ]_WGS84 = [ dX dY dZ ] + ( 1 + dS ) [ m11 m12 m13; m21 m22 m23; m31 m32 m33 ] [ X Y Z ]_local

See also:

transform7params

void mrpt::topography::transform10params(
    const mrpt::math::TPoint3D& in_point,
    const TDatum10Params& in_datum,
    mrpt::math::TPoint3D& out_point
    )

10-parameter Molodensky-Badekas transformation: [ X Y Z ]_WGS84 = [ dX dY dZ ] + ( 1 + dS ) [ 1 RZ -RY; -RZ 1 RX; RY -RX 1 ] [ X-Xp Y-Yp Z-Zp ]_local + [Xp Yp Zp]

See also:

transform7params

void mrpt::topography::transformHelmert2D(const mrpt::math::TPoint2D& p, const TDatumHelmert2D& d, mrpt::math::TPoint2D& o)

Helmert 2D transformation: [ X Y ]_WGS84 = [ dX dY ] + ( 1 + dS ) [ cos(alpha) -sin(alpha); sin(alpha) cos(alpha) ] [ X-Xp Y-Yp ]_local + [Xp Yp].

See also:

transformHelmert3D

void mrpt::topography::transformHelmert2D_TOPCON(const mrpt::math::TPoint2D& p, const TDatumHelmert2D_TOPCON& d, mrpt::math::TPoint2D& o)

Same as transformHelmert2D(), but taking the affine transformation coefficients directly (as used by TOPCON equipment/software) instead of rotation angle and scale parameters.

Helmert 2D transformation, TOPCON convention: [ X Y ]_WGS84 = [ a b; -b a ] [ X Y ]_local + [ c d ].

See also:

transformHelmert2D

void mrpt::topography::transformHelmert3D(const mrpt::math::TPoint3D& p, const TDatumHelmert3D& d, mrpt::math::TPoint3D& o)

Helmert3D transformation: [ X Y Z ]_WGS84 = [ dX dY dZ ] + ( 1 + dS ) [ 1 -RZ RY; RZ 1 -RX; -RY RX 1 ] [ X Y Z ]_local This is the “position vector” sign convention (EPSG:9606).

Helmert 3D transformation (position vector convention): [ X Y Z ]_WGS84 = [ dX dY dZ ] + ( 1 + dS ) [ 1 -RZ RY; RZ 1 -RX; -RY RX 1 ] [ X Y Z ]_local.

For the “coordinate frame rotation” convention (EPSG:9607), see transform7params().

See also:

transformHelmert2D

void mrpt::topography::transformHelmert3D_TOPCON(const mrpt::math::TPoint3D& p, const TDatumHelmert3D_TOPCON& d, mrpt::math::TPoint3D& o)

Same as transformHelmert3D(), but taking the affine transformation coefficients directly (as used by TOPCON equipment/software) instead of rotation angle and scale parameters.

Helmert 3D transformation, TOPCON convention: [ X Y ]_WGS84 = [ a b; d e ] [ X Y ]_local + [ c f ], Z_WGS84 = Z_local + g.

See also:

transformHelmert3D

void mrpt::topography::transform1D(const mrpt::math::TPoint3D& p, const TDatum1DTransf& d, mrpt::math::TPoint3D& o)

1D transformation: [ Z ]_WGS84 = (dy * X - dx * Y + Z)*(1+e)+DZ

See also:

transformHelmert3D

void mrpt::topography::transfInterpolation(const mrpt::math::TPoint3D& p, const TDatumTransfInterpolation& d, mrpt::math::TPoint3D& o)

Interpolation: [ X Y ]_WGS84 = [ dX dY ] + [ 1 -sin(beta); 0 cos(beta) ] [ dSx*X; dSy*Y ] [ Z ]_WGS84 = Z.

Interpolation: [ X Y ]_WGS84 = [ dX dY ] + [ 1 -sin(beta); 0 cos(beta) ] [ dSx*X; dSy*Y ].

dSx and dSy are the full scale factors (TDatumTransfInterpolation takes them in ppm, i.e. 1e6 means a unit scale).

void mrpt::topography::UTMToGeodetic(
    double X,
    double Y,
    int zone,
    char hem,
    double& out_lon,
    double& out_lat,
    const TEllipsoid& ellip = TEllipsoid::Ellipsoid_WGS84()
    )

Returns the Geodetic coordinates of the UTM input point.

Parameters:

X	East coordinate of the input point.
Y	North coordinate of the input point.
zone	UTM longitude zone number, 1 to 60 (Spanish: “huso”).
hem	hemisphere (‘N’/’n’ for North or ‘S’/s’ for South ). An exception will be raised on any other value.
ellip	the reference ellipsoid used for the transformation (default: WGS84)
out_lat	Out latitude, in degrees.
out_lon	Out longitude, in degrees.

void mrpt::topography::UTMToGeodetic(
    const TUTMCoords& UTMCoords,
    int zone,
    char hem,
    TGeodeticCoords& GeodeticCoords,
    const TEllipsoid& ellip = TEllipsoid::Ellipsoid_WGS84()
    )

Returns the Geodetic coordinates of the UTM input point.

Parameters:

UTMCoords	UTM input coordinates.
zone	UTM longitude zone number, 1 to 60 (Spanish: “huso”).
hem	hemisphere (‘N’/’n’ for North or ‘S’/s’ for South ). An exception will be raised on any other value.
GeodeticCoords	Out geodetic coordinates.
ellip	the reference ellipsoid used for the transformation (default: WGS84)

void mrpt::topography::GeodeticToUTM(
    double in_latitude_degrees,
    double in_longitude_degrees,
    double& out_UTM_x,
    double& out_UTM_y,
    int& out_UTM_zone,
    char& out_UTM_latitude_band,
    const TEllipsoid& ellip = TEllipsoid::Ellipsoid_WGS84()
    )

Convert latitude and longitude coordinates into UTM coordinates, computing the corresponding UTM zone and latitude band.

For the southern hemisphere, the standard UTM false northing (1e7 m) is applied so that out_UTM_y is always positive. The projection uses the Krueger series to order n^6 (Karney 2011), with an accuracy better than 1 mm within the UTM zones. Zones are the regular 6-degree ones (the Norway and Svalbard exceptions are not applied), and latitudes outside the UTM range [-80,84] are not rejected. Example:

Input:
 Lat=40.3154333    Lon=-3.4857166
Output:
 x = 458731
 y = 4462881
 utm_zone = 30
 utm_band = T

void mrpt::topography::geodeticToUTM(
    const TGeodeticCoords& GeodeticCoords,
    TUTMCoords& UTMCoords,
    int& UTMZone,
    char& UTMLatitudeBand,
    const TEllipsoid& ellip = TEllipsoid::Ellipsoid_WGS84()
    )

Convert geodetic coordinates into UTM coordinates, computing the corresponding UTM zone and latitude band.

Equivalent to GeodeticToUTM(), but taking/returning MRPT topography types (TGeodeticCoords, TUTMCoords) directly. For the southern hemisphere, the standard UTM false northing (1e7 m) is applied so that UTMCoords.y is always positive, matching the convention expected by UTMToGeodetic().

See also:

GeodeticToUTM, UTMToGeodetic

void mrpt::topography::GeodeticToUTM(
    const TGeodeticCoords& GeodeticCoords,
    TUTMCoords& UTMCoords,
    int& UTMZone,
    char& UTMLatitudeBand,
    const TEllipsoid& ellip = TEllipsoid::Ellipsoid_WGS84()
    )

Convert latitude and longitude coordinates into UTM coordinates, computing the corresponding UTM zone and latitude band.

The projection uses the Krueger series to order n^6 (Karney 2011), with an accuracy better than 1 mm within the UTM zones. Zones are the regular 6-degree ones (the Norway and Svalbard exceptions are not applied), and latitudes outside the UTM range [-80,84] are not rejected. Example:

Input:
 Lat=40.3154333    Lon=-3.4857166
Output:
 x = 458731
 y = 4462881
 utm_zone = 30
 utm_band = T

void mrpt::topography::ENU_axes_from_WGS84(
    double in_longitude_reference_degrees,
    double in_latitude_reference_degrees,
    double in_height_reference_meters,
    mrpt::math::TPose3D& out_ENU,
    bool only_angles = false
    )

Returns the East-North-Up (ENU) coordinate system associated to the given point.

This is the reference employed in geodeticToENU_WGS84 The “Up” (Z) direction in ENU is the normal to the ellipsoid, which coincides with the direction of an increasing geodetic height.

Parameters:

only_angles

If set to true, the (x,y,z) fields will be left zeroed.

See also:

geodeticToENU_WGS84

void mrpt::topography::ENU_axes_from_WGS84(
    const TGeodeticCoords& in_coords,
    mrpt::math::TPose3D& out_ENU,
    bool only_angles = false
    )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void mrpt::topography::registerAllClasses_mrpt_topography()

Forces manual RTTI registration of all serializable classes in this namespace.

Should never be required to be explicitly called by users, except if building MRPT as a static library.