org.apache.sis.referencing.operation.matrix

Class MatrixSIS

Object

MatrixSIS

All Implemented Interfaces:

Serializable, Cloneable, LenientComparable, Matrix

Direct Known Subclasses:

Matrix1, Matrix2, Matrix3, Matrix4

public abstract class MatrixSIS
extends Object
implements Matrix, LenientComparable, Cloneable, Serializable

A Matrix able to perform some operations of interest to Spatial Information Systems (SIS). This class completes the GeoAPI Matrix interface with some operations used by sis-referencing. It is not a Matrix­SIS goal to provide all possible Matrix operations, as there is too many of them. This class focuses on:

• Only the basic matrix operations needed for referencing by coordinates:
  • is­Identity()
  • multiply(Matrix)
  • inverse()
  • transpose()
• Other operations which are not general-purpose matrix operations, but are needed in the context of referencing by coordinates:
  • is­Affine()
  • normalize­Columns()
  • convert­Before(int, Number, Number)
  • convert­After(int, Number, Number)

Since:

0.4

See Also:

Matrices, Serialized Form

Defined in the sis-referencing module

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	MatrixSIS() For sub-class constructors.

Method Summary

Modifier and Type	Method and Description
static MatrixSIS	castOrCopy(Matrix matrix) Casts or copies the given matrix to a SIS implementation.
MatrixSIS	clone() Returns a clone of this matrix.
void	convertAfter(int tgtDim, Number scale, Number offset) Assuming that this matrix represents an affine transform, pre-concatenates a scale and a translation on the given dimension.
void	convertBefore(int srcDim, Number scale, Number offset) Assuming that this matrix represents an affine transform, concatenates a scale and a translation on the given dimension.
boolean	equals(Matrix matrix, double tolerance) Compares the given matrices for equality, using the given absolute tolerance threshold.
boolean	equals(Object object) Returns true if the specified object is of the same class than this matrix and all of the data members are equal to the corresponding data members in this matrix.
boolean	equals(Object object, ComparisonMode mode) Compares this matrix with the given object for equality.
abstract double	getElement(int row, int column) Retrieves the value at the specified row and column of this matrix.
double[]	getElements() Returns a copy of all matrix elements in a flat, row-major (column indices vary fastest) array.
Number	getNumber(int row, int column) Retrieves the value at the specified row and column of this matrix, wrapped in a Number.
int	hashCode() Returns a hash code value based on the data values in this matrix.
MatrixSIS	inverse() Returns the inverse of this matrix.
boolean	isAffine() Returns true if this matrix represents an affine transform.
abstract boolean	isIdentity() Returns true if this matrix is an identity matrix.
double[]	multiply(double[] vector) Returns a new vector which is the result of multiplying this matrix with the specified vector.
MatrixSIS	multiply(Matrix matrix) Returns a new matrix which is the result of multiplying this matrix with the specified one.
void	normalizeColumns() Normalizes all columns in-place.
MatrixSIS	removeColumns(int lower, int upper) Returns a new matrix with the same elements than this matrix except for the specified columns.
MatrixSIS	removeRows(int lower, int upper) Returns a new matrix with the same elements than this matrix except for the specified rows.
abstract void	setElements(double[] elements) Sets all matrix elements from a flat, row-major (column indices vary fastest) array.
void	setMatrix(Matrix matrix) Sets this matrix to the values of another matrix.
void	setNumber(int row, int column, Number value) Modifies the value at the specified row and column of this matrix.
MatrixSIS	solve(Matrix matrix) Returns the value of U which solves this × U = matrix.
String	toString() Returns a unlocalized string representation of this matrix.
abstract void	transpose() Sets the value of this matrix to its transpose.

Methods inherited from class Object

finalize, get­Class, notify, notify­All, wait, wait, wait

Methods inherited from interface Matrix

get­Num­Col, get­Num­Row, set­Element

Constructor Detail

MatrixSIS

