sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1600847 - in /sis/branches/JDK8/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/transform: LinearTransform.java PassThroughTransform.java package-info.java
Date Fri, 06 Jun 2014 11:40:25 GMT
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>



Mime
View raw message