public class Geodesic extends Object
The shortest path between two points on a ellipsoid at (lat1, lon1) and (lat2, lon2) is called the geodesic. Its length is s12 and the geodesic from point 1 to point 2 has azimuths azi1 and azi2 at the two end points. (The azimuth is the heading measured clockwise from north. azi2 is the "forward" azimuth, i.e., the heading that takes you beyond point 2 not back to point 1.)
Given lat1, lon1, azi1, and s12, we can
determine lat2, lon2, and azi2. This is the
direct geodesic problem and its solution is given by the function
Direct
. (If s12 is sufficiently large that the
geodesic wraps more than halfway around the earth, there will be another
geodesic between the points with a smaller s12.)
Given lat1, lon1, lat2, and lon2, we can
determine azi1, azi2, and s12. This is the
inverse geodesic problem, whose solution is given by Inverse
. Usually, the solution to the inverse problem is unique. In cases
where there are multiple solutions (all with the same s12, of
course), all the solutions can be easily generated once a particular
solution is provided.
The standard way of specifying the direct problem is the specify the
distance s12 to the second point. However it is sometimes useful
instead to specify the arc length a12 (in degrees) on the auxiliary
sphere. This is a mathematical construct used in solving the geodesic
problems. The solution of the direct problem in this form is provided by
ArcDirect
. An arc length in excess of 180° indicates
that the geodesic is not a shortest path. In addition, the arc length
between an equatorial crossing and the next extremum of latitude for a
geodesic is 90°.
This class can also calculate several other quantities related to geodesics. These are:
The quantities m12, M12, M21 which all specify the behavior of nearby geodesics obey addition rules. If points 1, 2, and 3 all lie on a single geodesic, then the following rules hold:
The results of the geodesic calculations are bundled up into a GeodesicData
object which includes the input parameters and all the
computed results, i.e., lat1, lon1, azi1, lat2,
lon2, azi2, s12, a12, m12, M12,
M21, S12.
The functions Direct
,
ArcDirect
, and
Inverse
include an
optional final argument outmask which allows you specify which
results should be computed and returned. If you omit outmask, then
the "standard" geodesic results are computed (latitudes, longitudes,
azimuths, and distance). outmask is bitor'ed combination of GeodesicMask
values. For example, if you wish just to compute the distance
between two points you would call, e.g.,
GeodesicData g = Geodesic.WGS84.Inverse(lat1, lon1, lat2, lon2,
GeodesicMask.DISTANCE);
Additional functionality is provided by the GeodesicLine
class,
which allows a sequence of points along a geodesic to be computed.
The shortest distance returned by the solution of the inverse problem is (obviously) uniquely defined. However, in a few special cases there are multiple azimuths which yield the same shortest distance. Here is a catalog of those cases:
The calculations are accurate to better than 15 nm (15 nanometers) for the WGS84 ellipsoid. 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. Here is a table of the approximate maximum error (expressed as a distance) for an ellipsoid with the same equatorial radius as the WGS84 ellipsoid and different values of the flattening.
f error 0.01 25 nm 0.02 30 nm 0.05 10 um 0.1 1.5 mm 0.2 300 mm
The algorithms are described in
Example of use:
// Solve the direct geodesic problem.
// This program reads in lines with lat1, lon1, azi1, s12 and prints
// out lines with lat2, lon2, azi2 (for the WGS84 ellipsoid).
import java.util.*;
import net.sf.geographiclib.*;
public class Direct {
public static void main(String[] args) {
try {
Scanner in = new Scanner(System.in);
double lat1, lon1, azi1, s12;
while (true) {
lat1 = in.nextDouble(); lon1 = in.nextDouble();
azi1 = in.nextDouble(); s12 = in.nextDouble();
GeodesicData g = Geodesic.WGS84.Direct(lat1, lon1, azi1, s12);
System.out.println(g.lat2 + " " + g.lon2 + " " + g.azi2);
}
}
catch (Exception e) {}
}
}
Modifier and Type  Field and Description 

