GeographicLib::Geocentric Class Reference

Geocentric coordinates More...

#include <Geocentric.hpp>

Public Member Functions
void	Forward (real lat, real lon, real h, real &X, real &Y, real &Z) const
void	Forward (real lat, real lon, real h, real &X, real &Y, real &Z, std::vector< real > &M) const
	Geocentric ()
	Geocentric (real a, real f)
void	Reverse (real X, real Y, real Z, real &lat, real &lon, real &h) const
void	Reverse (real X, real Y, real Z, real &lat, real &lon, real &h, std::vector< real > &M) const
Inspector functions
bool	Init () const
Math::real	MajorRadius () const
Math::real	Flattening () const

Static Public Member Functions
static const Geocentric &	WGS84 ()

Private Types
typedef Math::real	real

Private Member Functions
void	IntForward (real lat, real lon, real h, real &X, real &Y, real &Z, real M[dim2_]) const
void	IntReverse (real X, real Y, real Z, real &lat, real &lon, real &h, real M[dim2_]) const

Static Private Member Functions
static void	Rotate (real M[dim2_], real x, real y, real z, real &X, real &Y, real &Z)
static void	Rotation (real sphi, real cphi, real slam, real clam, real M[dim2_])
static void	Unrotate (real M[dim2_], real X, real Y, real Z, real &x, real &y, real &z)

Private Attributes
real	_a
real	_e2
real	_e2a
real	_e2m
real	_e4a
real	_f
real	_maxrad

Static Private Attributes
static const size_t	dim2_ = dim_ * dim_
static const size_t	dim_ = 3

Friends
class	GravityCircle
class	GravityModel
class	LocalCartesian
class	MagneticCircle
class	MagneticModel
class	NormalGravity

Detailed Description

Geocentric coordinates

Convert between geodetic coordinates latitude = lat, longitude = lon, height = h (measured vertically from the surface of the ellipsoid) to geocentric coordinates (X, Y, Z). The origin of geocentric coordinates is at the center of the earth. The Z axis goes thru the north pole, lat = 90°. The X axis goes thru lat = 0, lon = 0. Geocentric coordinates are also known as earth centered, earth fixed (ECEF) coordinates.

The conversion from geographic to geocentric coordinates is straightforward. For the reverse transformation we use

• H. Vermeille, Direct transformation from geocentric coordinates to geodetic coordinates, J. Geodesy 76, 451–454 (2002).

Several changes have been made to ensure that the method returns accurate results for all finite inputs (even if h is infinite). The changes are described in Appendix B of

• C. F. F. Karney, Geodesics on an ellipsoid of revolution, Feb. 2011; preprint arxiv:1102.1215v1.

Vermeille similarly updated his method in

• H. Vermeille, An analytical method to transform geocentric into geodetic coordinates, J. Geodesy 85, 105–117 (2011).

See geocentric for more information.

The errors in these routines are close to round-off. Specifically, for points within 5000 km of the surface of the ellipsoid (either inside or outside the ellipsoid), the error is bounded by 7 nm (7 nanometers) for the WGS84 ellipsoid. See geocentric for further information on the errors.

Example of use:

// Example of using the GeographicLib::Geocentric class
 
#include <iostream>
#include <exception>
#include <cmath>
#include <GeographicLib/Geocentric.hpp>
 
using namespace std;
using namespace GeographicLib;
 
int main() {
  try {
    Geocentric earth(Constants::WGS84_a(), Constants::WGS84_f());
    // Alternatively: const Geocentric& earth = Geocentric::WGS84();
    {
      // Sample forward calculation
      double lat = 27.99, lon = 86.93, h = 8820; // Mt Everest
      double X, Y, Z;
      earth.Forward(lat, lon, h, X, Y, Z);
      cout << floor(X / 1000 + 0.5) << " "
           << floor(Y / 1000 + 0.5) << " "
           << floor(Z / 1000 + 0.5) << "\n";
    }
    {
      // Sample reverse calculation
      double X = 302e3, Y = 5636e3, Z = 2980e3;
      double lat, lon, h;
      earth.Reverse(X, Y, Z, lat, lon, h);
      cout << lat << " " << lon << " " << h << "\n";
    }
  }
  catch (const exception& e) {
    cerr << "Caught exception: " << e.what() << "\n";
    return 1;
  }
}

