GeographicLib::Ellipsoid Class Reference

Properties of an ellipsoid. More...

`#include <GeographicLib/Ellipsoid.hpp>`

## Public Member Functions

Constructor
| Ellipsoid (real a, real f)
Ellipsoid dimensions.
Math::real | EquatorialRadius () const
Math::real | PolarRadius () const
Math::real | QuarterMeridian () const
Math::real | Area () const
Math::real | Volume () const
Ellipsoid shape
Math::real | Flattening () const
Math::real | SecondFlattening () const
Math::real | ThirdFlattening () const
Math::real | EccentricitySq () const
Math::real | SecondEccentricitySq () const
Math::real | ThirdEccentricitySq () const
Latitude conversion.
Math::real | ParametricLatitude (real phi) const
Math::real | InverseParametricLatitude (real beta) const
Math::real | GeocentricLatitude (real phi) const
Math::real | InverseGeocentricLatitude (real theta) const
Math::real | RectifyingLatitude (real phi) const
Math::real | InverseRectifyingLatitude (real mu) const
Math::real | AuthalicLatitude (real phi) const
Math::real | InverseAuthalicLatitude (real xi) const
Math::real | ConformalLatitude (real phi) const
Math::real | InverseConformalLatitude (real chi) const
Math::real | IsometricLatitude (real phi) const
Math::real | InverseIsometricLatitude (real psi) const
Other quantities.
Math::real | CircleRadius (real phi) const
Math::real | CircleHeight (real phi) const
Math::real | MeridianDistance (real phi) const
Math::real | MeridionalCurvatureRadius (real phi) const
Math::real | TransverseCurvatureRadius (real phi) const
Math::real | NormalCurvatureRadius (real phi, real azi) const

## Static Public Member Functions

static const Ellipsoid & | WGS84 ()
Eccentricity conversions.
static Math::real | SecondFlatteningToFlattening (real fp)
static Math::real | FlatteningToSecondFlattening (real f)
static Math::real | ThirdFlatteningToFlattening (real n)
static Math::real | FlatteningToThirdFlattening (real f)
static Math::real | EccentricitySqToFlattening (real e2)
static Math::real | FlatteningToEccentricitySq (real f)
static Math::real | SecondEccentricitySqToFlattening (real ep2)
static Math::real | FlatteningToSecondEccentricitySq (real f)
static Math::real | ThirdEccentricitySqToFlattening (real epp2)
static Math::real | FlatteningToThirdEccentricitySq (real f)

## Detailed Description

Properties of an ellipsoid.

This class returns various properties of the ellipsoid and converts between various types of latitudes. This is for the most part a thin wrapper on top of the AuxLatitude class which is called with exact = true so that the results are valid for arbitrary flattenings −100 < f < 99/100 (i.e., 1/100 < b/a < 100).

Example of use:

// Example of using the GeographicLib::Ellipsoid class
#include <iostream>
#include <iomanip>
#include <exception>
#include <GeographicLib/Ellipsoid.hpp>
using namespace std;
using namespace GeographicLib;
int main() {
try {
Ellipsoid wgs84(Constants::WGS84_a(), Constants::WGS84_f());
// Alternatively: const Ellipsoid& wgs84 = Ellipsoid::WGS84();
cout << "The latitude half way between the equator and the pole is "
<< wgs84.InverseRectifyingLatitude(45) << "\n";
cout << "Half the area of the ellipsoid lies between latitudes +/- "
<< wgs84.InverseAuthalicLatitude(30) << "\n";
cout << "The northernmost edge of a square Mercator map is at latitude "
<< wgs84.InverseIsometricLatitude(180) << "\n";
cout << "Table phi(deg) beta-phi xi-phi mu-phi chi-phi theta-phi (mins)\n"
<< fixed << setprecision(2);
for (int i = 0; i <= 90; i += 15) {
double phi = i,
bet = wgs84.ParametricLatitude(phi),
xi = wgs84.AuthalicLatitude(phi),
mu = wgs84.RectifyingLatitude(phi),
chi = wgs84.ConformalLatitude(phi),
theta = wgs84.GeocentricLatitude(phi);
cout << i << " "
<< (bet-phi)*60 << " "
<< (xi-phi)*60 << " "
<< (mu-phi)*60 << " "
<< (chi-phi)*60 << " "
<< (theta-phi)*60 << "\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
Ellipsoid.hpp
Header for GeographicLib::Ellipsoid 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::Ellipsoid::Ellipsoid
Ellipsoid(real a, real f)
GeographicLib
Namespace for GeographicLib.
Definition: Accumulator.cpp:12
std
Definition: NearestNeighbor.hpp:812

Definition at line 31 of file Ellipsoid.hpp.

## Constructor & Destructor Documentation

## Ellipsoid()

GeographicLib::Ellipsoid::Ellipsoid | ( | 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.

## Member Function Documentation

## EquatorialRadius()

Math::real GeographicLib::Ellipsoid::EquatorialRadius | ( |  | ) | const

inline

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

Definition at line 65 of file Ellipsoid.hpp.

## PolarRadius()

Math::real GeographicLib::Ellipsoid::PolarRadius | ( |  | ) | const

inline

Returns
  b the polar semi-axis (meters).

Definition at line 70 of file Ellipsoid.hpp.

## QuarterMeridian()

Math::real GeographicLib::Ellipsoid::QuarterMeridian | ( |  | ) | const

Returns
  L the distance between the equator and a pole along a meridian (meters). For a sphere L = (π/2) a. The radius of a sphere with the same meridian length is L / (π/2).

Definition at line 41 of file Ellipsoid.cpp.

## Area()

Math::real GeographicLib::Ellipsoid::Area | ( |  | ) | const

Returns
  A the total area of the ellipsoid (meters2). For a sphere A = 4π a2. The radius of a sphere with the same area is sqrt(A / (4π)).

Definition at line 44 of file Ellipsoid.cpp.

## Volume()

Math::real GeographicLib::Ellipsoid::Volume | ( |  | ) | const

inline

Returns
  V the total volume of the ellipsoid (meters3). For a sphere V = (4π / 3) a3. The radius of a sphere with the same volume is cbrt(V / (4π/3)).

Definition at line 91 of file Ellipsoid.hpp.

References GeographicLib::Math::pi(), and GeographicLib::Math::sq().

## Flattening()

Math::real GeographicLib::Ellipsoid::Flattening | ( |  | ) | const

inline

Returns
  f = (a − b) / a, the flattening of the ellipsoid. This is the value used in the constructor. This is zero, positive, or negative for a sphere, oblate ellipsoid, or prolate ellipsoid.

Definition at line 105 of file Ellipsoid.hpp.

## SecondFlattening()

Math::real GeographicLib::Ellipsoid::SecondFlattening | ( |  | ) | const

inline

Returns
  f ' = (a − b) / b, the second flattening of the ellipsoid. This is zero, positive, or negative for a sphere, oblate ellipsoid, or prolate ellipsoid.

Definition at line 112 of file Ellipsoid.hpp.

## ThirdFlattening()

Math::real GeographicLib::Ellipsoid::ThirdFlattening | ( |  | ) | const

inline

Returns
  n = (a − b) / (a + b), the third flattening of the ellipsoid. This is zero, positive, or negative for a sphere, oblate ellipsoid, or prolate ellipsoid.

Definition at line 119 of file Ellipsoid.hpp.

## EccentricitySq()

Math::real GeographicLib::Ellipsoid::EccentricitySq | ( |  | ) | const

inline

Returns
  e2 = (a2 − b2) / a2, the eccentricity squared of the ellipsoid. This is zero, positive, or negative for a sphere, oblate ellipsoid, or prolate ellipsoid.

Definition at line 127 of file Ellipsoid.hpp.

## SecondEccentricitySq()

Math::real GeographicLib::Ellipsoid::SecondEccentricitySq | ( |  | ) | const

inline

Returns
  e' 2 = (a2 − b2) / b2, the second eccentricity squared of the ellipsoid. This is zero, positive, or negative for a sphere, oblate ellipsoid, or prolate ellipsoid.

Definition at line 135 of file Ellipsoid.hpp.

## ThirdEccentricitySq()

Math::real GeographicLib::Ellipsoid::ThirdEccentricitySq | ( |  | ) | const

inline

Returns
  e'' 2 = (a2 − b2) / (a2 + b2), the third eccentricity squared of the ellipsoid. This is zero, positive, or negative for a sphere, oblate ellipsoid, or prolate ellipsoid.

Definition at line 144 of file Ellipsoid.hpp.

## ParametricLatitude()

Math::real GeographicLib::Ellipsoid::ParametricLatitude | ( | real | phi | ) | const

Parameters

  [in] | phi | the geographic latitude (degrees).

Returns
  β the parametric latitude (degrees).

The geographic latitude, φ, is the angle between the equatorial plane and a vector normal to the surface of the ellipsoid.

The parametric latitude (also called the reduced latitude), β, allows the cartesian coordinated of a meridian to be expressed conveniently in parametric form as

- R = a cos β
- Z = b sin β

where a and b are the equatorial radius and the polar semi-axis. For a sphere β = φ.

φ must lie in the range [−90°, 90°]; the result is undefined if this condition does not hold. The returned value β lies in [−90°, 90°].

Definition at line 47 of file Ellipsoid.cpp.

## InverseParametricLatitude()

Math::real GeographicLib::Ellipsoid::InverseParametricLatitude | ( | real | beta | ) | const

Parameters

  [in] | beta | the parametric latitude (degrees).

Returns
  φ the geographic latitude (degrees).

β must lie in the range [−90°, 90°]; the result is undefined if this condition does not hold. The returned value φ lies in [−90°, 90°].

Definition at line 52 of file Ellipsoid.cpp.

## GeocentricLatitude()

Math::real GeographicLib::Ellipsoid::GeocentricLatitude | ( | real | phi | ) | const

Parameters

  [in] | phi | the geographic latitude (degrees).

Returns
  θ the geocentric latitude (degrees).

The geocentric latitude, θ, is the angle between the equatorial plane and a line between the center of the ellipsoid and a point on the ellipsoid. For a sphere θ = φ.

φ must lie in the range [−90°, 90°]; the result is undefined if this condition does not hold. The returned value θ lies in [−90°, 90°].

Definition at line 57 of file Ellipsoid.cpp.

## InverseGeocentricLatitude()

Math::real GeographicLib::Ellipsoid::InverseGeocentricLatitude | ( | real | theta | ) | const

Parameters

  [in] | theta | the geocentric latitude (degrees).

Returns
  φ the geographic latitude (degrees).

θ must lie in the range [−90°, 90°]; the result is undefined if this condition does not hold. The returned value φ lies in [−90°, 90°].

Definition at line 62 of file Ellipsoid.cpp.

## RectifyingLatitude()

Math::real GeographicLib::Ellipsoid::RectifyingLatitude | ( | real | phi | ) | const

Parameters

  [in] | phi | the geographic latitude (degrees).

Returns
  μ the rectifying latitude (degrees).

The rectifying latitude, μ, has the property that the distance along a meridian of the ellipsoid between two points with rectifying latitudes μ1 and μ2 is equal to (μ2 - μ1) L / 90°, where L = QuarterMeridian(). For a sphere μ = φ.

φ must lie in the range [−90°, 90°]; the result is undefined if this condition does not hold. The returned value μ lies in [−90°, 90°].

Definition at line 67 of file Ellipsoid.cpp.

## InverseRectifyingLatitude()

Math::real GeographicLib::Ellipsoid::InverseRectifyingLatitude | ( | real | mu | ) | const

Parameters

  [in] | mu | the rectifying latitude (degrees).

Returns
  φ the geographic latitude (degrees).

μ must lie in the range [−90°, 90°]; the result is undefined if this condition does not hold. The returned value φ lies in [−90°, 90°].

Definition at line 72 of file Ellipsoid.cpp.

## AuthalicLatitude()

Math::real GeographicLib::Ellipsoid::AuthalicLatitude | ( | real | phi | ) | const

Parameters

  [in] | phi | the geographic latitude (degrees).

Returns
  ξ the authalic latitude (degrees).

The authalic latitude, ξ, has the property that the area of the ellipsoid between two circles with authalic latitudes ξ1 and ξ2 is equal to (sin ξ2 - sin ξ1) A / 2, where A = Area(). For a sphere ξ = φ.

φ must lie in the range [−90°, 90°]; the result is undefined if this condition does not hold. The returned value ξ lies in [−90°, 90°].

Definition at line 77 of file Ellipsoid.cpp.

## InverseAuthalicLatitude()

Math::real GeographicLib::Ellipsoid::InverseAuthalicLatitude | ( | real | xi | ) | const

Parameters

  [in] | xi | the authalic latitude (degrees).

Returns
  φ the geographic latitude (degrees).

ξ must lie in the range [−90°, 90°]; the result is undefined if this condition does not hold. The returned value φ lies in [−90°, 90°].

Definition at line 82 of file Ellipsoid.cpp.

## ConformalLatitude()

Math::real GeographicLib::Ellipsoid::ConformalLatitude | ( | real | phi | ) | const

Parameters

  [in] | phi | the geographic latitude (degrees).

Returns
  χ the conformal latitude (degrees).

The conformal latitude, χ, gives the mapping of the ellipsoid to a sphere which which is conformal (angles are preserved) and in which the equator of the ellipsoid maps to the equator of the sphere. For a sphere χ = φ.

φ must lie in the range [−90°, 90°]; the result is undefined if this condition does not hold. The returned value χ lies in [−90°, 90°].

Definition at line 87 of file Ellipsoid.cpp.

## InverseConformalLatitude()

Math::real GeographicLib::Ellipsoid::InverseConformalLatitude | ( | real | chi | ) | const

Parameters

  [in] | chi | the conformal latitude (degrees).

Returns
  φ the geographic latitude (degrees).

χ must lie in the range [−90°, 90°]; the result is undefined if this condition does not hold. The returned value φ lies in [−90°, 90°].

Definition at line 92 of file Ellipsoid.cpp.

## IsometricLatitude()

Math::real GeographicLib::Ellipsoid::IsometricLatitude | ( | real | phi | ) | const

Parameters

  [in] | phi | the geographic latitude (degrees).

Returns
  ψ the isometric latitude (degrees).

The isometric latitude gives the mapping of the ellipsoid to a plane which which is conformal (angles are preserved) and in which the equator of the ellipsoid maps to a straight line of constant scale; this mapping defines the Mercator projection. For a sphere ψ = sinh−1 tan φ.

φ must lie in the range [−90°, 90°]; the result is undefined if this condition does not hold. The value returned for φ = ±90° is some (positive or negative) large but finite value, such that InverseIsometricLatitude returns the original value of φ.

Definition at line 97 of file Ellipsoid.cpp.

## InverseIsometricLatitude()

Math::real GeographicLib::Ellipsoid::InverseIsometricLatitude | ( | real | psi | ) | const

Parameters

  [in] | psi | the isometric latitude (degrees).

Returns
  φ the geographic latitude (degrees).

The returned value φ lies in [−90°, 90°]. For a sphere φ = tan−1 sinh ψ.

Definition at line 102 of file Ellipsoid.cpp.

## CircleRadius()

Math::real GeographicLib::Ellipsoid::CircleRadius | ( | real | phi | ) | const

Parameters

  [in] | phi | the geographic latitude (degrees).

Returns
  R = a cos β the radius of a circle of latitude φ (meters). R (π/180°) gives meters per degree longitude measured along a circle of latitude.

φ must lie in the range [−90°, 90°]; the result is undefined if this condition does not hold.

Definition at line 107 of file Ellipsoid.cpp.

References GeographicLib::AuxAngle::x().

## CircleHeight()

Math::real GeographicLib::Ellipsoid::CircleHeight | ( | real | phi | ) | const

Parameters

  [in] | phi | the geographic latitude (degrees).

Returns
  Z = b sin β the distance of a circle of latitude φ from the equator measured parallel to the ellipsoid axis (meters).

φ must lie in the range [−90°, 90°]; the result is undefined if this condition does not hold.

Definition at line 115 of file Ellipsoid.cpp.

References GeographicLib::AuxAngle::y().

## MeridianDistance()

Math::real GeographicLib::Ellipsoid::MeridianDistance | ( | real | phi | ) | const

Parameters

  [in] | phi | the geographic latitude (degrees).

Returns
  s the distance along a meridian between the equator and a point of latitude φ (meters). s is given by s = μ L / 90°, where L = QuarterMeridian()).

φ must lie in the range [−90°, 90°]; the result is undefined if this condition does not hold.

Definition at line 123 of file Ellipsoid.cpp.

## MeridionalCurvatureRadius()

Math::real GeographicLib::Ellipsoid::MeridionalCurvatureRadius | ( | real | phi | ) | const

Parameters

  [in] | phi | the geographic latitude (degrees).

Returns
  ρ the meridional radius of curvature of the ellipsoid at latitude φ (meters); this is the curvature of the meridian. rho is given by ρ = (180°/π) ds / dφ, where s = MeridianDistance(); thus ρ (π/180°) gives meters per degree latitude measured along a meridian.

φ must lie in the range [−90°, 90°]; the result is undefined if this condition does not hold.

Definition at line 129 of file Ellipsoid.cpp.

## TransverseCurvatureRadius()

Math::real GeographicLib::Ellipsoid::TransverseCurvatureRadius | ( | real | phi | ) | const

Parameters

  [in] | phi | the geographic latitude (degrees).

Returns
  ν the transverse radius of curvature of the ellipsoid at latitude φ (meters); this is the curvature of a curve on the ellipsoid which also lies in a plane perpendicular to the ellipsoid and to the meridian. ν is related to R = CircleRadius() by R = ν cos φ.

φ must lie in the range [−90°, 90°]; the result is undefined if this condition does not hold.

Definition at line 134 of file Ellipsoid.cpp.

## NormalCurvatureRadius()

Math::real GeographicLib::Ellipsoid::NormalCurvatureRadius | ( | real | phi,
|  | real | azi
| ) |  | const

Parameters

  [in] | phi | the geographic latitude (degrees).
  [in] | azi | the angle between the meridian and the normal section (degrees).

Returns
  the radius of curvature of the ellipsoid in the normal section at latitude φ inclined at an angle azi to the meridian (meters).

φ must lie in the range [−90°, 90°]; the result is undefined this condition does not hold.

Definition at line 139 of file Ellipsoid.cpp.

## SecondFlatteningToFlattening()

static Math::real GeographicLib::Ellipsoid::SecondFlatteningToFlattening | ( | real | fp | ) |

inlinestatic

Parameters

  [in] | fp | = f ' = (a − b) / b, the second flattening.

Returns
  f = (a − b) / a, the flattening.

f ' should lie in (−1, ∞). The returned value f lies in (−∞, 1).

Definition at line 401 of file Ellipsoid.hpp.

## FlatteningToSecondFlattening()

static Math::real GeographicLib::Ellipsoid::FlatteningToSecondFlattening | ( | real | f | ) |

inlinestatic

Parameters

  [in] | f | = (a − b) / a, the flattening.

Returns
  f ' = (a − b) / b, the second flattening.

f should lie in (−∞, 1). The returned value f ' lies in (−1, ∞).

Definition at line 411 of file Ellipsoid.hpp.

## ThirdFlatteningToFlattening()

static Math::real GeographicLib::Ellipsoid::ThirdFlatteningToFlattening | ( | real | n | ) |

inlinestatic

Parameters

  [in] | n | = (a − b) / (a + b), the third flattening.

Returns
  f = (a − b) / a, the flattening.

n should lie in (−1, 1). The returned value f lies in (−∞, 1).

Definition at line 422 of file Ellipsoid.hpp.

## FlatteningToThirdFlattening()

static Math::real GeographicLib::Ellipsoid::FlatteningToThirdFlattening | ( | real | f | ) |

inlinestatic

Parameters

  [in] | f | = (a − b) / a, the flattening.

Returns
  n = (a − b) / (a + b), the third flattening.

f should lie in (−∞, 1). The returned value n lies in (−1, 1).

Definition at line 433 of file Ellipsoid.hpp.

## EccentricitySqToFlattening()

static Math::real GeographicLib::Ellipsoid::EccentricitySqToFlattening | ( | real | e2 | ) |

inlinestatic

Parameters

  [in] | e2 | = e2 = (a2 − b2) / a2, the eccentricity squared.

Returns
  f = (a − b) / a, the flattening.

e2 should lie in (−∞, 1). The returned value f lies in (−∞, 1).

Definition at line 445 of file Ellipsoid.hpp.

## FlatteningToEccentricitySq()

static Math::real GeographicLib::Ellipsoid::FlatteningToEccentricitySq | ( | real | f | ) |

inlinestatic

Parameters

  [in] | f | = (a − b) / a, the flattening.

Returns
  e2 = (a2 − b2) / a2, the eccentricity squared.

f should lie in (−∞, 1). The returned value e2 lies in (−∞, 1).

Definition at line 457 of file Ellipsoid.hpp.

## SecondEccentricitySqToFlattening()

static Math::real GeographicLib::Ellipsoid::SecondEccentricitySqToFlattening | ( | real | ep2 | ) |

inlinestatic

Parameters

  [in] | ep2 | = e' 2 = (a2 − b2) / b2, the second eccentricity squared.

Returns
  f = (a − b) / a, the flattening.

e' 2 should lie in (−1, ∞). The returned value f lies in (−∞, 1).

Definition at line 469 of file Ellipsoid.hpp.

## FlatteningToSecondEccentricitySq()

static Math::real GeographicLib::Ellipsoid::FlatteningToSecondEccentricitySq | ( | real | f | ) |

inlinestatic

Parameters

  [in] | f | = (a − b) / a, the flattening.

Returns
  e' 2 = (a2 − b2) / b2, the second eccentricity squared.

f should lie in (−∞, 1). The returned value e' 2 lies in (−1, ∞).

Definition at line 481 of file Ellipsoid.hpp.

References GeographicLib::Math::sq().

## ThirdEccentricitySqToFlattening()

static Math::real GeographicLib::Ellipsoid::ThirdEccentricitySqToFlattening | ( | real | epp2 | ) |

inlinestatic

Parameters

  [in] | epp2 | = e'' 2 = (a2 − b2) / (a2 + b2), the third eccentricity squared.

Returns
  f = (a − b) / a, the flattening.

e'' 2 should lie in (−1, 1). The returned value f lies in (−∞, 1).

Definition at line 493 of file Ellipsoid.hpp.

## FlatteningToThirdEccentricitySq()

static Math::real GeographicLib::Ellipsoid::FlatteningToThirdEccentricitySq | ( | real | f | ) |

inlinestatic

Parameters

  [in] | f | = (a − b) / a, the flattening.

Returns
  e'' 2 = (a2 − b2) / (a2 + b2), the third eccentricity squared.

f should lie in (−∞, 1). The returned value e'' 2 lies in (−1, 1).

Definition at line 507 of file Ellipsoid.hpp.

References GeographicLib::Math::sq().

## WGS84()

const Ellipsoid & GeographicLib::Ellipsoid::WGS84 | ( |  | ) |

static

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

Definition at line 36 of file Ellipsoid.cpp.

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

- Ellipsoid.hpp
- Ellipsoid.cpp