static Geodesic 
WGS84
A global instantiation of Geodesic with the parameters for the WGS84
ellipsoid.

Constructor and Description 

Geodesic(double a,
double f)
Constructor for a ellipsoid with

Modifier and Type  Method and Description 

GeodesicData 
ArcDirect(double lat1,
double lon1,
double azi1,
double a12)
Solve the direct geodesic problem where the length of the geodesic
is specified in terms of arc length.

GeodesicData 
ArcDirect(double lat1,
double lon1,
double azi1,
double a12,
int outmask)
Solve the direct geodesic problem where the length of the geodesic is
specified in terms of arc length and with a subset of the geodesic results
returned.

GeodesicLine 
ArcDirectLine(double lat1,
double lon1,
double azi1,
double a12)
Define a
GeodesicLine in terms of the direct geodesic problem
specified in terms of arc length with all capabilities included. 
GeodesicLine 
ArcDirectLine(double lat1,
double lon1,
double azi1,
double a12,
int caps)
Define a
GeodesicLine in terms of the direct geodesic problem
specified in terms of arc length with a subset of the capabilities
included. 
GeodesicData 
Direct(double lat1,
double lon1,
double azi1,
boolean arcmode,
double s12_a12,
int outmask)
The general direct geodesic problem.

GeodesicData 
Direct(double lat1,
double lon1,
double azi1,
double s12)
Solve the direct geodesic problem where the length of the geodesic
is specified in terms of distance.

GeodesicData 
Direct(double lat1,
double lon1,
double azi1,
double s12,
int outmask)
Solve the direct geodesic problem where the length of the geodesic is
specified in terms of distance and with a subset of the geodesic results
returned.

GeodesicLine 
DirectLine(double lat1,
double lon1,
double azi1,
double s12)
Define a
GeodesicLine in terms of the direct geodesic problem
specified in terms of distance with all capabilities included. 
GeodesicLine 
DirectLine(double lat1,
double lon1,
double azi1,
double s12,
int caps)
Define a
GeodesicLine in terms of the direct geodesic problem
specified in terms of distance with a subset of the capabilities included. 
double 
EllipsoidArea() 
double 
Flattening() 
GeodesicLine 
GenDirectLine(double lat1,
double lon1,
double azi1,
boolean arcmode,
double s12_a12,
int caps)
Define a
GeodesicLine in terms of the direct geodesic problem
specified in terms of either distance or arc length with a subset of the
capabilities included. 
GeodesicData 
Inverse(double lat1,
double lon1,
double lat2,
double lon2)
Solve the inverse geodesic problem.

GeodesicData 
Inverse(double lat1,
double lon1,
double lat2,
double lon2,
int outmask)
Solve the inverse geodesic problem with a subset of the geodesic results
returned.

GeodesicLine 
InverseLine(double lat1,
double lon1,
double lat2,
double lon2)
Define a
GeodesicLine in terms of the inverse geodesic problem
with all capabilities included. 
GeodesicLine 
InverseLine(double lat1,
double lon1,
double lat2,
double lon2,
int caps)
Define a
GeodesicLine in terms of the inverse geodesic problem
with a subset of the capabilities included. 
GeodesicLine 
Line(double lat1,
double lon1,
double azi1)
Set up to compute several points on a single geodesic with all
capabilities included.

GeodesicLine 
Line(double lat1,
double lon1,
double azi1,
int caps)
Set up to compute several points on a single geodesic with a subset of the
capabilities included.

double 
MajorRadius() 
public static final Geodesic WGS84
public Geodesic(double a, double f)
a
 equatorial radius (meters).f
 flattening of ellipsoid. Setting f = 0 gives a sphere.
Negative f gives a prolate ellipsoid.GeographicErr
 if a or (1 − f ) a is
