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 ellipoid 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 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 elliopsoidal 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;
  }
}

Definition at line 82 of file Ellipsoid3.hpp.

Member Typedef Documentation

◆ vec3

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

A type to hold three-dimentional positions and directions in Cartesian coordinates.

Definition at line 88 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 semi-axis.
[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 semiaxeis.

Definition at line 182 of file Ellipsoid3.hpp.

Referenced by Ellipsoid3().

◆ b()

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

inline

Returns: b the median semiaxeis.

Definition at line 186 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 semiaxeis.

Definition at line 190 of file Ellipsoid3.hpp.

Referenced by Ellipsoid3().

◆ e2()

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

inline

Returns: e2 the eccentricity squared.

Definition at line 194 of file Ellipsoid3.hpp.

Referenced by Ellipsoid3().

◆ k2()

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

inline

Returns: k2 the oblateness parameter squared.

Definition at line 198 of file Ellipsoid3.hpp.

Referenced by Ellipsoid3().

◆ kp2()

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

inline

Returns: kp2 the prolateness parameter squared.

Definition at line 202 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 247 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 267 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:

Public Types

Public Member Functions

Static Public Member Functions

Normalizing functions

Detailed Description

Member Typedef Documentation

◆ vec3

Constructor & Destructor Documentation

◆ Ellipsoid3() [1/3]

◆ Ellipsoid3() [2/3]

◆ Ellipsoid3() [3/3]

Member Function Documentation

◆ a()

◆ b()

◆ c()

◆ e2()

◆ k2()

◆ kp2()

◆ Norm() [1/2]

◆ Norm() [2/2]

◆ AngNorm() [1/2]

◆ AngNorm() [2/2]

◆ cart2toellip() [1/3]

◆ cart2toellip() [2/3]

◆ cart2toellip() [3/3]

◆ elliptocart2() [1/2]

◆ elliptocart2() [2/2]

◆ Earth()