Transformations between cartesian and triaxial coordinates. More...

#include <GeographicLib/Triaxial/Cartesian3.hpp>

Public Types
enum	coord { GEODETIC , PARAMETRIC , GEOCENTRIC , ELLIPSOIDAL , GEODETIC_X , PARAMETRIC_X , GEOCENTRIC_X , PLANETODETIC , GEOGRAPHIC , PLANETOCENTRIC }
using	vec3 = Ellipsoid3::vec3

Public Member Functions
template<int n>
Angle	meridianplane (ang lam, bool alt) const
Transformations for points on the ellipsoid.
	Cartesian3 (const Ellipsoid3 &t)
	Cartesian3 (real a, real b, real c)
	Cartesian3 (real b, real e2, real k2, real kp2)
void	anytocart2 (coord coordin, Angle lat, Angle lon, vec3 &R) const
void	anytocart2 (coord coordin, real lat, real lon, vec3 &R) const
void	cart2toany (vec3 R, coord coordout, Angle &lat, Angle &lon) const
void	cart2toany (vec3 R, coord coordout, real &lat, real &lon) const
void	anytoany (coord coordin, Angle lat1, Angle lon1, coord coordout, Angle &lat2, Angle &lon2) const
void	anytoany (coord coordin, real lat1, real lon1, coord coordout, real &lat2, real &lon2) const
Transformations for points and directions on the ellipsoid.
void	anytocart2 (coord coordin, Angle lat, Angle lon, Angle azi, vec3 &R, vec3 &V) const
void	anytocart2 (coord coordin, real lat, real lon, real azi, vec3 &R, vec3 &V) const
void	cart2toany (vec3 R, vec3 V, coord coordout, Angle &lat, Angle &lon, Angle &azi) const
void	cart2toany (vec3 R, vec3 V, coord coordout, real &lat, real &lon, real &azi) const
Transformations for arbitrary points.
void	anytocart (coord coordin, Angle lat, Angle lon, real h, vec3 &R) const
void	anytocart (coord coordin, real lat, real lon, real h, vec3 &R) const
void	carttoany (vec3 R, coord coordout, Angle &lat, Angle &lon, real &h) const
void	carttoany (vec3 R, coord coordout, real &lat, real &lon, real &h) const
Transferring an arbitrary point onto the ellipsoid.
void	cart2tocart (vec3 R2, real h, vec3 &R) const
void	carttocart2 (vec3 R, vec3 &R2, real &h) const
Generating random points on the ellipsoid.
template<class G>
void	cart2rand (G &g, vec3 &R) const
template<class G>
void	cart2rand (G &g, vec3 &R, vec3 &V) const
Inspector function
const Ellipsoid3 &	t () const

Detailed Description

Transformations between cartesian and triaxial coordinates.

The Cartesian3 class supports transformations between cartesian coordinates and various coordinates for a triaxial ellipsoid. This is covered in Appendices A and B of

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

Besides ellipsoidal coordinates defined in Ellipsoid3, the following coordinates are supported:

geodetic coordinates \((\phi, \lambda)\) defined by
\[ \hat{\mathbf U} = [\cos\phi \cos\lambda, \cos\phi \sin\lambda, \sin\phi]^T, \]
where \(\hat{\mathbf U}\) is the normal to the surface of the ellipsoid.
parametric coordinates \((\phi', \lambda')\) defined by
\[ \mathbf R = [a \cos\phi' \cos\lambda', b \cos\phi' \sin\lambda', c \sin\phi']^T, \]
geocentric coordinates \((\phi'', \lambda'')\) defined by
\[ \hat{\mathbf R} = [\cos\phi'' \cos\lambda'', \cos\phi'' \sin\lambda'', \sin\phi'']^T. \]

For each of these 3 coordinates, the "north pole" is at \([0, 0, c]^T\) and the origin for longitudes is \([a, 0, 0]^T\). We also define alternate versions (named "geodetic*", etc., where the north pole is placed at \([a, 0, 0]^T\) and the origin for longitude is \([0, 0, -c]\). This latter set of coordinates is appropriate for ellipsoids that are nearly prolate.

Directions on the ellipsoid are easily specified in cartesian coordinates as a vector tangent to the surface of the ellipsoid. This is converted to a heading by defined the angle the vector makes (measured clockwise) from the coordinate-specific north. This is defined as the direction of a line of constant (coordinate-specific) longitude. The resulting heading is denoted by \(\alpha\) for ellipsoidal coordinates and by \(\zeta\) for the other coordinates. The unstarred coordinates all share the same direction for north, and likewise for the starred coordinates. Note that the lines of constant longitude and latitude are only orthogonal (in general) for ellipsoidal coordinates.

Arbitrary points (not necessarily lying on the ellipsoid) an additional "height" is required to specify the position. For ellipsoidal coordinates, we find the confocal ellipsoid on which the point lies and the height is then defined as \(H = u - c\) where \(u\) is the semiminor axes of the confocal ellipsoid; the ellipsoid latitude and longitude are those for the confocal ellipsoid For the other coordinates systems, we define \(h\) a the height above the closest point on the ellipsoid and the latitude and longitude refer to the closest point.

Note: The family of confocal ellipsoids has semiaxes \([\sqrt{a^2 - c^2 + u^2}, \sqrt{b^2 - c^2 + u^2}, u]\).; In the function names "any" stands for any of the seven coordinate systems enumerated by Cartesian3::coord. "cart2" refers to a point given in cartesian coordinates that lies on the ellipsoid. On the other hand, "cart" refers to an arbitrary point.

Example of use:

// Example of using the Triaxial::Cartesian3 class.
 
#include <iostream>
#include <iomanip>
#include <exception>
#include <random>
#include <GeographicLib/Triaxial/Cartesian3.hpp>
 
using namespace std;
using namespace GeographicLib;
 
int main() {
  try {
    using Triaxial::Cartesian3;
    Cartesian3 cart(3, 2, 1);
    unsigned long long
      s1 = std::random_device()(),
      s2 = std::random_device()();
    std::seed_seq seq{s1, s2};
    std::mt19937 g(seq);
    cout << "10 random points on the ellipsoid with semiaxes [3, 2, 1]\n"
         << "X Y Z beta omega\n" << fixed << setprecision(3);
    Cartesian3::vec3 r;
    Angle bet, omg;
    for (int i = 0; i < 10; ++i) {
      cart.cart2rand(g, r);
      cart.cart2toany(r, Cartesian3::ELLIPSOIDAL, bet, omg);
      cout << r[0] << " " << r[1] << " " << r[2] << " "
           << double(bet) << " " << double(omg) << "\n";
    }
  }
  catch (const exception& e) {
    cerr << "Caught exception: " << e.what() << "\n";
    return 1;
  }
}

Cart3Convert is a command-line utility providing access to the functionality of Cartestian3.

Definition at line 101 of file Cartesian3.hpp.

Member Typedef Documentation

◆ vec3

using GeographicLib::Triaxial::Cartesian3::vec3 = Ellipsoid3::vec3

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

Definition at line 107 of file Cartesian3.hpp.

Member Enumeration Documentation

◆ coord

enum GeographicLib::Triaxial::Cartesian3::coord

Enumerator for all the coordinates.

Enumerator
GEODETIC	Geodetic coordinates, phi, lam, zet h;
PARAMETRIC	Parametric coordinates, phi', lam', zet, h;
GEOCENTRIC	Geocentric coordinates, phi'', lam'', zet, h;
ELLIPSOIDAL	Ellipsoidal coordinates, beta, omg, alp, H;
GEODETIC_X	Geodetic coordinates with pole aligned with the major axis.
PARAMETRIC_X	Parametric coordinates with pole aligned with the major axis.
GEOCENTRIC_X	Geocentric coordinates with pole aligned with the major axis.
PLANETODETIC	An alias for GEODETIC;
GEOGRAPHIC	Another alias for GEODETIC;
PLANETOCENTRIC	An alias for GEOCENTRIC;

Definition at line 192 of file Cartesian3.hpp.

Constructor & Destructor Documentation

◆ Cartesian3() [1/3]

GeographicLib::Triaxial::Cartesian3::Cartesian3 ( const Ellipsoid3 & t )

Constructor for a triaxial ellipsoid defined by Ellipsoid3 object.

Parameters

[in] t the Ellipsoid3 object.

Definition at line 17 of file Cartesian3.cpp.

References t().

Referenced by Cartesian3(), and Cartesian3().

◆ Cartesian3() [2/3]

GeographicLib::Triaxial::Cartesian3::Cartesian3	(	real	a,
		real	b,
		real	c )

Constructor for a triaxial ellipsoid with semiaxes.

Parameters

[in]	a	the largest semiaxis.
[in]	b	the middle semiaxis.
[in]	c	the smallest 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 27 of file Cartesian3.cpp.

References Cartesian3().

◆ Cartesian3() [3/3]

GeographicLib::Triaxial::Cartesian3::Cartesian3	(	real	b,
		real	e2,
		real	k2,
		real	kp2 )

Alternate constructor for a triaxial ellipsoid.

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.

Note: The constructor normalizes k2 and kp2 to ensure then k2 + kp2 = 1.

Definition at line 31 of file Cartesian3.cpp.

References Cartesian3().

Member Function Documentation

◆ anytocart2() [1/4]

void GeographicLib::Triaxial::Cartesian3::anytocart2	(	coord	coordin,
		Angle	lat,
		Angle	lon,
		vec3 &	R ) const

Convert latitude and longitude to a point on the surface.

Parameters

[in]	coordin	one of the coordinate types, Cartesian3::coord.
[in]	lat	the latitude of the point.
[in]	lon	the longitude of the point.
[out]	R	the cartesian position on the surface of the ellipsoid.

Exceptions

GeographicErr if coordin is not recognized.

Definition at line 273 of file Cartesian3.cpp.

References ELLIPSOIDAL, GEOCENTRIC, GEOCENTRIC_X, GEODETIC, GEODETIC_X, PARAMETRIC, and PARAMETRIC_X.

Referenced by anytoany(), anytocart(), anytocart2(), and anytocart2().

◆ anytocart2() [2/4]

void GeographicLib::Triaxial::Cartesian3::anytocart2	(	coord	coordin,
		real	lat,
		real	lon,
		vec3 &	R ) const

inline

Convert latitude and longitude in degrees to a point on the surface.

Parameters

[in]	coordin	one of the coordinate types, Cartesian3::coord.
[in]	lat	the latitude of the point (in degrees).
[in]	lon	the longitude of the point (in degrees).
[out]	R	the cartesian position on the surface of the ellipsoid.

Exceptions

GeographicErr if coordin is not recognized.

Definition at line 306 of file Cartesian3.hpp.

References anytocart2().

◆ cart2toany() [1/4]

void GeographicLib::Triaxial::Cartesian3::cart2toany	(	vec3	R,
		coord	coordout,
		Angle &	lat,
		Angle &	lon ) const

Convert a point on the surface to latitude and longitude.

Parameters

[in]	R	the cartesian position on the surface of the ellipsoid.
[in]	coordout	one of the coordinate types, Cartesian3::coord.
[out]	lat	the latitude of the point.
[out]	lon	the longitude of the point.

Exceptions

GeographicErr if coordout is not recognized.

Definition at line 253 of file Cartesian3.cpp.

References ELLIPSOIDAL, GEOCENTRIC, GEOCENTRIC_X, GEODETIC, GEODETIC_X, PARAMETRIC, and PARAMETRIC_X.

Referenced by anytoany(), cart2toany(), cart2toany(), and carttoany().

◆ cart2toany() [2/4]

void GeographicLib::Triaxial::Cartesian3::cart2toany	(	vec3	R,
		coord	coordout,
		real &	lat,
		real &	lon ) const

inline

Convert a point on the surface to latitude and longitude in degrees.

Parameters

[in]	R	the cartesian position on the surface of the ellipsoid.
[in]	coordout	one of the coordinate types, Cartesian3::coord.
[out]	lat	the latitude of the point (in degrees).
[out]	lon	the longitude of the point (in degrees).

Exceptions

GeographicErr if coordout is not recognized.

Definition at line 328 of file Cartesian3.hpp.

References cart2toany().

◆ anytoany() [1/2]

void GeographicLib::Triaxial::Cartesian3::anytoany	(	coord	coordin,
		Angle	lat1,
		Angle	lon1,
		coord	coordout,
		Angle &	lat2,
		Angle &	lon2 ) const

Convert between latitudes and longitudes.

Parameters

[in]	coordin	one of the coordinate types, Cartesian3::coord.
[in]	lat1	the coordin latitude of the point.
[in]	lon1	the coordin longitude of the point.
[in]	coordout	one of the coordinate types, Cartesian3::coord.
[out]	lat2	the coordout latitude of the point.
[out]	lon2	the coordout longitude of the point.

Exceptions

GeographicErr if coordin or coordout is not recognized.

Definition at line 293 of file Cartesian3.cpp.

References anytocart2(), and cart2toany().

Referenced by anytoany().

◆ anytoany() [2/2]

void GeographicLib::Triaxial::Cartesian3::anytoany	(	coord	coordin,
		real	lat1,
		real	lon1,
		coord	coordout,
		real &	lat2,
		real &	lon2 ) const

inline

Convert between latitudes and longitudes in degrees.

Parameters

[in]	coordin	one of the coordinate types, Cartesian3::coord.
[in]	lat1	the coordin latitude of the point (in degrees).
[in]	lon1	the coordin longitude of the point (in degrees).
[in]	coordout	one of the coordinate types, Cartesian3::coord.
[out]	lat2	the coordout latitude of the point (in degrees).
[out]	lon2	the coordout longitude of the point (in degrees).

Exceptions

GeographicErr if coordin or coordout is not recognized.

Definition at line 356 of file Cartesian3.hpp.

References anytoany().

◆ anytocart2() [3/4]

void GeographicLib::Triaxial::Cartesian3::anytocart2	(	coord	coordin,
		Angle	lat,
		Angle	lon,
		Angle	azi,
		vec3 &	R,
		vec3 &	V ) const

Convert latitude, longitude, and azimuth to cartesian position and direction.

Parameters

[in]	coordin	one of the coordinate types, Cartesian3::coord.
[in]	lat	the latitude of the point.
[in]	lon	the longitude of the point.
[in]	azi	the azimuth of the heading.
[out]	R	the cartesian position on the surface of the ellipsoid.
[out]	V	the cartesian direction tangent to the ellipsoid.

Exceptions

GeographicErr if coordin is not recognized.

Definition at line 320 of file Cartesian3.cpp.

References ELLIPSOIDAL, GEOCENTRIC, GEOCENTRIC_X, GEODETIC, GEODETIC_X, PARAMETRIC, and PARAMETRIC_X.

◆ anytocart2() [4/4]

void GeographicLib::Triaxial::Cartesian3::anytocart2	(	coord	coordin,
		real	lat,
		real	lon,
		real	azi,
		vec3 &	R,
		vec3 &	V ) const

inline

Convert latitude, longitude, and azimuth in degrees to cartesian position and direction.

Parameters

[in]	coordin	one of the coordinate types, Cartesian3::coord.
[in]	lat	the latitude of the point (in degrees).
[in]	lon	the longitude of the point (in degrees).
[in]	azi	the azimuth of the heading (in degrees).
[out]	R	the cartesian position on the surface of the ellipsoid.
[out]	V	the cartesian direction tangent to the ellipsoid.

Exceptions

GeographicErr if coordin is not recognized.

Definition at line 393 of file Cartesian3.hpp.

References anytocart2().

◆ cart2toany() [3/4]

void GeographicLib::Triaxial::Cartesian3::cart2toany	(	vec3	R,
		vec3	V,
		coord	coordout,
		Angle &	lat,
		Angle &	lon,
		Angle &	azi ) const

Convert position and direction on surface to latitude, longitude, and azimuth.

Parameters

[in]	R	the cartesian position on the surface of the ellipsoid.
[in]	V	the cartesian direction tangent to the ellipsoid.
[in]	coordout	one of the coordinate types, Cartesian3::coord.
[out]	lat	the latitude of the point.
[out]	lon	the longitude of the point.
[out]	azi	the azimuth of the heading.

Exceptions

GeographicErr if coordout is not recognized.

Definition at line 300 of file Cartesian3.cpp.

References ELLIPSOIDAL, GEOCENTRIC, GEOCENTRIC_X, GEODETIC, GEODETIC_X, PARAMETRIC, and PARAMETRIC_X.

◆ cart2toany() [4/4]

void GeographicLib::Triaxial::Cartesian3::cart2toany	(	vec3	R,
		vec3	V,
		coord	coordout,
		real &	lat,
		real &	lon,
		real &	azi ) const

inline

Convert position and direction on surface to latitude, longitude, and azimuth in degrees.

Parameters

[in]	R	the cartesian position on the surface of the ellipsoid.
[in]	V	the cartesian direction tangent to the ellipsoid.
[in]	coordout	one of the coordinate types, Cartesian3::coord.
[out]	lat	the latitude of the point (in degrees).
[out]	lon	the longitude of the point (in degrees).
[out]	azi	the azimuth of the heading (in degrees).

Exceptions

GeographicErr if coordout is not recognized.

Definition at line 423 of file Cartesian3.hpp.

References cart2toany().

◆ anytocart() [1/2]

void GeographicLib::Triaxial::Cartesian3::anytocart	(	coord	coordin,
		Angle	lat,
		Angle	lon,
		real	h,
		vec3 &	R ) const

Convert latitude, longitude, and height to a cartesian position.

Parameters

[in]	coordin	one of the coordinate types, Cartesian3::coord.
[in]	lat	the latitude of the point.
[in]	lon	the longitude of the point.
[in]	h	the height (in meters).
[out]	R	the cartesian position of the point.

Exceptions

GeographicErr if coordin is not recognized.

Definition at line 351 of file Cartesian3.cpp.

References anytocart2(), cart2tocart(), and ELLIPSOIDAL.

Referenced by anytocart().

◆ anytocart() [2/2]

void GeographicLib::Triaxial::Cartesian3::anytocart	(	coord	coordin,
		real	lat,
		real	lon,
		real	h,
		vec3 &	R ) const

inline

Convert latitude, longitude in degrees, and height to a cartesian position.

Parameters

[in]	coordin	one of the coordinate types, Cartesian3::coord.
[in]	lat	the latitude of the point (in degrees).
[in]	lon	the longitude of the point (in degrees).
[in]	h	the height (in meters).
[out]	R	the cartesian position of the point.

Exceptions

GeographicErr if coordin is not recognized.

Definition at line 455 of file Cartesian3.hpp.

References anytocart().

◆ carttoany() [1/2]

void GeographicLib::Triaxial::Cartesian3::carttoany	(	vec3	R,
		coord	coordout,
		Angle &	lat,
		Angle &	lon,
		real &	h ) const

Convert a cartesian position to latitude, longitude, and height.

Parameters

[in]	R	the cartesian position of the point.
[in]	coordout	one of the coordinate types, Cartesian3::coord.
[out]	lat	the latitude of the point.
[out]	lon	the longitude of the point.
[out]	h	the height (in meters).

Exceptions

GeographicErr if coordin is not recognized.

Definition at line 340 of file Cartesian3.cpp.

References cart2toany(), carttocart2(), and ELLIPSOIDAL.

Referenced by carttoany().

◆ carttoany() [2/2]

void GeographicLib::Triaxial::Cartesian3::carttoany	(	vec3	R,
		coord	coordout,
		real &	lat,
		real &	lon,
		real &	h ) const

inline

Convert a cartesian position to latitude, longitude in degrees, and height.

Parameters

[in]	R	the cartesian position of the point.
[in]	coordout	one of the coordinate types, Cartesian3::coord.
[out]	lat	the latitude of the point (in degrees).
[out]	lon	the longitude of the point (in degrees).
[out]	h	the height (in meters).

Exceptions

GeographicErr if coordin is not recognized.

Definition at line 481 of file Cartesian3.hpp.

References carttoany().

◆ cart2tocart()

void GeographicLib::Triaxial::Cartesian3::cart2tocart	(	vec3	R2,
		real	h,
		vec3 &	R ) const

Convert a point on the ellipsoid and a height to a cartesian position.

Parameters

[in]	R2	the cartesian position of the point on the ellipsoid.
[in]	h	the height above the ellipsoid (in meters).
[out]	R	the cartesian position of the point.

Definition at line 362 of file Cartesian3.cpp.

References GeographicLib::Math::hypot3().

Referenced by anytocart().

◆ carttocart2()

void GeographicLib::Triaxial::Cartesian3::carttocart2	(	vec3	R,
		vec3 &	R2,
		real &	h ) const

Find the closest point on the ellipsoid

Parameters

[in]	R	the cartesian position of the point.
[out]	R2	the cartesian position of the closest point on the ellipsoid.
[out]	h	the height above the ellipsoid (in meters).

Definition at line 370 of file Cartesian3.cpp.

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

Referenced by carttoany().

◆ cart2rand() [1/2]

template<class G>

void GeographicLib::Triaxial::Cartesian3::cart2rand	(	G &	g,
		vec3 &	R ) const

inline

Generate a random point on the ellipsoid.

Template Parameters

G	the type of the random generator.

Parameters

[in,out]	g	the random generator.
[out]	R	a cartesian position uniformly sampled on the surface of the ellipsoid.

See the example listed in the description of this class for an example of using this function.

The method of sampling is given by Marples and Williams (2023) Algorithm 1, based on the general method of Williamson (1987).

Definition at line 554 of file Cartesian3.hpp.

References GeographicLib::Math::hypot3().

Referenced by cart2rand().

◆ cart2rand() [2/2]

template<class G>

void GeographicLib::Triaxial::Cartesian3::cart2rand	(	G &	g,
		vec3 &	R,
		vec3 &	V ) const

inline

Generate a random point and direction on the ellipsoid.

Template Parameters

G	the type of the random generator.

Parameters

[in,out]	g	the random generator.
[out]	R	a cartesian position uniformly sampled on the surface of the ellipsoid.
[out]	V	a cartesian direction uniformly sampled tangent to the ellipsoid.

Definition at line 572 of file Cartesian3.hpp.

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

◆ t()

const Ellipsoid3 & GeographicLib::Triaxial::Cartesian3::t ( ) const

inline

Returns: the Ellipsoid3 object for this projection.

Definition at line 550 of file Cartesian3.hpp.

Referenced by Cartesian3().

◆ meridianplane()

template<int n>

Angle GeographicLib::Triaxial::Cartesian3::meridianplane	(	ang	lam,
		bool	alt ) const

Definition at line 199 of file Cartesian3.cpp.

References GeographicLib::AngleT< T >::modang().

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

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ vec3

Member Enumeration Documentation

◆ coord

Constructor & Destructor Documentation

◆ Cartesian3() [1/3]

◆ Cartesian3() [2/3]

◆ Cartesian3() [3/3]

Member Function Documentation

◆ anytocart2() [1/4]

◆ anytocart2() [2/4]

◆ cart2toany() [1/4]

◆ cart2toany() [2/4]

◆ anytoany() [1/2]

◆ anytoany() [2/2]

◆ anytocart2() [3/4]

◆ anytocart2() [4/4]

◆ cart2toany() [3/4]

◆ cart2toany() [4/4]

◆ anytocart() [1/2]

◆ anytocart() [2/2]

◆ carttoany() [1/2]

◆ carttoany() [2/2]

◆ cart2tocart()

◆ carttocart2()

◆ cart2rand() [1/2]

◆ cart2rand() [2/2]

◆ t()

◆ meridianplane()