sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject [sis] 02/02: Document better the algorithm source and the accuracy.
Date Wed, 31 Jul 2019 14:58:27 GMT
This is an automated email from the ASF dual-hosted git repository.

desruisseaux pushed a commit to branch geoapi-4.0
in repository https://gitbox.apache.org/repos/asf/sis.git

commit efb50393c3cc73ace142572dc0df222788c5a76b
Author: Martin Desruisseaux <martin.desruisseaux@geomatys.com>
AuthorDate: Wed Jul 31 11:17:43 2019 +0200

    Document better the algorithm source and the accuracy.
---
 .../sis/referencing/GeodesicsOnEllipsoid.java      | 32 ++++++++++++++--------
 .../apache/sis/referencing/GeodeticCalculator.java | 30 +++++++++++++++++---
 .../sis/referencing/GeodeticCalculatorTest.java    |  4 +--
 ide-project/NetBeans/nbproject/genfiles.properties |  2 +-
 ide-project/NetBeans/nbproject/project.xml         |  1 +
 5 files changed, 50 insertions(+), 19 deletions(-)

diff --git a/core/sis-referencing/src/main/java/org/apache/sis/referencing/GeodesicsOnEllipsoid.java
b/core/sis-referencing/src/main/java/org/apache/sis/referencing/GeodesicsOnEllipsoid.java
index 7ccf8ef..27fd3fd 100644
--- a/core/sis-referencing/src/main/java/org/apache/sis/referencing/GeodesicsOnEllipsoid.java
+++ b/core/sis-referencing/src/main/java/org/apache/sis/referencing/GeodesicsOnEllipsoid.java
@@ -80,12 +80,23 @@ import static org.apache.sis.internal.metadata.ReferencingServices.NAUTICAL_MILE
  */
 class GeodesicsOnEllipsoid extends GeodeticCalculator {
     /**
-     * Whether to include code used for JUnit tests only.
-     * This value should be {@code false} in releases.
+     * Factor by which the accuracy is improved compared to {@link Formulas#ANGULAR_TOLERANCE}
value.
+     * For example the linear accuracy that {@code GeodesicsOnEllipsoid} aims to achieve
is:
      *
-     * @see #snapshot()
+     * <blockquote><code>
+     * accuracy = {@linkplain Formulas#LINEAR_TOLERANCE} / ACCURACY_IMPROVEMENT
+     * </code></blockquote>
+     *
+     * We take a finer accuracy than default SIS configuration in order to met the accuracy
of numbers
+     * published in Karney (2013). If this value is modified, the effect can be verified
by executing
+     * the {@code GeodesicsOnEllipsoidTest} methods that compare computed values against
Karney's tables.
+     * Remember to update {@link GeodeticCalculator} class javadoc if this value is changed.
+     *
+     * <p><b>Note:</b> when the iteration loop detects that it reached
this requested accuracy, the loop
+     * completes the iteration step which was in progress. Consequently the final accuracy
is one iteration
+     * better than the accuracy computed from this value.</p>
      */
-    static final boolean STORE_LOCAL_VARIABLES = true;
+    static final double ACCURACY_IMPROVEMENT = 20;
 
     /**
      * Difference between ending point and antipode of starting point for considering them
as nearly antipodal.
@@ -115,15 +126,12 @@ class GeodesicsOnEllipsoid extends GeodeticCalculator {
     private static final double LATITUDE_THRESHOLD = 0.001 / (NAUTICAL_MILE*60) * (PI/180);
 
     /**
-     * Desired accuracy in radians. We take a finer accuracy than default SIS configuration
in order to met the
-     * accuracy of numbers published in Karney (2013). If this value is modified, the effect
can be verified by
-     * executing the {@code GeodesicsOnEllipsoidTest} methods that compare computed values
against Karney's tables.
+     * Whether to include code used for JUnit tests only.
+     * This value should be {@code false} in releases.
      *
-     * <p><b>Note:</b> when the iteration loop detects that it reached
this accuracy, the loop completes the
-     * iteration step which was in progress. Consequently the final accuracy is one iteration
better than this
-     * accuracy.</p>
+     * @see #snapshot()
      */
-    private static final double ACCURACY = Formulas.ANGULAR_TOLERANCE * (PI/180) / 20;
+    static final boolean STORE_LOCAL_VARIABLES = true;
 
     /**
      * The square of eccentricity: ℯ² = (a²-b²)/a² where
@@ -746,7 +754,7 @@ class GeodesicsOnEllipsoid extends GeodeticCalculator {
             λ1E = sphericalToGeodeticLongitude(ω1, σ1);
             λ2E = sphericalToGeodeticLongitude(ω2, σ2);
             final double Δλ_error = IEEEremainder(λ2E - λ1E - Δλ, 2*PI);
-            final boolean done = (abs(Δλ_error) <= ACCURACY);
+            final boolean done = (abs(Δλ_error) <= Formulas.ANGULAR_TOLERANCE * (PI/180)
/ ACCURACY_IMPROVEMENT);
             if (--nbIter < 0 && !done) {
                 throw new GeodesicException(Resources.format(Resources.Keys.NoConvergence));
             }
diff --git a/core/sis-referencing/src/main/java/org/apache/sis/referencing/GeodeticCalculator.java
b/core/sis-referencing/src/main/java/org/apache/sis/referencing/GeodeticCalculator.java
index 70cccd3..b225bf6 100644
--- a/core/sis-referencing/src/main/java/org/apache/sis/referencing/GeodeticCalculator.java
+++ b/core/sis-referencing/src/main/java/org/apache/sis/referencing/GeodeticCalculator.java
@@ -72,15 +72,37 @@ import static java.lang.Math.*;
  *   </li>
  * </ul>
  *
+ * <div class="section">Algorithms and accuracy</div>
+ * {@code GeodeticCalculator} uses two set of formulas, depending if the figure of the Earth
+ * {@linkplain Ellipsoid#isSphere() is a sphere} or an ellipsoid.
+ * Publications relevant to this class are:
+ *
+ * <ul>
+ *   <li>Wikipedia, <a href="https://en.wikipedia.org/wiki/Great-circle_navigation">Great-circle
navigation</a>
+ *       for the spherical formulas.</li>
+ *   <li>Charles F. F. Karney (2013), <a href="https://doi.org/10.1007/s00190-012-0578-z">Algorithms
for geodesics</a>
+ *       for the ellipsoidal formulas.</li>
+ *   <li>Charles F. F. Karney (2010), <a href="http://doi.org/10.5281/zenodo.32156">Test
set for geodesics</a>
+ *       for {@code GeodeticCalculator} tests.</li>
+ *   <li>Charles F. F. Karney, <a href="https://geographiclib.sourceforge.io/">GeographicLib</a>
+ *       for the reference implementation.</li>
+ * </ul>
+ *
+ * {@code GeodeticCalculator} aims for a positional accuracy of one millimetre.
+ * Azimuthal accuracy corresponds to an error of one millimeter at a distance of one kilometer,
+ * except for nearly antipodal points (less than 1° of longitude and latitude from antipode)
+ * and points close to the poles where the azimuthal errors are larger.
+ * Karney's GeographicLib should be used if better accuracy is desired.
+ * Apache SIS accuracy does not go as far as GeographicLib because the rest of Apache SIS
+ * library (map projections, <i>etc.</i>) aims for an one centimetre accuracy
anyway.
+ *
+ * <div class="section">Thread safety</div>
  * This class is not thread-safe. If geodetic calculations are needed in a multi-threads
environment,
  * then a distinct instance of {@code GeodeticCalculator} needs to be created for each thread.
  *
  * @author  Martin Desruisseaux (Geomatys)
  * @version 1.0
- *
- * @see <a href="https://en.wikipedia.org/wiki/Great-circle_navigation">Great-circle
navigation on Wikipedia</a>
- *
- * @since 1.0
+ * @since   1.0
  * @module
  */
 public class GeodeticCalculator {
diff --git a/core/sis-referencing/src/test/java/org/apache/sis/referencing/GeodeticCalculatorTest.java
b/core/sis-referencing/src/test/java/org/apache/sis/referencing/GeodeticCalculatorTest.java
index a822518..9972170 100644
--- a/core/sis-referencing/src/test/java/org/apache/sis/referencing/GeodeticCalculatorTest.java
+++ b/core/sis-referencing/src/test/java/org/apache/sis/referencing/GeodeticCalculatorTest.java
@@ -490,11 +490,11 @@ public strictfp class GeodeticCalculatorTest extends TestCase {
                     }
                 } else {
                     /*
-                     * When ellipsoidal formulas are used, we aim for an 1 cm accuracy in
coordinate values.
+                     * When ellipsoidal formulas are used, we aim for an 1 mm accuracy in
coordinate values.
                      * We also aim for azimuthd such as the error is less than 1 cm after
the first 10 km.
                      * If points are nearly antipodal, we relax the azimuth tolerance threshold
to 1 meter.
                      */
-                    linearTolerance    = Formulas.LINEAR_TOLERANCE;
+                    linearTolerance    = Formulas.LINEAR_TOLERANCE / GeodesicsOnEllipsoid.ACCURACY_IMPROVEMENT;
                     latitudeTolerance  = Formulas.ANGULAR_TOLERANCE;
                     longitudeTolerance = Formulas.ANGULAR_TOLERANCE / cosφ2;
                     azimuthTolerance   = Formulas.LINEAR_TOLERANCE * (180/PI) / 10000;
diff --git a/ide-project/NetBeans/nbproject/genfiles.properties b/ide-project/NetBeans/nbproject/genfiles.properties
index 1bc6a00..829da57 100644
--- a/ide-project/NetBeans/nbproject/genfiles.properties
+++ b/ide-project/NetBeans/nbproject/genfiles.properties
@@ -3,6 +3,6 @@
 build.xml.data.CRC32=58e6b21c
 build.xml.script.CRC32=462eaba0
 build.xml.stylesheet.CRC32=28e38971@1.53.1.46
-nbproject/build-impl.xml.data.CRC32=30bc0b09
+nbproject/build-impl.xml.data.CRC32=2c1568a8
 nbproject/build-impl.xml.script.CRC32=9b707f2e
 nbproject/build-impl.xml.stylesheet.CRC32=3a2fa800@1.91.1.48
diff --git a/ide-project/NetBeans/nbproject/project.xml b/ide-project/NetBeans/nbproject/project.xml
index 61072de..0592484 100644
--- a/ide-project/NetBeans/nbproject/project.xml
+++ b/ide-project/NetBeans/nbproject/project.xml
@@ -113,6 +113,7 @@
             <word>marshalling</word>
             <word>metadata</word>
             <word>metres</word>
+            <word>millimetre</word>
             <word>monospaced</word>
             <word>namespace</word>
             <word>namespaces</word>


Mime
View raw message