org.locationtech.proj4j.geodesic.GeodesicLine

public class GeodesicLine extends Object

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);
      }
    }
  }
}

Field Summary

Fields

Modifier and Type

Field

Description

private double

_a

private double

_a13

private double

_A1m1

private double

_A2m1

private double

_A3c

private double

_A4

private double

_azi1

private double

_b

private double

_B11

private double

_B21

private double

_B31

private double

_B41

private double[]

_C1a

private double[]

_C1pa

private double

_c2

private double[]

_C2a

private double[]

_C3a

private double[]

_C4a

private double

_calp0

private double

_calp1

private int

_caps

private double

_comg1

private double

_csig1

private double

_ctau1

private double

_dn1

private double

_f

private double

_f1

private double

_k2

private double

_lat1

private double

_lon1

private double

_s13

private double

_salp0

private double

_salp1

private double

_somg1

private double

_ssig1

private double

_stau1

private static final int

nC1_

private static final int

nC1p_

private static final int

nC2_

private static final int

nC3_

private static final int

nC4_
Constructor Summary

Constructors

Modifier

Constructor

Description

private

GeodesicLine()

A default constructor.

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

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

protected

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

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

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

Modifier and Type

Method

Description

double

Arc()

GeodesicData

ArcPosition(double a12)

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

GeodesicData

ArcPosition(double a12, int outmask)

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.

double

Azimuth()

Pair

AzimuthCosines()

int

Capabilities()

boolean

Capabilities(int testcaps)

double

Distance()

double

EquatorialArc()

double

EquatorialAzimuth()

Pair

EquatorialAzimuthCosines()

double

EquatorialRadius()

double

Flattening()

double

GenDistance(boolean arcmode)

The distance or arc length to point 3.

void

GenSetDistance(boolean arcmode, double s13_a13)

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

private boolean

Init()

double

Latitude()

private void

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

double

Longitude()

GeodesicData

Position(boolean arcmode, double s12_a12, int outmask)

The general position function.

GeodesicData

Position(double s12)

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

GeodesicData

Position(double s12, int outmask)

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

(package private) void

SetArc(double a13)

Specify position of point 3 in terms of arc length.

void

SetDistance(double s13)

Specify position of point 3 in terms of distance.

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details
- nC1_
  private static final int nC1_
  
  See Also:
  
  Constant Field Values
- nC1p_
  private static final int nC1p_
  
  See Also:
  
  Constant Field Values
- nC2_
  private static final int nC2_
  
  See Also:
  
  Constant Field Values
- nC3_
  private static final int nC3_
  
  See Also:
  
  Constant Field Values
- nC4_
  private static final int nC4_
  
  See Also:
  
  Constant Field Values
- _lat1
  
  private double _lat1
- _lon1
  
  private double _lon1
- _azi1
  
  private double _azi1
- _a
  
  private double _a
- _f
  
  private double _f
- _b
  
  private double _b
- _c2
  
  private double _c2
- _f1
  
  private double _f1
- _salp0
  
  private double _salp0
- _calp0
  
  private double _calp0
- _k2
  
  private double _k2
- _salp1
  
  private double _salp1
- _calp1
  
  private double _calp1
- _ssig1
  
  private double _ssig1
- _csig1
  
  private double _csig1
- _dn1
  
  private double _dn1
- _stau1
  
  private double _stau1
- _ctau1
  
  private double _ctau1
- _somg1
  
  private double _somg1
- _comg1
  
  private double _comg1
- _A1m1
  
  private double _A1m1
- _A2m1
  
  private double _A2m1
- _A3c
  
  private double _A3c
- _B11
  
  private double _B11
- _B21
  
  private double _B21
- _B31
  
  private double _B31
- _A4
  
  private double _A4
- _B41
  
  private double _B41
- _a13
  
  private double _a13
- _s13
  
  private double _s13
- _C1a
  
  private double[] _C1a
- _C1pa
  
  private double[] _C1pa
- _C2a
  
  private double[] _C2a
- _C3a
  
  private double[] _C3a
- _C4a
  
  private double[] _C4a
- _caps
  
  private int _caps
Constructor Details
- GeodesicLine
  
  public GeodesicLine(Geodesic g, double lat1, double lon1, double azi1)
  
  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+.
- GeodesicLine
  public GeodesicLine(Geodesic g, double lat1, double lon1, double azi1, int caps)
  
  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.
- GeodesicLine
  
  protected GeodesicLine(Geodesic g, double lat1, double lon1, double azi1, double salp1, double calp1, int caps, boolean arcmode, double s13_a13)
