Class GeodesicLine
- java.lang.Object
-
- org.locationtech.proj4j.geodesic.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. AlternativelyArcPosition
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 toPosition
. TheGeodesic.InverseLine
orGeodesic.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 withGeodesic.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 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.
-
-
-
Field Detail
-
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 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
- AGeodesic
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
- AGeodesic
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 ofGeodesicMask
values specifying the capabilities the GeodesicLine object should possess, i.e., which quantities can be returned in calls toPosition
.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.
-
caps |=
-
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 ofGeodesicMask
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 theGeodesicMask.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 ofGeodesicMask
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
andArcPosition
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 ofGeodesicMask
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.
-
outmask |=
-
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'edGeodesicMask
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).
-
-