Package net.sf.geographiclib

Geodesic routines from GeographicLib implemented in Java

Version:
2.0

The documentation for other versions is available at https://geographiclib.sourceforge.io/Java/.

Licensed under the MIT/X11 License; see LICENSE.txt.

Abstract

GeographicLib-Java is a Java implementation of the geodesic algorithms from GeographicLib. This is a self-contained library which makes it easy to do geodesic computations for an ellipsoid of revolution in a Java program. It requires Java version 1.7 or later.

Downloading

Download either the source or the pre-built package as follows:

The pre-built package

GeographicLib-Java is available as a pre-built package on Maven Central (thanks to Chris Bennight for help on this deployment). So, if you use maven to build your code, you just need to include the dependency 

   <dependency>
     <groupId>net.sf.geographiclib</groupId>
     <artifactId>GeographicLib-Java</artifactId>
     <version>2.0</version>
   </dependency>
in your pom.xml.

Obtaining the source

The source is hosted on github. Releases are tagged as v1.52, v2.0, etc.

Sample programs

Included with the source are 3 small test programs

  • direct/src/main/java/Direct.java is a simple command line utility for solving the direct geodesic problem;
  • inverse/src/main/java/Inverse.java is a simple command line utility for solving the inverse geodesic problem;
  • planimeter/src/main/java/Planimeter.java is a simple command line utility for computing the area of a geodesic polygon given its vertices.

Here, for example, is Inverse.java 


 // Solve the inverse geodesic problem.
 //
 // This program reads in lines with lat1, lon1, lat2, lon2 and prints
 // out lines with azi1, azi2, s12 (for the WGS84 ellipsoid).

 import java.util.*;
 import net.sf.geographiclib.*;
 public class Inverse {
   public static void main(String[] args) {
     try {
       Scanner in = new Scanner(System.in);
       double lat1, lon1, lat2, lon2;
       while (true) {
         lat1 = in.nextDouble(); lon1 = in.nextDouble();
         lat2 = in.nextDouble(); lon2 = in.nextDouble();
         GeodesicData g = Geodesic.WGS84.Inverse(lat1, lon1, lat2, lon2);
         System.out.format("%.11f %.11f %.6f%n", g.azi1, g.azi2, g.s12);
       }
     }
     catch (Exception e) {}
   }
 }

Compiling and running a sample program

Here's how to compile and run Inverse.java using maven (the recommended way) and without using maven. (Thanks to Skip Breidbach for supplying the maven support.)

Using maven

The sample code includes a pom.xml which specifies GeographicLib-Java as a dependency which maven will download from Maven Central. You can compile and run Inverse.java with 
 cd inverse
 mvn compile
 echo -30 0 29.5 179.5 | mvn -q exec:java

Without using maven

Compile and run as follows 
 cd inverse/src/main/java
 javac -cp .:../../../../src/main/java Inverse.java
 echo -30 0 29.5 179.5 | java -cp .:../../../../src/main/java Inverse

Using the library

  • Put 
       import net.sf.geographiclib.*
    in your source code.
  • Make calls to the geodesic routines from your code.
  • Compile and run in one of the ways described above.

The important classes are

  • Geodesic, for direct and inverse geodesic calculations;
  • GeodesicLine, an efficient way of calculating multiple points on a single geodesic;
  • GeodesicData, the object containing the results of the geodesic calculations;
  • GeodesicMask, the constants that let you specify the variables to return in GeodesicData and the capabilities of a GeodesicLine;
  • Constants, the parameters for the WGS84 ellipsoid;
  • PolygonArea, a class to compute the perimeter and area of a geodesic polygon (returned as a PolygonResult).

The documentation is generated using javadoc when mvn package -P release is run (the top of the documentation tree is target/apidocs/index.html). This is also available on the web at https://geographiclib.sourceforge.io/html/java/index.html.

External links

