Class GeneralMatrix
- All Implemented Interfaces:
Serializable
,Cloneable
,ExtendedPrecisionMatrix
,LenientComparable
,org.opengis.referencing.operation.Matrix
- Direct Known Subclasses:
NonSquareMatrix
Support for extended precision
This class can optionally support extended precision using the double-double arithmetic. In extended precision mode, theelements
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
FieldsModifier and TypeFieldDescription(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
ConstructorsConstructorDescriptionGeneralMatrix
(int numRow, int numCol, boolean setToIdentity, int precision) Creates a matrix of sizenumRow
×numCol
.GeneralMatrix
(int numRow, int numCol, double[] elements) Constructs anumRow
×numCol
matrix initialized to the values in theelements
array.GeneralMatrix
(GeneralMatrix matrix) Creates a clone of the given matrix, forclone()
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 TypeMethodDescriptionclone()
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 thisGeneralMatrix
implementation.final boolean
Returnstrue
if the specified object is of typeGeneralMatrix
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 givendd
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 aNumber
or aDoubleDouble
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
hashCode()
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 firstDoubleDouble.error
value in theelements
array, or 0 if none.(package private) static void
inferErrors
(double[] elements) Infers allDoubleDouble.error
with a default values inferred fromDoubleDouble.value
.final boolean
isAffine()
Returnstrue
if this matrix represents an affine transform.(package private) final boolean
isAffine
(boolean square) Implementation ofisAffine()
with control on whether we require the matrix to be square.(package private) final boolean
Returnstrue
if this matrix uses extended precision.final boolean
Returnstrue
if this matrix is an identity matrix.(package private) final void
set
(int row, int column, DoubleDouble dd) Stores the value of the givendd
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) 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 org.apache.sis.referencing.operation.matrix.MatrixSIS
castOrCopy, convertAfter, convertBefore, ensureLengthMatch, ensureNumRowMatch, ensureSizeMatch, equals, equals, getElements, indexOutOfBounds, inverse, isAffine, multiply, multiply, normalizeColumns, removeColumns, removeRows, setElements, setNumber, solve, toString, translate
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDSerial number for inter-operability with different versions.- See Also:
-
ZERO_THRESHOLD
private static final double ZERO_THRESHOLDThreshold value relative to 1 ULP of the greatest magnitude of elements added in a sum. For example, in a sum likeA + B + C + D
, if the greatest term in absolute value isC
, then the threshold isMath.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 thanMath.ulp(max)
would not be significant. Those cases could be caught by aZERO_THRESHOLD
value of 1. On the other hand, if all the extra precision of double-double arithmetic was considered valid, then theZERO_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 thandouble
arithmetic anyway.Note: A similar constant exists inorg.apache.sis.math.Plane
.- See Also:
-
elements
final double[] elementsAll matrix elements in a flat, row-major (column indices vary fastest) array. The array length isnumRow * 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 theDoubleDouble.error
for each value in the first half. -
numRow
short numRowNumber of rows and columns. This is non-final only forNonSquareMatrix.transpose()
purpose. -
numCol
short numColNumber of rows and columns. This is non-final only forNonSquareMatrix.transpose()
purpose.
-
-
Constructor Details
-
GeneralMatrix
GeneralMatrix(int numRow, int numCol, boolean setToIdentity, int precision) Creates a matrix of sizenumRow
×numCol
. IfsetToIdentity
istrue
, 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, orfalse
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 anumRow
×numCol
matrix initialized to the values in theelements
array. The array values are copied in one row at a time in row major fashion. The array shall be exactlynumRow*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, forclone()
usage only.
-
-
Method Details
-
createExtendedPrecision
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, orfalse
for leaving it initialized to zero.
-
inferErrors
static void inferErrors(double[] elements) Infers allDoubleDouble.error
with a default values inferred fromDoubleDouble.value
. For example if a matrix element is exactly 3.141592653589793, there is good chances that the user's intent was to specify theMath.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 firstDoubleDouble.error
value in theelements
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 thisGeneralMatrix
implementation. -
getNumRow
public final int getNumRow()Returns the number of rows in this matrix.- Specified by:
getNumRow
in interfaceorg.opengis.referencing.operation.Matrix
-
getNumCol
public final int getNumCol()Returns the number of columns in this matrix.- Specified by:
getNumCol
in interfaceorg.opengis.referencing.operation.Matrix
-
isExtendedPrecision
final boolean isExtendedPrecision()Returnstrue
if this matrix uses extended precision.- Overrides:
isExtendedPrecision
in classMatrixSIS
-
get
Stores the value at the specified row and column in the givendd
object. This method does not need to verify argument validity. -
set
Stores the value of the givendd
object at the specified row and column. This method does not need to verify argument validity. -
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 classMatrixSIS
- Parameters:
row
- the row index, from 0 inclusive togetNumRow()
exclusive.column
- the column index, from 0 inclusive togetNumCol()
exclusive.- Returns:
- the current value at the given row and column, rounded to nearest integer.
- Since:
- 1.3
- See Also:
-
getNumber
Retrieves the value at the specified row and column of this matrix, wrapped in aNumber
or aDoubleDouble
depending on available precision.- Overrides:
getNumber
in classMatrixSIS
- Parameters:
row
- the row index, from 0 inclusive togetNumRow()
exclusive.column
- the column index, from 0 inclusive togetNumCol()
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 interfaceorg.opengis.referencing.operation.Matrix
- Specified by:
getElement
in classMatrixSIS
- Parameters:
row
- the row index, from 0 inclusive togetNumRow()
exclusive.column
- the column index, from 0 inclusive togetNumCol()
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 interfaceorg.opengis.referencing.operation.Matrix
- Parameters:
row
- the row index, from 0 inclusive togetNumRow()
exclusive.column
- the column index, from 0 inclusive togetNumCol()
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. Seeelements
for more discussion.This method may return a direct reference to the internal array. Do not modify., unless the
copy
argument istrue
.- Parameters:
copy
- iftrue
, 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 interfaceExtendedPrecisionMatrix
- 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 isMatrix.getNumRow() * Matrix.getNumCol()
.- Overrides:
getElements
in classMatrixSIS
- 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 forDoubleDouble.error
terms.- Overrides:
getElements
in classMatrixSIS
- Parameters:
dest
- the destination array. May be longer than necessary (this happen when the caller needs to appendDoubleDouble.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 beMatrix.getNumRow() * Matrix.getNumCol()
.- Specified by:
setElements
in classMatrixSIS
- Parameters:
newValues
- The new matrix elements in a row-major array.- See Also:
-
setElements
Sets all matrix elements likesetElements(double[])
, but from an array ofNumber
instead ofdouble
. The main purpose of this method is to fetch theDoubleDouble.error
terms when such instances are found.Restrictions
- This matrix must use extended-precision elements as by
createExtendedPrecision(int, int, boolean)
. - If this method returns
false
, then error terms are not initialized - they may have any values.
- Parameters:
newValues
- the new matrix elements in a row-major array.- Returns:
true
if at leat oneDoubleDouble
instance has been found, in which case all errors terms have been initialized, orfalse
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:
- This matrix must use extended-precision elements as by
-
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 ofGeneralMatrix
.- Overrides:
setMatrix
in classMatrixSIS
- 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()Returnstrue
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 byMatrixSIS.toString()
) - returningfalse
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. -
isAffine
final boolean isAffine(boolean square) Implementation ofisAffine()
with control on whether we require the matrix to be square.- Parameters:
square
-true
if the matrix must be square, orfalse
for allowing non-square matrices.
-
isIdentity
public final boolean isIdentity()Returnstrue
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 byMatrixSIS.toString()
) - returningfalse
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 interfaceorg.opengis.referencing.operation.Matrix
- Specified by:
isIdentity
in classMatrixSIS
- 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 byGeneralMatrix
is valid only for square matrix.NonSquareMatrix
must override. -
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
Returnstrue
if the specified object is of typeGeneralMatrix
and all of the data members are equal to the corresponding data members in this matrix.- Specified by:
equals
in interfaceLenientComparable
- Overrides:
equals
in classMatrixSIS
- 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. -
clone
Returns a clone of this matrix.
-