Class GeodesicLine


  • public class GeodesicLine
    extends java.lang.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

    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 int nC1_  
      private static int nC1p_  
      private static int nC2_  
      private static int nC3_  
      private static 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

      All Methods Instance Methods Concrete Methods 
      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 java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • _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 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

      • 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 Detail

      • 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 lon2lon1 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

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