GeographicLib::Rhumb Class Reference

Solve of the direct and inverse rhumb problems. More...

#include <Rhumb.hpp>

Public Types
enum	mask {   NONE, LATITUDE, LONGITUDE, AZIMUTH,   DISTANCE, AREA, LONG_UNROLL, ALL }

Public Member Functions
void	Direct (real lat1, real lon1, real azi12, real s12, real &lat2, real &lon2) const
void	Direct (real lat1, real lon1, real azi12, real s12, real &lat2, real &lon2, real &S12) const
void	GenDirect (real lat1, real lon1, real azi12, real s12, unsigned outmask, real &lat2, real &lon2, real &S12) const
void	GenInverse (real lat1, real lon1, real lat2, real lon2, unsigned outmask, real &s12, real &azi12, real &S12) const
void	Inverse (real lat1, real lon1, real lat2, real lon2, real &s12, real &azi12) const
void	Inverse (real lat1, real lon1, real lat2, real lon2, real &s12, real &azi12, real &S12) const
RhumbLine	Line (real lat1, real lon1, real azi12) const
	Rhumb (real a, real f, bool exact=true)

Private Types
typedef Math::real	real

Private Member Functions
real	DConformalToRectifying (real chix, real chiy) const
real	DE (real x, real y) const
real	Deatanhe (real x, real y) const
real	DIsometric (real latx, real laty) const
real	DIsometricToRectifying (real psix, real psiy) const
real	DRectifying (real latx, real laty) const
real	DRectifyingToConformal (real mux, real muy) const
real	DRectifyingToIsometric (real mux, real muy) const
void	GenDirect (real lat1, real lon1, real azi12, bool, real s12, unsigned outmask, real &lat2, real &lon2, real &, real &, real &, real &, real &, real &S12) const
void	GenInverse (real lat1, real lon1, real lat2, real lon2, unsigned outmask, real &s12, real &azi12, real &, real &, real &, real &, real &S12) const
real	MeanSinXi (real psi1, real psi2) const

Static Private Member Functions
static real	Dasinh (real x, real y)
static real	Datan (real x, real y)
static real	Dcosh (real x, real y)
static real	Dgd (real x, real y)
static real	Dgdinv (real x, real y)
static real	Dlog (real x, real y)
static real	Dsin (real x, real y)
static real	Dsinh (real x, real y)
static real	Dtan (real x, real y)
static real	gd (real x)
static real	SinCosSeries (bool sinp, real x, real y, const real c[], int n)

Private Attributes
real	_c2
Ellipsoid	_ell
bool	_exact
real	_R [maxpow_+1]

Static Private Attributes
static const int	maxpow_ = GEOGRAPHICLIB_RHUMBAREA_ORDER
static const int	tm_maxord = GEOGRAPHICLIB_TRANSVERSEMERCATOR_ORDER

Friends
template<class T >
class	PolygonAreaT
class	RhumbLine

Inspector functions.
Math::real	MajorRadius () const
Math::real	Flattening () const
Math::real	EllipsoidArea () const
static const Rhumb &	WGS84 ()

Detailed Description

Solve of the direct and inverse rhumb problems.

The path of constant azimuth between two points on a ellipsoid at (lat1, lon1) and (lat2, lon2) is called the rhumb line (also called the loxodrome). Its length is s12 and its azimuth is azi12. (The azimuth is the heading measured clockwise from north.)

Given lat1, lon1, azi12, and s12, we can determine lat2, and lon2. This is the direct rhumb problem and its solution is given by the function Rhumb::Direct.

Given lat1, lon1, lat2, and lon2, we can determine azi12 and s12. This is the inverse rhumb problem, whose solution is given by Rhumb::Inverse. This finds the shortest such rhumb line, i.e., the one that wraps no more than half way around the earth. If the end points are on opposite meridians, there are two shortest rhumb lines and the east-going one is chosen.

These routines also optionally calculate the area under the rhumb line, S12. This is the area, measured counter-clockwise, of the rhumb line quadrilateral with corners (lat1,lon1), (0,lon1), (0,lon2), and (lat2,lon2).

Note that rhumb lines may be appreciably longer (up to 50%) than the corresponding Geodesic. For example the distance between London Heathrow and Tokyo Narita via the rhumb line is 11400 km which is 18% longer than the geodesic distance 9600 km.

For more information on rhumb lines see rhumb.

Example of use:

// Example of using the GeographicLib::Rhumb class
 
#include <iostream>
#include <exception>
#include <GeographicLib/Rhumb.hpp>
#include <GeographicLib/Constants.hpp>
 
using namespace std;
using namespace GeographicLib;
 
int main() {
  try {
    Rhumb rhumb(Constants::WGS84_a(), Constants::WGS84_f());
    // Alternatively: const Rhumb& rhumb = Rhumb::WGS84();
    {
      // Sample direct calculation, travelling about NE from JFK
      double lat1 = 40.6, lon1 = -73.8, s12 = 5.5e6, azi12 = 51;
      double lat2, lon2;
      rhumb.Direct(lat1, lon1, azi12, s12, lat2, lon2);
      cout << lat2 << " " << lon2 << "\n";
    }
    {
      // Sample inverse calculation, JFK to LHR
      double
        lat1 = 40.6, lon1 = -73.8, // JFK Airport
        lat2 = 51.6, lon2 = -0.5;  // LHR Airport
      double s12, azi12;
      rhumb.Inverse(lat1, lon1, lat2, lon2, s12, azi12);
      cout << s12 << " " << azi12 << "\n";
    }
  }
  catch (const exception& e) {
    cerr << "Caught exception: " << e.what() << "\n";
    return 1;
  }
}

Definition at line 66 of file Rhumb.hpp.

Member Typedef Documentation

real

typedef Math::real GeographicLib::Rhumb::real

private

Definition at line 68 of file Rhumb.hpp.

Member Enumeration Documentation

mask

enum GeographicLib::Rhumb::mask

Bit masks for what calculations to do. They specify which results to return in the general routines Rhumb::GenDirect and Rhumb::GenInverse routines. RhumbLine::mask is a duplication of this enum.

Enumerator
NONE	No output.
LATITUDE	Calculate latitude lat2.
LONGITUDE	Calculate longitude lon2.
AZIMUTH	Calculate azimuth azi12.
DISTANCE	Calculate distance s12.
AREA	Calculate area S12.
LONG_UNROLL	Unroll lon2 in the direct calculation.
ALL	Calculate everything. (LONG_UNROLL is not included in this mask.)

Definition at line 190 of file Rhumb.hpp.

Constructor & Destructor Documentation

Rhumb()

GeographicLib::Rhumb::Rhumb	(	real	a,
		real	f,
		bool	exact = true
	)

Constructor for a 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.
[in]	exact	if true (the default) use an addition theorem for elliptic integrals to compute divided differences; otherwise use series expansion (accurate for |f| < 0.01).

Exceptions

GeographicErr

if a or (1 − f) a is not positive.

See rhumb, for a detailed description of the exact parameter.

Definition at line 18 of file src/Rhumb.cpp.

Member Function Documentation

Dasinh()

static real GeographicLib::Rhumb::Dasinh ( real  x, real  y  )

inlinestaticprivate

Definition at line 126 of file Rhumb.hpp.

Datan()

static real GeographicLib::Rhumb::Datan ( real  x, real  y  )

inlinestaticprivate

Definition at line 104 of file Rhumb.hpp.

DConformalToRectifying()

Math::real GeographicLib::Rhumb::DConformalToRectifying ( real  chix, real  chiy  ) const

private

Definition at line 292 of file src/Rhumb.cpp.

Dcosh()

static real GeographicLib::Rhumb::Dcosh ( real  x, real  y  )

inlinestaticprivate

Definition at line 121 of file Rhumb.hpp.

DE()

Math::real GeographicLib::Rhumb::DE ( real  x, real  y  ) const

private

Definition at line 176 of file src/Rhumb.cpp.

Deatanhe()

real GeographicLib::Rhumb::Deatanhe ( real  x, real  y  ) const

inlineprivate

Definition at line 142 of file Rhumb.hpp.

Dgd()

static real GeographicLib::Rhumb::Dgd ( real  x, real  y  )

inlinestaticprivate

Definition at line 133 of file Rhumb.hpp.

Dgdinv()

static real GeographicLib::Rhumb::Dgdinv ( real  x, real  y  )

inlinestaticprivate

Definition at line 138 of file Rhumb.hpp.

Direct() [1/2]

void GeographicLib::Rhumb::Direct ( real  lat1, real  lon1, real  azi12, real  s12, real &  lat2, real &  lon2  ) const

inline

Solve the direct rhumb problem without the area.

Definition at line 280 of file Rhumb.hpp.

Direct() [2/2]

void GeographicLib::Rhumb::Direct ( real  lat1, real  lon1, real  azi12, real  s12, real &  lat2, real &  lon2, real &  S12  ) const

inline

Solve the direct rhumb problem returning also the area.

Parameters

[in]	lat1	latitude of point 1 (degrees).
[in]	lon1	longitude of point 1 (degrees).
[in]	azi12	azimuth of the rhumb line (degrees).
[in]	s12	distance between point 1 and point 2 (meters); it can be negative.
[out]	lat2	latitude of point 2 (degrees).
[out]	lon2	longitude of point 2 (degrees).
[out]	S12	area under the rhumb line (meters2).

lat1 should be in the range [−90°, 90°]. The value of lon2 returned is in the range [−180°, 180°].

If point 1 is a pole, the cosine of its latitude is taken to be 1/ε² (where ε is 2^-52). This position, which is extremely close to the actual pole, allows the calculation to be carried out in finite terms. If s12 is large enough that the rhumb line crosses a pole, the longitude of point 2 is indeterminate (a NaN is returned for lon2 and S12).

Definition at line 271 of file Rhumb.hpp.

DIsometric()

Math::real GeographicLib::Rhumb::DIsometric ( real  latx, real  laty  ) const

private

Definition at line 213 of file src/Rhumb.cpp.

DIsometricToRectifying()

Math::real GeographicLib::Rhumb::DIsometricToRectifying ( real  psix, real  psiy  ) const

private

Definition at line 302 of file src/Rhumb.cpp.

Dlog()

static real GeographicLib::Rhumb::Dlog ( real  x, real  y  )

inlinestaticprivate

Definition at line 92 of file Rhumb.hpp.

DRectifying()

Math::real GeographicLib::Rhumb::DRectifying ( real  latx, real  laty  ) const

private

Definition at line 205 of file src/Rhumb.cpp.

DRectifyingToConformal()

Math::real GeographicLib::Rhumb::DRectifyingToConformal ( real  mux, real  muy  ) const

private

Definition at line 297 of file src/Rhumb.cpp.

DRectifyingToIsometric()

Math::real GeographicLib::Rhumb::DRectifyingToIsometric ( real  mux, real  muy  ) const

private

Definition at line 315 of file src/Rhumb.cpp.

Dsin()

static real GeographicLib::Rhumb::Dsin ( real  x, real  y  )

inlinestaticprivate

Definition at line 111 of file Rhumb.hpp.

Dsinh()

static real GeographicLib::Rhumb::Dsinh ( real  x, real  y  )

inlinestaticprivate

Definition at line 116 of file Rhumb.hpp.

Dtan()

static real GeographicLib::Rhumb::Dtan ( real  x, real  y  )

inlinestaticprivate

Definition at line 97 of file Rhumb.hpp.

EllipsoidArea()

Math::real GeographicLib::Rhumb::EllipsoidArea ( ) const

inline

Definition at line 410 of file Rhumb.hpp.

Flattening()

Math::real GeographicLib::Rhumb::Flattening ( ) const

