GeographicLib 2.3

Public Member Functions | Static Public Member Functions | Friends | List of all members
GeographicLib::Geocentric Class Reference

Geocentric coordinates More...

`#include <GeographicLib/Geocentric.hpp>`

## Public Member Functions
| Geocentric (real a, real f)
| Geocentric ()
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
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 | EquatorialRadius () const
Math::real | Flattening () const

## Static Public Member Functions
static const Geocentric & | WGS84 ()

## Friends
class | LocalCartesian
class | MagneticCircle
class | MagneticModel
class | GravityCircle
class | GravityModel
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 coordinates 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 coordinates 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;
}
}
main
int main(int argc, const char *const argv[])
Definition: CartConvert.cpp:29
Geocentric.hpp
Header for GeographicLib::Geocentric class.
GeographicLib::Constants::WGS84_f
static T WGS84_f()
Definition: Constants.hpp:141
GeographicLib::Constants::WGS84_a
static T WGS84_a()
Definition: Constants.hpp:135
GeographicLib::Geocentric::Geocentric
Geocentric()
Definition: Geocentric.hpp:118
GeographicLib
Namespace for GeographicLib.
Definition: Accumulator.cpp:12
std
Definition: NearestNeighbor.hpp:812

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

Definition at line 67 of file Geocentric.hpp.

## Constructor & Destructor Documentation

## ◆ Geocentric() [1/2]

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

Constructor for an 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 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

## ◆ 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.

Referenced by main(), and GeographicLib::LocalCartesian::Reset().

## ◆ 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.

## ◆ 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 minimizes |h |is returned, i.e., (lat, lon) corresponds to the closest point on the ellipsoid. 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 − e2) / sqrt(1 − e2 sin2lat). The value of lon returned is in the range [−180°, 180°].

Definition at line 195 of file Geocentric.hpp.

Referenced by main().

## ◆ 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 = MT ⋅ v0, where MT is the transpose of M.

Definition at line 224 of file Geocentric.hpp.

## ◆ Init()

bool GeographicLib::Geocentric::Init | ( |  | ) | const
| inline

Returns
  true if the object has been initialized.

Definition at line 243 of file Geocentric.hpp.

## ◆ EquatorialRadius()

Math::real GeographicLib::Geocentric::EquatorialRadius | ( |  | ) | const
| inline

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

Definition at line 248 of file Geocentric.hpp.

References GeographicLib::Math::NaN().

Referenced by GeographicLib::LocalCartesian::EquatorialRadius(), and GeographicLib::MagneticModel::EquatorialRadius().

## ◆ 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 255 of file Geocentric.hpp.

References GeographicLib::Math::NaN().

Referenced by GeographicLib::LocalCartesian::Flattening(), and GeographicLib::MagneticModel::Flattening().

## ◆ 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 Geocentric.cpp.

References GeographicLib::Constants::WGS84_a(), and GeographicLib::Constants::WGS84_f().

## Friends And Related Function Documentation

## ◆ 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.

## ◆ 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.

## ◆ NormalGravity

friend class NormalGravity
| friend

Definition at line 75 of file Geocentric.hpp.

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

- Geocentric.hpp
- Geocentric.cpp