GeographicLib::GeodesicLine Class Reference

A geodesic line. More...

#include <GeographicLib/GeodesicLine.hpp>

List of all members.

Public Types

enum  mask {
  NONE, LATITUDE, LONGITUDE, AZIMUTH,
  DISTANCE, DISTANCE_IN, REDUCEDLENGTH, GEODESICSCALE,
  AREA, 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
Inspector functions



bool Init () const
Math::real Latitude () const
Math::real Longitude () const
Math::real Azimuth () const
Math::real EquatorialAzimuth () const
Math::real EquatorialArc () const
Math::real MajorRadius () const
Math::real Flattening () const
unsigned Capabilities () const
bool Capabilities (unsigned testcaps) const

Friends

class Geodesic

Detailed Description

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. GeodesicLine.Position returns the location of point 2 a distance s12 along the geodesic. Alternatively GeodesicLine.ArcPosition gives the position of point 2 an arc length a12 along the geodesic.

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:

// Example of using the GeographicLib::GeodesicLine class

#include <iostream>
#include <exception>
#include <cmath>
#include <iomanip>
#include <GeographicLib/Geodesic.hpp>
#include <GeographicLib/GeodesicLine.hpp>
#include <GeographicLib/Constants.hpp>

using namespace std;
using namespace GeographicLib;

int main() {
  try {
    // Print waypoints between JFK and SIN
    Geodesic geod(Constants::WGS84_a(), Constants::WGS84_f());
    // Alternatively: const Geodesic& geod = Geodesic::WGS84();
    double
      lat1 = 40.640, lon1 = -73.779, // JFK
      lat2 =  1.359, lon2 = 103.989; // SIN
    double s12, azi1, azi2,
      a12 = geod.Inverse(lat1, lon1, lat2, lon2, s12, azi1, azi2);
    const GeographicLib::GeodesicLine line(geod, lat1, lon1, azi1);
    // Alternatively
    // const GeographicLib::GeodesicLine line = geod.Line(lat1, lon1, azi1);
    double ds = 500e3;          // Nominal distance between points = 500 km
    int num = int(ceil(s12 / ds)); // The number of intervals
    cout << fixed << setprecision(3);
    {
      // Use intervals of equal length
      double ds = s12 / num;
      for (int i = 0; i <= num; ++i) {
        double lat, lon;
       line.Position(i * ds, lat, lon);
       cout << i << " " << lat << " " << lon << "\n";
      }
    }
    {
      // Slightly faster, use intervals of equal arc length
      double da = a12 / num;
      for (int i = 0; i <= num; ++i) {
        double lat, lon;
       line.ArcPosition(i * da, lat, lon);
       cout << i << " " << lat << " " << lon << "\n";
      }
    }
  }
  catch (const exception& e) {
    cerr << "Caught exception: " << e.what() << "\n";
    return 1;
  }
  return 0;
}

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

Definition at line 59 of file GeodesicLine.hpp.


Member Enumeration Documentation

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.

ALL 

All capabilities, calculate everything.

Definition at line 97 of file GeodesicLine.hpp.


Constructor & Destructor Documentation

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).

Parameters:
[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]; lon1 and azi1 should be in the range [540, 540).

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 35 of file GeodesicLine.cpp.

References GeographicLib::Math::AngNormalize(), GeographicLib::Math::degree(), GeographicLib::Math::hypot(), and GeographicLib::Math::sq().

