GeographicLib: GeographicLib::Geodesic Class Reference

GeographicLib 2.5

Loading...
Searching...
No Matches
Public Types | Static Public Member Functions | Friends | List of all members
GeographicLib::Geodesic Class Reference

Geodesic calculations More...

`#include <GeographicLib/Geodesic.hpp>`

## Public Types
enum | mask { NONE , LATITUDE , LONGITUDE , AZIMUTH , DISTANCE , STANDARD , DISTANCE_IN , REDUCEDLENGTH , GEODESICSCALE , AREA , LONG_UNROLL , ALL }

## Public Member Functions
Constructor
| Geodesic (real a, real f, bool exact=false)
Direct geodesic problem specified in terms of distance.
Math::real | Direct (real lat1, real lon1, real azi1, real s12, real &lat2, real &lon2, real &azi2, real &m12, real &M12, real &M21, real &S12) const
Math::real | Direct (real lat1, real lon1, real azi1, real s12, real &lat2, real &lon2) const
Math::real | Direct (real lat1, real lon1, real azi1, real s12, real &lat2, real &lon2, real &azi2) const
Math::real | Direct (real lat1, real lon1, real azi1, real s12, real &lat2, real &lon2, real &azi2, real &m12) const
Math::real | Direct (real lat1, real lon1, real azi1, real s12, real &lat2, real &lon2, real &azi2, real &M12, real &M21) const
Math::real | Direct (real lat1, real lon1, real azi1, real s12, real &lat2, real &lon2, real &azi2, real &m12, real &M12, real &M21) const
Direct geodesic problem specified in terms of arc length.
void | ArcDirect (real lat1, real lon1, real azi1, real a12, real &lat2, real &lon2, real &azi2, real &s12, real &m12, real &M12, real &M21, real &S12) const
void | ArcDirect (real lat1, real lon1, real azi1, real a12, real &lat2, real &lon2) const
void | ArcDirect (real lat1, real lon1, real azi1, real a12, real &lat2, real &lon2, real &azi2) const
void | ArcDirect (real lat1, real lon1, real azi1, real a12, real &lat2, real &lon2, real &azi2, real &s12) const
void | ArcDirect (real lat1, real lon1, real azi1, real a12, real &lat2, real &lon2, real &azi2, real &s12, real &m12) const
void | ArcDirect (real lat1, real lon1, real azi1, real a12, real &lat2, real &lon2, real &azi2, real &s12, real &M12, real &M21) const
void | ArcDirect (real lat1, real lon1, real azi1, real a12, real &lat2, real &lon2, real &azi2, real &s12, real &m12, real &M12, real &M21) const
General version of the direct geodesic solution.
Math::real | GenDirect (real lat1, real lon1, real azi1, bool arcmode, real s12_a12, unsigned outmask, real &lat2, real &lon2, real &azi2, real &s12, real &m12, real &M12, real &M21, real &S12) const
Inverse geodesic problem.
Math::real | Inverse (real lat1, real lon1, real lat2, real lon2, real &s12, real &azi1, real &azi2, real &m12, real &M12, real &M21, real &S12) const
Math::real | Inverse (real lat1, real lon1, real lat2, real lon2, real &s12) const
Math::real | Inverse (real lat1, real lon1, real lat2, real lon2, real &azi1, real &azi2) const
Math::real | Inverse (real lat1, real lon1, real lat2, real lon2, real &s12, real &azi1, real &azi2) const
Math::real | Inverse (real lat1, real lon1, real lat2, real lon2, real &s12, real &azi1, real &azi2, real &m12) const
Math::real | Inverse (real lat1, real lon1, real lat2, real lon2, real &s12, real &azi1, real &azi2, real &M12, real &M21) const
Math::real | Inverse (real lat1, real lon1, real lat2, real lon2, real &s12, real &azi1, real &azi2, real &m12, real &M12, real &M21) const
General version of inverse geodesic solution.
Math::real | GenInverse (real lat1, real lon1, real lat2, real lon2, unsigned outmask, real &s12, real &azi1, real &azi2, real &m12, real &M12, real &M21, real &S12) const
Inspector functions.
Math::real | EquatorialRadius () const
Math::real | Flattening () const
bool | Exact () const
Math::real | EllipsoidArea () const

## Static Public Member Functions
static const Geodesic & | WGS84 ()

## Friends
class | GeodesicLine

## Interface to GeodesicLine.
typedef GeodesicLine | LineClass
GeodesicLine | Line (real lat1, real lon1, real azi1, unsigned caps=ALL) const
GeodesicLine | InverseLine (real lat1, real lon1, real lat2, real lon2, unsigned caps=ALL) const
GeodesicLine | DirectLine (real lat1, real lon1, real azi1, real s12, unsigned caps=ALL) const
GeodesicLine | ArcDirectLine (real lat1, real lon1, real azi1, real a12, unsigned caps=ALL) const
GeodesicLine | GenDirectLine (real lat1, real lon1, real azi1, bool arcmode, real s12_a12, unsigned caps=ALL) const

## Detailed Description

Geodesic calculations

