net.sf.geographiclib.package-info Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of GeographicLib-Java Show documentation
This is a Java implementation of the geodesic algorithms from GeographicLib. This is a self-contained library to solve geodesic problems on an ellipsoid model of the earth. It requires Java version 1.7 or later.
There is a newer version: 2.0
Show newest version
/**
 * Geodesic routines from GeographicLib implemented in Java
 * @author Charles F. F. Karney ([email protected])
 * @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
 * 
 * 
 *   
 *   GeographicLib-1.49.tar.gz
 * 

 *   
 *   GeographicLib-1.49.zip
 * 
 * 
 * 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 {@code
 *   
 *     net.sf.geographiclib
 *     GeographicLib-Java
 *     1.49
 *    }
 * in your {@code pom.xml}.
 *
 * Sample programs
 * 
 * Included with the source are 3 small test programs
 * 

 * 
 *    {@code direct/src/main/java/Direct.java} is a simple command line utility
 *    for solving the direct geodesic problem;
 * 

 *    {@code inverse/src/main/java/Inverse.java} is a simple command line
 *    utility for solving the inverse geodesic problem;
 * 

 *    {@code 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 {@code Inverse.java} 
{@code
 * // 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 {@code 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 {@code Inverse.java}
 * The sample code includes a {@code 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
 * 

 * 
 *   {@link net.sf.geographiclib.Geodesic}, for direct and inverse geodesic
 *   calculations;
 * 

 *   {@link net.sf.geographiclib.GeodesicLine}, an efficient way of
 *   calculating multiple points on a single geodesic;
 * 

 *   {@link net.sf.geographiclib.GeodesicData}, the object containing the
 *   results of the geodesic calculations;
 * 

 *   {@link net.sf.geographiclib.GeodesicMask}, the constants that let you
 *   specify the variables to return in {@link
 *   net.sf.geographiclib.GeodesicData} and the capabilities of a {@link
 *   net.sf.geographiclib.GeodesicLine};
 * 

 *   {@link net.sf.geographiclib.Constants}, the parameters for the WGS84
 *   ellipsoid;
 * 

 *   {@link net.sf.geographiclib.PolygonArea}, a class to compute the
 *   perimeter and area of a geodesic polygon (returned as a {@link
 *   net.sf.geographiclib.PolygonResult}).
 * 
 * 
 * The documentation is generated using javadoc when
 * {@code mvn package -P release} is run (the top of the documentation tree is
 * {@code target/apidocs/index.html}).  This is also available on the web at
 * 
 * https://geographiclib.sourceforge.io/html/java/index.html.
 *
 * 
External links
 * 
 * 
 *   These algorithms are derived in C. F. F. Karney,
 *   
 *   Algorithms for geodesics,
 *   J. Geodesy 87, 43–55 (2013)
 *   (addenda).
 * 

 *   A longer paper on geodesics: C. F. F. Karney,
 *   Geodesics
 *   on an ellipsoid of revolution,
 *   Feb. 2011
 *   (
 *   errata).
 * 

 *   
 *   The GeographicLib web site.
 * 

 *   
 *     Main project page
 * 

 *   
 *     git repository
 * 

 *   Implementations in various languages:
 *   
 *     
 *       C++ (complete library):
 *       
 *         documentation,
 *       
 *         download
 *     

 *       C (geodesic routines):
 *       
 *         documentation, also included with recent versions of
 *       
 *         proj.4
 *     

 *       Fortran (geodesic routines):
 *       
 *         documentation
 *     

 *       Java (geodesic routines):
 *       
 *         Maven Central package,
 *       
 *         documentation
 *     

 *       JavaScript (geodesic routines):
 *       
 *         npm package,
 *       
 *         documentation
 *     

 *       Python (geodesic routines):
 *       
 *         PyPI package,
 *       
 *         documentation
 *     

 *       Matlab/Octave (geodesic and some other routines):
 *       
 *         Matlab Central package,
 *       
 *         documentation
 *     

 *       C# (.NET wrapper for complete C++ library):
 *       
 *         documentation.
 *   
 * 

 *   The section in the GeographicLib documentation on geodesics:
 *   
 *   Geodesics on an ellipsoid of revolution
 * 

 *   
 *   A geodesic bibliography
 * 

 *   The wikipedia page,
 *   
 *   Geodesics on an ellipsoid
 * 
 *
 * 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
 *   {@link net.sf.geographiclib.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.
 * 
 * 
 **********************************************************************/
package net.sf.geographiclib;