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 which makes it easy to do geodesic computations for an ellipsoid of revolution in a Java program. It requires Java version 1.1 or later.
The newest version!
/**
 * Geodesic routines from GeographicLib implemented in Java
 * @author Charles F. F. Karney ([email protected])
 * @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 {@code
 *   
 *     net.sf.geographiclib
 *     GeographicLib-Java
 *     2.0
 *    }
 * in your {@code 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
 * 

 * 
 *    {@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.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 {@code 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 {@code 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
 * 

 * 
 *   {@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.
 * 

 *   
 *     git repository
 * 

 *   The library has been implemented in a few other
 *   
 *   languages
 * 

 *   
 *   A geodesic bibliography
 * 

 *   The wikipedia page,
 *   
 *   Geodesics on an ellipsoid
 * 
 *
 * 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
 *    φ₁ = 0 and φ₂ = 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
 *      {@link net.sf.geographiclib.GeodesicMask#LONG_UNROLL} and the area
 *      goes, while azimuths −0° and −180° are reckoned to
 *      be west-going.
 *   

 *      When computing longitude differences, if λ₂
 *      − λ₁ = ±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 {@link net.sf.geographiclib.Pair} as a
 *   parameter instead of returning a new {@link net.sf.geographiclib.Pair}.
 *   The previous versions are deprecated.
 * 

 *   Geodesic.MajorRadius() is now called
 *   {@link net.sf.geographiclib.Geodesic#EquatorialRadius()} and similarly for
 *   {@link net.sf.geographiclib.GeodesicLine},
 *   {@link net.sf.geographiclib.Gnomonic}, and
 *   {@link net.sf.geographiclib.PolygonArea}.
 * 

 *   Update to Java 1.7 or later to support testing on Mac OSX.
 * 
 * 

 *   Version 1.50
 *   (released 2019-09-24)
 * 
 * 
 *   {@link net.sf.geographiclib.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
 *   {@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;