GeographicLib: GeographicLib::Rhumb Class Reference

GeographicLib 2.7

Loading...
Searching...
No Matches
GeographicLib::Rhumb Class Reference

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 }
typedef RhumbLine | LineClass

## Public Member Functions
| Rhumb (real a, real f, bool exact=false)
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 counterclockwise, 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.

This implementation is described in

- C. F. F. Karney,
  The area of rhumb polygons,
  Stud. Geophys. Geod. 68(3–4), 99–120 (2024); DOI: 10.1007/s11200-024-0709-z.

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;
}
}
main
int main(int argc, const char *const argv[])
Definition Cart3Convert.cpp:52
Constants.hpp
Header for GeographicLib::Constants class.
Rhumb.hpp
Header for GeographicLib::Rhumb and GeographicLib::RhumbLine classes.
GeographicLib::Constants::WGS84_f
static T WGS84_f()
Definition Constants.hpp:118
GeographicLib::Constants::WGS84_a
static T WGS84_a()
Definition Constants.hpp:112
GeographicLib::Rhumb::Rhumb
Rhumb(real a, real f, bool exact=false)
Definition Rhumb.cpp:18
GeographicLib
Namespace for GeographicLib.
Definition Accumulator.cpp:12
std
Definition NearestNeighbor.hpp:806

Definition at line 80 of file Rhumb.hpp.

## Member Typedef Documentation

## ◆ LineClass

typedef RhumbLine GeographicLib::Rhumb::LineClass

Typedef for the class for computing multiple points on a rhumb line.

Definition at line 310 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 122 of file Rhumb.hpp.

## Constructor & Destructor Documentation

## ◆ Rhumb()

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

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 use the exact expressions for the auxiliary latitudes; otherwise use series expansion (accurate for |f| < 0.01) [default false].

Exceptions

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

Definition at line 18 of file Rhumb.cpp.

Referenced by WGS84().

## 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 (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/ε2 (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 201 of file Rhumb.hpp.

References AREA, LATITUDE, and LONGITUDE.

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

References LATITUDE, and LONGITUDE.

## ◆ 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 (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 242 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 (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/ε2 (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 268 of file Rhumb.hpp.

References AREA, AZIMUTH, and DISTANCE.

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

References AZIMUTH, and DISTANCE.

## ◆ 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 (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 205 of file Rhumb.cpp.

References GeographicLib::Math::AngDiff(), AREA, GeographicLib::Math::atan2d(), AZIMUTH, GeographicLib::AuxLatitude::CHI, GeographicLib::Math::degree(), GeographicLib::AuxAngle::degrees(), DISTANCE, GeographicLib::DAuxLatitude::Dlam(), GeographicLib::AuxAngle::lam(), GeographicLib::AuxLatitude::MU, GeographicLib::AuxLatitude::PHI, and GeographicLib::AuxAngle::tan().

## ◆ 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/ε2 (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 239 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 337 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 343 of file Rhumb.hpp.

## ◆ EllipsoidArea()

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

Returns
  total area of ellipsoid in meters2. 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 351 of file Rhumb.hpp.

References GeographicLib::Math::td.

## ◆ WGS84()

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

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

Definition at line 32 of file Rhumb.cpp.

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

## Friends And Related Symbol Documentation

## ◆ RhumbLine

friend class RhumbLine
| friend

Definition at line 83 of file Rhumb.hpp.

References RhumbLine.

Referenced by Line(), and RhumbLine.

## ◆ PolygonAreaT

template<class T>

friend class PolygonAreaT
| friend

Definition at line 84 of file Rhumb.hpp.

References GEOGRAPHICLIB_RHUMBAREA_ORDER, and PolygonAreaT.

Referenced by PolygonAreaT.

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

- Rhumb.hpp
- Rhumb.cpp