CartConvert is a command-line utility providing access to the functionality of Geocentric and LocalCartesian.

Definition at line 67 of file Geocentric.hpp.

Member Typedef Documentation

real

typedef Math::real GeographicLib::Geocentric::real

private

Definition at line 69 of file Geocentric.hpp.

Constructor & Destructor Documentation

Geocentric() [1/2]

GeographicLib::Geocentric::Geocentric	(	real	a,
		real	f
	)

Constructor for a ellipsoid with

Parameters

[in]	a	equatorial radius (meters).
[in]	f	flattening of ellipsoid. Setting f = 0 gives a sphere. Negative f gives a prolate ellipsoid.

Exceptions

GeographicErr

if a or (1 − f) a is not positive.

Definition at line 16 of file src/Geocentric.cpp.

Geocentric() [2/2]

GeographicLib::Geocentric::Geocentric ( )

inline

A default constructor (for use by NormalGravity).

Definition at line 118 of file Geocentric.hpp.

Member Function Documentation

Flattening()

Math::real GeographicLib::Geocentric::Flattening ( ) const

inline

Returns

f the flattening of the ellipsoid. This is the value used in the constructor.

Definition at line 254 of file Geocentric.hpp.

Forward() [1/2]

void GeographicLib::Geocentric::Forward ( real  lat, real  lon, real  h, real &  X, real &  Y, real &  Z  ) const

inline

Convert from geodetic to geocentric coordinates.

Parameters

[in]	lat	latitude of point (degrees).
[in]	lon	longitude of point (degrees).
[in]	h	height of point above the ellipsoid (meters).
[out]	X	geocentric coordinate (meters).
[out]	Y	geocentric coordinate (meters).
[out]	Z	geocentric coordinate (meters).

lat should be in the range [−90°, 90°].

Definition at line 132 of file Geocentric.hpp.

Forward() [2/2]

void GeographicLib::Geocentric::Forward ( real  lat, real  lon, real  h, real &  X, real &  Y, real &  Z, std::vector< real > &  M  ) const

inline

Convert from geodetic to geocentric coordinates and return rotation matrix.

Parameters

[in]	lat	latitude of point (degrees).
[in]	lon	longitude of point (degrees).
[in]	h	height of point above the ellipsoid (meters).
[out]	X	geocentric coordinate (meters).
[out]	Y	geocentric coordinate (meters).
[out]	Z	geocentric coordinate (meters).
[out]	M	if the length of the vector is 9, fill with the rotation matrix in row-major order.

Let v be a unit vector located at (lat, lon, h). We can express v as column vectors in one of two ways

• in east, north, up coordinates (where the components are relative to a local coordinate system at (lat, lon, h)); call this representation v1.
• in geocentric X, Y, Z coordinates; call this representation v0.

Then we have v0 = M ⋅ v1.

Definition at line 161 of file Geocentric.hpp.

Init()

bool GeographicLib::Geocentric::Init ( ) const

inline

Returns

true if the object has been initialized.

Definition at line 242 of file Geocentric.hpp.

IntForward()

void GeographicLib::Geocentric::IntForward ( real  lat, real  lon, real  h, real &  X, real &  Y, real &  Z, real  M[dim2_]  ) const

private

Definition at line 36 of file src/Geocentric.cpp.

IntReverse()

void GeographicLib::Geocentric::IntReverse ( real  X, real  Y, real  Z, real &  lat, real &  lon, real &  h, real  M[dim2_]  ) const

private

Definition at line 51 of file src/Geocentric.cpp.

MajorRadius()

Math::real GeographicLib::Geocentric::MajorRadius ( ) const

inline

Returns

a the equatorial radius of the ellipsoid (meters). This is the value used in the constructor.

Definition at line 247 of file Geocentric.hpp.

Reverse() [1/2]

void GeographicLib::Geocentric::Reverse ( real  X, real  Y, real  Z, real &  lat, real &  lon, real &  h  ) const

inline

Convert from geocentric to geodetic to coordinates.

Parameters

[in]	X	geocentric coordinate (meters).
[in]	Y	geocentric coordinate (meters).
[in]	Z	geocentric coordinate (meters).
[out]	lat	latitude of point (degrees).
[out]	lon	longitude of point (degrees).
[out]	h	height of point above the ellipsoid (meters).

