GeographicLib: GeographicLib::GeodesicExact Class Reference (original) (raw)

Exact geodesic calculations. More...

#include <[GeographicLib/GeodesicExact.hpp](GeodesicExact%5F8hpp%5Fsource.html)>

Exact geodesic calculations.

The equations for geodesics on an ellipsoid can be expressed in terms of incomplete elliptic integrals. The Geodesic class expands these integrals in a series in the flattening f and this provides an accurate solution for f ∈ [-0.01, 0.01]. The GeodesicExact class computes the ellitpic integrals directly and so provides a solution which is valid for all f. However, in practice, its use should be limited to about b/a ∈ [0.01, 100] or f ∈ [−99, 0.99].

For the WGS84 ellipsoid, these classes are 2–3 times slower than the series solution and 2–3 times less accurate (because it's less easy to control round-off errors with the elliptic integral formulation); i.e., the error is about 40 nm (40 nanometers) instead of 15 nm. However the error in the series solution scales as _f_7 while the error in the elliptic integral solution depends weakly on f. If the quarter meridian distance is 10000 km and the ratio b/a = 1 − f is varied then the approximate maximum error (expressed as a distance) is

  1 - f  error (nm)
  1/128     387
  1/64      345
  1/32      269
  1/16      210
  1/8       115
  1/4        69
  1/2        36
    1        15
    2        25
    4        96
    8       318
   16       985
   32      2352
   64      6008
  128     19024

The area in this classes is computing by finding an accurate approximation to the area integrand using a discrete sine transform fitting N equally spaced points in σ. N chosen to ensure full accuracy for b/a ∈ [0.01, 100] or f ∈ [−99, 0.99].

The algorithms are described in

• C. F. F. Karney, Geodesics on an arbitrary ellipsoid of revolution, J. Geodesy 98, 4:1–14 (2024); DOI: 10.1007/s00190-023-01813-2.

See Geodesics in terms of elliptic integrals for the formulation. See the documentation on the Geodesic class for additional information on the geodesic problems.

Example of use:

#include

#include

using namespace std;

try {

GeodesicExact geod(Constants::WGS84_a(), Constants::WGS84_f());

{

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";

}

{

double

lat1 = 40.6, lon1 = -73.8,

lat2 = 51.6, lon2 = -0.5;

double s12;

geod.Inverse(lat1, lon1, lat2, lon2, s12);

cout << s12 << "\n";

}

}

catch (const exception& e) {

cerr << "Caught exception: " << e.what() << "\n";

return 1;

}

}

int main(int argc, const char *const argv[])

Header for GeographicLib::Constants class.

Header for GeographicLib::GeodesicExact class.

Exact geodesic calculations.

Namespace for GeographicLib.

GeodSolve is a command-line utility providing access to the functionality of GeodesicExact and GeodesicLineExact (via the -E option).

Definition at line 85 of file GeodesicExact.hpp.

◆ LineClass

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

Definition at line 707 of file GeodesicExact.hpp.

◆ mask

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

Definition at line 163 of file GeodesicExact.hpp.

◆ Direct() [1/6]

Perform the direct geodesic calculation where the length of the geodesic is specified in terms of distance.

Parameters

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 GeodesicExact::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 286 of file GeodesicExact.hpp.

◆ Direct() [2/6]

◆ Direct() [3/6]

◆ Direct() [4/6]

◆ Direct() [5/6]

◆ Direct() [6/6]

◆ ArcDirect() [1/7]

Perform the direct geodesic calculation where the length of the geodesic is specified in terms of arc length.

Parameters

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 GeodesicExact::Direct which omit some of the output parameters.

Definition at line 398 of file GeodesicExact.hpp.

◆ ArcDirect() [2/7]

◆ ArcDirect() [3/7]

◆ ArcDirect() [4/7]

◆ ArcDirect() [5/7]

◆ ArcDirect() [6/7]

◆ ArcDirect() [7/7]

◆ GenDirect()

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

Parameters

Returns

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

The GeodesicExact::mask values possible for outmask are

• outmask |= GeodesicExact::LATITUDE for the latitude lat2;
• outmask |= GeodesicExact::LONGITUDE for the latitude lon2;
• outmask |= GeodesicExact::AZIMUTH for the latitude azi2;
• outmask |= GeodesicExact::DISTANCE for the distance s12;
• outmask |= GeodesicExact::REDUCEDLENGTH for the reduced length m12;
• outmask |= GeodesicExact::GEODESICSCALE for the geodesic scales M12 and M21;
• outmask |= GeodesicExact::AREA for the area S12;
• outmask |= GeodesicExact::ALL for all of the above;
• outmask |= GeodesicExact::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 GeodesicExact::DISTANCE and arcmode is false, then s12 = s12_a12. It is not necessary to include GeodesicExact::DISTANCE_IN in outmask; this is automatically included is arcmode is false.

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

Definition at line 402 of file GeodesicExact.cpp.

References DISTANCE_IN, and GeodesicLineExact.

Referenced by GeographicLib::Geodesic::GenDirect().

◆ Inverse() [1/7]

Perform the inverse geodesic calculation.

Parameters

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 following functions are overloaded versions of GeodesicExact::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 577 of file GeodesicExact.hpp.

◆ Inverse() [2/7]

◆ Inverse() [3/7]

◆ Inverse() [4/7]

◆ Inverse() [5/7]

◆ Inverse() [6/7]

◆ Inverse() [7/7]

◆ GenInverse()

The general inverse geodesic calculation. GeodesicExact::Inverse is defined in terms of this function.

Parameters

Returns

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

The GeodesicExact::mask values possible for outmask are

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

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

Definition at line 800 of file GeodesicExact.cpp.

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

◆ Line()

Set up to compute several points on a single geodesic.

Parameters

Returns

a GeodesicLineExact object.

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

The GeodesicExact::mask values are

• caps |= GeodesicExact::LATITUDE for the latitude lat2; this is added automatically;
• caps |= GeodesicExact::LONGITUDE for the latitude lon2;
• caps |= GeodesicExact::AZIMUTH for the azimuth azi2; this is added automatically;
• caps |= GeodesicExact::DISTANCE for the distance s12;
• caps |= GeodesicExact::REDUCEDLENGTH for the reduced length m12;
• caps |= GeodesicExact::GEODESICSCALE for the geodesic scales M12 and M21;
• caps |= GeodesicExact::AREA for the area S12;
• caps |= GeodesicExact::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 |= GeodesicExact::ALL for all of the above.

The default value of caps is GeodesicExact::ALL which turns on all the capabilities.

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 397 of file GeodesicExact.cpp.

References GeodesicLineExact.

◆ InverseLine()

◆ DirectLine()

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

Parameters

Returns

a GeodesicLineExact object.

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

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

Definition at line 431 of file GeodesicExact.cpp.

References GenDirectLine().

◆ ArcDirectLine()

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

Parameters

Returns

a GeodesicLineExact object.

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

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

Definition at line 437 of file GeodesicExact.cpp.

References GenDirectLine().

◆ GenDirectLine()

◆ EquatorialRadius()

Returns

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

Definition at line 852 of file GeodesicExact.hpp.

◆ Flattening()

Returns

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

Definition at line 858 of file GeodesicExact.hpp.

◆ EllipsoidArea()

Returns

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

Definition at line 866 of file GeodesicExact.hpp.

◆ WGS84()

◆ GeodesicLineExact

◆ Geodesic

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

• GeodesicExact.hpp
• GeodesicExact.cpp