Skip navigation links

Package net.sf.geographiclib

Geodesic routines from GeographicLib implemented in Java

See: Description

Package net.sf.geographiclib Description

Geodesic routines from GeographicLib implemented in Java

Version:
1.49

The documentation for other versions is available at https://geographiclib.sourceforge.io/m.nn/java for versions numbers m.nn ≥ 1.31.

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.2 or later.

Downloading

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

Obtaining the source

GeographicLib-Java is part of GeographicLib which available for download at

as either a compressed tar file (tar.gz) or a zip file. After unpacking the source, the Java library can be found in GeographicLib-1.49/java. (This library is completely independent from the rest of GeodegraphicLib.) The library consists of the files in the src/main/java/net/sf/geographiclib subdirectory.

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>1.49</version>
   </dependency> 
in your pom.xml.

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.println(g.azi1 + " " + g.azi2 + " " + g.s12);
       }
     }
     catch (Exception e) {}
   }
 }

Compiling and running a sample program

Three difference ways of compiling and running Inverse.java are given. These differ in the degree to which they utilize maven to manage your Java code and its dependencies. (Thanks to Skip Breidbach for supplying the maven support.)

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 
On Windows, change this to
 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 maven to package GeographicLib

Use maven to create a jar file by running (in the main java directory)
 mvn package 
(Your first run of maven may take a long time, because it needs to download some additional packages to your local repository.) Then compile and run Inverse.java with
 cd inverse/src/main/java
 javac -cp .:../../../../target/GeographicLib-Java-1.49.jar Inverse.java
 echo -30 0 29.5 179.5 |
   java -cp .:../../../../target/GeographicLib-Java-1.49.jar Inverse 

Using maven to build and run Inverse.java

The sample code includes a pom.xml which specifies GeographicLib-Jave as a dependency. You can build and install this dependency by running (in the main java directory)
 mvn install 
Alternatively, you can let maven download it 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 

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 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)
Skip navigation links

Copyright © 2017. All Rights Reserved.