protected MatrixSIS()

For sub-class constructors.

Method Detail

castOrCopy

public static MatrixSIS castOrCopy(Matrix matrix)

Casts or copies the given matrix to a SIS implementation. If matrix is already an instance of Matrix­SIS, then it is returned unchanged. Otherwise all elements are copied in a new Matrix­SIS object.

Parameters:

matrix - the matrix to cast or copy, or null.

Returns:

the matrix argument if it can be safely casted (including null argument), or a copy of the given matrix otherwise.

See Also:

Matrices.copy(Matrix)

getNumber

public Number getNumber(int row,
                        int column)

Retrieves the value at the specified row and column of this matrix, wrapped in a Number. The Number type depends on the matrix accuracy.

Parameters:

row - the row index, from 0 inclusive to Matrix.get­Num­Row() exclusive.

column - the column index, from 0 inclusive to Matrix.get­Num­Col() exclusive.

Returns:

the current value at the given row and column.

setNumber

public void setNumber(int row,
                      int column,
                      Number value)

Modifies the value at the specified row and column of this matrix. This method is the converses of get­Number(int, int).

Parameters:

row - the row index, from 0 inclusive to Matrix.get­Num­Row() exclusive.

column - the column index, from 0 inclusive to Matrix.get­Num­Col() exclusive.

value - the new matrix element value.

Since:

0.8

See Also:

Matrix.set­Element(int, int, double)

getElement

public abstract double getElement(int row,
                                  int column)

Retrieves the value at the specified row and column of this matrix.

Specified by:

get­Element in interface Matrix

Parameters:

row - the row index, from 0 inclusive to Matrix.get­Num­Row() exclusive.

column - the column index, from 0 inclusive to Matrix.get­Num­Col() exclusive.

Returns:

the current value at the given row and column.

getElements

public double[] getElements()

Returns a copy of all matrix elements in a flat, row-major (column indices vary fastest) array. The array length is Matrix.get­Num­Row() * Matrix.get­Num­Col().

Returns:

a copy of all current matrix elements in a row-major array.

setElements

public abstract void setElements(double[] elements)

Sets all matrix elements from a flat, row-major (column indices vary fastest) array. The array length shall be Matrix.get­Num­Row() * Matrix.get­Num­Col().

Parameters:

elements - The new matrix elements in a row-major array.

Throws:

Illegal­Argument­Exception - if the given array does not have the expected length.

Unsupported­Operation­Exception - if this matrix is unmodifiable.

See Also:

Matrices.create(int, int, double[])

setMatrix

public void setMatrix(Matrix matrix)
               throws MismatchedMatrixSizeException

Sets this matrix to the values of another matrix. The given matrix must have the same size.

Parameters:

matrix - the matrix to copy.

Throws:

Mismatched­Matrix­Size­Exception - if the given matrix has a different size than this matrix.

Since:

0.7

isAffine

public 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.

Returns:

true if this matrix represents an affine transform.

See Also:

Matrices.is­Affine(Matrix), Linear­Transform.is­Affine()

isIdentity

public abstract 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:

return Matrices.isIdentity(this, 0.0);

Specified by:

is­Identity in interface Matrix

Returns:

true if this matrix is an identity matrix.

See Also:

Matrices.is­Identity(Matrix, double), Affine­Transform.is­Identity()

transpose

public abstract void transpose()

Sets the value of this matrix to its transpose.

Throws:

Unsupported­Operation­Exception - if this matrix is unmodifiable.

normalizeColumns

public void normalizeColumns()

Normalizes all columns in-place. Each columns in this matrix is considered as a vector. For each column (vector), this method computes the magnitude (vector length) as the square root of the sum of all square values. Then, all values in the column are divided by that magnitude.

This method is useful when the matrix is a transform derivative. In such matrix, each column is a vector representing the displacement in target space when an ordinate in the source space is increased by one. Invoking this method turns those vectors into unitary vectors, which is useful for forming the basis of a new coordinate system.

