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

A geodesic line. More...

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

A geodesic line.

GeodesicLine facilitates the determination of a series of points on a single geodesic. The starting point (lat1, lon1) and the azimuth azi1 are specified in the constructor; alternatively, the Geodesic::Line method can be used to create a GeodesicLine. GeodesicLine.Position returns the location of point 2 a distance s12 along the geodesic. In addition, GeodesicLine.ArcPosition gives the position of point 2 an arc length a12 along the geodesic.

You can register the position of a reference point 3 a distance (arc length), s13 (a13) along the geodesic with the GeodesicLine.SetDistance (GeodesicLine.SetArc) functions. Points a fractional distance along the line can be found by providing, for example, 0.5 * Distance() as an argument to GeodesicLine.Position. The Geodesic::InverseLine or Geodesic::DirectLine methods return GeodesicLine objects with point 3 set to the point 2 of the corresponding geodesic problem. GeodesicLine objects created with the public constructor or with Geodesic::Line have s13 and a13 set to NaNs.

The default copy constructor and assignment operators work with this class. Similarly, a vector can be used to hold GeodesicLine objects.

The calculations are accurate to better than 15 nm (15 nanometers). See Sec. 9 of arXiv:1102.1215v1 for details. With exact = false (the default) in the constructor for the Geodesic object, 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. For very eccentric ellipsoids, set exact = true in the constructor for the Geodesic object; this will delegate the calculations to GeodesicLineExact.

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:

#include

#include

#include

#include

using namespace std;

try {

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

double

lat1 = 40.640, lon1 = -73.779,

lat2 = 1.359, lon2 = 103.989;

GeodesicLine line = geod.InverseLine(lat1, lon1, lat2, lon2);

double ds0 = 500e3;

int num = int(ceil(line.Distance() / ds0));

cout << fixed << setprecision(3);

{

double ds = line.Distance() / num;

for (int i = 0; i <= num; ++i) {

double lat, lon;

line.Position(i * ds, lat, lon);

cout << i << " " << lat << " " << lon << "\n";

}

}

{

double da = line.Arc() / num;

for (int i = 0; i <= num; ++i) {

double lat, lon;

line.ArcPosition(i * da, lat, lon);

cout << i << " " << lat << " " << lon << "\n";

}

}

{

Geodesic geoda(6.4e6, 0.5, true);

GeodesicLine linea = geoda.InverseLine(lat1, lon1, lat2, lon2);

if (! (linea.Init() == lineb.Init() &&

linea.Azimuth() == lineb.Azimuth() &&

linea.Arc() == lineb.Arc()) )

cerr << "Incompatible results compared to GeodesicLineExact\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::GeodesicLine class.

Header for GeographicLib::Geodesic class.

Exact geodesic calculations.

Math::real Flattening() const

Math::real Longitude() const

Math::real EquatorialArc() const

unsigned Capabilities() const

Math::real Latitude() const

Math::real EquatorialAzimuth() const

Math::real Azimuth() const

Math::real Distance() const

Math::real EquatorialRadius() const

unsigned Capabilities() const

Math::real Latitude() const

Math::real Distance() const

Math::real EquatorialAzimuth() const

Math::real Azimuth() const

void ArcPosition(real a12, real &lat2, real &lon2, real &azi2, real &s12, real &m12, real &M12, real &M21, real &S12) const

Math::real Position(real s12, real &lat2, real &lon2, real &azi2, real &m12, real &M12, real &M21, real &S12) const

Math::real EquatorialRadius() const

Math::real Longitude() const

Math::real EquatorialArc() const

Math::real Flattening() const

Namespace for GeographicLib.

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

Definition at line 74 of file GeodesicLine.hpp.

◆ BaseClass

Typedef for the base class implementing geodesics.

Definition at line 198 of file GeodesicLine.hpp.

◆ mask

Bit masks for what calculations to do. They signify to the GeodesicLine::GeodesicLine constructor and to Geodesic::Line what capabilities should be included in the GeodesicLine object. This is merely a duplication of Geodesic::mask.

Definition at line 126 of file GeodesicLine.hpp.

Constructor for a geodesic line staring at latitude lat1, longitude lon1, and azimuth azi1 (all in degrees).

Parameters

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

The GeodesicLine::mask values are

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

The default value of caps is GeodesicLine::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 124 of file GeodesicLine.cpp.

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

◆ GeodesicLine() [2/2]

A default constructor. If GeodesicLine::Position is called on the resulting object, it returns immediately (without doing any calculations). The object can be set with a call to Geodesic::Line. Use Init() to test whether object is still in this uninitialized state.

Definition at line 251 of file GeodesicLine.hpp.

◆ Position() [1/6]

Compute the position of point 2 which is a distance s12 (meters) from point 1.

Parameters

Returns

a12 arc length from point 1 to point 2 (degrees).

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

The GeodesicLine object must have been constructed with caps |= GeodesicLine::DISTANCE_IN; otherwise Math::NaN() is returned and no parameters are set. Requesting a value which the GeodesicLine object is not capable of computing is not an error; the corresponding argument will not be altered.

The following functions are overloaded versions of GeodesicLine::Position 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 297 of file GeodesicLine.hpp.

Referenced by main(), GeographicLib::Gnomonic::Reverse(), and GeographicLib::CassiniSoldner::Reverse().

◆ Position() [2/6]

◆ Position() [3/6]

◆ Position() [4/6]

◆ Position() [5/6]

◆ Position() [6/6]

◆ ArcPosition() [1/7]

Compute the position of point 2 which is an arc length a12 (degrees) from point 1.

Parameters

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

Requesting a value which the GeodesicLine object is not capable of computing is not an error; the corresponding argument will not be altered.

The following functions are overloaded versions of GeodesicLine::ArcPosition which omit some of the output parameters.

Definition at line 410 of file GeodesicLine.hpp.

◆ ArcPosition() [2/7]

◆ ArcPosition() [3/7]

◆ ArcPosition() [4/7]

◆ ArcPosition() [5/7]

◆ ArcPosition() [6/7]

◆ ArcPosition() [7/7]

◆ GenPosition()

The general position function. GeodesicLine::Position and GeodesicLine::ArcPosition are defined in terms of this function.

Parameters

Returns

a12 arc length from point 1 to point 2 (degrees).

The GeodesicLine::mask values possible for outmask are

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

Requesting a value which the GeodesicLine object is not capable of computing is not an error; the corresponding argument will not be altered. Note, however, that the arc length is always computed and returned as the function value.

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

Definition at line 142 of file GeodesicLine.cpp.

References GeographicLib::Math::AngNormalize(), AREA, GeographicLib::Math::atan2d(), AZIMUTH, GeographicLib::Math::degree(), DISTANCE, DISTANCE_IN, GeographicLib::GeodesicLineExact::GenPosition(), GEODESICSCALE, Init(), LATITUDE, LONG_UNROLL, LONGITUDE, GeographicLib::Math::NaN(), REDUCEDLENGTH, GeographicLib::Math::sincosd(), and GeographicLib::Math::sq().

Referenced by GeographicLib::CassiniSoldner::Forward(), main(), SetArc(), and SetDistance().

◆ SetDistance()

Specify position of point 3 in terms of distance.

Parameters

This is only useful if the GeodesicLine object has been constructed with caps |= GeodesicLine::DISTANCE_IN.

Definition at line 311 of file GeodesicLine.cpp.

References GenPosition().

Referenced by GenSetDistance().

◆ SetArc()

◆ GenSetDistance()

Specify position of point 3 in terms of either distance or arc length.

Parameters

Definition at line 327 of file GeodesicLine.cpp.

References SetArc(), and SetDistance().

◆ Init()

◆ Latitude()

◆ Longitude()

◆ Azimuth() [1/2]

Returns

azi1 the azimuth (degrees) of the geodesic line at point 1.

Definition at line 622 of file GeodesicLine.hpp.

Referenced by main().

◆ Azimuth() [2/2]

The sine and cosine of azi1.

Parameters

Definition at line 631 of file GeodesicLine.hpp.

◆ EquatorialAzimuth() [1/2]

◆ EquatorialAzimuth() [2/2]

The sine and cosine of azi0.

Parameters

Definition at line 649 of file GeodesicLine.hpp.

◆ EquatorialArc()

Returns

a1 the arc length (degrees) between the northward equatorial crossing and point 1.

The result lies in [−180°, 180°].

Definition at line 658 of file GeodesicLine.hpp.

◆ EquatorialRadius()

Returns

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

Definition at line 666 of file GeodesicLine.hpp.

◆ Flattening()

Returns

f the flattening of the ellipsoid. This is the value inherited from the Geodesic object used in the constructor.

Definition at line 673 of file GeodesicLine.hpp.

◆ Exact()

Returns

exact whether the exact formulation is used. This is the value returned by the Geodesic object used in the constructor.

Definition at line 680 of file GeodesicLine.hpp.

◆ Capabilities() [1/2]

Returns

caps the computational capabilities that this object was constructed with. LATITUDE and AZIMUTH are always included.

Definition at line 686 of file GeodesicLine.hpp.

◆ Capabilities() [2/2]

Test what capabilities are available.

Parameters

Returns

true if the GeodesicLine object has all these capabilities.

Definition at line 694 of file GeodesicLine.hpp.

◆ GenDistance()

The distance or arc length to point 3.

Parameters

Returns

s13 if arcmode is false; a13 if arcmode is true.

Definition at line 706 of file GeodesicLine.hpp.

Referenced by main().

◆ Distance()

◆ Arc()

Returns

a13, the arc length to point 3 (degrees).

Definition at line 717 of file GeodesicLine.hpp.

◆ Geodesic

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

• GeodesicLine.hpp
• GeodesicLine.cpp