sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1668185 - in /sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform: AbstractMathTransform.java ContextualParameters.java
Date Sat, 21 Mar 2015 00:42:35 GMT
Author: desruisseaux
Date: Sat Mar 21 00:42:35 2015
New Revision: 1668185

URL: http://svn.apache.org/r1668185
Log:
Referencing javadoc: try to explain better the purpose of ContextualParameters.

Modified:
    sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/AbstractMathTransform.java
    sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/ContextualParameters.java

Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/AbstractMathTransform.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/AbstractMathTransform.java?rev=1668185&r1=1668184&r2=1668185&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/AbstractMathTransform.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/AbstractMathTransform.java
[UTF-8] Sat Mar 21 00:42:35 2015
@@ -169,40 +169,47 @@ public abstract class AbstractMathTransf
 
     /**
      * Returns the parameter values for this math transform, or {@code null} if unknown.
-     * Callers should not modify the returned parameters, as modifications (if allowed)
-     * will generally not be reflected back in this {@code MathTransform}.
+     * This is not necessarily the parameters that the user specified at construction time,
+     * since implementations may have applied normalizations.
      *
-     * <div class="note"><b>Relationship with ISO 19111:</b>
-     * This method is similar to {@link SingleOperation#getParameterValues()}, except that
typical
-     * {@link MathTransform} implementations return parameters in standard units (usually
-     * {@linkplain SI#METRE metres} or {@linkplain NonSI#DEGREE_ANGLE decimal degrees}).
-     * </div>
+     * <div class="section">Normalized and contextual parameters</div>
+     * Most Apache SIS implementations of map projections perform their calculations on an
ellipsoid
+     * having a semi-major axis length of 1. In such cases, the group returned by this method
contains
+     * a {@code "semi_major"} parameter with a value of 1. If the real axis length is desired,
we need
+     * to take in account the context of this math transform, i.e. the scales and offsets
applied before
+     * and after this transform. This information is provided by {@link #getContextualParameters()}.
      *
      * @return The parameter values for this math transform, or {@code null} if unspecified.
+     *         Note that those parameters may be normalized (e.g. represent a transformation
+     *         of an ellipsoid of semi-major axis length of 1).
      *
+     * @see #getContextualParameters()
      * @see SingleOperation#getParameterValues()
      */
     @Override
     public ParameterValueGroup getParameterValues() {
         /*
          * Do NOT try to infer the parameters from getContextualParameters(). This is usually
not appropriate
-         * because if ContextualParameters declares "normalize" and "denormalize" affine
transforms,
-         * they need to be taken in account in a way that only the subclass know.
+         * because if ContextualParameters declares "normalize" and "denormalize" affine
transforms, then those
+         * transforms need to be taken in account in a way that only the subclass know.
          */
         return null;
     }
 
     /**
-     * Returns the parameters of this transform as a sequence of
-     * <cite>normalize</cite> → <cite>non-linear kernel</cite>
→ <cite>denormalize</cite>) transforms
-     * (<i>optional operation</i>).
+     * Returns the parameters for a sequence of <cite>normalize</cite> → {@code
this} → <cite>denormalize</cite>
+     * transforms (<i>optional operation</i>).
      *
      * Subclasses can override this method if they choose to split their computation in linear
and non-linear parts.
-     * Such separation is optional: it can leads to better performance, but should not change
significantly the
-     * result (ignoring differences in rounding errors).
-     *
-     * @return The parameters values splitted in a sequence of <cite>normalize</cite>
→ <cite>non-linear
-     *         kernel</cite> → <cite>denormalize</cite> transforms, or
{@code null} if unspecified.
+     * Such split is optional: it can leads to better performance (because SIS can concatenate
efficiently consecutive
+     * linear transforms), but should not change significantly the result (ignoring differences
in rounding errors).
+     * If a split has been done, then this {@code MathTransform} represents only the non-linear
step and Apache SIS
+     * needs this method for reconstructing the parameters of the complete transform.
+     *
+     * @return The parameters values for the sequence of <cite>normalize</cite>
→ {@code this} → <cite>denormalize</cite>
+     *         transforms, or {@code null} if unspecified.
+     *         Callers should not modify the returned parameters, since modifications (if
allowed)
+     *         will generally not be reflected back in this {@code MathTransform}.
      *
      * @since 0.6
      */

Modified: sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/ContextualParameters.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/ContextualParameters.java?rev=1668185&r1=1668184&r2=1668185&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/ContextualParameters.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/ContextualParameters.java
[UTF-8] Sat Mar 21 00:42:35 2015
@@ -43,9 +43,19 @@ import static org.apache.sis.util.Argume
 
 
 /**
- * The parameters of a coordinate operation as a sequence of
- * <cite>normalize</cite> → <cite>non-linear kernel</cite> →
<cite>denormalize</cite> transforms.
- * The normalize and denormalize parts must be affine transforms.
+ * The parameters that describe a sequence of
+ * <cite>normalize</cite> → <cite>non-linear kernel</cite> →
<cite>denormalize</cite> transforms as a whole.
+ * The normalize and denormalize steps must be affine transforms, while the non-linear kernel
is arbitrary.
+ *
+ * <div class="note"><b>Note:</b> actually there is nothing in this class
which force the kernel to be non-linear.
+ * But this class is useless if the kernel is linear, because 3 linear steps can be efficiently
+ * {@linkplain java.awt.geom.AffineTransform#concatenate concatenated} in a single affine
transform.</div>
+ *
+ * <p>Contextual parameters can be {@linkplain AbstractMathTransform#getContextualParameters()
associated}
+ * to the <cite>non-linear kernel</cite> step of the above-cited sequence.
+ * Since the {@link AbstractMathTransform#getParameterValues()} method of the non-linear
kernel returns only
+ * normalized parameters (e.g. a map projection on an ellipsoid having a <cite>semi-major</cite>
axis length of 1),
+ * Apache SIS needs contextual information for reconstructing the parameters of the complete
transforms chain.</p>
  *
  * <div class="section">Usage in map projections</div>
  * This object is used mostly for Apache SIS implementation of map projections, where the
kernel is a
@@ -59,12 +69,12 @@ import static org.apache.sis.util.Argume
  *     For example both <cite>"Mercator (variant A)"</cite> and <cite>"Mercator
(variant B)"</cite> operation methods
  *     instantiate the same {@link org.apache.sis.referencing.operation.Mercator} class,
but with different descriptors.</li>
  *
- *   <li>The map projection constructor fetches all parameters that he needs from the
user-supplied
+ *   <li>The map projection constructor fetches all parameters that it needs from the
user-supplied
  *     {@link ParameterValueGroup}, initializes the projection, then saves the parameter
values that
  *     it actually used in a new {@code ContextualParameters} instance.</li>
  *
- *   <li>The constructor should invoke {@link #normalizeGeographic(double)}
- *     and {@link #denormalizeCartesian(double, double, double, double)}.
+ *   <li>The map projection constructor may keep only the non-linear parameters for
itself, and gives the linear parameters
+ *     to the {@link #normalizeGeographic(double)} and {@link #denormalizeCartesian(double,
double, double, double)} methods.
  *     The constructor is free to apply additional operations on the two affine transforms
  *     ({@linkplain #normalization(boolean) normalize / denormalize}) after the above-cited
methods have been invoked.</li>
  * </ol>
@@ -132,7 +142,7 @@ public class ContextualParameters extend
     }
 
     /**
-     * Creates a matrix for a linear part of the sequence.
+     * Creates a matrix for a linear step of the sequence.
      * It is important that the matrices created here are instances of {@link MatrixSIS},
in order
      * to allow {@link #normalization(boolean)} to return the reference to the (de)normalize
matrices.
      */
@@ -394,7 +404,7 @@ public class ContextualParameters extend
          * before the projection. However it may contains more than just this normalization,
          * because it may have been concatenated with any user-defined transform (for example
          * in order to apply a change of axis order). We need to separate the "user-defined"
-         * part from the "normalize" part.
+         * step from the "normalize" step.
          */
         Matrix userDefined = inverse ? denormalize : normalize;
         if (!inverse) try {



Mime
View raw message