Throws:

Unsupported­Operation­Exception - if this matrix is unmodifiable.

convertBefore

public void convertBefore(int srcDim,
                          Number scale,
                          Number offset)

Assuming that this matrix represents an affine transform, concatenates a scale and a translation on the given dimension. Converting a point with the resulting matrix is equivalent to first convert the point with ordinates[src­Dim] = ordinates[src­Dim] * scale + offset, then apply the original matrix.

Equivalence between this method and Java2D Affine­Transform methods

If this matrix was an instance of Java2D Affine­Transform, then invoking this method would be equivalent to invoke the following Affine­Transform methods in the order shown below:

MatrixSIS method	AffineTransform methods
concatenate(0, scale, offset)	at.translate(offset, 0); at.scale(scale, 1);
concatenate(1, scale, offset)	at.translate(0, offset); at.scale(1, scale);

Parameters:

src­Dim - the dimension of the ordinate to rescale in the source coordinates.

scale - the amount by which to multiply the source ordinate value before to apply the transform, or null if none.

offset - the amount by which to translate the source ordinate value before to apply the transform, or null if none.

Throws:

Unsupported­Operation­Exception - if this matrix is unmodifiable.

Since:

0.6

See Also:

Affine­Transform.concatenate(Affine­Transform)

convertAfter

public void convertAfter(int tgtDim,
                         Number scale,
                         Number offset)

Assuming that this matrix represents an affine transform, pre-concatenates a scale and a translation on the given dimension. Converting a point with the resulting matrix is equivalent to first convert the point with the original matrix, then convert the result with ordinates[tgt­Dim] = ordinates[tgt­Dim] * scale + offset.

Parameters:

tgt­Dim - the dimension of the ordinate to rescale in the target coordinates.

scale - the amount by which to multiply the target ordinate value after this transform, or null if none.

offset - the amount by which to translate the target ordinate value after this transform, or null if none.

Throws:

Unsupported­Operation­Exception - if this matrix is unmodifiable.

Since:

0.6

See Also:

Affine­Transform.pre­Concatenate(Affine­Transform)

multiply

public MatrixSIS multiply(Matrix matrix)
                   throws MismatchedMatrixSizeException

Returns a new matrix which is the result of multiplying this matrix with the specified one. In other words, returns this × matrix.

Relationship with coordinate operations

In the context of coordinate operations, Matrix.multiply(other) is equivalent to Affine­Transform.concatenate(other): first transforms by the supplied transform and then transform the result by the original transform.

Parameters:

matrix - the matrix to multiply to this matrix.

Returns:

the result of this × matrix.

Throws:

Mismatched­Matrix­Size­Exception - if the number of rows in the given matrix is not equals to the number of columns in this matrix.

multiply

public double[] multiply(double[] vector)

Returns a new vector which is the result of multiplying this matrix with the specified vector. In other words, returns this × vector. The length of the given vector must be equal to the number of columns in this matrix, and the length of the returned vector will be equal to the number of rows in this matrix.

Relationship with coordinate operations

In the context of coordinate operations, Matrix.multiply(vector) is related to Affine­Transform.transform(…) except that the last vector number is implicitly 1 in Affine­Transform operations. While this multiply(double[]) method could be used for coordinate transformation, it is not its purpose. This method is designed for occasional uses when accuracy is more important than performance.

Parameters:

vector - the vector to multiply to this matrix.

Returns:

the result of this × vector.

Throws:

Mismatched­Matrix­Size­Exception - if the length of the given vector is not equals to the number of columns in this matrix.

Since:

0.8

solve

public MatrixSIS solve(Matrix matrix)
                throws MismatchedMatrixSizeException,
                       NoninvertibleMatrixException

Returns the value of U which solves this × U = matrix. This is equivalent to first computing the inverse of this, then multiplying the result by the given matrix.

Parameters:

matrix - the matrix to solve.

Returns:

