sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject [sis] 01/02: Renamed GeodeticCalculator.createCircularRegion2D(…) as createGeodesicCircle2D(…).
Date Wed, 31 Jul 2019 14:58:26 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 2aecabdc69a4400f664ff133968d981e2e27d3a8
Author: Martin Desruisseaux <martin.desruisseaux@geomatys.com>
AuthorDate: Sun Jul 28 10:13:22 2019 +0200

    Renamed GeodeticCalculator.createCircularRegion2D(…) as createGeodesicCircle2D(…).
---
 .../org/apache/sis/distance/LatLonPointRadius.java |  2 +-
 .../apache/sis/referencing/GeodeticCalculator.java | 27 +++++++++++++++-------
 .../sis/referencing/GeodeticCalculatorTest.java    |  6 ++---
 3 files changed, 23 insertions(+), 12 deletions(-)

diff --git a/core/sis-referencing/src/main/java/org/apache/sis/distance/LatLonPointRadius.java
b/core/sis-referencing/src/main/java/org/apache/sis/distance/LatLonPointRadius.java
index a485f43..976bec6 100644
--- a/core/sis-referencing/src/main/java/org/apache/sis/distance/LatLonPointRadius.java
+++ b/core/sis-referencing/src/main/java/org/apache/sis/distance/LatLonPointRadius.java
@@ -36,7 +36,7 @@ import org.apache.sis.referencing.GeodeticCalculator;
  * Represents a 2D point associated with a radius to enable great circle
  * estimation on earth surface.
  *
- * @deprecated Replaced by {@link org.apache.sis.referencing.GeodeticCalculator#createCircularRegion2D(double)}.
+ * @deprecated Replaced by {@link org.apache.sis.referencing.GeodeticCalculator#createGeodesicCircle2D(double)}.
  */
 @Deprecated
 public class LatLonPointRadius {
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 f99dd1c..70cccd3 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
@@ -715,9 +715,12 @@ public class GeodeticCalculator {
      * The {@code tolerance} parameter should not be too small for avoiding creation of unreasonably
long chain of Bézier curves.
      * For example a value of 1/10 of geodesic length may be sufficient.
      *
-     * <b>Limitations:</b>
-     * This method depends on the presence of {@code java.desktop} module. This limitations
may be addressed
+     * <div class="note"><b>Note:</b>
+     * this method depends on the presence of {@code java.desktop} module. This constraint
may be addressed
      * in a future Apache SIS version (see <a href="https://issues.apache.org/jira/browse/SIS-453">SIS-453</a>).
+     * The "2D" suffix in the method name represents this relationship with Java2D.
+     * The {@code createGeodesicPath(…)} method name (without suffix) is reserved for a
future version
+     * using ISO curves instead.</div>
      *
      * @param  tolerance  maximal error between the approximated curve and actual geodesic
track
      *                    in the units of measurement given by {@link #getDistanceUnit()}.
@@ -746,18 +749,26 @@ public class GeodeticCalculator {
     }
 
     /**
-     * Creates an approximation of the region at a constant geodesic distance around the
start point.
+     * Creates an approximation of the curve at a constant geodesic distance around the start
point.
      * The returned shape is circlelike with the {@linkplain #getStartPoint() start point}
in its center.
      * The coordinates are expressed in the coordinate reference system specified at creation
time.
      * The approximation uses cubic Bézier curves.
      *
-     * <p>This method tries to stay within the given tolerance threshold of the geodesic
track.
+     * <div class="note"><b>Note:</b>
+     * some authors define geodesic circle as the curve which enclose the maximum area for
a given perimeter.
+     * This method adopts a different definition, the locus of points at a fixed geodesic
distance from center point.
+     * </div>
+     *
+     * This method tries to stay within the given tolerance threshold of the geodesic track.
      * The {@code tolerance} parameter should not be too small for avoiding creation of unreasonably
long chain of Bézier curves.
-     * For example a value of 1/10 of geodesic length may be sufficient.</p>
+     * For example a value of 1/10 of geodesic length may be sufficient.
      *
-     * <b>Limitations:</b>
-     * This method depends on the presence of {@code java.desktop} module. This limitations
may be addressed
+     * <div class="note"><b>Note:</b>
+     * this method depends on the presence of {@code java.desktop} module. This constraint
may be addressed
      * in a future Apache SIS version (see <a href="https://issues.apache.org/jira/browse/SIS-453">SIS-453</a>).
+     * The "2D" suffix in the method name represents this relationship with Java2D.
+     * The {@code createGeodesicCircle(…)} method name (without suffix) is reserved for
a future version
+     * using ISO curves instead.</div>
      *
      * @param  tolerance  maximal error in the units of measurement given by {@link #getDistanceUnit()}.
      *                    This is approximate; the actual errors may vary around that value.
@@ -765,7 +776,7 @@ public class GeodeticCalculator {
      * @throws TransformException if the coordinates can not be transformed to {@linkplain
#getPositionCRS() position CRS}.
      * @throws IllegalStateException if some required properties have not been specified.
      */
-    public Shape createCircularRegion2D(final double tolerance) throws TransformException
{
+    public Shape createGeodesicCircle2D(final double tolerance) throws TransformException
{
         ArgumentChecks.ensureStrictlyPositive("tolerance", tolerance);
         if (isInvalid(START_POINT | GEODESIC_DISTANCE)) {
             computeDistance();
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 4d6e52f..a822518 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
@@ -266,17 +266,17 @@ public strictfp class GeodeticCalculatorTest extends TestCase {
     }
 
     /**
-     * Tests {@link GeodeticCalculator#createCircularRegion2D(double)}.
+     * Tests {@link GeodeticCalculator#createGeodesicCircle2D(double)}.
      *
      * @throws TransformException if an error occurred while transforming coordinates.
      */
     @Test
     @DependsOnMethod("testUsingTransform")
-    public void testCircularRegion2D() throws TransformException {
+    public void testGeodesicCircle2D() throws TransformException {
         final GeodeticCalculator c = create(true);
         c.setStartGeographicPoint(-33.0, -71.6);                // Valparaíso
         c.setGeodesicDistance(100000);                          // 100 km
-        Shape region = c.createCircularRegion2D(10000);
+        Shape region = c.createGeodesicCircle2D(10000);
         if (VisualCheck.SHOW_WIDGET) {
             VisualCheck.show(region);
         }


Mime
View raw message