Class GeneralMatrix

java.lang.Object
org.apache.sis.referencing.operation.matrix.MatrixSIS
org.apache.sis.referencing.operation.matrix.GeneralMatrix
All Implemented Interfaces:
Serializable, Cloneable, ExtendedPrecisionMatrix, LenientComparable, org.opengis.referencing.operation.Matrix
Direct Known Subclasses:
NonSquareMatrix

class GeneralMatrix extends MatrixSIS implements ExtendedPrecisionMatrix
A two dimensional array of numbers. Row and column numbering begins with zero.

Support for extended precision

This class can optionally support extended precision using the double-double arithmetic. In extended precision mode, the elements array have twice its normal length. The first half of the array contains the same value than in normal precision mode, while the second half contains the DoubleDouble.error.
Since:
0.4
Version:
1.3
See Also:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    (package private) final double[]
    All matrix elements in a flat, row-major (column indices vary fastest) array.
    (package private) short
    Number of rows and columns.
    (package private) short
    Number of rows and columns.
    private static final long
    Serial number for inter-operability with different versions.
    private static final double
    Threshold value relative to 1 ULP of the greatest magnitude of elements added in a sum.

    Fields inherited from interface org.apache.sis.internal.referencing.ExtendedPrecisionMatrix

    IDENTITY, ZERO
  • Constructor Summary

    Constructors
    Constructor
    Description
    GeneralMatrix(int numRow, int numCol, boolean setToIdentity, int precision)
    Creates a matrix of size numRow × numCol.
    GeneralMatrix(int numRow, int numCol, double[] elements)
    Constructs a numRow × numCol matrix initialized to the values in the elements array.
    Creates a clone of the given matrix, for clone() usage only.
    GeneralMatrix(org.opengis.referencing.operation.Matrix matrix)
    Constructs a new matrix and copies the initial values from the given matrix.
  • Method Summary

    Modifier and Type
    Method
    Description
    Returns a clone of this matrix.
    (package private) static GeneralMatrix
    createExtendedPrecision(int numRow, int numCol, boolean setToIdentity)
    Creates a new extended precision matrix of the given size.
    private static void
    ensureValidSize(int numRow, int numCol)
    Ensures that the given matrix size is valid for this GeneralMatrix implementation.
    final boolean
    equals(Object object)
    Returns true if the specified object is of type GeneralMatrix and all of the data members are equal to the corresponding data members in this matrix.
    (package private) final void
    get(int row, int column, DoubleDouble dd)
    Stores the value at the specified row and column in the given dd object.
    final double
    getElement(int row, int column)
    Retrieves the value at the specified row and column of this matrix.
    final double[]
    Returns a copy of all matrix elements in a flat, row-major (column indices vary fastest) array.
    (package private) final void
    getElements(double[] dest)
    Copies the matrix elements in the given flat array.
    final double[]
    Returns a copy of all matrix elements, potentially followed by the error terms for extended-precision arithmetic.
    (package private) static double[]
    getExtendedElements(org.opengis.referencing.operation.Matrix matrix, int numRow, int numCol, boolean copy)
    Returns all elements of the given matrix followed by the error terms for extended-precision arithmetic.
    long
    getInteger(int row, int column)
    Retrieves the value at the specified row and column of this matrix, rounded to nearest integer.
    getNumber(int row, int column)
    Retrieves the value at the specified row and column of this matrix, wrapped in a Number or a DoubleDouble depending on available precision.
    final int
    Returns the number of columns in this matrix.
    final int
    Returns the number of rows in this matrix.
    final int
    Returns a hash code value based on the data values in this object.
    (package private) static int
    indexOfErrors(int numRow, int numCol, double[] elements)
    Returns the index of the first DoubleDouble.error value in the elements array, or 0 if none.
    (package private) static void
    inferErrors(double[] elements)
    Infers all DoubleDouble.error with a default values inferred from DoubleDouble.value.
    final boolean
    Returns true if this matrix represents an affine transform.
    (package private) final boolean
    isAffine(boolean square)
    Implementation of isAffine() with control on whether we require the matrix to be square.
    (package private) final boolean
    Returns true if this matrix uses extended precision.
    final boolean
    Returns true if this matrix is an identity matrix.
    (package private) final void
    set(int row, int column, DoubleDouble dd)
    Stores the value of the given dd object at the specified row and column.
    final void
    setElement(int row, int column, double value)
    Modifies the value at the specified row and column of this matrix.
    final void
    setElements(double[] newValues)
    Sets all matrix elements from a flat, row-major (column indices vary fastest) array.
    (package private) final boolean
    setElements(Number[] newValues)
    Sets all matrix elements like setElements(double[]), but from an array of Number instead of double.
    void
    setMatrix(org.opengis.referencing.operation.Matrix matrix)
    Sets this matrix to the values of another matrix.
    (package private) final void
    setToProduct(org.opengis.referencing.operation.Matrix A, org.opengis.referencing.operation.Matrix B)
    Sets this matrix to the product of the given matrices: this = A × B.
    void
    Sets the value of this matrix to its transpose.

    Methods inherited from class java.lang.Object

    finalize, getClass, notify, notifyAll, wait, wait, wait
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      Serial number for inter-operability with different versions.
      See Also:
    • ZERO_THRESHOLD

      private static final double ZERO_THRESHOLD
      Threshold value relative to 1 ULP of the greatest magnitude of elements added in a sum. For example, in a sum like A + B + C + D, if the greatest term in absolute value is C, then the threshold is Math.ulp(C) * 1.0E-14. If the sum is lower than that threshold, then the result is assumed to be zero.

      Note that if we were using double arithmetic instead of double-double, then all results smaller than Math.ulp(max) would not be significant. Those cases could be caught by a ZERO_THRESHOLD value of 1. On the other hand, if all the extra precision of double-double arithmetic was considered valid, then the ZERO_THRESHOLD value would be approximately 1E-16. In reality, the extra digits in our double-double arithmetic were usually guessed rather than provided, and the last digits are also subject to rounding errors anyway. So we put the threshold to some arbitrary mid-value, which may change in any future SIS version according experience gained. As long as the value is smaller than 1, it still more accurate than double arithmetic anyway.

      Note: A similar constant exists in org.apache.sis.math.Plane.
      See Also:
    • elements

      final double[] elements
      All matrix elements in a flat, row-major (column indices vary fastest) array. The array length is numRow * numCol.

      In extended precision mode, the length of this array is actually twice the above-cited length. The first half contains DoubleDouble.value, and the second half contains the DoubleDouble.error for each value in the first half.

    • numRow

      short numRow
      Number of rows and columns. This is non-final only for NonSquareMatrix.transpose() purpose.
    • numCol

      short numCol
      Number of rows and columns. This is non-final only for NonSquareMatrix.transpose() purpose.
  • Constructor Details

    • GeneralMatrix

      GeneralMatrix(int numRow, int numCol, boolean setToIdentity, int precision)
      Creates a matrix of size numRow × numCol. If setToIdentity is true, then the elements on the diagonal (j == i) are set to 1.
      Parameters:
      numRow - number of rows.
      numCol - number of columns.
      setToIdentity - true for initializing the matrix to the identity matrix, or false for leaving it initialized to zero.
      precision - 1 for normal precision, or 2 for extended precision. No other value is allowed (this is not verified).
    • GeneralMatrix

      GeneralMatrix(int numRow, int numCol, double[] elements)
      Constructs a numRow × numCol matrix initialized to the values in the elements array. The array values are copied in one row at a time in row major fashion. The array shall be exactly numRow*numCol in length.
      Parameters:
      numRow - number of rows.
      numCol - number of columns.
      elements - initial values.
    • GeneralMatrix

      GeneralMatrix(org.opengis.referencing.operation.Matrix matrix)
      Constructs a new matrix and copies the initial values from the given matrix.
      Parameters:
      matrix - the matrix to copy.
    • GeneralMatrix

      GeneralMatrix(GeneralMatrix matrix)
      Creates a clone of the given matrix, for clone() usage only.
  • Method Details

    • createExtendedPrecision

      static GeneralMatrix createExtendedPrecision(int numRow, int numCol, boolean setToIdentity)
      Creates a new extended precision matrix of the given size.
      Parameters:
      numRow - number of rows.
      numCol - number of columns.
      setToIdentity - true for initializing the matrix to the identity matrix, or false for leaving it initialized to zero.
    • inferErrors

      static void inferErrors(double[] elements)
      Infers all DoubleDouble.error with a default values inferred from DoubleDouble.value. For example if a matrix element is exactly 3.141592653589793, there is good chances that the user's intent was to specify the Math.PI value, in which case this method will infer that we would need to add 1.2246467991473532E-16 in order to get a value closer to π.
    • indexOfErrors

      static int indexOfErrors(int numRow, int numCol, double[] elements)
      Returns the index of the first DoubleDouble.error value in the elements array, or 0 if none. This method returns a non-zero value only if the matrix has been created in extended precision mode.
    • ensureValidSize

      private static void ensureValidSize(int numRow, int numCol)
      Ensures that the given matrix size is valid for this GeneralMatrix implementation.
    • getNumRow

      public final int getNumRow()
      Returns the number of rows in this matrix.
      Specified by:
      getNumRow in interface org.opengis.referencing.operation.Matrix
    • getNumCol

      public final int getNumCol()
      Returns the number of columns in this matrix.
      Specified by:
      getNumCol in interface org.opengis.referencing.operation.Matrix
    • isExtendedPrecision

      final boolean isExtendedPrecision()
      Returns true if this matrix uses extended precision.
      Overrides:
      isExtendedPrecision in class MatrixSIS
    • get

      final void get(int row, int column, DoubleDouble dd)
      Stores the value at the specified row and column in the given dd object. This method does not need to verify argument validity.
      Overrides:
      get in class MatrixSIS
    • set

      final void set(int row, int column, DoubleDouble dd)
      Stores the value of the given dd object at the specified row and column. This method does not need to verify argument validity.
      Overrides:
      set in class MatrixSIS
    • getInteger

      public long getInteger(int row, int column)
      Retrieves the value at the specified row and column of this matrix, rounded to nearest integer.
      Overrides:
      getInteger in class MatrixSIS
      Parameters:
      row - the row index, from 0 inclusive to getNumRow() exclusive.
      column - the column index, from 0 inclusive to getNumCol() exclusive.
      Returns:
      the current value at the given row and column, rounded to nearest integer.
      Since:
      1.3
      See Also:
    • getNumber

      public Number getNumber(int row, int column)
      Retrieves the value at the specified row and column of this matrix, wrapped in a Number or a DoubleDouble depending on available precision.
      Overrides:
      getNumber in class MatrixSIS
      Parameters:
      row - the row index, from 0 inclusive to getNumRow() exclusive.
      column - the column index, from 0 inclusive to getNumCol() exclusive.
      Returns:
      the current value at the given row and column.
    • getElement

      public final double getElement(int row, int column)
      Retrieves the value at the specified row and column of this matrix.
      Specified by:
      getElement in interface org.opengis.referencing.operation.Matrix
      Specified by:
      getElement in class MatrixSIS
      Parameters:
      row - the row index, from 0 inclusive to getNumRow() exclusive.
      column - the column index, from 0 inclusive to getNumCol() exclusive.
      Returns:
      the current value at the given row and column.
    • setElement

      public final void setElement(int row, int column, double value)
      Modifies the value at the specified row and column of this matrix.
      Specified by:
      setElement in interface org.opengis.referencing.operation.Matrix
      Parameters:
      row - the row index, from 0 inclusive to getNumRow() exclusive.
      column - the column index, from 0 inclusive to getNumCol() exclusive.
      value - the new value to set at the given row and column.
    • getExtendedElements

      static double[] getExtendedElements(org.opengis.referencing.operation.Matrix matrix, int numRow, int numCol, boolean copy)
      Returns all elements of the given matrix followed by the error terms for extended-precision arithmetic. The array will have twice the normal length. See elements for more discussion.

      This method may return a direct reference to the internal array. Do not modify., unless the copy argument is true.

      Parameters:
      copy - if true, then the returned array is guaranteed to be a copy, never the internal array.
    • getExtendedElements

      public final double[] getExtendedElements()
      Returns a copy of all matrix elements, potentially followed by the error terms for extended-precision arithmetic. Matrix elements are returned in a flat, row-major (column indices vary fastest) array.
      Specified by:
      getExtendedElements in interface ExtendedPrecisionMatrix
      Returns:
      a copy of matrix elements, potentially followed by error terms.
    • getElements

      public final double[] getElements()
      Returns a copy of all matrix elements in a flat, row-major (column indices vary fastest) array. The array length is Matrix.getNumRow() * Matrix.getNumCol().
      Overrides:
      getElements in class MatrixSIS
      Returns:
      a copy of all current matrix elements in a row-major array.
    • getElements

      final void getElements(double[] dest)
      Copies the matrix elements in the given flat array. This method does not verify the array length, since the destination array may contain room for DoubleDouble.error terms.
      Overrides:
      getElements in class MatrixSIS
      Parameters:
      dest - the destination array. May be longer than necessary (this happen when the caller needs to append DoubleDouble.error values after the elements).
    • setElements

      public final void setElements(double[] newValues)
      Sets all matrix elements from a flat, row-major (column indices vary fastest) array. The array length shall be Matrix.getNumRow() * Matrix.getNumCol().
      Specified by:
      setElements in class MatrixSIS
      Parameters:
      newValues - The new matrix elements in a row-major array.
      See Also:
    • setElements

      final boolean setElements(Number[] newValues)
      Sets all matrix elements like setElements(double[]), but from an array of Number instead of double. The main purpose of this method is to fetch the DoubleDouble.error terms when such instances are found.

      Restrictions

      Parameters:
      newValues - the new matrix elements in a row-major array.
      Returns:
      true if at leat one DoubleDouble instance has been found, in which case all errors terms have been initialized, or false otherwise, in which case no error term has been initialized (this is a all or nothing operation).
      Throws:
      IllegalArgumentException - if the given array does not have the expected length.
      See Also:
    • setMatrix

      public void setMatrix(org.opengis.referencing.operation.Matrix matrix) throws MismatchedMatrixSizeException
      Sets this matrix to the values of another matrix. This method overrides the default implementation with a more efficient implementation in the particular case where the other matrix is an instance of GeneralMatrix.
      Overrides:
      setMatrix in class MatrixSIS
      Parameters:
      matrix - the matrix to copy.
      Throws:
      MismatchedMatrixSizeException - if the given matrix has a different size than this matrix.
      Since:
      0.7
    • isAffine

      public final boolean isAffine()
      Returns true if this matrix represents an affine transform. A transform is affine if the matrix is square and its last row contains only zeros, except in the last column which contains 1.

      This method does not check the error terms, because those terms are not visible to the user (they cannot appear in the value returned by getElement(int, int), and are not shown by MatrixSIS.toString()) - returning false while the matrix clearly looks like affine would be confusing for the user. Furthermore, the errors can be non-zero only in the very last element and that value always smaller than 2.3E-16.

      Overrides:
      isAffine in class MatrixSIS
      Returns:
      true if this matrix represents an affine transform.
      See Also:
    • isAffine

      final boolean isAffine(boolean square)
      Implementation of isAffine() with control on whether we require the matrix to be square.
      Parameters:
      square - true if the matrix must be square, or false for allowing non-square matrices.
    • isIdentity

      public final boolean isIdentity()
      Returns true if this matrix is an identity matrix. This method is equivalent to the following code, except that it is potentially more efficient:

      This method does not check the error terms, because those terms are not visible to the user (they cannot appear in the value returned by getElement(int, int), and are not shown by MatrixSIS.toString()) - returning false while the matrix clearly looks like identity would be confusing for the user. Furthermore, the errors can be non-zero only on the diagonal, and those values always smaller than 2.3E-16.

      Another argument is that the extended precision is for reducing rounding errors during matrix arithmetic. But since the user provided the original data as double values, the extra precision usually have no "real" meaning.

      Specified by:
      isIdentity in interface org.opengis.referencing.operation.Matrix
      Specified by:
      isIdentity in class MatrixSIS
      Returns:
      true if this matrix is an identity matrix.
      See Also:
    • transpose

      public void transpose()
      Sets the value of this matrix to its transpose. The implementation provided by GeneralMatrix is valid only for square matrix. NonSquareMatrix must override.
      Specified by:
      transpose in class MatrixSIS
    • setToProduct

      final void setToProduct(org.opengis.referencing.operation.Matrix A, org.opengis.referencing.operation.Matrix B)
      Sets this matrix to the product of the given matrices: this = A × B. The matrix sizes much match - this is not verified unless assertions are enabled.
    • equals

      public final boolean equals(Object object)
      Returns true if the specified object is of type GeneralMatrix and all of the data members are equal to the corresponding data members in this matrix.
      Specified by:
      equals in interface LenientComparable
      Overrides:
      equals in class MatrixSIS
      Parameters:
      object - the object to compare with this matrix for equality.
      Returns:
      true if the given object is equal to this matrix.
      See Also:
    • hashCode

      public final int hashCode()
      Returns a hash code value based on the data values in this object.
      Overrides:
      hashCode in class MatrixSIS
      Returns:
      a hash code value for this matrix.
    • clone

      public MatrixSIS clone()
      Returns a clone of this matrix.
      Specified by:
      clone in interface org.opengis.referencing.operation.Matrix
      Overrides:
      clone in class MatrixSIS
      Returns:
      a new matrix of the same class and with the same values than this matrix.
      See Also: