Author: desruisseaux
Date: Thu Mar 26 12:20:45 2015
New Revision: 1669334
URL: http://svn.apache.org/r1669334
Log:
Referencing: documentation fixes and minor code tuning (e.g. no need to cache
the non-linear part of the concatenated transform).
Modified:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/provider/MillerCylindrical.java
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/Mercator.java
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/NormalizedProjection.java
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/package-info.java
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/ContextualParameters.java
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.java
Modified:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/provider/MillerCylindrical.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/provider/MillerCylindrical.java?rev=1669334&r1=1669333&r2=1669334&view=diff
==============================================================================
---
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/provider/MillerCylindrical.java
[UTF-8] (original)
+++
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/provider/MillerCylindrical.java
[UTF-8] Thu Mar 26 12:20:45 2015
@@ -28,7 +28,7 @@ import org.apache.sis.parameter.Paramete
/**
- * The provider for "<cite>Miller</cite>" projection.
+ * The provider for "<cite>Miller Cylindrical</cite>" projection.
* This is a {@link Mercator1SP} projection with the following modifications:
*
* <ol>
Modified:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/Mercator.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/Mercator.java?rev=1669334&r1=1669333&r2=1669334&view=diff
==============================================================================
---
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/Mercator.java
[UTF-8] (original)
+++
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/Mercator.java
[UTF-8] Thu Mar 26 12:20:45 2015
@@ -54,7 +54,7 @@ import static java.lang.Double.*;
* <div class="section">Behavior at poles</div>
* The projection of 90°N gives {@linkplain Double#POSITIVE_INFINITY positive
infinity}.
* The projection of 90°S gives {@linkplain Double#NEGATIVE_INFINITY negative
infinity}.
- * Projection of a latitude outside the [-90-ε … 90+ε]° range produces
{@linkplain Double#NaN NaN}.
+ * Projection of a latitude outside the [-90 … 90]° range produces {@linkplain
Double#NaN NaN}.
*
* @author André Gosselin (MPO)
* @author Martin Desruisseaux (MPO, IRD, Geomatys)
@@ -79,8 +79,10 @@ public class Mercator extends Normalized
* The {@code method} argument can be the description of one of the
following:
*
* <ul>
- * <li><cite>Mercator (variant A)</cite>, also known as <cite>Mercator
(1SP)</cite>.</li>
- * <li><cite>Mercator (variant B)</cite>, also known as <cite>Mercator
(2SP)</cite>.</li>
+ * <li><cite>"Mercator (variant A)"</cite>, also known as
<cite>"Mercator (1SP)"</cite>.</li>
+ * <li><cite>"Mercator (variant B)"</cite>, also known as
<cite>"Mercator (2SP)"</cite>.</li>
+ * <li><cite>"Popular Visualisation Pseudo Mercator"</cite>.</li>
+ * <li><cite>"Miller Cylindrical"</cite>.</li>
* </ul>
*
* @param method Description of the projection parameters.
@@ -122,12 +124,13 @@ public class Mercator extends Normalized
}
/**
- * Returns the parameter descriptors for this normalized projection. Note
that the returned descriptor is about
- * the normalized projection only, not the full projection. Consequently
the default implementation returns the
- * descriptor of <cite>Mercator (variant A)</cite> in all cases except for
the pseudo-Mercator projection,
- * because the <cite>Mercator (variant B)</cite> case is implemented as
the variant A with a different scale factor.
+ * Returns the parameter descriptors for this normalized projection.
+ * The default implementation returns the descriptor of <cite>"Mercator
(variant A)"</cite> in all cases
+ * except <cite>"Popular Visualisation Pseudo Mercator"</cite>.
+ * This method does not return the descriptor of other other cases because
the <cite>"Mercator (variant B)"</cite>
+ * case (for example) is implemented as <cite>"Mercator (variant
A)"</cite> with a different scale factor.
*
- * @return The <cite>Mercator (variant A)</cite> or <cite>Popular
Visualisation Pseudo Mercator</cite>
+ * @return The <cite>"Mercator (variant A)"</cite> or <cite>"Popular
Visualisation Pseudo Mercator"</cite>
* parameter descriptor.
*/
@Override
Modified:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/NormalizedProjection.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/NormalizedProjection.java?rev=1669334&r1=1669333&r2=1669334&view=diff
==============================================================================
---
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/NormalizedProjection.java
[UTF-8] (original)
+++
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/NormalizedProjection.java
[UTF-8] Thu Mar 26 12:20:45 2015
@@ -49,16 +49,33 @@ import java.util.Objects;
* <ul class="verbose">
* <li>On input, the {@link #transform(double[], int, double[], int,
boolean) transform(…)} method
* expects (<var>longitude</var>, <var>latitude</var>) angles in
<strong>radians</strong>.
- * Longitudes have the <cite>central meridian</cite> removed before the
transform method is invoked.
+ * Longitudes have the <cite>central meridian</cite> (λ₀) removed before the
transform method is invoked.
* The conversion from degrees to radians and the longitude rotation are
applied by the
- * {@linkplain ContextualParameters#normalization(boolean) normalize} affine
transform.</li>
+ * {@linkplain ContextualParameters#normalizeGeographicInputs normalize}
affine transform.</li>
*
* <li>On output, the {@link #transform(double[],int,double[],int,boolean)
transform(…)} method returns
- * (<var>easting</var>, <var>northing</var>) values on a sphere or ellipse
having a semi-major axis length of 1.
- * The multiplication by the scale factor and the false easting/northing
offsets are applied by the
- * {@linkplain ContextualParameters#normalization(boolean) denormalize}
affine transform.</li>
+ * (<var>x</var>, <var>y</var>) values on a sphere or ellipse having a
semi-major axis length of 1.
+ * The multiplication by the scale factor (<var>k</var>₀) and the
translation by false easting (FE) and false
+ * northing (FN) are applied by the {@linkplain
ContextualParameters#denormalizeCartesianOutputs denormalize}
+ * affine transform.</li>
* </ul>
*
+ * The normalize and denormalize steps are represented below by the matrices
on the left and right sides respectively.
+ * The matrices below show only the basic parameters common to all
projections. Some projections will put more elements
+ * in those matrices.
+ *
+ * <center>
+ * <table class="compact" style="td {vertical-align: middle}"
summary="Decomposition of a map projection">
+ * <tr>
+ * <td>{@include ../transform/formulas.html#Normalize}</td>
+ * <td>→</td>
+ * <td>{@code NormalizedProjection}</td>
+ * <td>→</td>
+ * <td>{@include ../transform/formulas.html#Denormalize}</td>
+ * </tr>
+ * </table>
+ * </center>
+ *
* {@code NormalizedProjection} does not store the above cited parameters
(central meridian, scale factor, <i>etc.</i>)
* on intend, in order to make clear that those parameters are not used by
subclasses.
* The ability to recognize two {@code NormalizedProjection}s as {@linkplain
#equals(Object, ComparisonMode) equivalent}
@@ -121,7 +138,7 @@ public abstract class NormalizedProjecti
* and error messages. Subclasses shall not use the values defined in this
object for computation purpose, except at
* construction time.
*/
- protected final ContextualParameters parameters;
+ final ContextualParameters parameters;
/**
* Ellipsoid excentricity, equal to <code>sqrt({@linkplain
#excentricitySquared})</code>.
@@ -232,7 +249,7 @@ public abstract class NormalizedProjecti
* This means that projections that implement this method are performed on
a sphere or ellipse
* having a semi-major axis length of 1.
*
- * <div class="note"><b>Note:</b> in <a
href="http://trac.osgeo.org/proj/";>PROJ.4</a>, the same standardization,
+ * <div class="note"><b>Note:</b> in <a
href="http://trac.osgeo.org/proj/";>Proj.4</a>, the same standardization,
* described above, is handled by {@code pj_fwd.c}.</div>
*
* <div class="section">Argument checks</div>
@@ -269,7 +286,7 @@ public abstract class NormalizedProjecti
* in the output coordinate. This means that projections that implement
this method are performed on a sphere
* or ellipse having a semi-major axis of 1.
*
- * <div class="note"><b>Note:</b> in <a
href="http://trac.osgeo.org/proj/";>PROJ.4</a>, the same standardization,
+ * <div class="note"><b>Note:</b> in <a
href="http://trac.osgeo.org/proj/";>Proj.4</a>, the same standardization,
* described above, is handled by {@code pj_inv.c}.</div>
*
* @param srcPts The array containing the source point coordinate, as
linear distance on a unit sphere or ellipse.
@@ -355,8 +372,8 @@ public abstract class NormalizedProjecti
* {@code object} is an instance of the same class than {@code this}, then
compares the excentricity.
*
* <p>If this method returns {@code true}, then for any given identical
source position, the two compared map
- * projections shall compute the same target position. Many of the
{@linkplain #parameters parameters}
- * used for creating the map projections are irrelevant and do not need to
be known.
+ * projections shall compute the same target position. Many of the
{@linkplain #getContextualParameters()
+ * contextual parameters} used for creating the map projections are
irrelevant and do not need to be known.
* Those projection parameters will be compared only if the comparison
mode is {@link ComparisonMode#STRICT}
* or {@link ComparisonMode#BY_CONTRACT BY_CONTRACT}.</p>
*
Modified:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/package-info.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/package-info.java?rev=1669334&r1=1669333&r2=1669334&view=diff
==============================================================================
---
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/package-info.java
[UTF-8] (original)
+++
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/projection/package-info.java
[UTF-8] Thu Mar 26 12:20:45 2015
@@ -118,14 +118,14 @@
* A map projection in this package is actually the concatenation of the
following transforms, in that order:
*
* <ul>
- * <li>{@link
org.apache.sis.referencing.operation.transform.ContextualParameters#normalizeGeographicInputs
normalize} affine transform</li>
- * <li>{@link
org.apache.sis.referencing.operation.projection.NormalizedProjection}
subclass</li>
- * <li>{@link
org.apache.sis.referencing.operation.transform.ContextualParameters#denormalizeCartesianOutputs
denormalize} affine transform</li>
+ * <li>A {@linkplain
org.apache.sis.referencing.operation.transform.ContextualParameters#normalizeGeographicInputs
normalization} affine transform</li>
+ * <li>A {@link
org.apache.sis.referencing.operation.projection.NormalizedProjection}
subclass</li>
+ * <li>A {@linkplain
org.apache.sis.referencing.operation.transform.ContextualParameters#denormalizeCartesianOutputs
denormalization} affine transform</li>
* </ul>
*
- * The first step (<cite>"normalize"</cite>) converts longitude and latitude
values from degrees to radians
+ * The first step (<cite>"normalization"</cite>) converts longitude and
latitude values from degrees to radians
* and removes the <cite>central meridian</cite> from the longitude.
- * The last step (<cite>"denormalize"</cite>) multiplies the result of the
middle step by the global scale factor
+ * The last step (<cite>"denormalization"</cite>) multiplies the result of the
middle step by the global scale factor
* (typically the product of the <cite>scale factor</cite> with the
<cite>semi-major</cite> axis length),
* then adds the <cite>false easting</cite> and <cite>false northing</cite>.
* This means that the middle step (<cite>"normalized projection"</cite>) is
performed on an ellipse (or sphere)
@@ -139,7 +139,7 @@
* {@linkplain org.opengis.referencing.cs.AxisDirection#NORTH North}) axis
orientation.
* However in some cases the actual input and output coordinates may be
different than the above by some scale factor,
* translation or rotation, if the projection implementation choose to combine
some linear coefficients with the
- * above-cited normalize and denormalize affine transforms.</p>
+ * above-cited normalization and denormalization affine transforms.</p>
*
* <div class="note"><b>Note:</b>
* In <a href="http://www.remotesensing.org/proj/";>Proj.4</a>, the same
standardization is handled by {@code pj_fwd.c}
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=1669334&r1=1669333&r2=1669334&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] Thu Mar 26 12:20:45 2015
@@ -60,24 +60,39 @@ import static org.apache.sis.util.Argume
* 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
+ * This object is used mostly for Apache SIS implementation of map
projections, where the non-linear kernel is a
* {@linkplain
org.apache.sis.referencing.operation.projection.NormalizedProjection normalized
projection}.
- * This object is typically created and used as below:
+ * The complete map projection is a chain of 3 transforms a below:
+ *
+ * <center>
+ * <table class="compact" style="td {vertical-align: middle}"
summary="Decomposition of a map projection">
+ * <tr>
+ * <td>{@include formulas.html#Normalize}</td>
+ * <td>→</td>
+ * <td>Map projection on a normalized ellipsoid</td>
+ * <td>→</td>
+ * <td>{@include formulas.html#Denormalize}</td>
+ * </tr>
+ * </table>
+ * </center>
+ *
+ * {@code ContextualParameters} is typically created and used as below:
*
* <ol class="verbose">
- * <li>A {@link
MathTransformProvider#createMathTransform(ParameterValueGroup)} method
instantiates a
- * class from the {@linkplain
org.apache.sis.referencing.operation.projection map projection package}.
+ * <li>A {@link MathTransformProvider} instantiates a class from the
+ * {@linkplain org.apache.sis.referencing.operation.projection map
projection package}.
* Note that different {@code MathTransformProvider}s may instantiate the
same map projection class.
* 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.projection.Mercator} class,
* but with different descriptors.</li>
*
* <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
+ * {@link org.apache.sis.parameter.Parameters}, initializes the
projection, then saves the parameter values that
* it actually used in a new {@code ContextualParameters} instance.</li>
*
- * <li>The map projection constructor may keep only the non-linear
parameters for itself, and gives the linear parameters to the
- * {@link #normalizeGeographicInputs(double)} and {@link
#denormalizeCartesianOutputs(double, double, double)} methods.
+ * <li>The map projection constructor may keep only the non-linear
parameters for itself,
+ * and gives the linear parameters to the {@link
#normalizeGeographicInputs normalizeGeographicInputs(…)}
+ * and {@link #denormalizeCartesianOutputs denormalizeCartesianOutputs(…)}
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>
@@ -92,6 +107,7 @@ import static org.apache.sis.util.Argume
* @module
*
* @see AbstractMathTransform#getContextualParameters()
+ * @see org.apache.sis.referencing.operation.projection.NormalizedProjection
*/
public class ContextualParameters extends FormattableObject implements
ParameterValueGroup, Cloneable, Serializable {
/**
@@ -189,7 +205,7 @@ public class ContextualParameters extend
/**
* Prepends a normalization step before the non-linear kernel, which will
convert ordinate values
* in the two first dimensions from degrees to radians. Before this
conversion, the normalization
- * can optionally subtract the given λ0 value (in degrees) from the
longitude.
+ * can optionally subtract the given λ₀ value (in degrees) from the
longitude.
*
* <p>In other words, invoking this method is equivalent to convert
coordinates using the following
* affine transform before any other operation:</p>
@@ -218,17 +234,17 @@ public class ContextualParameters extend
}
/**
- * Appends a normalization step after the non-linear kernel, which will
scale the projected ordinates
+ * Appends a denormalization step after the non-linear kernel, which will
scale the projected ordinates
* and add the false easting and northing.
*
* <p>In other words, invoking this method is equivalent to convert
coordinates using the following
* affine transform after the non-linear kernel:</p>
*
- * <center><p>{@include formulas.html#Deormalize}</p></center>
+ * <center><p>{@include formulas.html#Denormalize}</p></center>
*
- * @param scale The <cite>semi-major axis length</cite> (<var>a</var>),
optionally multiplied by other scale factor (<var>k</var>₀).
- * @param tx The false easting (FE).
- * @param ty The false northing (FN).
+ * @param scale The <cite>semi-major axis length</cite> (<var>a</var>),
optionally multiplied by other scale factor (<var>k</var>₀).
+ * @param tx The false easting (FE).
+ * @param ty The false northing (FN).
* @return The denormalization affine transform as a matrix.
* Callers can change that matrix directly if they want to apply
additional denormalization operations.
*/
@@ -263,7 +279,7 @@ public class ContextualParameters extend
* transforms.
* @throws FactoryException if an error occurred while creating a math
transform instance.
*/
- public MathTransform createConcatenatedTransform(final
MathTransformFactory factory, MathTransform kernel)
+ public MathTransform createConcatenatedTransform(final
MathTransformFactory factory, final MathTransform kernel)
throws FactoryException
{
final MathTransform n = factory.createAffineTransform(normalize);
@@ -271,9 +287,6 @@ public class ContextualParameters extend
Matrix m;
if ((m = MathTransforms.getMatrix(n)) != null) normalize = m;
if ((m = MathTransforms.getMatrix(d)) != null) denormalize = m;
- if (factory instanceof DefaultMathTransformFactory) {
- kernel = ((DefaultMathTransformFactory) factory).unique(kernel);
- }
return
factory.createConcatenatedTransform(factory.createConcatenatedTransform(n,
kernel), d);
}
Modified:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.java?rev=1669334&r1=1669333&r2=1669334&view=diff
==============================================================================
---
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.java
[UTF-8] (original)
+++
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/DefaultMathTransformFactory.java
[UTF-8] Thu Mar 26 12:20:45 2015
@@ -864,7 +864,7 @@ public class DefaultMathTransformFactory
/**
* Replaces the given transform by a unique instance, if one already
exists.
*/
- final MathTransform unique(final MathTransform tr) {
+ private MathTransform unique(final MathTransform tr) {
return pool.unique(tr);
}
