Loading...
Searching...
No Matches
GeographicLib::Triaxial::Ellipsoid3 Class Reference

A triaxial ellipsoid. More...

`#include <GeographicLib/Triaxial/Ellipsoid3.hpp>`

## Public Types

using | vec3 = std::array<Math::real, 3>

## Public Member Functions

| Ellipsoid3 ()
| Ellipsoid3 (real a, real b, real c)
| Ellipsoid3 (real b, real e2, real k2, real kp2)
Inspector functions
real | a () const
real | b () const
real | c () const
real | e2 () const
real | k2 () const
real | kp2 () const
Coordinate conversions.
void | cart2toellip (vec3 R, Angle &bet, Angle &omg) const
void | cart2toellip (vec3 R, vec3 V, Angle &bet, Angle &omg, Angle &alp) const
void | cart2toellip (Angle bet, Angle omg, vec3 V, Angle &alp) const
void | elliptocart2 (Angle bet, Angle omg, vec3 &R) const
void | elliptocart2 (Angle bet, Angle omg, Angle alp, vec3 &R, vec3 &V) const

## Static Public Member Functions

static const Ellipsoid3 & | Earth ()

## Normalizing functions

void | Norm (vec3 &R) const
void | Norm (vec3 &R, vec3 &V) const
static bool | AngNorm (Angle &bet, Angle &omg, Angle &alp, bool alt=false)
static bool | AngNorm (Angle &bet, Angle &omg, bool alt=false)

## Detailed Description

A triaxial ellipsoid.

The class holds the basic information about a triaxial ellipsoid given by

\[ S(\mathbf R) = \frac{X^2}{a^2} + \frac{Y^2}{b^2} + \frac{Z^2}{c^2} - 1 = 0, \]

where the semiaxes satisfy \( a \ge b \ge c > 0\). It is useful to characterize the shape of the ellipsoid by

