sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject [sis] 01/04: Documentation updates.
Date Thu, 15 Aug 2019 15:41:22 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 e6a19fdfd424fb375e634783fa44c1520850cbff
Author: Martin Desruisseaux <martin.desruisseaux@geomatys.com>
AuthorDate: Tue Aug 13 17:21:55 2019 +0200

    Documentation updates.
---
 .../apache/sis/coverage/grid/GridDerivation.java   | 22 +++++++++++++---------
 .../sis/referencing/GeodesicsOnEllipsoid.java      |  3 ++-
 .../apache/sis/referencing/GeodeticCalculator.java | 19 +++++++++++++++----
 3 files changed, 30 insertions(+), 14 deletions(-)

diff --git a/core/sis-feature/src/main/java/org/apache/sis/coverage/grid/GridDerivation.java
b/core/sis-feature/src/main/java/org/apache/sis/coverage/grid/GridDerivation.java
index 56c1080..e19b807 100644
--- a/core/sis-feature/src/main/java/org/apache/sis/coverage/grid/GridDerivation.java
+++ b/core/sis-feature/src/main/java/org/apache/sis/coverage/grid/GridDerivation.java
@@ -289,6 +289,7 @@ public class GridDerivation {
      * @throws IllegalStateException if a {@link #subgrid(GridGeometry) subgrid(…)} or
{@link #slice(DirectPosition) slice(…)}
      *         method has already been invoked.
      *
+     * @see #subsample(int...)
      * @see GridExtent#resize(long...)
      */
     public GridDerivation resize(GridExtent extent, double... scales) {
@@ -370,7 +371,7 @@ public class GridDerivation {
      *   <li>{@linkplain GridGeometry#getExtent() Extent} in {@link #base} grid.</li>
      * </ul>
      *
-     * An optional {@link #margin(int...) margin} can be specified for increasing the size
of the grid extent computed by this method.
+     * An optional {@linkplain #margin(int...) margin} can be specified for increasing the
size of the grid extent computed by this method.
      * For example if the caller wants to apply bilinear interpolations in an image, (s)he
will need 1 more pixel on each image border.
      * If the caller wants to apply bi-cubic interpolations, (s)he will need 2 more pixels
on each image border.
      *
@@ -392,8 +393,8 @@ public class GridDerivation {
      * @throws IllegalStateException if a {@link #subgrid(Envelope, double...) subgrid(…)}
or {@link #slice(DirectPosition) slice(…)}
      *         method has already been invoked.
      *
+     * @see #getIntersection()
      * @see #getSubsamplings()
-     * @see #subsample(int...)
      */
     public GridDerivation subgrid(final GridGeometry gridOfInterest) {
         ArgumentChecks.ensureNonNull("gridOfInterest", gridOfInterest);
@@ -491,7 +492,8 @@ public class GridDerivation {
      * @throws IllegalStateException if a {@link #subgrid(GridGeometry) subgrid(…)} or
{@link #slice(DirectPosition) slice(…)}
      *         method has already been invoked.
      *
-     * @see GridExtent#subsample(int[])
+     * @see #getIntersection()
+     * @see #getSubsamplings()
      */
     public GridDerivation subgrid(final Envelope areaOfInterest, double... resolution) {
         ensureSubgridNotSet();
@@ -662,7 +664,7 @@ public class GridDerivation {
 
     /**
      * Applies a subsampling on the grid geometry to build.
-     * The {@code subsamplings} argument is often the array returned by {@link #getSubsamplings()},
but not necessarily.
+     * This method can be invoked as an alternative to {@code subgrid(…)} methods if only
the resolution needs to be changed.
      * The {@linkplain GridGeometry#getExtent() extent} of the {@linkplain #build() built}
grid geometry will be derived
      * from {@link #getIntersection()} as below for each dimension <var>i</var>:
      *
@@ -918,7 +920,9 @@ public class GridDerivation {
     }
 
     /**
-     * Returns an <em>estimation</em> of the steps for accessing cells along
each axis of base grid.
+     * Returns an <em>estimation</em> of the strides for accessing cells along
each axis of base grid.
+     * If {@link #subsample(int...)} has been invoked, then this method returns the argument
values given to that method.
+     * Otherwise if a {@code subgrid(…)} method has been invoked, then this method computes
the subsamplings as below:
      * Given a conversion from {@code gridOfInterest} grid coordinates
      * (<var>x</var>, <var>y</var>, <var>z</var>) to
{@link #base} grid coordinates
      * (<var>x′</var>, <var>y′</var>, <var>z′</var>)
defined as below (generalize to as many dimensions as needed):
@@ -932,13 +936,13 @@ public class GridDerivation {
      * Then this method returns {|s₀|, |s₁|, |s₂|} rounded toward zero or nearest integer
      * (depending on the {@linkplain GridRoundingMode grid rounding mode}) and clamped to
1
      * (i.e. all values in the returned array are strictly positive, no zero values).
-     * It means that an iteration over {@code gridOfInterest} grid coordinates with a step
Δ<var>x</var>=1
-     * corresponds approximately to an iteration in {@link #base} grid coordinates with a
step of Δ<var>x′</var>=s₀,
-     * a step Δ<var>y</var>=1 corresponds approximately to a step Δ<var>y′</var>=s₁,
<i>etc.</i>
+     * It means that an iteration over {@code gridOfInterest} grid coordinates with a stride
Δ<var>x</var>=1
+     * corresponds approximately to an iteration in {@link #base} grid coordinates with a
stride of Δ<var>x′</var>=s₀,
+     * a stride Δ<var>y</var>=1 corresponds approximately to a stride Δ<var>y′</var>=s₁,
<i>etc.</i>
      * If the conversion changes grid axis order, then the order of elements in the returned
array
      * is the order of axes in the {@link #base} grid.
      *
-     * @return an <em>estimation</em> of the steps for accessing cells along
each axis of {@link #base} grid.
+     * @return an <em>estimation</em> of the strides for accessing cells along
each axis of {@link #base} grid.
      *
      * @see #subgrid(GridGeometry)
      * @see #subgrid(Envelope, double...)
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 0191dc4..5af8a70 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
@@ -60,6 +60,7 @@ import static java.lang.Math.*;
  *
  * <p><b>Limitations:</b>
  * Current implementation is still unable to compute the geodesics in some cases.
+ * In particular, calculation may fail for antipodal points.
  * See <a href="https://issues.apache.org/jira/browse/SIS-467">SIS-467</a>.</p>
  *
  * <p>If the following cases where more than one geodesics exist, current implementation
returns an arbitrary one:</p>
@@ -923,7 +924,7 @@ class GeodesicsOnEllipsoid extends GeodeticCalculator {
      * Computes rhumb line using series expansion.
      *
      * <p><b>Source:</b> G.G. Bennett, 1996. <a href="https://doi.org/10.1017/S0373463300013151">
-     * Practical Rhumb Line Calculations on the Spheroid</a>. J. Navigation 49(1),
112--119.</p>
+     * Practical Rhumb Line Calculations on the Spheroid</a>. J. Navigation 49(1),
112-119.</p>
      */
     @Override
     final void computeRhumbLine() {
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 6ebfdb4..d4dbabe 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
@@ -79,23 +79,34 @@ import static org.apache.sis.internal.metadata.ReferencingServices.NAUTICAL_MILE
  *
  * <ul>
  *   <li>Wikipedia, <a href="https://en.wikipedia.org/wiki/Great-circle_navigation">Great-circle
navigation</a>
- *       for the spherical formulas.</li>
+ *       for spherical formulas.</li>
+ *   <li>Wikipedia, <a href="https://en.wikipedia.org/wiki/Rhumb_line">Rhumb
line</a>
+ *       for 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>
+ *       for ellipsoidal formulas.</li>
+ *   <li>G.G. Bennett, 1996. <a href="https://doi.org/10.1017/S0373463300013151">Practical
Rhumb Line Calculations
+ *       on the Spheroid</a> for 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,
+ * {@code GeodeticCalculator} aims for a positional accuracy of one centimetre.
+ * Azimuthal accuracy corresponds to an error of one centimetre 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">Limitations</div>
+ * Current implementation can not compute the geodesics in some cases.
+ * In particular, calculation may fail for antipodal points on an ellipsoid.
+ * Karney's algorithm should cover those cases,
+ * but this {@code GeodeticCalculator} implementation may not be sufficiently tuned.
+ * See <a href="https://issues.apache.org/jira/browse/SIS-467">SIS-467</a> for
more information.
+ *
  * <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.


Mime
View raw message