In general there are multiple solutions and the result which maximizes h is returned. If there are still multiple solutions with different latitudes (applies only if Z = 0), then the solution with lat > 0 is returned. If there are still multiple solutions with different longitudes (applies only if X = Y = 0) then lon = 0 is returned. The value of h returned satisfies h ≥ − a (1 − e²) / sqrt(1 − e² sin²lat). The value of lon returned is in the range [−180°, 180°].

Definition at line 194 of file Geocentric.hpp.

Reverse() [2/2]

void GeographicLib::Geocentric::Reverse ( real  X, real  Y, real  Z, real &  lat, real &  lon, real &  h, std::vector< real > &  M  ) const

inline

Convert from geocentric to geodetic to coordinates.

Parameters

[in]	X	geocentric coordinate (meters).
[in]	Y	geocentric coordinate (meters).
[in]	Z	geocentric coordinate (meters).
[out]	lat	latitude of point (degrees).
[out]	lon	longitude of point (degrees).
[out]	h	height of point above the ellipsoid (meters).
[out]	M	if the length of the vector is 9, fill with the rotation matrix in row-major order.

Let v be a unit vector located at (lat, lon, h). We can express v as column vectors in one of two ways

• in east, north, up coordinates (where the components are relative to a local coordinate system at (lat, lon, h)); call this representation v1.
• in geocentric X, Y, Z coordinates; call this representation v0.

Then we have v1 = M^T ⋅ v0, where M^T is the transpose of M.

Definition at line 223 of file Geocentric.hpp.

Rotate()

static void GeographicLib::Geocentric::Rotate ( real  M[dim2_], real  x, real  y, real  z, real &  X, real &  Y, real &  Z  )

inlinestaticprivate

Definition at line 81 of file Geocentric.hpp.

Rotation()

void GeographicLib::Geocentric::Rotation ( real  sphi, real  cphi, real  slam, real  clam, real  M[dim2_]  )

staticprivate

Definition at line 155 of file src/Geocentric.cpp.

Unrotate()

static void GeographicLib::Geocentric::Unrotate ( real  M[dim2_], real  X, real  Y, real  Z, real &  x, real &  y, real &  z  )

inlinestaticprivate

Definition at line 89 of file Geocentric.hpp.

WGS84()

const Geocentric & GeographicLib::Geocentric::WGS84 ( )

static

A global instantiation of Geocentric with the parameters for the WGS84 ellipsoid.

Definition at line 31 of file src/Geocentric.cpp.

Friends And Related Function Documentation

GravityCircle

friend class GravityCircle

friend

Definition at line 73 of file Geocentric.hpp.

GravityModel

friend class GravityModel

friend

Definition at line 74 of file Geocentric.hpp.

LocalCartesian

friend class LocalCartesian

friend

Definition at line 70 of file Geocentric.hpp.

MagneticCircle

friend class MagneticCircle

friend

Definition at line 71 of file Geocentric.hpp.

MagneticModel

friend class MagneticModel

friend

Definition at line 72 of file Geocentric.hpp.

NormalGravity

friend class NormalGravity

friend

Definition at line 75 of file Geocentric.hpp.

Member Data Documentation

_a

real GeographicLib::Geocentric::_a

private

Definition at line 78 of file Geocentric.hpp.

_e2

real GeographicLib::Geocentric::_e2

private

Definition at line 78 of file Geocentric.hpp.

_e2a

real GeographicLib::Geocentric::_e2a

private

Definition at line 78 of file Geocentric.hpp.

_e2m

real GeographicLib::Geocentric::_e2m

private

Definition at line 78 of file Geocentric.hpp.

_e4a

real GeographicLib::Geocentric::_e4a

private

Definition at line 78 of file Geocentric.hpp.

_f

real GeographicLib::Geocentric::_f

private

Definition at line 78 of file Geocentric.hpp.

_maxrad

real GeographicLib::Geocentric::_maxrad

private

Definition at line 78 of file Geocentric.hpp.

dim2_

const size_t GeographicLib::Geocentric::dim2_ = dim_ * dim_

staticprivate

Definition at line 77 of file Geocentric.hpp.

dim_

const size_t GeographicLib::Geocentric::dim_ = 3

staticprivate

Definition at line 76 of file Geocentric.hpp.

---

The documentation for this class was generated from the following files:

• Geocentric.hpp
• src/Geocentric.cpp