the U matrix that satisfies this × U = matrix.

Throws:

Mismatched­Matrix­Size­Exception - if the number of rows in the given matrix is not equals to the number of columns in this matrix.

Noninvertible­Matrix­Exception - if this matrix is not invertible.

inverse

public MatrixSIS inverse()
                  throws NoninvertibleMatrixException

Returns the inverse of this matrix.

Returns:

the inverse of this matrix.

Throws:

Noninvertible­Matrix­Exception - if this matrix is not invertible.

See Also:

Affine­Transform.create­Inverse()

removeRows

public MatrixSIS removeRows(int lower,
                            int upper)

Returns a new matrix with the same elements than this matrix except for the specified rows. This method is useful for removing a range of target dimensions in an affine transform.

Parameters:

lower - index of the first row to remove (inclusive).

upper - index after the last row to remove (exclusive).

Returns:

a copy of this matrix with the specified rows removed.

Since:

0.7

removeColumns

public MatrixSIS removeColumns(int lower,
                               int upper)

Returns a new matrix with the same elements than this matrix except for the specified columns. This method is useful for removing a range of source dimensions in an affine transform. Coordinates will be converted as if the values in the removed dimensions were zeros.

Parameters:

lower - index of the first column to remove (inclusive).

upper - index after the last column to remove (exclusive).

Returns:

a copy of this matrix with the specified columns removed.

Since:

0.7

hashCode

public int hashCode()

Returns a hash code value based on the data values in this matrix.

Overrides:

hash­Code in class Object

Returns:

a hash code value for this matrix.

equals

public boolean equals(Object object)

Returns true if the specified object is of the same class than this matrix and all of the data members are equal to the corresponding data members in this matrix.

Specified by:

equals in interface Lenient­Comparable

Overrides:

equals in class Object

Parameters:

object - the object to compare with this matrix for equality.

Returns:

true if the given object is equal to this matrix.

See Also:

Comparison­Mode.STRICT

equals

public boolean equals(Matrix matrix,
                      double tolerance)

Compares the given matrices for equality, using the given absolute tolerance threshold. The given matrix does not need to be the same implementation class than this matrix.

The matrix elements are compared as below:

• Double.Na­N values are considered equals to all other NaN values.
• Infinite values are considered equal to other infinite values of the same sign.
• All other values are considered equal if the absolute value of their difference is smaller than or equals to the given threshold.

Parameters:

matrix - the matrix to compare.

tolerance - the tolerance value.

Returns:

true if this matrix is close enough to the given matrix given the tolerance value.

See Also:

Matrices.equals(Matrix, Matrix, double, boolean)

equals

public boolean equals(Object object,
                      ComparisonMode mode)

Compares this matrix with the given object for equality. To be considered equal, the two objects must meet the following conditions, which depend on the mode argument:

• STRICT: the two matrices must be of the same class, have the same size and the same element values.
• BY_CONTRACT: the two matrices must have the same size and the same element values, but are not required to be the same implementation class (any Matrix is okay).
• IGNORE_METADATA: same as BY_CONTRACT.
• APPROXIMATIVE: the two matrices must have the same size, but the element values can differ up to some threshold. The threshold value is determined empirically and may change in any future SIS versions.

Specified by:

equals in interface Lenient­Comparable

Parameters:

object - the object to compare to this.

mode - the strictness level of the comparison.

Returns:

true if both objects are equal.

See Also:

Matrices.equals(Matrix, Matrix, Comparison­Mode)

clone

public MatrixSIS clone()

Returns a clone of this matrix.

Specified by:

clone in interface Matrix

Overrides:

clone in class Object

Returns:

a new matrix of the same class and with the same values than this matrix.

See Also:

Matrices.copy(Matrix)

toString

public String toString()

Returns a unlocalized string representation of this matrix. For each column, the numbers are aligned on the decimal separator.

Overrides:

to­String in class Object

See Also:

Matrices.to­String(Matrix)