Public Member Functions
double	Arc ()

GeodesicData	ArcPosition (double a12)

GeodesicData	ArcPosition (double a12, int outmask)

double	Azimuth ()

Pair	AzimuthCosines ()

int	Capabilities ()

boolean	Capabilities (int testcaps)

double	Distance ()

double	EquatorialArc ()

double	EquatorialAzimuth ()

Pair	EquatorialAzimuthCosines ()

double	Flattening ()

double	GenDistance (boolean arcmode)

void	GenSetDistance (boolean arcmode, double s13_a13)

	GeodesicLine (Geodesic g, double lat1, double lon1, double azi1)

	GeodesicLine (Geodesic g, double lat1, double lon1, double azi1, int caps)

double	Latitude ()

double	Longitude ()

double	MajorRadius ()

GeodesicData	Position (double s12)

GeodesicData	Position (double s12, int outmask)

GeodesicData	Position (boolean arcmode, double s12_a12, int outmask)

void	SetDistance (double s13)

Protected Member Functions
	GeodesicLine (Geodesic g, double lat1, double lon1, double azi1, double salp1, double calp1, int caps, boolean arcmode, double s13_a13)

Private Member Functions
	GeodesicLine ()

boolean	Init ()

void	LineInit (Geodesic g, double lat1, double lon1, double azi1, double salp1, double calp1, int caps)

Private Attributes
double	_a

double	_a13

double	_C1a []

int	_caps

double	_lat1

Static Private Attributes
static final int	nC1_ = Geodesic.nC1_

static final int	nC1p_ = Geodesic.nC1p_

static final int	nC2_ = Geodesic.nC2_

static final int	nC3_ = Geodesic.nC3_

static final int	nC4_ = Geodesic.nC4_

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; alternatively, the Geodesic.Line method can be used to create a GeodesicLine. Position returns the location of point 2 a distance s12 along the geodesic. Alternatively 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 SetDistance (SetArc) functions. Points a fractional distance along the line can be found by providing, for example, 0.5 * Distance as an argument to 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 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.

The algorithms are described in

C. F. F. Karney, Algorithms for geodesics, J. Geodesy 87, 43–55 (2013) (addenda).

Here's an example of using this class

import net.sf.geographiclib.*;
public class GeodesicLineTest {
  public static void main(String[] args) {
    // Print waypoints between JFK and SIN
    Geodesic geod = Geodesic.WGS84;
    double
      lat1 = 40.640, lon1 = -73.779, // JFK
      lat2 =  1.359, lon2 = 103.989; // SIN
    GeodesicLine line = geod.InverseLine(lat1, lon1, lat2, lon2,
                                         GeodesicMask.DISTANCE_IN |
                                         GeodesicMask.LATITUDE |
                                         GeodesicMask.LONGITUDE);
    double ds0 = 500e3;     // Nominal distance between points = 500 km
    // The number of intervals
    int num = (int)(Math.ceil(line.Distance() / ds0));
    {
      // Use intervals of equal length
      double ds = line.Distance() / num;
      for (int i = 0; i <= num; ++i) {
        GeodesicData g = line.Position(i * ds,
                                       GeodesicMask.LATITUDE |
                                       GeodesicMask.LONGITUDE);
        System.out.println(i + " " + g.lat2 + " " + g.lon2);
      }
    }
    {
      // Slightly faster, use intervals of equal arc length
      double da = line.Arc() / num;
      for (int i = 0; i <= num; ++i) {
        GeodesicData g = line.ArcPosition(i * da,
                                          GeodesicMask.LATITUDE |
                                          GeodesicMask.LONGITUDE);
        System.out.println(i + " " + g.lat2 + " " + g.lon2);
      }
    }
  }
}

Definition at line 93 of file GeodesicLine.java.

Constructor & Destructor Documentation

net.sf.geographiclib.GeodesicLine.GeodesicLine	(	Geodesic	g,
		double	lat1,
		double	lon1,
		double	azi1
	)

inline

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

Parameters

g	A Geodesic object used to compute the necessary information about the GeodesicLine.
lat1	latitude of point 1 (degrees).
lon1	longitude of point 1 (degrees).
azi1	azimuth at point 1 (degrees).

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

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 127 of file GeodesicLine.java.

net.sf.geographiclib.GeodesicLine.GeodesicLine	(	Geodesic	g,
		double	lat1,
		double	lon1,
		double	azi1,
		int	caps
	)

inline

Constructor for a geodesic line staring at latitude lat1, longitude lon1, and azimuth azi1 (all in degrees) with a subset of the capabilities included.

Parameters

g	A Geodesic object used to compute the necessary information about the GeodesicLine.
lat1	latitude of point 1 (degrees).
lon1	longitude of point 1 (degrees).
azi1	azimuth at point 1 (degrees).
caps	bitor'ed combination of GeodesicMask values specifying the capabilities the GeodesicLine object should possess, i.e., which quantities can be returned in calls to Position.