\[\begin{align} e &= \frac{\sqrt{a^2-c^2}}b,\\ k &= \frac{\sqrt{b^2-c^2}}{\sqrt{a^2-c^2}},\\ k' &= \frac{\sqrt{a^2-b^2}}{\sqrt{a^2-c^2}}; \end{align} \]

note that \(k^2 + k'^2 = 1\). The spherical limit \( e\rightarrow 0 \) is nonuniform since the values of \(k\) and \(k'\) depend on how the limit is taken. In this cases, it's convenient to specify the ellipsoid in terms of these parameters. The semiaxes are related to these parameters by

\[[a,b,c] = b \bigl[ \sqrt{1 + e^2k'^2}, 1, \sqrt{1 - e^2k^2} \bigr]. \]

Positions on the ellipsoid are given in term so the ellipsoidal coordinates given in Section 2 of

- C. F. F. Karney,
  Jacobi's solution for geodesics on a triaxial ellipsoid,
  Technical Report, SRI International, Nov. 2025.
  arxiv:2511.01621

Ellipsoidal latitude * \(\beta\) and the ellipsoidal longitude \(\omega\) which are defined * by

\[\mathbf R = \begin{bmatrix} a \cos\omega \sqrt{k^2\cos^2\beta + k'^2} \\ b \cos\beta \sin\omega \\ c \sin\beta \sqrt{k^2 + k'^2\sin^2\omega} \end{bmatrix}. \]

Headings are given by the direction \( \alpha \) measured clockwise from a line of constant \( \omega \). Conversions between cartesian and ellipsoidal coordinates is provided by cart2toellip() and elliptocart2().

The ellipsoid coordinates "cover" the ellipsoid twice; the replacement

\[\begin{align} \omega & \rightarrow -\omega,\\ \beta & \rightarrow \pi-\beta,\\ \alpha & \rightarrow \pi+\alpha, \end{align} \]

leaves the position and direction unchanged; see AngNorm(),

Example of use:

// Example of using the Triaxial::Ellipsoid3 class.
#include <iostream>
#include <iomanip>
#include <exception>
#include <GeographicLib/Triaxial/Ellipsoid3.hpp>
using namespace std;
using namespace GeographicLib;
int main() {
try {
using Triaxial::Ellipsoid3;
using ang = Angle;
using vec3 = Ellipsoid3::vec3;
Ellipsoid3 t(3, 2, 1);
ang bet{40}, omg{20}, alp{80};
vec3 r, v;
t.elliptocart2(bet, omg, alp, r, v);
cout << fixed << setprecision(3)
<< "[bet, omg, alp] = ["
<< double(bet) << " " << double(omg) << " " << double(alp)
<< "]\n => r = [" << r[0] << " " << r[1] << " " << r[2]
<< "], v = [" << v[0] << " " << v[1] << " " << v[2] << "]\n";
ang betn, omgn, alpn;
t.cart2toellip(r, v, betn, omgn, alpn);
cout << " => [bet, omg, alp] = ["
<< double(betn) << " " << double(omgn) << " " << double(alpn) << "]\n";
}
catch (const exception& e) {
cerr << "Caught exception: " << e.what() << "\n";
return 1;
}
}
main
int main(int argc, const char *const argv[])
Definition Cart3Convert.cpp:52
Ellipsoid3.hpp
Header for GeographicLib::Triaxial::Ellipsoid3 class.
ang
GeographicLib::Angle ang
Definition Geod3Solve.cpp:26
GeographicLib::Triaxial::Ellipsoid3
A triaxial ellipsoid.
Definition Ellipsoid3.hpp:89
GeographicLib::Triaxial::Ellipsoid3::Ellipsoid3
Ellipsoid3()
Definition Ellipsoid3.cpp:17
GeographicLib::Triaxial::Ellipsoid3::vec3
std::array< Math::real, 3 > vec3
Definition Ellipsoid3.hpp:95
GeographicLib
Namespace for GeographicLib.
Definition Accumulator.cpp:12
GeographicLib::Angle
AngleT< Math::real > Angle
Definition Angle.hpp:760
std
Definition NearestNeighbor.hpp:806

Definition at line 89 of file Ellipsoid3.hpp.

## Member Typedef Documentation

## vec3

using GeographicLib::Triaxial::Ellipsoid3::vec3 = std::array<Math::real, 3>

A type to hold three-dimensional positions and directions in cartesian coordinates.

Definition at line 95 of file Ellipsoid3.hpp.

## Constructor & Destructor Documentation

## Ellipsoid3() [1/3]

GeographicLib::Triaxial::Ellipsoid3::Ellipsoid3 | ( |  | ) |

The default constructor for a unit sphere in the oblate limit.

Definition at line 17 of file Ellipsoid3.cpp.

References Ellipsoid3().

Referenced by Earth(), and Ellipsoid3().

## Ellipsoid3() [2/3]

GeographicLib::Triaxial::Ellipsoid3::Ellipsoid3 | ( | real | a,
|  | real | b,
|  | real | c )

An ellipsoid specified by its semiaxes.

Parameters

  [in] | a | the major semiaxis.
  [in] | b | the median semiaxis.
  [in] | c | the minor semiaxis.

Exceptions

  GeographicErr | if the required ordering is semiaxes is violated.

The semiaxes must satisfy a ≥ b ≥ c > 0. If a = c (a sphere), then the oblate limit is taken.

Definition at line 21 of file Ellipsoid3.cpp.

References a(), b(), c(), and GeographicLib::Math::sq().

## Ellipsoid3() [3/3]

GeographicLib::Triaxial::Ellipsoid3::Ellipsoid3 | ( | real | b,
|  | real | e2,
|  | real | k2,
|  | real | kp2 )

An ellipsoid specified by its median semiaxis and shape.

Parameters

  [in] | b | the middle semiaxis.
  [in] | e2 | the eccentricity squared \(e^2 = (a^2 - c^2)/b^2\).
  [in] | k2 | the oblateness parameter squared \(k^2 = (b^2 - c^2) / (a^2 - c^2)\).
  [in] | kp2 | the prolateness parameter squared \(k'^2= (a^2 - b^2) / (a^2 - c^2)\).

Exceptions

  GeographicErr | if the required ordering is semiaxes is violated.

This form of the constructor is important when the eccentricity is small and giving e2 allows for more precision.

In the case of a sphere with e2 = 0, this constructor distinguishes between and "oblate sphere" (k2 = 1), a "prolate sphere" (k2 = 0), and a "triaxial sphere" (k2 &isin (0,1)). These distinctions matter when ellipsoidal coordinates are used.

Note
  The constructor normalizes k2 and kp2 so that k2 + kp2 = 1.

Definition at line 46 of file Ellipsoid3.cpp.

References b(), e2(), k2(), and kp2().

## Member Function Documentation

## a()

real GeographicLib::Triaxial::Ellipsoid3::a | ( |  | ) | const

inline

Returns
  a the major semiaxis.

Definition at line 190 of file Ellipsoid3.hpp.

Referenced by Ellipsoid3().

## b()

real GeographicLib::Triaxial::Ellipsoid3::b | ( |  | ) | const

inline

Returns
  b the median semiaxis.

Definition at line 194 of file Ellipsoid3.hpp.

Referenced by Ellipsoid3(), Ellipsoid3(), and GeographicLib::Triaxial::Conformal3::ForwardOther().

## c()

real GeographicLib::Triaxial::Ellipsoid3::c | ( |  | ) | const

inline

Returns
  c the minor semiaxis.

Definition at line 198 of file Ellipsoid3.hpp.

Referenced by Ellipsoid3().

## e2()

real GeographicLib::Triaxial::Ellipsoid3::e2 | ( |  | ) | const

inline

Returns
  e2 the eccentricity squared.

Definition at line 202 of file Ellipsoid3.hpp.

Referenced by Ellipsoid3().

## k2()

real GeographicLib::Triaxial::Ellipsoid3::k2 | ( |  | ) | const

inline

Returns
  k2 the oblateness parameter squared.

Definition at line 206 of file Ellipsoid3.hpp.

Referenced by Ellipsoid3().

## kp2()

real GeographicLib::Triaxial::Ellipsoid3::kp2 | ( |  | ) | const

inline

Returns
  kp2 the prolateness parameter squared.

Definition at line 210 of file Ellipsoid3.hpp.

Referenced by Ellipsoid3().

## Norm() [1/2]

void GeographicLib::Triaxial::Ellipsoid3::Norm | ( | vec3 & | R | ) | const

Scale a position to ensure it lies on the ellipsoid

Parameters

  [in,out] | R | the position.

The components of R are scaled so that it lies on the ellipsoid. The resulting position is not in general the closest point on the ellipsoid. Use Cartesian3::carttocart2() for that.

Definition at line 67 of file Ellipsoid3.cpp.

References GeographicLib::Math::hypot3().

Referenced by Norm().

## Norm() [2/2]

void GeographicLib::Triaxial::Ellipsoid3::Norm | ( | vec3 & | R,
|  | vec3 & | V ) const

Scale a position and direction to the ellipsoid

Parameters

  [in,out] | R | the position.
  [in,out] | V | the position.

The components of R are scaled so that it lies on the ellipsoid. Then V is projected to be tangent to the surface and is normalized to a unit vector.

Definition at line 73 of file Ellipsoid3.cpp.

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

## AngNorm() [1/2]

bool GeographicLib::Triaxial::Ellipsoid3::AngNorm | ( | Angle & | bet,
|  | Angle & | omg,
|  | Angle & | alp,
|  | bool | alt = false )

inlinestatic

Set the sheet for coordinates.

Parameters

  [in,out] | bet | the ellipsoidal latitude.
  [in,out] | omg | the ellipsoidal longitude.
  [in,out] | alp | the heading.
  [in] | alt | if true switch to the alternate sheet.

Returns
  whether the coordinates were changed.

If alt = false (the default), the conventional sheet is used switching the values of bet, omg, and alp, so that bet ∈ [-π/2, &pi/2].

If alt = true, the alternate sheet is used switching the values of bet, omg, and alp, so that omg ∈ [0, π].

This routine does not change n (the number of turns) for the coordinates.

Definition at line 255 of file Ellipsoid3.hpp.

References GeographicLib::AngleT< T >::c(), and GeographicLib::AngleT< T >::s().

Referenced by GeographicLib::Triaxial::Geodesic3::Inverse(), GeographicLib::Triaxial::GeodesicLine3::pos1(), GeographicLib::Triaxial::GeodesicLine3::Position(), and GeographicLib::Triaxial::Conformal3::ReverseSphere().

## AngNorm() [2/2]

bool GeographicLib::Triaxial::Ellipsoid3::AngNorm | ( | Angle & | bet,
|  | Angle & | omg,
|  | bool | alt = false )

inlinestatic

Set the sheet for coordinates.

Parameters

  [in,out] | bet | the ellipsoidal latitude.
  [in,out] | omg | the ellipsoidal longitude.
  [in] | alt | if true switch to the alternate sheet.

Returns
  whether the coordinated were changed.

This acts precisely the same and AngNorm(Angle&, Angle&, Angle&, bool) except that alp is omitted.

Definition at line 275 of file Ellipsoid3.hpp.

References GeographicLib::AngleT< T >::c(), and GeographicLib::AngleT< T >::s().

## cart2toellip() [1/3]

void GeographicLib::Triaxial::Ellipsoid3::cart2toellip | ( | vec3 | R,
|  | Angle & | bet,
|  | Angle & | omg ) const

Convert a cartesian position to ellipsoidal coordinates.

Parameters

  [in] | R | the cartesian position.
  [out] | bet | the ellipsoidal latitude.
  [out] | omg | the ellipsoidal longitude.

Note
  R must lie on the surface of the ellipsoid. The "2" in "cart2" is used to emphasize this.

Definition at line 112 of file Ellipsoid3.cpp.

Referenced by cart2toellip().

## cart2toellip() [2/3]

void GeographicLib::Triaxial::Ellipsoid3::cart2toellip | ( | vec3 | R,
|  | vec3 | V,
|  | Angle & | bet,
|  | Angle & | omg,
|  | Angle & | alp ) const

Convert a cartesian position and direction to ellipsoidal coordinates.

Parameters

  [in] | R | the cartesian position.
  [in] | V | the cartesian direction.
  [out] | bet | the ellipsoidal latitude.
  [out] | omg | the ellipsoidal longitude.
  [out] | alp | the azimuth.

Note
  R must lie on the surface of the ellipsoid and V must be tangent to the surface at that point. The "2" in "cart2" is used to emphasize this.

Definition at line 169 of file Ellipsoid3.cpp.

References cart2toellip().

## cart2toellip() [3/3]

void GeographicLib::Triaxial::Ellipsoid3::cart2toellip | ( | Angle | bet,
|  | Angle | omg,
|  | vec3 | V,
|  | Angle & | alp ) const

Convert an ellipsoid position and cartesian direction to a heading.

Parameters

  [in] | bet | the ellipsoidal latitude.
  [in] | omg | the ellipsoidal longitude.
  [in] | V | the cartesian direction.
  [out] | alp | the azimuth.

This is a variant of cart2toellip(vec3, vec3, Angle&, Angle&, Angle&) where bet and omg are used to ensure that the correct sheet is used in determining alp.

Note
  V must be tangent to the surface of the ellipsoid. The "2" in "cart2" is used to emphasize this.

Definition at line 116 of file Ellipsoid3.cpp.

References GeographicLib::AngleT< T >::c(), GeographicLib::Math::norm(), and GeographicLib::AngleT< T >::s().

## elliptocart2() [1/2]

void GeographicLib::Triaxial::Ellipsoid3::elliptocart2 | ( | Angle | bet,
|  | Angle | omg,
|  | vec3 & | R ) const

Convert ellipsoidal coordinates to a cartesian position.

Parameters

  [in] | bet | the ellipsoidal latitude.
  [in] | omg | the ellipsoidal longitude.
  [out] | R | the cartesian position.

Definition at line 176 of file Ellipsoid3.cpp.

References GeographicLib::AngleT< T >::c(), and GeographicLib::AngleT< T >::s().

Referenced by elliptocart2().

## elliptocart2() [2/2]

void GeographicLib::Triaxial::Ellipsoid3::elliptocart2 | ( | Angle | bet,
|  | Angle | omg,
|  | Angle | alp,
|  | vec3 & | R,
|  | vec3 & | V ) const

Convert coordinates and heading to a cartesian position and direction.

Parameters

  [in] | bet | the ellipsoidal latitude.
  [in] | omg | the ellipsoidal longitude.
  [in] | alp | the azimuth.
  [out] | R | the cartesian position.
  [out] | V | the cartesian direction.

Definition at line 183 of file Ellipsoid3.cpp.

References GeographicLib::AngleT< T >::c(), elliptocart2(), and GeographicLib::AngleT< T >::s().

## Earth()

const Ellipsoid3 & GeographicLib::Triaxial::Ellipsoid3::Earth | ( |  | ) |

static

A global instantiation of Ellipsoid3 with the parameters for the Earth.

Definition at line 226 of file Ellipsoid3.cpp.

References Ellipsoid3(), GeographicLib::Constants::Triaxial_Earth_a(), GeographicLib::Constants::Triaxial_Earth_b(), and GeographicLib::Constants::Triaxial_Earth_c().

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

- Ellipsoid3.hpp
- Ellipsoid3.cpp