Author: desruisseaux
Date: Fri Jun 6 11:40:24 2014
New Revision: 1600847
URL: http://svn.apache.org/r1600847
Log:
Javadoc.
Modified:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/LinearTransform.java
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/PassThroughTransform.java
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/package-info.java
Modified:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/LinearTransform.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/LinearTransform.java?rev=1600847&r1=1600846&r2=1600847&view=diff
==============================================================================
---
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/LinearTransform.java
[UTF-8] (original)
+++
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/LinearTransform.java
[UTF-8] Fri Jun 6 11:40:24 2014
@@ -50,17 +50,21 @@ import org.opengis.referencing.operation
* A <cite>projective</cite> transform can be used as a generalization of
affine transforms.
* In such case the computation performed by SIS is similar to {@code
PerspectiveTransform}
* in <cite>Java Advanced Imaging</cite>.
- *
- * <p>For example a square matrix of size 4×4 is used for transforming
three-dimensional coordinates.
- * The transformed points {@code (x',y',z')} are computed as below:</p>
+ * For example a square matrix of size 4×4 is used for transforming
three-dimensional coordinates.
+ * The transformed points {@code (x',y',z')} are computed as below:
*
* <center><p>{@include formulas.html#ProjectiveTransform}</p></center>
*
+ * {@section Instantiation}
+ * The easiest way to instantiate a {@code LinearTransform} is to use the
{@link MathTransforms#linear(Matrix)}
+ * convenience method.
+ *
* @author Martin Desruisseaux (IRD, Geomatys)
* @since 0.4 (derived from geotk-2.0)
* @version 0.4
* @module
*
+ * @see java.awt.geom.AffineTransform
* @see <a
href="http://mathworld.wolfram.com/AffineTransformation.html";>Affine
transformation on MathWorld</a>
*/
public interface LinearTransform extends MathTransform {
Modified:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/PassThroughTransform.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/PassThroughTransform.java?rev=1600847&r1=1600846&r2=1600847&view=diff
==============================================================================
---
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/PassThroughTransform.java
[UTF-8] (original)
+++
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/PassThroughTransform.java
[UTF-8] Fri Jun 6 11:40:24 2014
@@ -40,7 +40,21 @@ import static org.apache.sis.util.Argume
*
* <div class="note"><b>Example:</b> giving (<var>latitude</var>,
<var>longitude</var>, <var>height</var>) coordinates,
* {@code PassThroughTransform} can convert the height values from feet to
meters without affecting the latitude and
- * longitude values.</div>
+ * longitude values. Such transform can be built as below:
+ *
+ * {@preformat java
+ * MathTransform feetToMetres = MathTransforms.linear(0.3048, 0); //
One-dimensional conversion.
+ * MathTransform tr = PassThroughTransform.create(2, feetToMetres, 0); //
Three-dimensional conversion.
+ * }
+ * </div>
+ *
+ * {@section Immutability and thread safety}
+ * {@code PassThroughTransform} is immutable and thread-safe if its
{@linkplain #subTransform} is also
+ * immutable and thread-safe.
+ *
+ * {@section Serialization}
+ * Serialized instances of this class are not guaranteed to be compatible with
future SIS versions.
+ * Serialization should be used only for short term storage or RMI between
applications running the same SIS version.
*
* @author Martin Desruisseaux (IRD, Geomatys)
* @since 0.5 (derived from geotk-1.2)
@@ -60,16 +74,14 @@ public class PassThroughTransform extend
/**
* Number of unaffected ordinates after the affected ones.
- * Always 0 when used through the strict OpenGIS API.
*/
final int numTrailingOrdinates;
/**
- * The sub transform.
- *
- * @see #getSubTransform()
+ * The sub-transform to apply on the {@linkplain #getModifiedCoordinates()
modified coordinates}.
+ * This is often the sub-transform specified at construction time, but not
necessarily.
*/
- final MathTransform subTransform;
+ protected final MathTransform subTransform;
/**
* The inverse transform. This field will be computed only when needed,
@@ -78,10 +90,13 @@ public class PassThroughTransform extend
PassThroughTransform inverse;
/**
- * Creates a pass through transform.
+ * Constructor for sub-classes.
+ * Users should invoke the static {@link #create(int, MathTransform, int)}
factory method instead,
+ * since the most optimal pass-through transform for the given {@code
subTransform} is not necessarily
+ * a {@code PassThroughTransform} instance.
*
* @param firstAffectedOrdinate Index of the first affected ordinate.
- * @param subTransform The sub transform.
+ * @param subTransform The sub-transform to apply on modified
coordinates.
* @param numTrailingOrdinates Number of trailing ordinates to pass
through.
*
* @see #create(int, MathTransform, int)
@@ -117,9 +132,9 @@ public class PassThroughTransform extend
* {@code dimTarget - numTrailingOrdinates} exclusive.
*
* @param firstAffectedOrdinate Index of the first affected ordinate.
- * @param subTransform The sub transform.
+ * @param subTransform The sub-transform to apply on modified
coordinates.
* @param numTrailingOrdinates Number of trailing ordinates to pass
through.
- * @return A pass through transform.
+ * @return A pass-through transform, not necessarily a {@code
PassThroughTransform} instance.
*/
public static MathTransform create(final int firstAffectedOrdinate,
final MathTransform subTransform,
@@ -213,31 +228,8 @@ public class PassThroughTransform extend
}
/**
- * Returns the sub transform.
- *
- * @return The sub transform.
- */
- public final MathTransform getSubTransform() {
- return subTransform;
- }
-
- /**
- * Ordered sequence of positive integers defining the positions in a
coordinate
- * tuple of the coordinates affected by this pass-through transform. The
returned
- * index are for source coordinates.
- *
- * @return The modified coordinates.
- */
- public final int[] getModifiedCoordinates() {
- final int[] index = new int[subTransform.getSourceDimensions()];
- for (int i=0; i<index.length; i++) {
- index[i] = i + firstAffectedOrdinate;
- }
- return index;
- }
-
- /**
- * Gets the dimension of input points.
+ * Gets the dimension of input points. This the source dimension of the
+ * {@linkplain #subTransform sub-transform} plus the number of
pass-through dimensions.
*
* @return {@inheritDoc}
*/
@@ -247,7 +239,8 @@ public class PassThroughTransform extend
}
/**
- * Gets the dimension of output points.
+ * Gets the dimension of output points. This the target dimension of the
+ * {@linkplain #subTransform sub-transform} plus the number of
pass-through dimensions.
*
* @return {@inheritDoc}
*/
@@ -257,7 +250,22 @@ public class PassThroughTransform extend
}
/**
- * Tests whether this transform does not move any points.
+ * Returns the ordered sequence of positive integers defining the
positions in a source
+ * coordinate tuple of the coordinates affected by this pass-through
operation.
+ *
+ * @return Indices of the modified source coordinates.
+ */
+ public int[] getModifiedCoordinates() {
+ final int[] index = new int[subTransform.getSourceDimensions()];
+ for (int i=0; i<index.length; i++) {
+ index[i] = i + firstAffectedOrdinate;
+ }
+ return index;
+ }
+
+ /**
+ * Tests whether this transform does not move any points. A {@code
PassThroughTransform}
+ * is identity if the {@linkplain #subTransform sub-transform} is also
identity.
*
* @return {@inheritDoc}
*/
@@ -291,7 +299,7 @@ public class PassThroughTransform extend
/**
* Transforms many coordinates in a list of ordinal values.
*
- * @throws TransformException If the {@linkplain #getSubTransform()
sub-transform} failed.
+ * @throws TransformException If the {@linkplain #subTransform
sub-transform} failed.
*/
@Override
public void transform(double[] srcPts, int srcOff, final double[] dstPts,
int dstOff, int numPts)
@@ -337,7 +345,7 @@ public class PassThroughTransform extend
/**
* Transforms many coordinates in a list of ordinal values.
*
- * @throws TransformException If the {@linkplain #getSubTransform()
sub-transform} failed.
+ * @throws TransformException If the {@linkplain #subTransform
sub-transform} failed.
*/
@Override
public void transform(float[] srcPts, int srcOff, final float[] dstPts,
int dstOff, int numPts)
@@ -383,7 +391,7 @@ public class PassThroughTransform extend
/**
* Transforms many coordinates in a list of ordinal values.
*
- * @throws TransformException If the {@linkplain #getSubTransform()
sub-transform} failed.
+ * @throws TransformException If the {@linkplain #subTransform
sub-transform} failed.
*/
@Override
public void transform(final double[] srcPts, int srcOff, final float[]
dstPts, int dstOff, int numPts)
@@ -407,7 +415,7 @@ public class PassThroughTransform extend
/**
* Transforms many coordinates in a list of ordinal values.
*
- * @throws TransformException If the {@linkplain #getSubTransform()
sub-transform} failed.
+ * @throws TransformException If the {@linkplain #subTransform
sub-transform} failed.
*/
@Override
public void transform(final float[] srcPts, int srcOff, final double[]
dstPts, int dstOff, int numPts)
@@ -432,7 +440,7 @@ public class PassThroughTransform extend
* Gets the derivative of this transform at a point.
*
* @return {@inheritDoc}
- * @throws TransformException If the {@linkplain #getSubTransform()
sub-transform} failed.
+ * @throws TransformException If the {@linkplain #subTransform
sub-transform} failed.
*/
@Override
public Matrix derivative(final DirectPosition point) throws
TransformException {
@@ -448,7 +456,7 @@ public class PassThroughTransform extend
}
/**
- * Creates a pass through transform from a matrix. This method is invoked
when the
+ * Creates a pass-through transform from a matrix. This method is invoked
when the
* sub-transform can be expressed as a matrix. It is also invoked for
computing the
* matrix returned by {@link #derivative}.
*
@@ -534,7 +542,7 @@ public class PassThroughTransform extend
* Creates the inverse transform of this object.
*
* @return {@inheritDoc}
- * @throws NoninvertibleTransformException If the {@linkplain
#getSubTransform() sub-transform} is not invertible.
+ * @throws NoninvertibleTransformException If the {@linkplain
#subTransform sub-transform} is not invertible.
*/
@Override
public synchronized MathTransform inverse() throws
NoninvertibleTransformException {
Modified:
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/package-info.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/package-info.java?rev=1600847&r1=1600846&r2=1600847&view=diff
==============================================================================
---
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/package-info.java
[UTF-8] (original)
+++
sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform/package-info.java
[UTF-8] Fri Jun 6 11:40:24 2014
@@ -17,12 +17,29 @@
/**
* Conversions or transformations of multi-dimensional coordinate points.
- * A {@link org.opengis.referencing.operation.MathTransform} usually performs
conversions or transformations
- * from points given in a {@linkplain
org.apache.sis.referencing.operation.DefaultCoordinateOperation#getSourceCRS()
+ * {@link org.opengis.referencing.operation.MathTransform} provides a single
API for
+ * coordinate conversions or transformations, including map projections.
+ * Each {@code MathTransform} instances can:
+ *
+ * <ul>
+ * <li>transform a single point,</li>
+ * <li>transform efficiently an array of coordinates,</li>
+ * <li>transform a Java2D {@link java.awt.Shape} ({@link
org.opengis.referencing.operation.MathTransform2D} only),</li>
+ * <li>compute the transform derivative at a location (for advanced
users),</li>
+ * <li>be concatenated in a conversion or transformation chain.</li>
+ * </ul>
+ *
+ * {@code MathTransform} are truly <var>n</var>-dimensional, but specialized
implementations
+ * for 1D and 2D cases are provided for performance reasons or for
inter-operability with Java2D.
+ * In the 2D case, Apache SIS provides instances of the standard {@link
java.awt.geom.AffineTransform}
+ * class when possible.
+ *
+ * <p>{@code MathTransform} usually performs conversions or transformations
from points given in a
+ * {@linkplain
org.apache.sis.referencing.operation.DefaultCoordinateOperation#getSourceCRS()
* source coordinate reference system} to coordinate values for the same
points in the
* {@linkplain
org.apache.sis.referencing.operation.DefaultCoordinateOperation#getTargetCRS()
* target coordinate reference system}. However the conversions are not
necessarily between CRS;
- * a {@code MathTransform} can also be used for converting the sample values
in a raster for example.
+ * a {@code MathTransform} can also be used for converting the sample values
in a raster for example.</p>
*
* <p>This package does not include map projections, which are a special kind
of transforms defined
* in their own {@linkplain org.apache.sis.referencing.operation.projection
projection} package.</p>