- GeodesicLine
  
  private GeodesicLine()
  
  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.)
Method Details
- LineInit
  
  private void LineInit(Geodesic g, double lat1, double lon1, double azi1, double salp1, double calp1, int caps, Pair p)
- Position
  
  public GeodesicData Position(double s12)
  
  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.
- Position
  
  public GeodesicData Position(double s12, int outmask)
  
  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.
- ArcPosition
  
  public GeodesicData ArcPosition(double a12)
  
  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.
- ArcPosition
  
  public GeodesicData ArcPosition(double a12, int outmask)
  
  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.
- Position
  public GeodesicData Position(boolean arcmode, double s12_a12, int outmask)
  
  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.
- SetDistance
  
  public void SetDistance(double s13)
  
  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.
- SetArc
  
  void SetArc(double a13)
  
  Specify position of point 3 in terms of arc length.
  
  Parameters:
  
  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 |= GeodesicMask.DISTANCE.
- GenSetDistance
  
  public void GenSetDistance(boolean arcmode, double s13_a13)
  
  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.
- Init
  
  private boolean Init()
  
  Returns:
  
  true if the object has been initialized.
- Latitude
  
  public double Latitude()
  
  Returns:
  
  lat1 the latitude of point 1 (degrees).
- Longitude
  
  public double Longitude()
  
  Returns:
  
  lon1 the longitude of point 1 (degrees).
- Azimuth
  
  public double Azimuth()
  
  Returns:
  
  azi1 the azimuth (degrees) of the geodesic line at point 1.
- AzimuthCosines
  
  public Pair AzimuthCosines()
  
  Returns:
  
  pair of sine and cosine of azi1 the azimuth (degrees) of the geodesic line at point 1.
- EquatorialAzimuth
  
  public double EquatorialAzimuth()
  
  Returns:
  
  azi0 the azimuth (degrees) of the geodesic line as it crosses the equator in a northward direction.
- EquatorialAzimuthCosines
  
  public Pair EquatorialAzimuthCosines()
  
  Returns:
  
  pair of sine and cosine of azi0 the azimuth of the geodesic line as it crosses the equator in a northward direction.
- EquatorialArc
  
  public double EquatorialArc()
  
  Returns:
  
  a1 the arc length (degrees) between the northward equatorial crossing and point 1.
- EquatorialRadius
  
  public double EquatorialRadius()
  
  Returns:
  
  a the equatorial radius of the ellipsoid (meters). This is the value inherited from the Geodesic object used in the constructor.
- Flattening
  
  public double Flattening()
  
  Returns:
  
  f the flattening of the ellipsoid. This is the value inherited from the Geodesic object used in the constructor.
- Capabilities
  
  public int Capabilities()
  
  Returns:
  
  caps the computational capabilities that this object was constructed with. LATITUDE and AZIMUTH are always included.
- Capabilities
  
  public boolean Capabilities(int testcaps)
  
  Parameters:
  
  testcaps - a set of bitor'ed GeodesicMask values.
  
  Returns:
  
  true if the GeodesicLine object has all these capabilities.
- GenDistance
  
  public double GenDistance(boolean arcmode)
  
  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.
- Distance
  
  public double Distance()
  
  Returns:
  
  s13, the distance to point 3 (meters).
- Arc
  
  public double Arc()
  
  Returns:
  
  a13, the arc length to point 3 (degrees).

Class GeodesicLine

Field Summary

Constructor Summary

Method Summary

Methods inherited from class Object

Field Details

nC1_

nC1p_

nC2_

nC3_

nC4_

_lat1

_lon1

_azi1

_a

_f

_b

_c2

_f1

_salp0

_calp0

_k2

_salp1

_calp1

_ssig1

_csig1

_dn1

_stau1

_ctau1

_somg1

_comg1

_A1m1

_A2m1

_A3c

_B11

_B21

_B31

_A4

_B41

_a13

_s13

_C1a

_C1pa

_C2a

_C3a

_C4a

_caps

Constructor Details

GeodesicLine

GeodesicLine

GeodesicLine

GeodesicLine

Method Details

LineInit

Position

Position

ArcPosition

ArcPosition

Position

SetDistance

SetArc

GenSetDistance

Init

Latitude

Longitude

Azimuth

AzimuthCosines

EquatorialAzimuth

EquatorialAzimuthCosines

EquatorialArc

EquatorialRadius

Flattening

Capabilities

Capabilities

GenDistance

Distance

Arc