GeographicLib::GeodesicLine::GeodesicLine (  )  [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 206 of file GeodesicLine.hpp.


Member Function Documentation

Math::real GeographicLib::GeodesicLine::Position ( real  s12,
real &  lat2,
real &  lon2,
real &  azi2,
real &  m12,
real &  M12,
real &  M21,
real &  S12 
) const [inline]

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

Parameters:
[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); 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 (meters2); requires that the GeodesicLine object was constructed with caps |= GeodesicLine::AREA.
Returns:
a12 arc length of between point 1 and 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 252 of file GeodesicLine.hpp.

Referenced by GeographicLib::CassiniSoldner::Reverse().

Math::real GeographicLib::GeodesicLine::Position ( real  s12,
real &  lat2,
real &  lon2 
) const [inline]

See the documentation for GeodesicLine::Position.

Definition at line 266 of file GeodesicLine.hpp.

Math::real GeographicLib::GeodesicLine::Position ( real  s12,
real &  lat2,
real &  lon2,
real &  azi2 
) const [inline]

See the documentation for GeodesicLine::Position.

Definition at line 276 of file GeodesicLine.hpp.

Math::real GeographicLib::GeodesicLine::Position ( real  s12,
real &  lat2,
real &  lon2,
real &  azi2,
real &  m12 
) const [inline]

See the documentation for GeodesicLine::Position.

Definition at line 287 of file GeodesicLine.hpp.

Math::real GeographicLib::GeodesicLine::Position ( real  s12,
real &  lat2,
real &  lon2,
real &  azi2,
real &  M12,
real &  M21 
) const [inline]

See the documentation for GeodesicLine::Position.

Definition at line 299 of file GeodesicLine.hpp.

Math::real GeographicLib::GeodesicLine::Position ( real  s12,
real &  lat2,
real &  lon2,
real &  azi2,
real &  m12,
real &  M12,
real &  M21 
) const [inline]

See the documentation for GeodesicLine::Position.

Definition at line 312 of file GeodesicLine.hpp.

void GeographicLib::GeodesicLine::ArcPosition ( real  a12,
real &  lat2,
real &  lon2,
real &  azi2,
real &  s12,
real &  m12,
real &  M12,
real &  M21,
real &  S12 
) const [inline]

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

Parameters:
[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); requires that the GeodesicLine object was constructed with caps |= GeodesicLine::LONGITUDE.
[out] azi2 (forward) azimuth at point 2 (degrees).
[out] s12 distance between point 1 and 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 (meters2); 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 366 of file GeodesicLine.hpp.

void GeographicLib::GeodesicLine::ArcPosition ( real  a12,
real &  lat2,
real &  lon2 
) const [inline]

See the documentation for GeodesicLine::ArcPosition.

Definition at line 378 of file GeodesicLine.hpp.

void GeographicLib::GeodesicLine::ArcPosition ( real  a12,
real &  lat2,
real &  lon2,
real &  azi2 
) const [inline]

See the documentation for GeodesicLine::ArcPosition.

Definition at line 389 of file GeodesicLine.hpp.

void GeographicLib::GeodesicLine::ArcPosition ( real  a12,
real &  lat2,
real &  lon2,
real &  azi2,
real &  s12 
) const [inline]

See the documentation for GeodesicLine::ArcPosition.

Definition at line 401 of file GeodesicLine.hpp.

void GeographicLib::GeodesicLine::ArcPosition ( real  a12,
real &  lat2,
real &  lon2,
real &  azi2,
real &  s12,
real &  m12 
) const [inline]

See the documentation for GeodesicLine::ArcPosition.

Definition at line 412 of file GeodesicLine.hpp.

void GeographicLib::GeodesicLine::ArcPosition ( real  a12,
real &  lat2,
real &  lon2,
real &  azi2,
real &  s12,
real &  M12,
real &  M21 
) const [inline]

See the documentation for GeodesicLine::ArcPosition.

Definition at line 424 of file GeodesicLine.hpp.

void GeographicLib::GeodesicLine::ArcPosition ( real  a12,
real &  lat2,
real &  lon2,
real &  azi2,
real &  s12,
real &  m12,
real &  M12,
real &  M21 
) const [inline]

See the documentation for GeodesicLine::ArcPosition.

Definition at line 437 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.

Parameters:
[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 between point 1 and 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 (meters2); requires that the GeodesicLine object was constructed with caps |= GeodesicLine::AREA.
Returns:
a12 arc length of between point 1 and point 2 (degrees).

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.

Definition at line 124 of file GeodesicLine.cpp.

References GeographicLib::Math::AngNormalize(), GeographicLib::Math::AngNormalize2(), AREA, AZIMUTH, GeographicLib::Math::degree(), DISTANCE, DISTANCE_IN, GEODESICSCALE, GeographicLib::Math::hypot(), Init(), LATITUDE, LONGITUDE, GeographicLib::Math::NaN(), REDUCEDLENGTH, and GeographicLib::Math::sq().

Referenced by GeographicLib::CassiniSoldner::Forward().

bool GeographicLib::GeodesicLine::Init (  )  const [inline]
Returns:
true if the object has been initialized.

Definition at line 517 of file GeodesicLine.hpp.

Referenced by GenPosition().

Math::real GeographicLib::GeodesicLine::Latitude (  )  const [inline]
Returns:
lat1 the latitude of point 1 (degrees).

Definition at line 522 of file GeodesicLine.hpp.

References GeographicLib::Math::NaN().

Math::real GeographicLib::GeodesicLine::Longitude (  )  const [inline]
Returns:
lon1 the longitude of point 1 (degrees).

Definition at line 528 of file GeodesicLine.hpp.

References GeographicLib::Math::NaN().

Math::real GeographicLib::GeodesicLine::Azimuth (  )  const [inline]
Returns:
azi1 the azimuth (degrees) of the geodesic line at point 1.

Definition at line 534 of file GeodesicLine.hpp.

References GeographicLib::Math::NaN().

Math::real GeographicLib::GeodesicLine::EquatorialAzimuth (  )  const [inline]
Returns:
azi0 the azimuth (degrees) of the geodesic line as it crosses the equator in a northward direction.

Definition at line 541 of file GeodesicLine.hpp.

References GeographicLib::Math::degree(), and GeographicLib::Math::NaN().

Math::real GeographicLib::GeodesicLine::EquatorialArc (  )  const [inline]
Returns:
a1 the arc length (degrees) between the northward equatorial crossing and point 1.

Definition at line 551 of file GeodesicLine.hpp.

References GeographicLib::Math::degree(), and GeographicLib::Math::NaN().

Math::real GeographicLib::GeodesicLine::MajorRadius (  )  const [inline]
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 561 of file GeodesicLine.hpp.

References GeographicLib::Math::NaN().

Math::real GeographicLib::GeodesicLine::Flattening (  )  const [inline]
Returns:
f the flattening of the ellipsoid. This is the value inherited from the Geodesic object used in the constructor.

Definition at line 568 of file GeodesicLine.hpp.

References GeographicLib::Math::NaN().

unsigned GeographicLib::GeodesicLine::Capabilities (  )  const [inline]
Returns:
caps the computational capabilities that this object was constructed with. LATITUDE and AZIMUTH are always included.

Definition at line 584 of file GeodesicLine.hpp.

bool GeographicLib::GeodesicLine::Capabilities ( unsigned  testcaps  )  const [inline]
Parameters:
[in] testcaps a set of bitor'ed GeodesicLine::mask values.
Returns:
true if the GeodesicLine object has all these capabilities.

Definition at line 590 of file GeodesicLine.hpp.


Friends And Related Function Documentation

friend class Geodesic [friend]

Definition at line 62 of file GeodesicLine.hpp.


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 6 Oct 2014 for GeographicLib by  doxygen 1.6.1