The GeodesicMask values are

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

Definition at line 177 of file GeodesicLine.java.

net.sf.geographiclib.GeodesicLine.GeodesicLine	(	Geodesic	g,
		double	lat1,
		double	lon1,
		double	azi1,
		double	salp1,
		double	calp1,
		int	caps,
		boolean	arcmode,
		double	s13_a13
	)

inlineprotected

Definition at line 276 of file GeodesicLine.java.

net.sf.geographiclib.GeodesicLine.GeodesicLine ( )

inlineprivate

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. (This constructor was useful in C++, e.g., to allow vectors of GeodesicLine objects. It may not be needed in Java, so make it private.)

Definition at line 292 of file GeodesicLine.java.

Member Function Documentation

double net.sf.geographiclib.GeodesicLine.Arc ( )

inline

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

Definition at line 744 of file GeodesicLine.java.

GeodesicData net.sf.geographiclib.GeodesicLine.ArcPosition ( double a12 )

inline

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

Parameters

a12	arc length from point 1 to point 2 (degrees); it can be negative.

Returns: a GeodesicData object with the following fields: lat1, lon1, azi1, lat2, lon2, azi2, s12, a12. Some of these results may be missing if the GeodesicLine did not include the relevant capability.

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

The GeodesicLine object must have been constructed with caps |= GeodesicMask#DISTANCE_IN; otherwise no parameters are set.

Definition at line 355 of file GeodesicLine.java.

GeodesicData net.sf.geographiclib.GeodesicLine.ArcPosition	(	double	a12,
		int	outmask
	)

inline

Compute the position of point 2 which is an arc length a12 (degrees) from point 1 and with a subset of the geodesic results returned.

Parameters

a12	arc length from point 1 to point 2 (degrees); it can be negative.
outmask	a bitor'ed combination of GeodesicMask values specifying which results should be returned.

Returns: a GeodesicData object giving lat1, lon2, azi2, and a12.

Requesting a value which the GeodesicLine object is not capable of computing is not an error (no parameters will be set). The value of lon2 returned is in the range [−180°, 180°], unless the outmask includes the GeodesicMask#LONG_UNROLL flag.

Definition at line 374 of file GeodesicLine.java.

double net.sf.geographiclib.GeodesicLine.Azimuth ( )

inline

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

Definition at line 657 of file GeodesicLine.java.

Pair net.sf.geographiclib.GeodesicLine.AzimuthCosines ( )

inline

Returns: pair of sine and cosine of azi1 the azimuth (degrees) of the geodesic line at point 1.

Definition at line 664 of file GeodesicLine.java.

int net.sf.geographiclib.GeodesicLine.Capabilities ( )

inline

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

Definition at line 714 of file GeodesicLine.java.

boolean net.sf.geographiclib.GeodesicLine.Capabilities ( int testcaps )

inline

Parameters

testcaps a set of bitor'ed GeodesicMask values.

Returns: true if the GeodesicLine object has all these capabilities.

Definition at line 720 of file GeodesicLine.java.

double net.sf.geographiclib.GeodesicLine.Distance ( )

inline

Returns: s13, the distance to point 3 (meters).

Definition at line 739 of file GeodesicLine.java.

double net.sf.geographiclib.GeodesicLine.EquatorialArc ( )

inline

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

Definition at line 691 of file GeodesicLine.java.

double net.sf.geographiclib.GeodesicLine.EquatorialAzimuth ( )

inline

Returns: azi0 the azimuth (degrees) of the geodesic line as it crosses the equator in a northward direction.

Definition at line 673 of file GeodesicLine.java.

Pair net.sf.geographiclib.GeodesicLine.EquatorialAzimuthCosines ( )

inline

Returns: pair of sine and cosine of azi0 the azimuth of the geodesic line as it crosses the equator in a northward direction.

Definition at line 682 of file GeodesicLine.java.

double net.sf.geographiclib.GeodesicLine.Flattening ( )

inline

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

Definition at line 707 of file GeodesicLine.java.

double net.sf.geographiclib.GeodesicLine.GenDistance ( boolean arcmode )

inline

The distance or arc length to point 3.

Parameters

arcmode boolean flag determining the meaning of returned value.

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

Definition at line 733 of file GeodesicLine.java.

void net.sf.geographiclib.GeodesicLine.GenSetDistance	(	boolean	arcmode,
		double	s13_a13
	)

inline

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

Parameters

arcmode	boolean flag determining the meaning of the second parameter; if arcmode is false, then the GeodesicLine object must have been constructed with caps \|= GeodesicMask#DISTANCE_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 630 of file GeodesicLine.java.

boolean net.sf.geographiclib.GeodesicLine.Init ( )

inlineprivate

