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

#include <GeographicLib/Rhumb.hpp>

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

Public Member Functions
	Rhumb (real a, real f, bool exact=true)

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

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

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

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

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

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

RhumbLine	Line (real lat1, real lon1, real azi12) const

Inspector functions.
Math::real	EquatorialRadius () const

Math::real	Flattening () const

Math::real	EllipsoidArea () const

Static Public Member Functions
static const Rhumb &	WGS84 ()

Friends
class	RhumbLine

template<class T >
class	PolygonAreaT

Detailed Description

Solve of the direct and inverse rhumb problems.

The path of constant azimuth between two points on an 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 lines.

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 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 204 of file Rhumb.hpp.

Constructor & Destructor Documentation

◆ Rhumb()

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

Constructor for an 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 lines, for a detailed description of the exact parameter.

Definition at line 23 of file Rhumb.cpp.

References GeographicLib::Math::polyval().

Member Function Documentation

◆ Direct() [1/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 (meters²).

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 285 of file Rhumb.hpp.

Referenced by main().

◆ Direct() [2/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 294 of file Rhumb.hpp.

◆ GenDirect()

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 (meters²).

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 176 of file Rhumb.cpp.

References GeographicLib::RhumbLine::GenPosition(), and Line().

◆ Inverse() [1/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 (meters²).

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 352 of file Rhumb.hpp.

Referenced by main().

◆ Inverse() [2/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 361 of file Rhumb.hpp.

◆ GenInverse()

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 (meters²).

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 153 of file Rhumb.cpp.

References GeographicLib::Math::AngDiff(), AREA, GeographicLib::Math::atan2d(), AZIMUTH, GeographicLib::Math::degree(), DISTANCE, GeographicLib::Ellipsoid::IsometricLatitude(), GeographicLib::Math::qd, and GeographicLib::Ellipsoid::QuarterMeridian().

◆ 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 173 of file Rhumb.cpp.

References RhumbLine.

Referenced by GenDirect(), and main().

◆ EquatorialRadius()

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

inline

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

Definition at line 416 of file Rhumb.hpp.

References GeographicLib::Ellipsoid::EquatorialRadius().

Referenced by GeographicLib::RhumbLine::EquatorialRadius().

◆ 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 422 of file Rhumb.hpp.

References GeographicLib::Ellipsoid::Flattening().

Referenced by GeographicLib::RhumbLine::Flattening().

◆ EllipsoidArea()

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

inline

Returns: total area of ellipsoid in meters². The area of a polygon encircling a pole can be found by adding Geodesic::EllipsoidArea()/2 to the sum of S12 for each side of the polygon.

Definition at line 430 of file Rhumb.hpp.

References GeographicLib::Ellipsoid::Area().

◆ WGS84()

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

static

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

Definition at line 147 of file Rhumb.cpp.

References GeographicLib::Constants::WGS84_a(), and GeographicLib::Constants::WGS84_f().

Friends And Related Function Documentation

◆ RhumbLine

friend class RhumbLine

friend

Definition at line 69 of file Rhumb.hpp.

Referenced by Line().

◆ PolygonAreaT

template<class T >

friend class PolygonAreaT

friend

Definition at line 70 of file Rhumb.hpp.

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

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ mask

Constructor & Destructor Documentation

◆ Rhumb()

Member Function Documentation

◆ Direct() [1/2]

◆ Direct() [2/2]

◆ GenDirect()

◆ Inverse() [1/2]

◆ Inverse() [2/2]

◆ GenInverse()

◆ Line()

◆ EquatorialRadius()

◆ Flattening()

◆ EllipsoidArea()

◆ WGS84()

Friends And Related Function Documentation

◆ RhumbLine

◆ PolygonAreaT