(sis) 01/02: Add explanation about the differences compared to published article. Fix two wrong `@since` tags: put a placeholder for not-yet-determined release.

[de...@apache.org]

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 73b14d275fcaa9489f112214d96f45617af5cb64
Author: Martin Desruisseaux <ma...@geomatys.com>
AuthorDate: Fri May 3 12:32:03 2024 +0200

    Add explanation about the differences compared to published article.
    Fix two wrong `@since` tags: put a placeholder for not-yet-determined release.
---
 .../iso/identification/AbstractIdentification.java   |  4 ++--
 .../referencing/operation/projection/Robinson.java   | 20 ++++++++++++++++++--
 2 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/endorsed/src/org.apache.sis.metadata/main/org/apache/sis/metadata/iso/identification/AbstractIdentification.java b/endorsed/src/org.apache.sis.metadata/main/org/apache/sis/metadata/iso/identification/AbstractIdentification.java
index a301d3d51e..8fde87b8ed 100644
--- a/endorsed/src/org.apache.sis.metadata/main/org/apache/sis/metadata/iso/identification/AbstractIdentification.java
+++ b/endorsed/src/org.apache.sis.metadata/main/org/apache/sis/metadata/iso/identification/AbstractIdentification.java
@@ -520,7 +520,7 @@ public class AbstractIdentification extends ISOMetadata implements Identificatio
      *
      * @return smallest resolvable temporal period in a resource.
      *
-     * @since 0.5
+     * @since 2.0
      */
     @Override
     // @XmlElement at the end of this class.
@@ -533,7 +533,7 @@ public class AbstractIdentification extends ISOMetadata implements Identificatio
      *
      * @param  newValues  the new temporal resolutions.
      *
-     * @since 0.5
+     * @since 2.0
      */
     public void setTemporalResolutions(final Collection<? extends Duration> newValues) {
         temporalResolutions = writeCollection(newValues, temporalResolutions, Duration.class);
diff --git a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/projection/Robinson.java b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/projection/Robinson.java
index 4d51ebd276..5b64f8eb48 100644
--- a/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/projection/Robinson.java
+++ b/endorsed/src/org.apache.sis.referencing/main/org/apache/sis/referencing/operation/projection/Robinson.java
@@ -38,15 +38,25 @@ import static org.apache.sis.referencing.operation.provider.Robinson.*;
  * by interpolations of tabulated values instead of analytic function.
  * The table is indexed by latitude at a constant interval.
  *
- * <p>While the current implementation supports only the Robinson projection,
+ * <h2>Note on possible code reuse</h2>
+ * While the current implementation supports only the Robinson projection,
  * it could be generalized to any projection using interpolations in a similar way.
  * For example, the "Natural Earth" projection was initially defined by interpolations.
- * See {@link Variant} for a note about how to generalize.</p>
+ * See {@link Variant} for a note about how to generalize.
  *
  * <h2>References</h2>
  * <p>Snyder, J. P. (1990). <u>The Robinson projection: A computation algorithm.</u>
  * Cartography and Geographic Information Systems, 17 (4), p. 301-305.</p>
  *
+ * <h3>Changes compared to the reference</h3>
+ * The Snyder's article gives a program in the ANSI Fortran language. That program has been translated
+ * to Java in this class and adapted for SIS architecture (constants moved to normalization matrices).
+ * Robinson did not specify a particular interpolation method, but Snyder's program uses the Stirling's
+ * central-difference formula, while PROJ uses cubic splices. Some other software use Aitken interpolation.
+ * The Fortran program translated to Java did not converged well for the inverse projection of points near
+ * a pole (maybe it is the reason why PROJ uses cubic splines instead). We modified the algorithm with the
+ * use of derivative (∂y/∂φ) for faster convergence.
+ *
  * @author  Martin Desruisseaux (Geomatys)
  *
  * @see <a href="https://en.wikipedia.org/wiki/Robinson_projection">Robinson projection on Wikipedia</a>
@@ -167,6 +177,9 @@ public class Robinson extends NormalizedProjection {
      * The units of measurement are implementation-specific (see super-class javadoc).
      * The results must be multiplied by the denormalization matrix before to get linear distances.
      *
+     * <p>Robinson did not specify a particular interpolation method. This class uses the
+     * Stirling's central-difference formula as published in Snyder (1990) article.</p>
+     *
      * @return the matrix of the projection derivative at the given source position,
      *         or {@code null} if the {@code derivate} argument is {@code false}.
      * @throws ProjectionException if the coordinates cannot be converted.
@@ -209,6 +222,9 @@ public class Robinson extends NormalizedProjection {
     /**
      * Converts the specified (<var>x</var>,<var>y</var>) coordinates
      * and stores the result in {@code dstPts} (angles in radians).
+     *
+     * <p>Snyder's algorithm has been modified in this method with the use of derivative (∂y/∂φ)
+     * for faster convergence. It is particularly important for points near the poles.</p>
      */
     @Override
     protected void inverseTransform(final double[] srcPts, final int srcOff,