not positive.public GeodesicData Direct(double lat1, double lon1, double azi1, double s12)
lat1
 latitude of point 1 (degrees).lon1
 longitude of point 1 (degrees).azi1
 azimuth at point 1 (degrees).s12
 distance between point 1 and point 2 (meters); it can be
negative.GeodesicData
object with the following fields:
lat1, lon1, azi1, lat2, lon2,
azi2, s12, a12.
lat1 should be in the range [−90°, 90°]. The values of lon2 and azi2 returned are in the range [−180°, 180°].
If either point is at a pole, the azimuth is defined by keeping the longitude fixed, writing lat = ±(90° − ε), and taking the limit ε → 0+. An arc length greater that 180° signifies a geodesic which is not a shortest path. (For a prolate ellipsoid, an additional condition is necessary for a shortest path: the longitudinal extent must not exceed of 180°.)
public GeodesicData Direct(double lat1, double lon1, double azi1, double s12, int outmask)
lat1
 latitude of point 1 (degrees).lon1
 longitude of point 1 (degrees).azi1
 azimuth at point 1 (degrees).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.GeodesicData
object with the fields specified by
outmask computed.
lat1, lon1, azi1, s12, and a12 are
always included in the returned result. The value of lon2 returned
is in the range [−180°, 180°], unless the outmask
includes the GeodesicMask.LONG_UNROLL
flag.
public GeodesicData ArcDirect(double lat1, double lon1, double azi1, double a12)
lat1
 latitude of point 1 (degrees).lon1
 longitude of point 1 (degrees).azi1
 azimuth at point 1 (degrees).a12
 arc length between point 1 and point 2 (degrees); it can
be negative.GeodesicData
object with the following fields:
lat1, lon1, azi1, lat2, lon2,
azi2, s12, a12.
lat1 should be in the range [−90°, 90°]. The values of lon2 and azi2 returned are in the range [−180°, 180°].
If either point is at a pole, the azimuth is defined by keeping the longitude fixed, writing lat = ±(90° − ε), and taking the limit ε → 0+. An arc length greater that 180° signifies a geodesic which is not a shortest path. (For a prolate ellipsoid, an additional condition is necessary for a shortest path: the longitudinal extent must not exceed of 180°.)
public GeodesicData ArcDirect(double lat1, double lon1, double azi1, double a12, int outmask)
lat1
 latitude of point 1 (degrees).lon1
 longitude of point 1 (degrees).azi1
 azimuth at point 1 (degrees).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.GeodesicData
object with the fields specified by
outmask computed.
lat1, lon1, azi1, and a12 are always included
in the returned result. The value of lon2 returned is in the range
[−180°, 180°], unless the outmask includes the GeodesicMask.LONG_UNROLL
flag.
public GeodesicData Direct(double lat1, double lon1, double azi1, boolean arcmode, double s12_a12, int outmask)
lat1
 latitude of point 1 (degrees).lon1
 longitude of point 1 (degrees).azi1
 azimuth at point 1 (degrees).arcmode
 boolean flag determining the meaning of the
s12_a12.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.GeodesicData
object with the fields specified by
outmask computed.
The GeodesicMask
values possible for outmask are
GeodesicMask.LATITUDE
for the latitude
lat2;
GeodesicMask.LONGITUDE
for the latitude
lon2;
GeodesicMask.AZIMUTH
for the latitude
azi2;
GeodesicMask.DISTANCE
for the distance
s12;
GeodesicMask.REDUCEDLENGTH
for the reduced
length m12;
GeodesicMask.GEODESICSCALE
for the geodesic
scales M12 and M21;
GeodesicMask.AREA
for the area S12;
GeodesicMask.ALL
for all of the above;
GeodesicMask.LONG_UNROLL
, if set then
lon1 is unchanged and lon2 − lon1 indicates
how many times and in what sense the geodesic encircles the ellipsoid.
Otherwise lon1 and lon2 are both reduced to the range
[−180°, 180°].
The function value a12 is always computed and returned and this
equals s12_a12 is arcmode is true. If outmask
includes GeodesicMask.DISTANCE
and arcmode is false, then
s12 = s12_a12. It is not necessary to include GeodesicMask.DISTANCE_IN
in outmask; this is automatically
included is arcmode is false.
public GeodesicLine DirectLine(double lat1, double lon1, double azi1, double s12)
GeodesicLine
in terms of the direct geodesic problem
specified in terms of distance with all capabilities included.
lat1
 latitude of point 1 (degrees).lon1
 longitude of point 1 (degrees).azi1
 azimuth at point 1 (degrees).s12
 distance between point 1 and point 2 (meters); it can be