The shortest path between two points on an ellipsoid at (lat1, lon1) and (lat2, lon2) is called the geodesic. Its length is s12 and the geodesic from point 1 to point 2 has azimuths azi1 and azi2 at the two end points. (The azimuth is the heading measured clockwise from north. azi2 is the "forward" azimuth, i.e., the heading that takes you beyond point 2 not back to point 1.) In the figure below, latitude is labeled φ, longitude λ (with λ12 = λ2 − λ1), and azimuth α.

Given lat1, lon1, azi1, and s12, we can determine lat2, lon2, and azi2. This is the direct geodesic problem and its solution is given by the function Geodesic::Direct. (If s12 is sufficiently large that the geodesic wraps more than halfway around the earth, there will be another geodesic between the points with a smaller s12.)

Given lat1, lon1, lat2, and lon2, we can determine azi1, azi2, and s12. This is the inverse geodesic problem, whose solution is given by Geodesic::Inverse. Usually, the solution to the inverse problem is unique. In cases where there are multiple solutions (all with the same s12, of course), all the solutions can be easily generated once a particular solution is provided.

The standard way of specifying the direct problem is the specify the distance s12 to the second point. However it is sometimes useful instead to specify the arc length a12 (in degrees) on the auxiliary sphere. This is a mathematical construct used in solving the geodesic problems. The solution of the direct problem in this form is provided by Geodesic::ArcDirect. An arc length in excess of 180° indicates that the geodesic is not a shortest path. In addition, the arc length between an equatorial crossing and the next extremum of latitude for a geodesic is 90°.

This class can also calculate several other quantities related to geodesics. These are:

- reduced length. If we fix the first point and increase azi1 by dazi1 (radians), the second point is displaced m12 dazi1 in the direction azi2 + 90°. The quantity m12 is called the "reduced length" and is symmetric under interchange of the two points. On a curved surface the reduced length obeys a symmetry relation, m12 + m21 = 0. On a flat surface, we have m12 = s12. The ratio s12/m12 gives the azimuthal scale for an azimuthal equidistant projection.
- geodesic scale. Consider a reference geodesic and a second geodesic parallel to this one at point 1 and separated by a small distance dt. The separation of the two geodesics at point 2 is M12 dt where M12 is called the "geodesic scale". M21 is defined similarly (with the geodesics being parallel at point 2). On a flat surface, we have M12 = M21 = 1. The quantity 1/M12 gives the scale of the Cassini-Soldner projection.
- area. The area between the geodesic from point 1 to point 2 and the equation is represented by S12; it is the area, measured counter-clockwise, of the geodesic quadrilateral with corners (lat1,lon1), (0,lon1), (0,lon2), and (lat2,lon2). It can be used to compute the area of any geodesic polygon.

Overloaded versions of Geodesic::Direct, Geodesic::ArcDirect, and Geodesic::Inverse allow these quantities to be returned. In addition there are general functions Geodesic::GenDirect, and Geodesic::GenInverse which allow an arbitrary set of results to be computed. The quantities m12, M12, M21 which all specify the behavior of nearby geodesics obey addition rules. If points 1, 2, and 3 all lie on a single geodesic, then the following rules hold:

- s13 = s12 + s23
- a13 = a12 + a23
- S13 = S12 + S23
- m13 = m12 M23 + m23 M21
- M13 = M12 M23 − (1 − M12 M21) m23 / m12
- M31 = M32 M21 − (1 − M23 M32) m12 / m23

Additional functionality is provided by the GeodesicLine class, which allows a sequence of points along a geodesic to be computed.

The shortest distance returned by the solution of the inverse problem is (obviously) uniquely defined. However, in a few special cases there are multiple azimuths which yield the same shortest distance. Here is a catalog of those cases:

- lat1 = −lat2 (with neither point at a pole). If azi1 = azi2, the geodesic is unique. Otherwise there are two geodesics and the second one is obtained by setting [azi1, azi2] → [azi2, azi1], [M12, M21] → [M21, M12], S12 → −S12. (This occurs when the longitude difference is near ±180° for oblate ellipsoids.)
- lon2 = lon1 ± 180° (with neither point at a pole). If azi1 = 0° or ±180°, the geodesic is unique. Otherwise there are two geodesics and the second one is obtained by setting [azi1, azi2] → [−azi1, −azi2], S12 → −S12. (This occurs when lat2 is near −lat1 for prolate ellipsoids.)
- Points 1 and 2 at opposite poles. There are infinitely many geodesics which can be generated by setting [azi1, azi2] → [azi1, azi2] + [d, −d], for arbitrary d. (For spheres, this prescription applies when points 1 and 2 are antipodal.)
- s12 = 0 (coincident points). There are infinitely many geodesics which can be generated by setting [azi1, azi2] → [azi1, azi2] + [d, d], for arbitrary d.

The calculations are accurate to better than 15 nm (15 nanometers) for the WGS84 ellipsoid. See Sec. 9 of arXiv:1102.1215v1 for details. With exact = false (the default) in the constructor, the algorithms used by this class are based on series expansions using the flattening f as a small parameter. These are only accurate for |f| < 0.02; however reasonably accurate results will be obtained for |f| < 0.2. Here is a table of the approximate maximum error (expressed as a distance) for an ellipsoid with the same equatorial radius as the WGS84 ellipsoid and different values of the flattening.

        |f|      error
        0.01     25 nm
        0.02     30 nm
        0.05     10 um
        0.1     1.5 mm
        0.2     300 mm