inline

Returns

f the flattening of the ellipsoid. This is the value used in the constructor.

Definition at line 408 of file Rhumb.hpp.

gd()

static real GeographicLib::Rhumb::gd ( real  x )

inlinestaticprivate

Definition at line 78 of file Rhumb.hpp.

GenDirect() [1/2]

void GeographicLib::Rhumb::GenDirect ( real  lat1, real  lon1, real  azi12, bool  , real  s12, unsigned  outmask, real &  lat2, real &  lon2, real &  , real &  , real &  , real &  , real &  , real &  S12  ) const

inlineprivate

Definition at line 172 of file Rhumb.hpp.

GenDirect() [2/2]

void GeographicLib::Rhumb::GenDirect	(	real	lat1,
		real	lon1,
		real	azi12,
		real	s12,
		unsigned	outmask,
		real &	lat2,
		real &	lon2,
		real &	S12
	)		const

The general direct rhumb problem. Rhumb::Direct is defined in terms of this function.

Parameters

[in]	lat1	latitude of point 1 (degrees).
[in]	lon1	longitude of point 1 (degrees).
[in]	azi12	azimuth of the rhumb line (degrees).
[in]	s12	distance between point 1 and point 2 (meters); it can be negative.
[in]	outmask	a bitor'ed combination of Rhumb::mask values specifying which of the following parameters should be set.
[out]	lat2	latitude of point 2 (degrees).
[out]	lon2	longitude of point 2 (degrees).
[out]	S12	area under the rhumb line (meters2).

The Rhumb::mask values possible for outmask are

• outmask |= Rhumb::LATITUDE for the latitude lat2;
• outmask |= Rhumb::LONGITUDE for the latitude lon2;
• outmask |= Rhumb::AREA for the area S12;
• outmask |= Rhumb::ALL for all of the above;
• outmask |= Rhumb::LONG_UNROLL to unroll lon2 instead of wrapping it into the range [−180°, 180°].

With the Rhumb::LONG_UNROLL bit set, the quantity lon2 − lon1 indicates how many times and in what sense the rhumb line encircles the ellipsoid.

Definition at line 171 of file src/Rhumb.cpp.

GenInverse() [1/2]

void GeographicLib::Rhumb::GenInverse ( real  lat1, real  lon1, real  lat2, real  lon2, unsigned  outmask, real &  s12, real &  azi12, real &  , real &  , real &  , real &  , real &  S12  ) const

inlineprivate

Definition at line 178 of file Rhumb.hpp.

GenInverse() [2/2]

void GeographicLib::Rhumb::GenInverse	(	real	lat1,
		real	lon1,
		real	lat2,
		real	lon2,
		unsigned	outmask,
		real &	s12,
		real &	azi12,
		real &	S12
	)		const

The general inverse rhumb problem. Rhumb::Inverse is defined in terms of this function.

Parameters

[in]	lat1	latitude of point 1 (degrees).
[in]	lon1	longitude of point 1 (degrees).
[in]	lat2	latitude of point 2 (degrees).
[in]	lon2	longitude of point 2 (degrees).
[in]	outmask	a bitor'ed combination of Rhumb::mask values specifying which of the following parameters should be set.
[out]	s12	rhumb distance between point 1 and point 2 (meters).
[out]	azi12	azimuth of the rhumb line (degrees).
[out]	S12	area under the rhumb line (meters2).

The Rhumb::mask values possible for outmask are

• outmask |= Rhumb::DISTANCE for the latitude s12;
• outmask |= Rhumb::AZIMUTH for the latitude azi12;
• outmask |= Rhumb::AREA for the area S12;
• outmask |= Rhumb::ALL for all of the above;

Definition at line 148 of file src/Rhumb.cpp.

Inverse() [1/2]

void GeographicLib::Rhumb::Inverse ( real  lat1, real  lon1, real  lat2, real  lon2, real &  s12, real &  azi12  ) const

inline

