GeodesicLine (Java implementation of GeographicLib 1.44 API)

java.lang.Object
- net.sf.geographiclib.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. 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.

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
     GeodesicData g = geod.Inverse(lat1, lon1, lat2, lon2,
                  GeodesicMask.DISTANCE | GeodesicMask.AZIMUTH);
     GeodesicLine line = new GeodesicLine(geod, lat1, lon1, g.azi1,
                  GeodesicMask.DISTANCE_IN | GeodesicMask.LONGITUDE);
     double
       s12 = g.s12,
       a12 = g.a12,
       ds0 = 500e3;        // Nominal distance between points = 500 km
     int num = (int)(Math.ceil(s12 / ds0)); // The number of intervals
     {
       // Use intervals of equal length
       double ds = s12 / num;
       for (int i = 0; i <= num; ++i) {
         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 = a12 / num;
       for (int i = 0; i <= num; ++i) {
         g = line.ArcPosition(i * da,
                  GeodesicMask.LATITUDE | GeodesicMask.LONGITUDE);
         System.out.println(i + " " + g.lat2 + " " + g.lon2);
       }
     }
   }
 }

Constructor Summary

Constructors
Constructor and Description
`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).
`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

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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()`
`int`	`Capabilities()`
`boolean`	`Capabilities(int testcaps)`
`double`	`EquatorialArc()`
`double`	`EquatorialAzimuth()`
`double`	`Flattening()`
`double`	`Latitude()`
`double`	`Longitude()`
`double`	`MajorRadius()`
`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.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - 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;
- Method Detail
  - Position
```
public GeodesicData Position(double s12)
```
    Compute the position of point 2 which is a distance s12 (meters) from point 1.
    
    Parameters:
    
    s12 - distance between point 1 and 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 between point 1 and 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 between point 1 and 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 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 giving lat1, lon2, azi2, and a12.
    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 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.
  - 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.
  - EquatorialAzimuth
```
public double EquatorialAzimuth()
```
    Returns:
    
    azi0 the azimuth (degrees) 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.
  - MajorRadius
```
public double MajorRadius()
```
    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.

Class GeodesicLine

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

GeodesicLine

GeodesicLine

Method Detail

Position

Position

ArcPosition

ArcPosition

Position

Latitude

Longitude

Azimuth

EquatorialAzimuth

EquatorialArc

MajorRadius

Flattening

Capabilities

Capabilities