For very eccentric ellipsoids, set exact to true in the constructor; this will delegate the calculations to the GeodesicExact class.

The algorithms are described in

- C. F. F. Karney, Algorithms for geodesics, J. Geodesy 87, 43–55 (2013); DOI: 10.1007/s00190-012-0578-z; addenda: geod-addenda.html.

For more information on geodesics see Geodesics on an ellipsoid of revolution.

Example of use:

// Example of using the GeographicLib::Geodesic class
#include <iostream>
#include <exception>
#include <GeographicLib/Geodesic.hpp>
#include <GeographicLib/Constants.hpp>
using namespace std;
using namespace GeographicLib;
int main() {
try {
Geodesic geod(Constants::WGS84_a(), Constants::WGS84_f());
// Alternatively: const Geodesic& geod = Geodesic::WGS84();
{
// Sample direct calculation, travelling about NE from JFK
double lat1 = 40.6, lon1 = -73.8, s12 = 5.5e6, azi1 = 51;
double lat2, lon2;
geod.Direct(lat1, lon1, azi1, 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;
geod.Inverse(lat1, lon1, lat2, lon2, s12);
cout << s12 << "\n";
}
}
catch (const exception& e) {
cerr << "Caught exception: " << e.what() << "\n";
return 1;
}
}
main
int main(int argc, const char *const argv[])
Definition CartConvert.cpp:28
Constants.hpp
Header for GeographicLib::Constants class.
Geodesic.hpp
Header for GeographicLib::Geodesic class.
GeographicLib::Constants::WGS84_f
static T WGS84_f()
Definition Constants.hpp:141
GeographicLib::Constants::WGS84_a
static T WGS84_a()
Definition Constants.hpp:135
GeographicLib::Geodesic::Geodesic
Geodesic(real a, real f, bool exact=false)
Definition Geodesic.cpp:41
GeographicLib
Namespace for GeographicLib.
Definition Accumulator.cpp:12
std
Definition NearestNeighbor.hpp:806

GeodSolve is a command-line utility providing access to the functionality of Geodesic and GeodesicLine.

Definition at line 175 of file Geodesic.hpp.

## Member Typedef Documentation

## ◆ LineClass

typedef GeodesicLine GeographicLib::Geodesic::LineClass

Typedef for the class for computing multiple points on a geodesic.

Definition at line 819 of file Geodesic.hpp.

## Member Enumeration Documentation

## ◆ mask

enum GeographicLib::Geodesic::mask

Bit masks for what calculations to do. These masks do double duty. They signify to the GeodesicLine constructor and to Geodesic::Line what capabilities should be included in the GeodesicLine object. They also specify which results to return in the general routines Geodesic::GenDirect and Geodesic::GenInverse routines. GeodesicLine::mask is a duplication of this enum.

Enumerator
NONE | No capabilities, no output.
LATITUDE | Calculate latitude lat2. (It's not necessary to include this as a capability to GeodesicLine because this is included by default.)
LONGITUDE | Calculate longitude lon2.
AZIMUTH | Calculate azimuths azi1 and azi2. (It's not necessary to include this as a capability to GeodesicLine because this is included by default.)
DISTANCE | Calculate distance s12.
STANDARD | A combination of the common capabilities: Geodesic::LATITUDE, Geodesic::LONGITUDE, Geodesic::AZIMUTH, Geodesic::DISTANCE.
DISTANCE_IN | Allow distance s12 to be used as input in the direct geodesic problem.
REDUCEDLENGTH | Calculate reduced length m12.
GEODESICSCALE | Calculate geodesic scales M12 and M21.
AREA | Calculate area S12.
LONG_UNROLL | Unroll lon2 in the direct calculation.
ALL | All capabilities, calculate everything. (Geodesic::LONG_UNROLL is not included in this mask.)

Definition at line 266 of file Geodesic.hpp.

## Constructor & Destructor Documentation

## ◆ Geodesic()

GeographicLib::Geodesic::Geodesic | ( | 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 exact formulation in terms of elliptic integrals instead of series expansions (default false).

Exceptions

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

With exact = true, this class delegates the calculations to the GeodesicExact and GeodesicLineExact classes which solve the geodesic problems in terms of elliptic integrals.

Definition at line 41 of file Geodesic.cpp.

Referenced by WGS84().

## Member Function Documentation

## ◆ Direct() [1/6]

Math::real GeographicLib::Geodesic::Direct | ( | real | lat1,
|  | real | lon1,
|  | real | azi1,
|  | real | s12,
|  | real & | lat2,
|  | real & | lon2,
|  | real & | azi2,
|  | real & | m12,
|  | real & | M12,
|  | real & | M21,
|  | real & | S12 ) const
| inline

Solve the direct geodesic problem where the length of the geodesic is specified in terms of distance.

Parameters

  [in] | lat1 | latitude of point 1 (degrees).
  [in] | lon1 | longitude of point 1 (degrees).
  [in] | azi1 | azimuth at point 1 (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] | azi2 | (forward) azimuth at point 2 (degrees).
  [out] | m12 | reduced length of geodesic (meters).
  [out] | M12 | geodesic scale of point 2 relative to point 1 (dimensionless).
  [out] | M21 | geodesic scale of point 1 relative to point 2 (dimensionless).
  [out] | S12 | area under the geodesic (meters2).

Returns
  a12 arc length of between point 1 and point 2 (degrees).

lat1 should be in the range [−90°, 90°]. The values of lon2 and azi2 returned are in the range [−180°, 180°].

If either point is at a pole, the azimuth is defined by keeping the longitude fixed, writing lat = ±(90° − ε), and taking the limit ε → 0+. An arc length greater that 180° signifies a geodesic which is not a shortest path. (For a prolate ellipsoid, an additional condition is necessary for a shortest path: the longitudinal extent must not exceed of 180°.)

The following functions are overloaded versions of Geodesic::Direct which omit some of the output parameters. Note, however, that the arc length is always computed and returned as the function value.

Definition at line 394 of file Geodesic.hpp.

References AREA, AZIMUTH, GenDirect(), GEODESICSCALE, LATITUDE, LONGITUDE, and REDUCEDLENGTH.

## ◆ Direct() [2/6]

Math::real GeographicLib::Geodesic::Direct | ( | real | lat1,
|  | real | lon1,
|  | real | azi1,
|  | real | s12,
|  | real & | lat2,
|  | real & | lon2 ) const
| inline

See the documentation for Geodesic::Direct.

Definition at line 408 of file Geodesic.hpp.

References GenDirect(), LATITUDE, and LONGITUDE.

## ◆ Direct() [3/6]

Math::real GeographicLib::Geodesic::Direct | ( | real | lat1,
|  | real | lon1,
|  | real | azi1,
|  | real | s12,
|  | real & | lat2,
|  | real & | lon2,
|  | real & | azi2 ) const
| inline

See the documentation for Geodesic::Direct.

Definition at line 420 of file Geodesic.hpp.

References AZIMUTH, GenDirect(), LATITUDE, and LONGITUDE.

## ◆ Direct() [4/6]

Math::real GeographicLib::Geodesic::Direct | ( | real | lat1,
|  | real | lon1,
|  | real | azi1,
|  | real | s12,
|  | real & | lat2,
|  | real & | lon2,
|  | real & | azi2,
|  | real & | m12 ) const
| inline

See the documentation for Geodesic::Direct.

Definition at line 432 of file Geodesic.hpp.

References AZIMUTH, GenDirect(), LATITUDE, LONGITUDE, and REDUCEDLENGTH.

## ◆ Direct() [5/6]

Math::real GeographicLib::Geodesic::Direct | ( | real | lat1,
|  | real | lon1,
|  | real | azi1,
|  | real | s12,
|  | real & | lat2,
|  | real & | lon2,
|  | real & | azi2,
|  | real & | M12,
|  | real & | M21 ) const
| inline

See the documentation for Geodesic::Direct.

Definition at line 444 of file Geodesic.hpp.

References AZIMUTH, GenDirect(), GEODESICSCALE, LATITUDE, and LONGITUDE.

## ◆ Direct() [6/6]

Math::real GeographicLib::Geodesic::Direct | ( | real | lat1,
|  | real | lon1,
|  | real | azi1,
|  | real | s12,
|  | real & | lat2,
|  | real & | lon2,
|  | real & | azi2,
|  | real & | m12,
|  | real & | M12,
|  | real & | M21 ) const
| inline

See the documentation for Geodesic::Direct.

Definition at line 457 of file Geodesic.hpp.

References AZIMUTH, GenDirect(), GEODESICSCALE, LATITUDE, LONGITUDE, and REDUCEDLENGTH.

## ◆ ArcDirect() [1/7]

void GeographicLib::Geodesic::ArcDirect | ( | real | lat1,
|  | real | lon1,
|  | real | azi1,
|  | real | a12,
|  | real & | lat2,
|  | real & | lon2,
|  | real & | azi2,
|  | real & | s12,
|  | real & | m12,
|  | real & | M12,
|  | real & | M21,
|  | real & | S12 ) const
| inline

Solve the direct geodesic problem where the length of the geodesic is specified in terms of arc length.

Parameters

  [in] | lat1 | latitude of point 1 (degrees).
  [in] | lon1 | longitude of point 1 (degrees).
  [in] | azi1 | azimuth at point 1 (degrees).
  [in] | a12 | arc length between point 1 and point 2 (degrees); it can be negative.
  [out] | lat2 | latitude of point 2 (degrees).
  [out] | lon2 | longitude of point 2 (degrees).
  [out] | azi2 | (forward) azimuth at point 2 (degrees).
  [out] | s12 | distance between point 1 and point 2 (meters).
  [out] | m12 | reduced length of geodesic (meters).
  [out] | M12 | geodesic scale of point 2 relative to point 1 (dimensionless).
  [out] | M21 | geodesic scale of point 1 relative to point 2 (dimensionless).
  [out] | S12 | area under the geodesic (meters2).

lat1 should be in the range [−90°, 90°]. The values of lon2 and azi2 returned are in the range [−180°, 180°].

If either point is at a pole, the azimuth is defined by keeping the longitude fixed, writing lat = ±(90° − ε), and taking the limit ε → 0+. An arc length greater that 180° signifies a geodesic which is not a shortest path. (For a prolate ellipsoid, an additional condition is necessary for a shortest path: the longitudinal extent must not exceed of 180°.)

The following functions are overloaded versions of Geodesic::Direct which omit some of the output parameters.

Definition at line 506 of file Geodesic.hpp.

References AREA, AZIMUTH, DISTANCE, GenDirect(), GEODESICSCALE, LATITUDE, LONGITUDE, and REDUCEDLENGTH.

## ◆ ArcDirect() [2/7]

void GeographicLib::Geodesic::ArcDirect | ( | real | lat1,
|  | real | lon1,
|  | real | azi1,
|  | real | a12,
|  | real & | lat2,
|  | real & | lon2 ) const
| inline

See the documentation for Geodesic::ArcDirect.

Definition at line 519 of file Geodesic.hpp.

References GenDirect(), LATITUDE, and LONGITUDE.

## ◆ ArcDirect() [3/7]

void GeographicLib::Geodesic::ArcDirect | ( | real | lat1,
|  | real | lon1,
|  | real | azi1,
|  | real | a12,
|  | real & | lat2,
|  | real & | lon2,
|  | real & | azi2 ) const
| inline

See the documentation for Geodesic::ArcDirect.

Definition at line 530 of file Geodesic.hpp.

References AZIMUTH, GenDirect(), LATITUDE, and LONGITUDE.

## ◆ ArcDirect() [4/7]

void GeographicLib::Geodesic::ArcDirect | ( | real | lat1,
|  | real | lon1,
|  | real | azi1,
|  | real | a12,
|  | real & | lat2,
|  | real & | lon2,
|  | real & | azi2,
|  | real & | s12 ) const
| inline

See the documentation for Geodesic::ArcDirect.

Definition at line 541 of file Geodesic.hpp.

References AZIMUTH, DISTANCE, GenDirect(), LATITUDE, and LONGITUDE.

## ◆ ArcDirect() [5/7]

void GeographicLib::Geodesic::ArcDirect | ( | real | lat1,
|  | real | lon1,
|  | real | azi1,
|  | real | a12,
|  | real & | lat2,
|  | real & | lon2,
|  | real & | azi2,
|  | real & | s12,
|  | real & | m12 ) const
| inline

See the documentation for Geodesic::ArcDirect.

Definition at line 553 of file Geodesic.hpp.

References AZIMUTH, DISTANCE, GenDirect(), LATITUDE, LONGITUDE, and REDUCEDLENGTH.

## ◆ ArcDirect() [6/7]

void GeographicLib::Geodesic::ArcDirect | ( | real | lat1,
|  | real | lon1,
|  | real | azi1,
|  | real | a12,
|  | real & | lat2,
|  | real & | lon2,
|  | real & | azi2,
|  | real & | s12,
|  | real & | M12,
|  | real & | M21 ) const
| inline

See the documentation for Geodesic::ArcDirect.

Definition at line 566 of file Geodesic.hpp.

References AZIMUTH, DISTANCE, GenDirect(), GEODESICSCALE, LATITUDE, and LONGITUDE.

## ◆ ArcDirect() [7/7]

void GeographicLib::Geodesic::ArcDirect | ( | real | lat1,
|  | real | lon1,
|  | real | azi1,
|  | real | a12,
|  | real & | lat2,
|  | real & | lon2,
|  | real & | azi2,
|  | real & | s12,
|  | real & | m12,
|  | real & | M12,
|  | real & | M21 ) const
| inline

See the documentation for Geodesic::ArcDirect.

Definition at line 579 of file Geodesic.hpp.

References AZIMUTH, DISTANCE, GenDirect(), GEODESICSCALE, LATITUDE, LONGITUDE, and REDUCEDLENGTH.

## ◆ GenDirect()

Math::real GeographicLib::Geodesic::GenDirect | ( | real | lat1,
|  | real | lon1,
|  | real | azi1,
|  | bool | arcmode,
|  | real | s12_a12,
|  | unsigned | outmask,
|  | real & | lat2,
|  | real & | lon2,
|  | real & | azi2,
|  | real & | s12,
|  | real & | m12,
|  | real & | M12,
|  | real & | M21,
|  | real & | S12 ) const

The general direct geodesic problem. Geodesic::Direct and Geodesic::ArcDirect are defined in terms of this function.

Parameters

  [in] | lat1 | latitude of point 1 (degrees).
  [in] | lon1 | longitude of point 1 (degrees).
  [in] | azi1 | azimuth at point 1 (degrees).
  [in] | arcmode | boolean flag determining the meaning of the s12_a12.
  [in] | s12_a12 | if arcmode is false, this is the distance between point 1 and point 2 (meters); otherwise it is the arc length between point 1 and point 2 (degrees); it can be negative.
  [in] | outmask | a bitor'ed combination of Geodesic::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] | azi2 | (forward) azimuth at point 2 (degrees).
  [out] | s12 | distance between point 1 and point 2 (meters).
  [out] | m12 | reduced length of geodesic (meters).
  [out] | M12 | geodesic scale of point 2 relative to point 1 (dimensionless).
  [out] | M21 | geodesic scale of point 1 relative to point 2 (dimensionless).
  [out] | S12 | area under the geodesic (meters2).

Returns
  a12 arc length of between point 1 and point 2 (degrees).

The Geodesic::mask values possible for outmask are

- outmask |= Geodesic::LATITUDE for the latitude lat2;
- outmask |= Geodesic::LONGITUDE for the latitude lon2;
- outmask |= Geodesic::AZIMUTH for the latitude azi2;
- outmask |= Geodesic::DISTANCE for the distance s12;
- outmask |= Geodesic::REDUCEDLENGTH for the reduced length m12;
- outmask |= Geodesic::GEODESICSCALE for the geodesic scales M12 and M21;
- outmask |= Geodesic::AREA for the area S12;
- outmask |= Geodesic::ALL for all of the above;
- outmask |= Geodesic::LONG_UNROLL to unroll lon2 instead of wrapping it into the range [−180°, 180°].

The function value a12 is always computed and returned and this equals s12_a12 is arcmode is true. If outmask includes Geodesic::DISTANCE and arcmode is false, then s12 = s12_a12. It is not necessary to include Geodesic::DISTANCE_IN in outmask; this is automatically included is arcmode is false.

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

Definition at line 128 of file Geodesic.cpp.

References DISTANCE_IN, and GeodesicLine.

Referenced by ArcDirect(), ArcDirect(), ArcDirect(), ArcDirect(), ArcDirect(), ArcDirect(), ArcDirect(), Direct(), Direct(), Direct(), Direct(), Direct(), Direct(), and main().

## ◆ Inverse() [1/7]

Math::real GeographicLib::Geodesic::Inverse | ( | real | lat1,
|  | real | lon1,
|  | real | lat2,
|  | real | lon2,
|  | real & | s12,
|  | real & | azi1,
|  | real & | azi2,
|  | real & | m12,
|  | real & | M12,
|  | real & | M21,
|  | real & | S12 ) const
| inline

Solve the inverse geodesic problem.

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 | distance between point 1 and point 2 (meters).
  [out] | azi1 | azimuth at point 1 (degrees).
  [out] | azi2 | (forward) azimuth at point 2 (degrees).
  [out] | m12 | reduced length of geodesic (meters).
  [out] | M12 | geodesic scale of point 2 relative to point 1 (dimensionless).
  [out] | M21 | geodesic scale of point 1 relative to point 2 (dimensionless).
  [out] | S12 | area under the geodesic (meters2).

Returns
  a12 arc length of between point 1 and point 2 (degrees).

lat1 and lat2 should be in the range [−90°, 90°]. The values of azi1 and azi2 returned are in the range [−180°, 180°].

If either point is at a pole, the azimuth is defined by keeping the longitude fixed, writing lat = ±(90° − ε), and taking the limit ε → 0+.

The solution to the inverse problem is found using Newton's method. If this fails to converge (this is very unlikely in geodetic applications but does occur for very eccentric ellipsoids), then the bisection method is used to refine the solution.

The following functions are overloaded versions of Geodesic::Inverse which omit some of the output parameters. Note, however, that the arc length is always computed and returned as the function value.

Definition at line 689 of file Geodesic.hpp.

References AREA, AZIMUTH, DISTANCE, GEODESICSCALE, and REDUCEDLENGTH.

Referenced by main().

## ◆ Inverse() [2/7]

Math::real GeographicLib::Geodesic::Inverse | ( | real | lat1,
|  | real | lon1,
|  | real | lat2,
|  | real | lon2,
|  | real & | s12 ) const
| inline

See the documentation for Geodesic::Inverse.

Definition at line 701 of file Geodesic.hpp.

References DISTANCE.

## ◆ Inverse() [3/7]

Math::real GeographicLib::Geodesic::Inverse | ( | real | lat1,
|  | real | lon1,
|  | real | lat2,
|  | real | lon2,
|  | real & | azi1,
|  | real & | azi2 ) const
| inline

See the documentation for Geodesic::Inverse.

Definition at line 712 of file Geodesic.hpp.

References AZIMUTH.

## ◆ Inverse() [4/7]

Math::real GeographicLib::Geodesic::Inverse | ( | real | lat1,
|  | real | lon1,
|  | real | lat2,
|  | real | lon2,
|  | real & | s12,
|  | real & | azi1,
|  | real & | azi2 ) const
| inline

See the documentation for Geodesic::Inverse.

Definition at line 723 of file Geodesic.hpp.

References AZIMUTH, and DISTANCE.

## ◆ Inverse() [5/7]

Math::real GeographicLib::Geodesic::Inverse | ( | real | lat1,
|  | real | lon1,
|  | real | lat2,
|  | real | lon2,
|  | real & | s12,
|  | real & | azi1,
|  | real & | azi2,
|  | real & | m12 ) const
| inline

See the documentation for Geodesic::Inverse.

Definition at line 735 of file Geodesic.hpp.

References AZIMUTH, DISTANCE, and REDUCEDLENGTH.

## ◆ Inverse() [6/7]

Math::real GeographicLib::Geodesic::Inverse | ( | real | lat1,
|  | real | lon1,
|  | real | lat2,
|  | real | lon2,
|  | real & | s12,
|  | real & | azi1,
|  | real & | azi2,
|  | real & | M12,
|  | real & | M21 ) const
| inline

See the documentation for Geodesic::Inverse.

Definition at line 747 of file Geodesic.hpp.

References AZIMUTH, DISTANCE, and GEODESICSCALE.

## ◆ Inverse() [7/7]

Math::real GeographicLib::Geodesic::Inverse | ( | real | lat1,
|  | real | lon1,
|  | real | lat2,
|  | real | lon2,
|  | real & | s12,
|  | real & | azi1,
|  | real & | azi2,
|  | real & | m12,
|  | real & | M12,
|  | real & | M21 ) const
| inline

See the documentation for Geodesic::Inverse.

Definition at line 759 of file Geodesic.hpp.

References AZIMUTH, DISTANCE, GEODESICSCALE, and REDUCEDLENGTH.

## ◆ GenInverse()

Math::real GeographicLib::Geodesic::GenInverse | ( | real | lat1,
|  | real | lon1,
|  | real | lat2,
|  | real | lon2,
|  | unsigned | outmask,
|  | real & | s12,
|  | real & | azi1,
|  | real & | azi2,
|  | real & | m12,
|  | real & | M12,
|  | real & | M21,
|  | real & | S12 ) const

The general inverse geodesic calculation. Geodesic::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 Geodesic::mask values specifying which of the following parameters should be set.
  [out] | s12 | distance between point 1 and point 2 (meters).
  [out] | azi1 | azimuth at point 1 (degrees).
  [out] | azi2 | (forward) azimuth at point 2 (degrees).
  [out] | m12 | reduced length of geodesic (meters).
  [out] | M12 | geodesic scale of point 2 relative to point 1 (dimensionless).
  [out] | M21 | geodesic scale of point 1 relative to point 2 (dimensionless).
  [out] | S12 | area under the geodesic (meters2).

Returns
  a12 arc length of between point 1 and point 2 (degrees).

The Geodesic::mask values possible for outmask are

- outmask |= Geodesic::DISTANCE for the distance s12;
- outmask |= Geodesic::AZIMUTH for the latitude azi2;
- outmask |= Geodesic::REDUCEDLENGTH for the reduced length m12;
- outmask |= Geodesic::GEODESICSCALE for the geodesic scales M12 and M21;
- outmask |= Geodesic::AREA for the area S12;
- outmask |= Geodesic::ALL for all of the above.

The arc length is always computed and returned as the function value.

Definition at line 515 of file Geodesic.cpp.

References GeographicLib::Math::atan2d(), and AZIMUTH.

## ◆ Line()

GeodesicLine GeographicLib::Geodesic::Line | ( | real | lat1,
|  | real | lon1,
|  | real | azi1,
|  | unsigned | caps = ALL ) const

Set up to compute several points on a single geodesic.

Parameters

  [in] | lat1 | latitude of point 1 (degrees).
  [in] | lon1 | longitude of point 1 (degrees).
  [in] | azi1 | azimuth at point 1 (degrees).
  [in] | caps | bitor'ed combination of Geodesic::mask values specifying the capabilities the GeodesicLine object should possess, i.e., which quantities can be returned in calls to GeodesicLine::Position.

Returns
  a GeodesicLine object.

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

The Geodesic::mask values are

- caps |= Geodesic::LATITUDE for the latitude lat2; this is added automatically;
- caps |= Geodesic::LONGITUDE for the latitude lon2;
- caps |= Geodesic::AZIMUTH for the azimuth azi2; this is added automatically;
- caps |= Geodesic::DISTANCE for the distance s12;
- caps |= Geodesic::REDUCEDLENGTH for the reduced length m12;
- caps |= Geodesic::GEODESICSCALE for the geodesic scales M12 and M21;
- caps |= Geodesic::AREA for the area S12;
- caps |= Geodesic::DISTANCE_IN permits the length of the geodesic to be given in terms of s12; without this capability the length can only be specified in terms of arc length;
- caps |= Geodesic::ALL for all of the above.

The default value of caps is Geodesic::ALL.

If the point is at a pole, the azimuth is defined by keeping lon1 fixed, writing lat1 = ±(90 − ε), and taking the limit ε → 0+.

Definition at line 123 of file Geodesic.cpp.

References GeodesicLine.

Referenced by main().

## ◆ InverseLine()

GeodesicLine GeographicLib::Geodesic::InverseLine | ( | real | lat1,
|  | real | lon1,
|  | real | lat2,
|  | real | lon2,
|  | unsigned | caps = ALL ) const

Define a GeodesicLine in terms of the inverse geodesic problem.

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] | caps | bitor'ed combination of Geodesic::mask values specifying the capabilities the GeodesicLine object should possess, i.e., which quantities can be returned in calls to GeodesicLine::Position.

Returns
  a GeodesicLine object.

This function sets point 3 of the GeodesicLine to correspond to point 2 of the inverse geodesic problem.

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

Definition at line 532 of file Geodesic.cpp.

References GeographicLib::Math::atan2d(), DISTANCE, DISTANCE_IN, and GeodesicLine.

Referenced by main().

## ◆ DirectLine()

GeodesicLine GeographicLib::Geodesic::DirectLine | ( | real | lat1,
|  | real | lon1,
|  | real | azi1,
|  | real | s12,
|  | unsigned | caps = ALL ) const

Define a GeodesicLine in terms of the direct geodesic problem specified in terms of distance.

Parameters

  [in] | lat1 | latitude of point 1 (degrees).
  [in] | lon1 | longitude of point 1 (degrees).
  [in] | azi1 | azimuth at point 1 (degrees).
  [in] | s12 | distance between point 1 and point 2 (meters); it can be negative.
  [in] | caps | bitor'ed combination of Geodesic::mask values specifying the capabilities the GeodesicLine object should possess, i.e., which quantities can be returned in calls to GeodesicLine::Position.

Returns
  a GeodesicLine object.

This function sets point 3 of the GeodesicLine to correspond to point 2 of the direct geodesic problem.

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

Definition at line 158 of file Geodesic.cpp.

References GenDirectLine(), and GeodesicLine.

## ◆ ArcDirectLine()

GeodesicLine GeographicLib::Geodesic::ArcDirectLine | ( | real | lat1,
|  | real | lon1,
|  | real | azi1,
|  | real | a12,
|  | unsigned | caps = ALL ) const

Define a GeodesicLine in terms of the direct geodesic problem specified in terms of arc length.

Parameters

  [in] | lat1 | latitude of point 1 (degrees).
  [in] | lon1 | longitude of point 1 (degrees).
  [in] | azi1 | azimuth at point 1 (degrees).
  [in] | a12 | arc length between point 1 and point 2 (degrees); it can be negative.
  [in] | caps | bitor'ed combination of Geodesic::mask values specifying the capabilities the GeodesicLine object should possess, i.e., which quantities can be returned in calls to GeodesicLine::Position.

Returns
  a GeodesicLine object.

This function sets point 3 of the GeodesicLine to correspond to point 2 of the direct geodesic problem.

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

Definition at line 163 of file Geodesic.cpp.

References GenDirectLine(), and GeodesicLine.

## ◆ GenDirectLine()

GeodesicLine GeographicLib::Geodesic::GenDirectLine | ( | real | lat1,
|  | real | lon1,
|  | real | azi1,
|  | bool | arcmode,
|  | real | s12_a12,
|  | unsigned | caps = ALL ) const

Define a GeodesicLine in terms of the direct geodesic problem specified in terms of either distance or arc length.

Parameters

  [in] | lat1 | latitude of point 1 (degrees).
  [in] | lon1 | longitude of point 1 (degrees).
  [in] | azi1 | azimuth at point 1 (degrees).
  [in] | arcmode | boolean flag determining the meaning of the s12_a12.
  [in] | s12_a12 | if arcmode is false, this is the distance between point 1 and point 2 (meters); otherwise it is the arc length between point 1 and point 2 (degrees); it can be negative.
  [in] | caps | bitor'ed combination of Geodesic::mask values specifying the capabilities the GeodesicLine object should possess, i.e., which quantities can be returned in calls to GeodesicLine::Position.

Returns
  a GeodesicLine object.

This function sets point 3 of the GeodesicLine to correspond to point 2 of the direct geodesic problem.

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

Definition at line 145 of file Geodesic.cpp.

References GeographicLib::Math::AngNormalize(), GeographicLib::Math::AngRound(), DISTANCE_IN, GeodesicLine, and GeographicLib::Math::sincosd().

Referenced by ArcDirectLine(), DirectLine(), and main().

## ◆ EquatorialRadius()

Math::real GeographicLib::Geodesic::EquatorialRadius | ( |  | ) | const
| inline

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

Definition at line 963 of file Geodesic.hpp.

## ◆ Flattening()

Math::real GeographicLib::Geodesic::Flattening | ( |  | ) | const
| inline

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

Definition at line 969 of file Geodesic.hpp.

## ◆ Exact()

bool GeographicLib::Geodesic::Exact | ( |  | ) | const
| inline

Returns
  exact whether the exact formulation is used. This is the value used in the constructor.

Definition at line 975 of file Geodesic.hpp.

## ◆ EllipsoidArea()

Math::real GeographicLib::Geodesic::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 983 of file Geodesic.hpp.

References GeographicLib::Math::pi().

## ◆ WGS84()

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

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

Definition at line 94 of file Geodesic.cpp.

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

## Friends And Related Symbol Documentation

## ◆ GeodesicLine

friend class GeodesicLine
| friend

Definition at line 178 of file Geodesic.hpp.

References GeodesicLine, and GEOGRAPHICLIB_GEODESIC_ORDER.

Referenced by ArcDirectLine(), DirectLine(), GenDirect(), GenDirectLine(), GeodesicLine, InverseLine(), and Line().

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

- Geodesic.hpp
- Geodesic.cpp