Returns: true if the object has been initialized.

Definition at line 640 of file GeodesicLine.java.

double net.sf.geographiclib.GeodesicLine.Latitude ( )

inline

Returns: lat1 the latitude of point 1 (degrees).

Definition at line 645 of file GeodesicLine.java.

void net.sf.geographiclib.GeodesicLine.LineInit	(	Geodesic	g,
		double	lat1,
		double	lon1,
		double	azi1,
		double	salp1,
		double	calp1,
		int	caps
	)

inlineprivate

Definition at line 188 of file GeodesicLine.java.

double net.sf.geographiclib.GeodesicLine.Longitude ( )

inline

Returns: lon1 the longitude of point 1 (degrees).

Definition at line 651 of file GeodesicLine.java.

double net.sf.geographiclib.GeodesicLine.MajorRadius ( )

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 700 of file GeodesicLine.java.

GeodesicData net.sf.geographiclib.GeodesicLine.Position ( double s12 )

inline

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

Parameters

s12	distance from point 1 to point 2 (meters); it can be negative.

Returns: a GeodesicData object with the following fields: lat1, lon1, azi1, lat2, lon2, azi2, s12, a12. Some of these results may be missing if the GeodesicLine did not include the relevant capability.

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

The GeodesicLine object must have been constructed with caps |= GeodesicMask#DISTANCE_IN; otherwise no parameters are set.

Definition at line 311 of file GeodesicLine.java.

GeodesicData net.sf.geographiclib.GeodesicLine.Position	(	double	s12,
		int	outmask
	)

inline

Compute the position of point 2 which is a distance s12 (meters) from point 1 and with a subset of the geodesic results returned.

Parameters

s12	distance from point 1 to point 2 (meters); it can be negative.
outmask	a bitor'ed combination of GeodesicMask values specifying which results should be returned.

Returns: a GeodesicData object including the requested results.

The GeodesicLine object must have been constructed with caps |= GeodesicMask#DISTANCE_IN; otherwise no parameters are set. Requesting a value which the GeodesicLine object is not capable of computing is not an error (no parameters will be set). The value of lon2 returned is normally in the range [−180°, 180°]; however if the outmask includes the GeodesicMask#LONG_UNROLL flag, the longitude is "unrolled" so that the quantity lon2 − lon1 indicates how many times and in what sense the geodesic encircles the ellipsoid.

Definition at line 334 of file GeodesicLine.java.

GeodesicData net.sf.geographiclib.GeodesicLine.Position	(	boolean	arcmode,
		double	s12_a12,
		int	outmask
	)

inline

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

Parameters

arcmode	boolean flag determining the meaning of the second parameter; if arcmode is false, then the GeodesicLine object must have been constructed with caps \|= GeodesicMask#DISTANCE_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.
outmask	a bitor'ed combination of GeodesicMask values specifying which results should be returned.

Returns: a GeodesicData object with the requested results.

The GeodesicMask values possible for outmask are

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

Requesting a value which the GeodesicLine object is not capable of computing is not an error; Double.NaN is returned instead.

Definition at line 423 of file GeodesicLine.java.

void net.sf.geographiclib.GeodesicLine.SetDistance ( double s13 )

inline

Specify position of point 3 in terms of distance.

Parameters

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 |= GeodesicMask#DISTANCE_IN.

Definition at line 598 of file GeodesicLine.java.

Member Data Documentation

double net.sf.geographiclib.GeodesicLine._a

private

Definition at line 102 of file GeodesicLine.java.

double net.sf.geographiclib.GeodesicLine._a13

private

Definition at line 105 of file GeodesicLine.java.

double net.sf.geographiclib.GeodesicLine._C1a[]

private

Definition at line 107 of file GeodesicLine.java.

int net.sf.geographiclib.GeodesicLine._caps

private

Definition at line 109 of file GeodesicLine.java.

double net.sf.geographiclib.GeodesicLine._lat1

private

Definition at line 101 of file GeodesicLine.java.

final int net.sf.geographiclib.GeodesicLine.nC1_ = Geodesic.nC1_

staticprivate

Definition at line 95 of file GeodesicLine.java.

final int net.sf.geographiclib.GeodesicLine.nC1p_ = Geodesic.nC1p_

staticprivate

Definition at line 96 of file GeodesicLine.java.

final int net.sf.geographiclib.GeodesicLine.nC2_ = Geodesic.nC2_

staticprivate

Definition at line 97 of file GeodesicLine.java.

final int net.sf.geographiclib.GeodesicLine.nC3_ = Geodesic.nC3_

staticprivate

Definition at line 98 of file GeodesicLine.java.

final int net.sf.geographiclib.GeodesicLine.nC4_ = Geodesic.nC4_

staticprivate

Definition at line 99 of file GeodesicLine.java.

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

GeodesicLine.java

Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation