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 {
