sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1521666 - in /sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix: Matrix1.java Matrix2.java Matrix3.java package-info.java
Date Tue, 10 Sep 2013 22:28:02 GMT
Author: desruisseaux
Date: Tue Sep 10 22:28:01 2013
New Revision: 1521666

URL: http://svn.apache.org/r1521666
Log:
Push Matrix1,2,3,4 in public API, and added a rational in the package javadoc.
This is the same than what Vecmath (from Java3D) and Geotk did.

Modified:
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/Matrix1.java
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/Matrix2.java
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/Matrix3.java
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/package-info.java

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/Matrix1.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/Matrix1.java?rev=1521666&r1=1521665&r2=1521666&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/Matrix1.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/Matrix1.java
[UTF-8] Tue Sep 10 22:28:01 2013
@@ -29,7 +29,7 @@ import org.apache.sis.internal.util.Nume
  * @version 0.4
  * @module
  */
-final class Matrix1 extends MatrixSIS {
+public final class Matrix1 extends MatrixSIS {
     /**
      * Serial number for inter-operability with different versions.
      */
@@ -43,7 +43,7 @@ final class Matrix1 extends MatrixSIS {
     /**
      * The only element in this matrix.
      */
-    private double m00;
+    public double m00;
 
     /**
      * Creates a new identity matrix.
@@ -74,6 +74,8 @@ final class Matrix1 extends MatrixSIS {
 
     /**
      * Returns the number of rows in this matrix, which is always {@value #SIZE} in this
implementation.
+     *
+     * @return {@value SIZE}.
      */
     @Override
     public final int getNumRow() {
@@ -82,6 +84,8 @@ final class Matrix1 extends MatrixSIS {
 
     /**
      * Returns the number of columns in this matrix, which is always {@value #SIZE} in this
implementation.
+     *
+     * @return {@value SIZE}.
      */
     @Override
     public final int getNumCol() {
@@ -90,6 +94,13 @@ final class Matrix1 extends MatrixSIS {
 
     /**
      * Retrieves the value at the specified row and column of this matrix.
+     * This method can be invoked when the matrix size or type is unknown.
+     * If the matrix is known to be an instance of {@code Matrix1},
+     * then the {@link #m00} field can be read directly for efficiency.
+     *
+     * @param row    The row index, which can only be 0.
+     * @param column The column index, which can only be 0.
+     * @return       The current value.
      */
     @Override
     public double getElement(final int row, final int column) {
@@ -102,6 +113,13 @@ final class Matrix1 extends MatrixSIS {
 
     /**
      * Modifies the value at the specified row and column of this matrix.
+     * This method can be invoked when the matrix size or type is unknown.
+     * If the matrix is known to be an instance of {@code Matrix1},
+     * then the {@link #m00} field can be set directly for efficiency.
+     *
+     * @param row    The row index, which can only be 0.
+     * @param column The column index, which can only be 0.
+     * @param value  The new value to set.
      */
     @Override
     public void setElement(final int row, final int column, final double value) {

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/Matrix2.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/Matrix2.java?rev=1521666&r1=1521665&r2=1521666&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/Matrix2.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/Matrix2.java
[UTF-8] Tue Sep 10 22:28:01 2013
@@ -30,7 +30,7 @@ import org.apache.sis.internal.util.Nume
  * @version 0.4
  * @module
  */
-final class Matrix2 extends MatrixSIS {
+public final class Matrix2 extends MatrixSIS {
     /**
      * Serial number for inter-operability with different versions.
      */
@@ -41,10 +41,10 @@ final class Matrix2 extends MatrixSIS {
      */
     public static final int SIZE = 2;
 
-    /** The first matrix element in the first row.   */ private double m00;
-    /** The second matrix element in the first row.  */ private double m01;
-    /** The first matrix element in the second row.  */ private double m10;
-    /** The second matrix element in the second row. */ private double m11;
+    /** The first matrix element in the first row.   */ public double m00;
+    /** The second matrix element in the first row.  */ public double m01;
+    /** The first matrix element in the second row.  */ public double m10;
+    /** The second matrix element in the second row. */ public double m11;
 
     /**
      * Creates a new identity matrix.
@@ -100,6 +100,8 @@ final class Matrix2 extends MatrixSIS {
 
     /**
      * Returns the number of rows in this matrix, which is always {@value #SIZE} in this
implementation.
+     *
+     * @return {@value SIZE}.
      */
     @Override
     public final int getNumRow() {
@@ -108,6 +110,8 @@ final class Matrix2 extends MatrixSIS {
 
     /**
      * Returns the number of columns in this matrix, which is always {@value #SIZE} in this
implementation.
+     *
+     * @return {@value SIZE}.
      */
     @Override
     public final int getNumCol() {
@@ -116,6 +120,13 @@ final class Matrix2 extends MatrixSIS {
 
     /**
      * Retrieves the value at the specified row and column of this matrix.
+     * This method can be invoked when the matrix size or type is unknown.
+     * If the matrix is known to be an instance of {@code Matrix2},
+     * then the {@link #m00} … {@link #m11} fields can be read directly for efficiency.
+     *
+     * @param row    The row index, which can only be 0 or 1.
+     * @param column The column index, which can only be 0 or 1.
+     * @return       The current value at the given row and column.
      */
     @Override
     public double getElement(final int row, final int column) {
@@ -130,6 +141,13 @@ final class Matrix2 extends MatrixSIS {
 
     /**
      * Modifies the value at the specified row and column of this matrix.
+     * This method can be invoked when the matrix size or type is unknown.
+     * If the matrix is known to be an instance of {@code Matrix2},
+     * then the {@link #m00} … {@link #m11} fields can be set directly for efficiency.
+     *
+     * @param row    The row index, which can only be 0 or 1.
+     * @param column The column index, which can only be 0 or 1.
+     * @param value  The new value to set at the given row and column.
      */
     @Override
     public void setElement(final int row, final int column, final double value) {

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/Matrix3.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/Matrix3.java?rev=1521666&r1=1521665&r2=1521666&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/Matrix3.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/Matrix3.java
[UTF-8] Tue Sep 10 22:28:01 2013
@@ -31,7 +31,11 @@ import org.apache.sis.math.MathFunctions
  * @version 0.4
  * @module
  */
-final class Matrix3 extends MatrixSIS {
+public final class Matrix3 extends MatrixSIS {
+// Note: if the above 'final' keyword is removed, revisit the methods in this class
+// which invoke other methods: Matrix3(Matrix) constructor, setToIdentity(), etc.
+// We may want to protect them against overriding of the method they invoke.
+
     /**
      * Serial number for inter-operability with different versions.
      */
@@ -42,15 +46,15 @@ final class Matrix3 extends MatrixSIS {
      */
     public static final int SIZE = 3;
 
-     /** The first matrix element in the first row.   */ private double m00;
-     /** The second matrix element in the first row.  */ private double m01;
-     /** The third matrix element in the first row.   */ private double m02;
-     /** The first matrix element in the second row.  */ private double m10;
-     /** The second matrix element in the second row. */ private double m11;
-     /** The third matrix element in the second row.  */ private double m12;
-     /** The first matrix element in the third row.   */ private double m20;
-     /** The second matrix element in the third row.  */ private double m21;
-     /** The third matrix element in the third row.   */ private double m22;
+     /** The first matrix element in the first row.   */ public double m00;
+     /** The second matrix element in the first row.  */ public double m01;
+     /** The third matrix element in the first row.   */ public double m02;
+     /** The first matrix element in the second row.  */ public double m10;
+     /** The second matrix element in the second row. */ public double m11;
+     /** The third matrix element in the second row.  */ public double m12;
+     /** The first matrix element in the third row.   */ public double m20;
+     /** The second matrix element in the third row.  */ public double m21;
+     /** The third matrix element in the third row.   */ public double m22;
 
     /**
      * Creates a new identity matrix.
@@ -123,6 +127,8 @@ final class Matrix3 extends MatrixSIS {
 
     /**
      * Returns the number of rows in this matrix, which is always {@value #SIZE} in this
implementation.
+     *
+     * @return {@value SIZE}.
      */
     @Override
     public final int getNumRow() {
@@ -131,6 +137,8 @@ final class Matrix3 extends MatrixSIS {
 
     /**
      * Returns the number of columns in this matrix, which is always {@value #SIZE} in this
implementation.
+     *
+     * @return {@value SIZE}.
      */
     @Override
     public final int getNumCol() {
@@ -150,6 +158,13 @@ final class Matrix3 extends MatrixSIS {
 
     /**
      * Retrieves the value at the specified row and column of this matrix.
+     * This method can be invoked when the matrix size or type is unknown.
+     * If the matrix is known to be an instance of {@code Matrix3},
+     * then the {@link #m00} … {@link #m22} fields can be read directly for efficiency.
+     *
+     * @param row    The row index, from 0 inclusive to {@value #SIZE} exclusive.
+     * @param column The column index, from 0 inclusive to {@value #SIZE} exclusive.
+     * @return       The current value at the given row and column.
      */
     @Override
     public double getElement(final int row, final int column) {
@@ -169,6 +184,13 @@ final class Matrix3 extends MatrixSIS {
 
     /**
      * Modifies the value at the specified row and column of this matrix.
+     * This method can be invoked when the matrix size or type is unknown.
+     * If the matrix is known to be an instance of {@code Matrix3},
+     * then the {@link #m00} … {@link #m22} fields can be set directly for efficiency.
+     *
+     * @param row    The row index, from 0 inclusive to {@value #SIZE} exclusive.
+     * @param column The column index, from 0 inclusive to {@value #SIZE} exclusive.
+     * @param value  The new value to set at the given row and column.
      */
     @Override
     public void setElement(final int row, final int column, final double value) {
@@ -243,7 +265,7 @@ final class Matrix3 extends MatrixSIS {
      * {@inheritDoc}
      */
     @Override
-    public final void transpose() {
+    public void transpose() {
         double swap;
         swap = m01; m01 = m10; m10 = swap;
         swap = m02; m02 = m20; m20 = swap;

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/package-info.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/package-info.java?rev=1521666&r1=1521665&r2=1521666&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/package-info.java
(original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/operation/matrix/package-info.java
Tue Sep 10 22:28:01 2013
@@ -17,11 +17,19 @@
 
 /**
  * {@linkplain org.opengis.referencing.operation.Matrix} implementations tuned for spatio-temporal
referencing.
- * Matrices can be of arbitrary size, but the most common ones in the context of spatio-temporal
referencing are
- * not greater than 5×5 (because the matrix size in affine transforms is the number of
dimensions + 1).
+ * Matrices can be of arbitrary size, but the most common ones in the context of geospatial
coordinate operations
+ * are not greater than 5×5 (number of spatio-temporal dimensions + 1).
  * This package differs from other matrix packages by the special treatment done for such
small matrices.
  *
- * <p><b>Example:</b> In the two dimensional case, an affine transform
from a map projection (units in metres)
+ * <p>This package provides public implementations of small square matrices, with size
ranging from 1×1 to 4×4.
+ * Those implementations are made public because in many cases, the user know that (s)he
is working with (for
+ * example) three-dimensional Coordinate Reference Systems (CRS). If the number of CRS dimensions
is fixed to 3,
+ * then <cite>affine transforms</cite> between those CRS can be represented by
4×4 matrices,
+ * and the <cite>derivatives</cite> of those transforms can be represented by
3×3 matrices.
+ * Since the user know the matrices size, (s)he can use the specific implementation and read
or write
+ * directly the <var>m</var><sub><var>row</var> <var>column</var></sub>
field.</p>
+ *
+ * <p><b>Example:</b> in the two dimensional case, an affine transform
from a map projection (units in metres)
  * to the screen (units in pixels) can be performed by the following matrix multiplication:</p>
  *
  * <p><center><img src="doc-files/AffineTransform.png"></center></p>



Mime
View raw message