negative.GeodesicLine
object.
This function sets point 3 of the GeodesicLine to correspond to point 2 of the direct geodesic problem.
lat1 should be in the range [−90°, 90°].
public GeodesicLine DirectLine(double lat1, double lon1, double azi1, double s12, int caps)
GeodesicLine
in terms of the direct geodesic problem
specified in terms of distance with a subset of the capabilities included.
lat1
 latitude of point 1 (degrees).lon1
 longitude of point 1 (degrees).azi1
 azimuth at point 1 (degrees).s12
 distance between point 1 and point 2 (meters); it can be
negative.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
GeodesicLine.Position
.GeodesicLine
object.
This function sets point 3 of the GeodesicLine to correspond to point 2 of the direct geodesic problem.
lat1 should be in the range [−90°, 90°].
public GeodesicLine ArcDirectLine(double lat1, double lon1, double azi1, double a12)
GeodesicLine
in terms of the direct geodesic problem
specified in terms of arc length with all capabilities included.
lat1
 latitude of point 1 (degrees).lon1
 longitude of point 1 (degrees).azi1
 azimuth at point 1 (degrees).a12
 arc length between point 1 and point 2 (degrees); it can
be negative.GeodesicLine
object.
This function sets point 3 of the GeodesicLine to correspond to point 2 of the direct geodesic problem.
lat1 should be in the range [−90°, 90°].
public GeodesicLine ArcDirectLine(double lat1, double lon1, double azi1, double a12, int caps)
GeodesicLine
in terms of the direct geodesic problem
specified in terms of arc length with a subset of the capabilities
included.
lat1
 latitude of point 1 (degrees).lon1
 longitude of point 1 (degrees).azi1
 azimuth at point 1 (degrees).a12
 arc length between point 1 and point 2 (degrees); it can
be negative.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
GeodesicLine.Position
.GeodesicLine
object.
This function sets point 3 of the GeodesicLine to correspond to point 2 of the direct geodesic problem.
lat1 should be in the range [−90°, 90°].
public GeodesicLine GenDirectLine(double lat1, double lon1, double azi1, boolean arcmode, double s12_a12, int caps)
GeodesicLine
in terms of the direct geodesic problem
specified in terms of either distance or arc length with a subset of the
capabilities included.
lat1
 latitude of point 1 (degrees).lon1
 longitude of point 1 (degrees).azi1
 azimuth at point 1 (degrees).arcmode
 boolean flag determining the meaning of the s12_a12.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.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
GeodesicLine.Position
.GeodesicLine
object.
This function sets point 3 of the GeodesicLine to correspond to point 2 of the direct geodesic problem.
lat1 should be in the range [−90°, 90°].
public GeodesicData Inverse(double lat1, double lon1, double lat2, double lon2)
lat1
 latitude of point 1 (degrees).lon1
 longitude of point 1 (degrees).lat2
 latitude of point 2 (degrees).lon2
 longitude of point 2 (degrees).GeodesicData
object with the following fields:
lat1, lon1, azi1, lat2, lon2,
azi2, s12, a12.
lat1 and lat2 should be in the range [−90°, 90°]. The values of azi1 and azi2 returned are in the range [−180°, 180°].
If either point is at a pole, the azimuth is defined by keeping the longitude fixed, writing lat = ±(90° − ε), taking the limit ε → 0+.
The solution to the inverse problem is found using Newton's method. If this fails to converge (this is very unlikely in geodetic applications but does occur for very eccentric ellipsoids), then the bisection method is used to refine the solution.
public GeodesicData Inverse(double lat1, double lon1, double lat2, double lon2, int outmask)
lat1
 latitude of point 1 (degrees).lon1
 longitude of point 1 (degrees).lat2
 latitude of point 2 (degrees).lon2
 longitude of point 2 (degrees).outmask
 a bitor'ed combination of GeodesicMask
values
specifying which results should be returned.GeodesicData
object with the fields specified by
outmask computed.
The GeodesicMask
values possible for outmask are
GeodesicMask.DISTANCE
for the distance
s12;
GeodesicMask.AZIMUTH
for the latitude
azi2;
GeodesicMask.REDUCEDLENGTH
for the reduced
length m12;
GeodesicMask.GEODESICSCALE
for the geodesic
scales M12 and M21;
GeodesicMask.AREA
for the area S12;
GeodesicMask.ALL
for all of the above.
GeodesicMask.LONG_UNROLL
, if set then
lon1 is unchanged and lon2 − lon1 indicates
whether the geodesic is east going or west going. Otherwise lon1
and lon2 are both reduced to the range [−180°,
180°].
lat1, lon1, lat2, lon2, and a12 are always included in the returned result.
public GeodesicLine InverseLine(double lat1, double lon1, double lat2, double lon2)
GeodesicLine
in terms of the inverse geodesic problem
with all capabilities included.
lat1
 latitude of point 1 (degrees).lon1
 longitude of point 1 (degrees).lat2
 latitude of point 2 (degrees).lon2
 longitude of point 2 (degrees).GeodesicLine
object.
This function sets point 3 of the GeodesicLine to correspond to point 2 of the inverse geodesic problem.
lat1 and lat2 should be in the range [−90°, 90°].
public GeodesicLine InverseLine(double lat1, double lon1, double lat2, double lon2, int caps)
GeodesicLine
in terms of the inverse geodesic problem
with a subset of the capabilities included.
lat1
 latitude of point 1 (degrees).lon1
 longitude of point 1 (degrees).lat2
 latitude of point 2 (degrees).lon2
 longitude of point 2 (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
GeodesicLine.Position
.GeodesicLine
object.
This function sets point 3 of the GeodesicLine to correspond to point 2 of the inverse geodesic problem.
lat1 and lat2 should be in the range [−90°, 90°].
public GeodesicLine Line(double lat1, double lon1, double azi1)
lat1
 latitude of point 1 (degrees).lon1
 longitude of point 1 (degrees).azi1
 azimuth at point 1 (degrees).GeodesicLine
object.
lat1 should be in the range [−90°, 90°]. The full set of capabilities is included.
If the point is at a pole, the azimuth is defined by keeping the lon1 fixed, writing lat1 = ±(90 − ε), taking the limit ε → 0+.
public GeodesicLine Line(double lat1, double lon1, double azi1, int caps)
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 GeodesicLine.Position
.GeodesicLine
object.
The GeodesicMask
values are
GeodesicMask.LATITUDE
for the latitude
lat2; this is added automatically;
GeodesicMask.LONGITUDE
for the latitude
lon2;
GeodesicMask.AZIMUTH
for the azimuth azi2;
this is added automatically;
GeodesicMask.DISTANCE
for the distance
s12;
GeodesicMask.REDUCEDLENGTH
for the reduced length
m12;
GeodesicMask.GEODESICSCALE
for the geodesic
scales M12 and M21;
GeodesicMask.AREA
for the area S12;
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;
GeodesicMask.ALL
for all of the above.
If the point is at a pole, the azimuth is defined by keeping lon1 fixed, writing lat1 = ±(90 − ε), and taking the limit ε → 0+.
public double MajorRadius()
public double Flattening()
public double EllipsoidArea()
Copyright © 2017. All Rights Reserved.