Change log

  • Version 2.0 (released 2022-04-25)
    • This is a major reorganization with the Java library put into its own github repository. Despite this, there are only reasonably minor changes to the library itself.
    • Fix bug where the solution of the inverse geodesic problem with φ1 = 0 and φ2 = nan was treated as equatorial.
    • More careful treatment of ±0° and ±180°.
      • These behave consistently with taking the limits
        • ±0 means ±ε as ε → 0+
        • ±180 means ±(180 − ε) as ε → 0+
      • As a consequence, azimuths of +0° and +180° are reckoned to be east-going, as far as tracking the longitude with GeodesicMask.LONG_UNROLL and the area goes, while azimuths −0° and −180° are reckoned to be west-going.
      • When computing longitude differences, if λ2 − λ1 = ±180° (mod 360°), then the sign is picked depending on the sign of the difference.
      • The normal range for returned longitudes and azimuths is [−180°, 180°].
      • A separate test suite signtest.SignTest has been added to check this treatment.
    • The deprecated functions Geodesic.MajorRadius(), etc., have been removed.
  • Version 1.52 (released 2021-06-21)
    • Be more aggressive in preventing negative s12 and m12 for short lines.
  • Version 1.51 (released 2020-11-22)
    • In order to reduce the amount of memory allocation and garbage collection, introduce versions of GeoMath.norm, GeoMath.sum, GeoMath.AngDiff, and GeoMath.sincosd, which take a Pair as a parameter instead of returning a new Pair. The previous versions are deprecated.
    • Geodesic.MajorRadius() is now called Geodesic.EquatorialRadius() and similarly for GeodesicLine, Gnomonic, and PolygonArea.
    • Update to Java 1.7 or later to support testing on Mac OSX.
  • Version 1.50 (released 2019-09-24)
    • PolygonArea can now handle arbitrarily complex polygons. In the case of self-intersecting polygons the area is accumulated "algebraically", e.g., the areas of the 2 loops in a figure-8 polygon will partially cancel.
    • Fix two bugs in the computation of areas when some vertices are specified by an added edge.
    • Require Java 1.6 or later and so remove epsilon, min, hypot, log1p, copysign, cbrt from GeoMath.
    • GeoMath.cbrt, GeoMath.atanh, and GeoMath.asinh preserve the sign of −0.
  • Version 1.49 (released 2017-10-05)
    • Fix code formatting and add two tests.
  • Version 1.48 (released 2017-04-09)
    • Change default range for longitude and azimuth to (−180°, 180°] (instead of [−180°, 180°)).
  • Version 1.47 (released 2017-02-15)
    • Improve accuracy of area calculation (fixing a flaw introduced in version 1.46).
  • Version 1.46 (released 2016-02-15)
    • Fix bug where the wrong longitude was being returned with direct geodesic calculation with a negative distance when starting point was at a pole (this bug was introduced in version 1.44).
    • Add Geodesic.DirectLine, Geodesic.ArcDirectLine, Geodesic.GenDirectLine, Geodesic.InverseLine, GeodesicLine.SetDistance, GeodesicLine.SetArc, GeodesicLine.GenSetDistance, GeodesicLine.Distance, GeodesicLine.Arc, GeodesicLine.GenDistance.
    • More accurate inverse solution when longitude difference is close to 180°.
    • GeoMath.AngDiff now returns a Pair.
  • Version 1.45 (released 2015-09-30)
    • The solution of the inverse problem now correctly returns NaNs if one of the latitudes is a NaN.
    • Add implementation of the ellipsoidal Gnomonic (courtesy of Sebastian Mattheis).
    • Math.toRadians and Math.toDegrees are used instead of GeoMath.degree (which is now removed). This requires Java 1.2 or later (released 1998-12).
  • Version 1.44 (released 2015-08-14)
    • Improve accuracy of calculations by evaluating trigonometric functions more carefully and replacing the series for the reduced length with one with a smaller truncation error.
    • The allowed ranges for longitudes and azimuths is now unlimited; it used to be [−540°, 540°).
    • Enforce the restriction of latitude to [−90°, 90°] by returning NaNs if the latitude is outside this range.
    • Geodesic.Inverse sets s12 to zero for coincident points at pole (instead of returning a tiny quantity).
    • Geodesic.Inverse pays attentions to the GeodesicMask.LONG_UNROLL bit in outmask.
Author:
Charles F. F. Karney (charles@karney.com)