Solve the inverse rhumb problem without the area.

Definition at line 347 of file Rhumb.hpp.

Inverse() [2/2]

void GeographicLib::Rhumb::Inverse ( real  lat1, real  lon1, real  lat2, real  lon2, real &  s12, real &  azi12, real &  S12  ) const

inline

Solve the inverse rhumb problem returning also the area.

Parameters

[in]	lat1	latitude of point 1 (degrees).
[in]	lon1	longitude of point 1 (degrees).
[in]	lat2	latitude of point 2 (degrees).
[in]	lon2	longitude of point 2 (degrees).
[out]	s12	rhumb distance between point 1 and point 2 (meters).
[out]	azi12	azimuth of the rhumb line (degrees).
[out]	S12	area under the rhumb line (meters2).

The shortest rhumb line is found. If the end points are on opposite meridians, there are two shortest rhumb lines and the east-going one is chosen. lat1 and lat2 should be in the range [−90°, 90°]. The value of azi12 returned is in the range [−180°, 180°].

If either point is a pole, the cosine of its latitude is taken to be 1/ε² (where ε is 2^-52). This position, which is extremely close to the actual pole, allows the calculation to be carried out in finite terms.

Definition at line 338 of file Rhumb.hpp.

Line()

RhumbLine GeographicLib::Rhumb::Line	(	real	lat1,
		real	lon1,
		real	azi12
	)		const

Set up to compute several points on a single rhumb line.

Parameters

[in]	lat1	latitude of point 1 (degrees).
[in]	lon1	longitude of point 1 (degrees).
[in]	azi12	azimuth of the rhumb line (degrees).

Returns

a RhumbLine object.

lat1 should be in the range [−90°, 90°].

If point 1 is a pole, the cosine of its latitude is taken to be 1/ε² (where ε is 2^-52). This position, which is extremely close to the actual pole, allows the calculation to be carried out in finite terms.

Definition at line 168 of file src/Rhumb.cpp.

MajorRadius()

Math::real GeographicLib::Rhumb::MajorRadius ( ) const

inline

Returns

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

Definition at line 402 of file Rhumb.hpp.

MeanSinXi()

Math::real GeographicLib::Rhumb::MeanSinXi ( real  psi1, real  psi2  ) const

private

Definition at line 326 of file src/Rhumb.cpp.

SinCosSeries()

Math::real GeographicLib::Rhumb::SinCosSeries ( bool  sinp, real  x, real  y, const real  c[], int  n  )

staticprivate

Definition at line 221 of file src/Rhumb.cpp.

WGS84()

const Rhumb & GeographicLib::Rhumb::WGS84 ( )

static

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

Definition at line 142 of file src/Rhumb.cpp.

Friends And Related Function Documentation

PolygonAreaT

template<class T >

friend class PolygonAreaT

friend

Definition at line 70 of file Rhumb.hpp.

RhumbLine

friend class RhumbLine

friend

Definition at line 69 of file Rhumb.hpp.

Member Data Documentation

_c2

real GeographicLib::Rhumb::_c2

private

Definition at line 73 of file Rhumb.hpp.

_ell

Ellipsoid GeographicLib::Rhumb::_ell

private

Definition at line 71 of file Rhumb.hpp.

_exact

bool GeographicLib::Rhumb::_exact

private

Definition at line 72 of file Rhumb.hpp.

_R

real GeographicLib::Rhumb::_R[maxpow_+1]

private

Definition at line 77 of file Rhumb.hpp.

maxpow_

const int GeographicLib::Rhumb::maxpow_ = GEOGRAPHICLIB_RHUMBAREA_ORDER

staticprivate

Definition at line 75 of file Rhumb.hpp.

tm_maxord

const int GeographicLib::Rhumb::tm_maxord = GEOGRAPHICLIB_TRANSVERSEMERCATOR_ORDER

staticprivate

Definition at line 74 of file Rhumb.hpp.

---

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

• Rhumb.hpp
• src/Rhumb.cpp