Conversions between auxiliary latitudes. More...

#include <AuxLatitude.hpp>

Public Types
enum	aux { GEOGRAPHIC , PARAMETRIC , GEOCENTRIC , RECTIFYING , CONFORMAL , AUTHALIC , AUXNUMBER , COMMON , GEODETIC , REDUCED }

typedef T	real

typedef AuxAngle< real >	angle

Public Member Functions
	AuxLatitude (real f)

	AuxLatitude (real a, real b)

angle	Convert (int auxin, int auxout, const angle &zeta, bool series=false) const

angle	ToAuxiliary (int auxout, const angle &phi, real *diff=nullptr) const

angle	FromAuxiliary (int auxin, const angle &zeta, int *niter=nullptr) const

real	Flattening () const

Static Public Attributes
static const int	Lmax

Detailed Description

template<typename T = double>
class GeographicLib::AuxLatitude< T >

Conversions between auxiliary latitudes.

Note: This is just sample code. It is not part of GeographicLib itself.

This class is an implementation of the methods described in

C. F. F. Karney, On auxiliary latitudes, Technical Report, SRI International, December 2022. https://arxiv.org/abs/2212.05818

The provides accurate conversions between geographic (phi, φ), parametric (beta, β), geocentric (theta, θ), rectifying (mu, μ), conformal (chi, χ), and authalic (xi, ξ) latitudes for an ellipsoid of revolution. A latitude is represented by an AuxAngle in order to maintain precision close to the poles.

The class implements two methods for the conversion:

Direct evaluation of the defining equations, the exact method. These equations are formulated so as to preserve relative accuracy of the tangent of the latitude, ensuring high accuracy near the equator and the poles. Newton's method is used for those conversions that can't be expressed in closed form.
Expansions in powers of &e n, the third flattening, the series method. This delivers full accuracy for abs(f) ≤ 1/150. Here, f is the flattening of the ellipsoid.

The series method is the preferred method of conversion for any conversion involving μ, χ, or ξ, with abs(f) ≤ 1/150. The equations for the conversions between φ, β, and θ are sufficiently simple that the exact method should be used for such conversions and also for conversions with with abs(f) > 1/150.

Template Parameters

T	the floating-point type to use.

Example of use:

// Example of using the GeographicLib::AuxLatitude class.  See the paper
//
// - C. F. F. Karney,
//   On auxiliary latitudes,
//   Technical Report, SRI International, December 2022.
//   https://arxiv.org/abs/2212.05818
 
#include <iostream>
#include <iomanip>
#include <exception>
#include "AuxLatitude.hpp"
 
using namespace std;
 
int main() {
  try {
    typedef GeographicLib::AuxLatitude<double> latitude;
    typedef latitude::angle angle;
    double a = 2, b = 1;        // Equatorial radius and polar semi-axis
    latitude aux(a, b);
    bool series = false;        // Don't use series method
    int auxin = latitude::GEOGRAPHIC;
    cout << setprecision(9) << fixed;
    for (int l = 0; l <= 90; ++l) {
      angle phi(angle::degrees(l));
      for (int auxout = 0; auxout < latitude::AUXNUMBER; ++auxout) {
        angle eta = aux.Convert(auxin, auxout, phi, series);
        cout << (auxout ? " " : "") << eta.degrees();
      }
      cout << "\n";
    }
  }
  catch (const exception& e) {
    cerr << "Caught exception: " << e.what() << "\n";
    return 1;
  }
}

For more information on this projection, see Auxiliary latitudes.

Definition at line 271 of file AuxLatitude.hpp.

Member Typedef Documentation

◆ real

template<typename T = double>

typedef T GeographicLib::AuxLatitude< T >::real

The floating-point type for real numbers. This just connects to the template parameters for the class.

Definition at line 277 of file AuxLatitude.hpp.

◆ angle

template<typename T = double>

typedef AuxAngle<real> GeographicLib::AuxLatitude< T >::angle

The type used to represent angles.

Definition at line 281 of file AuxLatitude.hpp.

Member Enumeration Documentation

◆ aux

template<typename T = double>

enum GeographicLib::AuxLatitude::aux

The different auxiliary latitudes.

Enumerator
GEOGRAPHIC	Geographic latitude, phi, φ
PARAMETRIC	Parametric latitude, beta, β
GEOCENTRIC	Geocentric latitude, theta, θ
RECTIFYING	Rectifying latitude, mu, μ
CONFORMAL	Conformal latitude, chi, χ
AUTHALIC	Authalic latitude, xi, ξ
AUXNUMBER	The total number of auxiliary latitudes
COMMON	An alias for GEOGRAPHIC
GEODETIC	An alias for GEOGRAPHIC
REDUCED	An alias for PARAMETRIC

Definition at line 285 of file AuxLatitude.hpp.

