GeographicLib
1.49

A geodesic line. More...
#include <GeographicLib/GeodesicLine.hpp>
Public Types  
enum  mask { NONE, LATITUDE, LONGITUDE, AZIMUTH, DISTANCE, DISTANCE_IN, REDUCEDLENGTH, GEODESICSCALE, AREA, LONG_UNROLL, ALL } 
Public Member Functions  
Constructors  
GeodesicLine (const Geodesic &g, real lat1, real lon1, real azi1, unsigned caps=ALL)  
GeodesicLine ()  
Position in terms of distance  
Math::real  Position (real s12, real &lat2, real &lon2, real &azi2, real &m12, real &M12, real &M21, real &S12) const 
Math::real  Position (real s12, real &lat2, real &lon2) const 
Math::real  Position (real s12, real &lat2, real &lon2, real &azi2) const 
Math::real  Position (real s12, real &lat2, real &lon2, real &azi2, real &m12) const 
Math::real  Position (real s12, real &lat2, real &lon2, real &azi2, real &M12, real &M21) const 
Math::real  Position (real s12, real &lat2, real &lon2, real &azi2, real &m12, real &M12, real &M21) const 
Position in terms of arc length  
void  ArcPosition (real a12, real &lat2, real &lon2, real &azi2, real &s12, real &m12, real &M12, real &M21, real &S12) const 
void  ArcPosition (real a12, real &lat2, real &lon2) const 
void  ArcPosition (real a12, real &lat2, real &lon2, real &azi2) const 
void  ArcPosition (real a12, real &lat2, real &lon2, real &azi2, real &s12) const 
void  ArcPosition (real a12, real &lat2, real &lon2, real &azi2, real &s12, real &m12) const 
void  ArcPosition (real a12, real &lat2, real &lon2, real &azi2, real &s12, real &M12, real &M21) const 
void  ArcPosition (real a12, real &lat2, real &lon2, real &azi2, real &s12, real &m12, real &M12, real &M21) const 
The general position function.  
Math::real  GenPosition (bool arcmode, real s12_a12, unsigned outmask, real &lat2, real &lon2, real &azi2, real &s12, real &m12, real &M12, real &M21, real &S12) const 
Setting point 3  
void  SetDistance (real s13) 
void  SetArc (real a13) 
void  GenSetDistance (bool arcmode, real s13_a13) 
Inspector functions  
bool  Init () const 
Math::real  Latitude () const 
Math::real  Longitude () const 
Math::real  Azimuth () const 
void  Azimuth (real &sazi1, real &cazi1) const 
Math::real  EquatorialAzimuth () const 
void  EquatorialAzimuth (real &sazi0, real &cazi0) const 
Math::real  EquatorialArc () const 
Math::real  MajorRadius () const 
Math::real  Flattening () const 
unsigned  Capabilities () const 
bool  Capabilities (unsigned testcaps) const 
Math::real  GenDistance (bool arcmode) const 
Math::real  Distance () const 
Math::real  Arc () const 
Friends  
class  Geodesic 
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. 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, use GeodesicLineExact instead.
The algorithms are described in
For more information on geodesics see Geodesics on an ellipsoid of revolution.
Example of use:
GeodSolve is a commandline utility providing access to the functionality of Geodesic and GeodesicLine.
Definition at line 71 of file GeodesicLine.hpp.
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.
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. 
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. (LONG_UNROLL is not included in this mask.) 
Definition at line 121 of file GeodesicLine.hpp.
GeographicLib::GeodesicLine::GeodesicLine  (  const Geodesic &  g, 
real  lat1,  
real  lon1,  
real  azi1,  
unsigned  caps = ALL 

) 
Constructor for a geodesic line staring at latitude lat1, longitude lon1, and azimuth azi1 (all in degrees).
[in]  g  A Geodesic object used to compute the necessary information about the GeodesicLine. 
[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 GeodesicLine::mask values specifying the capabilities the GeodesicLine object should possess, i.e., which quantities can be returned in calls to GeodesicLine::Position. 
lat1 should be in the range [−90°, 90°].
The GeodesicLine::mask values are
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 118 of file GeodesicLine.cpp.
References GeographicLib::Math::AngNormalize(), GeographicLib::Math::AngRound(), GeodesicLine(), and GeographicLib::Math::sincosd().

inline 
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 235 of file GeodesicLine.hpp.
Referenced by GeodesicLine().

inline 
Compute the position of point 2 which is a distance s12 (meters) from point 1.
[in]  s12  distance from point 1 to point 2 (meters); it can be negative. 
[out]  lat2  latitude of point 2 (degrees). 
[out]  lon2  longitude of point 2 (degrees); requires that the GeodesicLine object was constructed with caps = GeodesicLine::LONGITUDE. 
[out]  azi2  (forward) azimuth at point 2 (degrees). 
[out]  m12  reduced length of geodesic (meters); requires that the GeodesicLine object was constructed with caps = GeodesicLine::REDUCEDLENGTH. 
[out]  M12  geodesic scale of point 2 relative to point 1 (dimensionless); requires that the GeodesicLine object was constructed with caps = GeodesicLine::GEODESICSCALE. 
[out]  M21  geodesic scale of point 1 relative to point 2 (dimensionless); requires that the GeodesicLine object was constructed with caps = GeodesicLine::GEODESICSCALE. 
[out]  S12  area under the geodesic (meters^{2}); requires that the GeodesicLine object was constructed with caps = GeodesicLine::AREA. 
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 281 of file GeodesicLine.hpp.
Referenced by GeographicLib::CassiniSoldner::Reverse().

inline 
See the documentation for GeodesicLine::Position.
Definition at line 295 of file GeodesicLine.hpp.

inline 
See the documentation for GeodesicLine::Position.
Definition at line 305 of file GeodesicLine.hpp.

inline 
See the documentation for GeodesicLine::Position.
Definition at line 316 of file GeodesicLine.hpp.

inline 
See the documentation for GeodesicLine::Position.
Definition at line 328 of file GeodesicLine.hpp.

inline 
See the documentation for GeodesicLine::Position.
Definition at line 341 of file GeodesicLine.hpp.

inline 
Compute the position of point 2 which is an arc length a12 (degrees) from point 1.
[in]  a12  arc length from point 1 to point 2 (degrees); it can be negative. 
[out]  lat2  latitude of point 2 (degrees). 
[out]  lon2  longitude of point 2 (degrees); requires that the GeodesicLine object was constructed with caps = GeodesicLine::LONGITUDE. 
[out]  azi2  (forward) azimuth at point 2 (degrees). 
[out]  s12  distance from point 1 to point 2 (meters); requires that the GeodesicLine object was constructed with caps = GeodesicLine::DISTANCE. 
[out]  m12  reduced length of geodesic (meters); requires that the GeodesicLine object was constructed with caps = GeodesicLine::REDUCEDLENGTH. 
[out]  M12  geodesic scale of point 2 relative to point 1 (dimensionless); requires that the GeodesicLine object was constructed with caps = GeodesicLine::GEODESICSCALE. 
[out]  M21  geodesic scale of point 1 relative to point 2 (dimensionless); requires that the GeodesicLine object was constructed with caps = GeodesicLine::GEODESICSCALE. 
[out]  S12  area under the geodesic (meters^{2}); requires that the GeodesicLine object was constructed with caps = GeodesicLine::AREA. 
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 394 of file GeodesicLine.hpp.

inline 
See the documentation for GeodesicLine::ArcPosition.
Definition at line 406 of file GeodesicLine.hpp.

inline 
See the documentation for GeodesicLine::ArcPosition.
Definition at line 417 of file GeodesicLine.hpp.

inline 
See the documentation for GeodesicLine::ArcPosition.
Definition at line 429 of file GeodesicLine.hpp.

inline 
See the documentation for GeodesicLine::ArcPosition.
Definition at line 440 of file GeodesicLine.hpp.

inline 
See the documentation for GeodesicLine::ArcPosition.
Definition at line 452 of file GeodesicLine.hpp.

inline 
See the documentation for GeodesicLine::ArcPosition.
Definition at line 465 of file GeodesicLine.hpp.
Math::real GeographicLib::GeodesicLine::GenPosition  (  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 position function. GeodesicLine::Position and GeodesicLine::ArcPosition are defined in terms of this function.
[in]  arcmode  boolean flag determining the meaning of the second parameter; if arcmode is false, then the GeodesicLine object must have been constructed with caps = GeodesicLine::DISTANCE_IN. 
[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 GeodesicLine::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); requires that the GeodesicLine object was constructed with caps = GeodesicLine::LONGITUDE. 
[out]  azi2  (forward) azimuth at point 2 (degrees). 
[out]  s12  distance from point 1 to point 2 (meters); requires that the GeodesicLine object was constructed with caps = GeodesicLine::DISTANCE. 
[out]  m12  reduced length of geodesic (meters); requires that the GeodesicLine object was constructed with caps = GeodesicLine::REDUCEDLENGTH. 
[out]  M12  geodesic scale of point 2 relative to point 1 (dimensionless); requires that the GeodesicLine object was constructed with caps = GeodesicLine::GEODESICSCALE. 
[out]  M21  geodesic scale of point 1 relative to point 2 (dimensionless); requires that the GeodesicLine object was constructed with caps = GeodesicLine::GEODESICSCALE. 
[out]  S12  area under the geodesic (meters^{2}); requires that the GeodesicLine object was constructed with caps = GeodesicLine::AREA. 
The GeodesicLine::mask values possible for outmask are
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 136 of file GeodesicLine.cpp.
References GeographicLib::Math::AngNormalize(), GeographicLib::Math::atan2d(), GeographicLib::Math::copysign(), GeographicLib::Math::degree(), GeographicLib::Math::hypot(), GeographicLib::Math::NaN(), GeographicLib::Math::sincosd(), and GeographicLib::Math::sq().
Referenced by GeographicLib::CassiniSoldner::Forward(), and main().
void GeographicLib::GeodesicLine::SetDistance  (  real  s13  ) 
Specify position of point 3 in terms of distance.
[in]  s13  the distance from point 1 to point 3 (meters); it can be negative. 
This is only useful if the GeodesicLine object has been constructed with caps = GeodesicLine::DISTANCE_IN.
Definition at line 301 of file GeodesicLine.cpp.
void GeographicLib::GeodesicLine::SetArc  (  real  a13  ) 
Specify position of point 3 in terms of arc length.
[in]  a13  the arc length from point 1 to point 3 (degrees); it can be negative. 
The distance s13 is only set if the GeodesicLine object has been constructed with caps = GeodesicLine::DISTANCE.
Definition at line 309 of file GeodesicLine.cpp.
References GeographicLib::Math::NaN().
void GeographicLib::GeodesicLine::GenSetDistance  (  bool  arcmode, 
real  s13_a13  
) 
Specify position of point 3 in terms of either distance or arc length.
[in]  arcmode  boolean flag determining the meaning of the second parameter; if arcmode is false, then the GeodesicLine object must have been constructed with caps = GeodesicLine::DISTANCE_IN. 
[in]  s13_a13  if arcmode is false, this is the distance from point 1 to point 3 (meters); otherwise it is the arc length from point 1 to point 3 (degrees); it can be negative. 
Definition at line 317 of file GeodesicLine.cpp.

inline 
Definition at line 589 of file GeodesicLine.hpp.
Referenced by GeographicLib::CassiniSoldner::Init().

inline 
Definition at line 594 of file GeodesicLine.hpp.
References GeographicLib::Math::NaN().
Referenced by GeographicLib::CassiniSoldner::LatitudeOrigin().

inline 
Definition at line 600 of file GeodesicLine.hpp.
References GeographicLib::Math::NaN().
Referenced by GeographicLib::CassiniSoldner::LongitudeOrigin().

inline 
Definition at line 606 of file GeodesicLine.hpp.
References GeographicLib::Math::NaN().
Referenced by main().

inline 
The sine and cosine of azi1.
[out]  sazi1  the sine of azi1. 
[out]  cazi1  the cosine of azi1. 
Definition at line 615 of file GeodesicLine.hpp.

inline 
The result lies in [−90°, 90°].
Definition at line 624 of file GeodesicLine.hpp.
References GeographicLib::Math::atan2d(), and GeographicLib::Math::NaN().

inline 
The sine and cosine of azi0.
[out]  sazi0  the sine of azi0. 
[out]  cazi0  the cosine of azi0. 
Definition at line 633 of file GeodesicLine.hpp.

inline 
The result lies in (−180°, 180°].
Definition at line 642 of file GeodesicLine.hpp.
References GeographicLib::Math::atan2d(), and GeographicLib::Math::NaN().

inline 
Definition at line 650 of file GeodesicLine.hpp.
References GeographicLib::Math::NaN().

inline 
Definition at line 657 of file GeodesicLine.hpp.
References GeographicLib::Math::NaN().

inline 
Definition at line 664 of file GeodesicLine.hpp.

inline 
Test what capabilities are available.
[in]  testcaps  a set of bitor'ed GeodesicLine::mask values. 
Definition at line 672 of file GeodesicLine.hpp.

inline 
The distance or arc length to point 3.
[in]  arcmode  boolean flag determining the meaning of returned value. 
Definition at line 684 of file GeodesicLine.hpp.
References GeographicLib::Math::NaN().
Referenced by main().

inline 
Definition at line 690 of file GeodesicLine.hpp.

inline 
Definition at line 695 of file GeodesicLine.hpp.

friend 
Definition at line 74 of file GeodesicLine.hpp.