Constructor & Destructor Documentation

◆ AuxLatitude() [1/2]

template<typename T >

GeographicLib::AuxLatitude< T >::AuxLatitude ( real f )

Constructor

Parameters

[in] f flattening of ellipsoid. Setting f = 0 gives a sphere. Negative f gives a prolate ellipsoid.

Note: the constructor does not precompute the coefficients for the Fourier series for the series conversions. These are computed and saved when first needed.

Definition at line 90 of file AuxLatitude.cpp.

References GeographicLib::AuxLatitude< T >::AUXNUMBER, and GeographicLib::AuxLatitude< T >::Lmax.

◆ AuxLatitude() [2/2]

template<typename T >

GeographicLib::AuxLatitude< T >::AuxLatitude	(	real	a,
		real	b
	)

Constructor

Parameters

[in]	a	equatorial radius.
[in]	b	polar semi-axis.

Note: the constructor does not precompute the coefficients for the Fourier series for the series conversions. These are computed and saved when first needed.

Definition at line 123 of file AuxLatitude.cpp.

References GeographicLib::AuxLatitude< T >::AUXNUMBER, and GeographicLib::AuxLatitude< T >::Lmax.

Member Function Documentation

◆ Convert()

template<typename T >

AuxAngle< T > GeographicLib::AuxLatitude< T >::Convert	(	int	auxin,
		int	auxout,
		const angle &	zeta,
		bool	series = `false`
	)		const

Convert between any two auxiliary latitudes.

Parameters

[in]	auxin	an AuxLatitude::aux indicating the type of auxiliary latitude zeta.
[in]	auxout	an AuxLatitude::aux indicating the type of auxiliary latitude eta.
[in]	zeta	the input auxiliary latitude.
[in]	series	if true use the Taylor series instead of the exact equations [default false].

Returns: the output auxiliary latitude eta.

With series = true, the Fourier coefficients for a specific auxin and auxout are computed and saved on the first call; the saved coefficients are used on subsequent calls. The series method is accurate for abs(f) ≤ 1/150; for other f, the exact method should be used

Definition at line 416 of file AuxLatitude.cpp.

References GeographicLib::AuxAngle< T >::normalized(), GeographicLib::AuxAngle< T >::x(), and GeographicLib::AuxAngle< T >::y().

◆ ToAuxiliary()

template<typename T >

AuxAngle< T > GeographicLib::AuxLatitude< T >::ToAuxiliary	(	int	auxout,
		const angle &	phi,
		real *	diff = `nullptr`
	)		const

Convert geographic latitude to an auxiliary latitude eta.

Parameters

[in]	auxout	an AuxLatitude::aux indicating the auxiliary latitude returned.
[in]	phi	the geographic latitude.
[out]	diff	optional pointer to the derivative d tan(eta) / d tan(phi).

Returns: the auxiliary latitude eta.

This uses the exact equations.

Definition at line 304 of file AuxLatitude.cpp.

◆ FromAuxiliary()

template<typename T >

AuxAngle< T > GeographicLib::AuxLatitude< T >::FromAuxiliary	(	int	auxin,
		const angle &	zeta,
		int *	niter = `nullptr`
	)		const

Convert an auxiliary latitude zeta to geographic latitude.

Parameters

[in]	auxin	an AuxLatitude::aux indicating the type of auxiliary latitude zeta.
[in]	zeta	the input auxiliary latitude.
[out]	niter	optional pointer to the number of iterations.

Returns: the geographic latitude phi.

This uses the exact equations.

Definition at line 321 of file AuxLatitude.cpp.

References GeographicLib::AuxAngle< T >::copyquadrant(), GeographicLib::AuxAngle< T >::tan(), GeographicLib::AuxAngle< T >::x(), and GeographicLib::AuxAngle< T >::y().

◆ Flattening()

template<typename T = double>

real GeographicLib::AuxLatitude< T >::Flattening ( ) const

inline

Returns: f, the flattening of the ellipsoid.

Definition at line 409 of file AuxLatitude.hpp.

Member Data Documentation

◆ Lmax

template<typename T = double>

const int GeographicLib::AuxLatitude< T >::Lmax

static

The order of the series expansions. This is set at compile time to either 4, 6, or 8, by the preprocessor macro GEOGRAPHICLIB_AUXLATITUDE_ORDER.

Definition at line 416 of file AuxLatitude.hpp.

Referenced by GeographicLib::AuxLatitude< T >::AuxLatitude().

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

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

◆ real

◆ angle

Member Enumeration Documentation

◆ aux

Constructor & Destructor Documentation

◆ AuxLatitude() [1/2]

◆ AuxLatitude() [2/2]

Member Function Documentation

◆ Convert()

◆ ToAuxiliary()

◆ FromAuxiliary()

◆ Flattening()

Member Data Documentation

◆ Lmax