org.geotoolkit.referencing.operation.matrix
Class Matrices

Object
  Static
      Matrices

public class Matrices
extends Static

Static utility methods for creating and manipulating matrices. The factory methods select one of the Matrix1, Matrix2, Matrix3, Matrix4 or GeneralMatrix implementations according the desired matrix size. Note that if the matrix size is know at compile time, it may be more efficient to invoke directly the constructor of the appropriate class instead.

Since:

3.20 (derived from 2.2)

Version:

3.21

Author:

Martin Desruisseaux (IRD, Geomatys)

Module:

referencing/geotk-referencing (download)

View source code for this class

Method Summary

static XMatrix	copy(Matrix matrix) Creates a new matrix which is a copy of the specified matrix.
static XMatrix	create(int size) Creates a square identity matrix of size size × size.
static XMatrix	create(int numRow, int numCol) Creates a matrix of size numRow × numCol.
static XMatrix	create(int numRow, int numCol, double[] elements) Creates a matrix of size numRow × numCol initialized to the given elements.
static XMatrix	createDimensionFilter(int sourceDim, int[] toKeep) Creates a matrix for an affine transform that keep only a subset of source ordinate values.
static boolean	equals(Matrix m1, Matrix m2, ComparisonMode mode) Compares the given matrices for equality, using the given comparison strictness level.
static boolean	equals(Matrix m1, Matrix m2, double epsilon, boolean relative) Compares the given matrices for equality, using the given relative or absolute tolerance threshold.
static void	filterRoundingErrors(XMatrix matrix, int scale, double tolerance) Rounds the coefficients that are relatively close to integers, given a threshold value.
static Matrix	getMatrix(MathTransform transform) If the given transform is linear, returns its coefficients as a matrix.
static Matrix	invert(Matrix matrix) Inverts the specified matrix, maybe (but not always) in place.
static boolean	isAffine(Matrix matrix) Returns true if the given matrix is affine.
static Matrix	multiply(Matrix matrix1, Matrix matrix2) Computes matrix1 × matrix2, reusing one of the given matrices.
static Matrix	resizeAffine(Matrix matrix, int sourceDimension, int targetDimension) Returns the given matrix resized to the given dimensions.
static void	reverseAxisDirection(Matrix matrix, int dimension, double span) Modifies the given matrix in order to reverse the direction of the axis at the given dimension.
static AffineTransform	toAffineTransform(Matrix matrix) Returns the given matrix as a Java2D affine transform.
static GeneralMatrix	toGeneralMatrix(Matrix matrix) Converts the specified matrix to GeneralMatrix.
static XMatrix	toOptimalMatrix(Matrix matrix) Converts the specified matrix to the most suitable Geotk implementation.
static XMatrix	toXMatrix(Matrix matrix) Converts the specified matrix to a Geotk implementation.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

create

public static XMatrix create(int size)

Creates a square identity matrix of size size × size.

Parameters:

size - For an affine transform, this is the number of source and target dimensions + 1.

Returns:

An identity matrix of the given size.

create

public static XMatrix create(int numRow,
                             int numCol)

Creates a matrix of size numRow × numCol. Elements on the diagonal (j == i) are set to 1.

Parameters:

numRow - For an affine transform, this is the number of target dimensions + 1.

numCol - For an affine transform, this is the number of source dimensions + 1.

Returns:

An identity matrix of the given size.

create

public static XMatrix create(int numRow,
                             int numCol,
                             double[] elements)

Creates a matrix of size numRow × numCol initialized to the given elements. The elements array size must be equals to numRow*numCol. Column indices vary fastest, as expected by the GeneralMatrix.GeneralMatrix(int,int,double[]) constructor.

Parameters:

numRow - Number of rows.

numCol - Number of columns.

elements - Elements of the matrix. Column indices vary fastest.

Returns:

A matrix initialized to the given elements.

createDimensionFilter

public static XMatrix createDimensionFilter(int sourceDim,
                                            int[] toKeep)
                                     throws IndexOutOfBoundsException

Creates a matrix for an affine transform that keep only a subset of source ordinate values. The matrix size will be (toKeep.length+1) × (sourceDim+1).

Parameters:

sourceDim - the dimension of source coordinates.

toKeep - the indices of source ordinate values to keep.

Returns:

The matrix for an affine transform keeping only the given dimensions, and discarding all others.

Throws:

IndexOutOfBoundsException - if a value of toKeep is lower than 0 or not smaller than sourceDim.

See Also:

MathTransforms.dimensionFilter(int, int[])

copy

public static XMatrix copy(Matrix matrix)

Creates a new matrix which is a copy of the specified matrix.

Parameters:

matrix - The matrix to copy.

Returns:

A copy of the given matrix.

Since:

3.20 (derived from 2.2)

getMatrix

public static Matrix getMatrix(MathTransform transform)

If the given transform is linear, returns its coefficients as a matrix. More specifically:

• If the given transform is an instance of LinearTransform, returns LinearTransform.getMatrix().
• Otherwise if the given transform is an instance of AffineTransform, returns its coefficients in a Matrix3 instance.
• Otherwise returns null.

Parameters:

transform - The transform, or null.

Returns:

The matrix of the given transform, or null if none.

Since:

3.16 (derived from 3.15)

toXMatrix

public static XMatrix toXMatrix(Matrix matrix)

Converts the specified matrix to a Geotk implementation. If matrix is already an instance of XMatrix, then it is returned unchanged. Otherwise all elements are copied in a new XMatrix object.

Parameters:

matrix - The matrix to convert, or null.

Returns:

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

Since:

3.16 (derived from 3.00)

toOptimalMatrix

public static XMatrix toOptimalMatrix(Matrix matrix)

Converts the specified matrix to the most suitable Geotk implementation. This method process as below:

• If the given matrix is already an instance of the Matrix1, Matrix2, Matrix3 or Matrix4 specialized classes, then it is returned unchanged.
• Otherwise if the given matrix is square and the number of rows & columns is 1, 2, 3 or 4, then the elements are copied in an instance of Matrix1, Matrix2, Matrix3 or Matrix4 respectively, and the new instance is returned.
• Otherwise this method delegates to toXMatrix(Matrix).

Using those specialized implementations brings a little bit of performance and, more important, precision in the floating point results of matrix operations.

Parameters:

matrix - The matrix to convert, or null.

Returns:

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

Since:

3.16 (derived from 3.00)

toGeneralMatrix

public static GeneralMatrix toGeneralMatrix(Matrix matrix)

Converts the specified matrix to GeneralMatrix. If matrix is already an instance of GeneralMatrix, then it is returned unchanged. Otherwise all elements are copied in a new GeneralMatrix object.

Consider using toXMatrix(Matrix) instead than this method if a XMatrix instance is sufficient. Use this method only if a GeneralMatrix is really necessary.

Parameters:

matrix - The matrix to convert, or null.

Returns:

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

Since:

3.16 (derived from 3.00)

toAffineTransform

public static AffineTransform toAffineTransform(Matrix matrix)
                                         throws IllegalArgumentException

Returns the given matrix as a Java2D affine transform.

Parameters:

matrix - The matrix to returns as an affine transform.

Returns:

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

Throws:

IllegalArgumentException - if the given matrix size is not 3×3 or the matrix is not affine.

Since:

3.20 (derived from 3.00)

See Also:

Matrix3.toAffineTransform(), GeneralMatrix.toAffineTransform2D()

isAffine

public static boolean isAffine(Matrix matrix)

Returns true if the given matrix is affine.

Parameters:

matrix - The matrix to test.

Returns:

true if the matrix is affine.

Since:

3.20 (derived from 3.17)

See Also:

XMatrix.isAffine()

resizeAffine

public static Matrix resizeAffine(Matrix matrix,
                                  int sourceDimension,
                                  int targetDimension)

Returns the given matrix resized to the given dimensions. This method can be invoked for adding or removing dimensions to an affine transform. The added or removed dimensions are always the last ones. More specifically:

• If source and target dimensions are added, the corresponding offset and scale factors will be 0 and 1 respectively. In other words, new dimensions are propagated unchanged.
• New source dimensions have no impact on existing dimensions (the corresponding scale factors are set to zero).

The caller should ensure that isAffine(Matrix) returns true before to invoke this method, since this is not verified by this method.

Parameters:

matrix - The matrix to resize.

sourceDimension - The desired number of source dimensions.

targetDimension - The desired number of target dimensions.

Returns:

The matrix for the given number of dimensions. This will be the matrix argument itself if no resizing was needed.

Since:

3.20 (derived from 3.16)

reverseAxisDirection

public static void reverseAxisDirection(Matrix matrix,
                                        int dimension,
                                        double span)

Modifies the given matrix in order to reverse the direction of the axis at the given dimension. The matrix is assumed affine, but this is not verified.

Parameters:

matrix - The matrix to modify.

dimension - The dimension of the axis to reverse.

span - The envelope span at the dimension of the axis to be reversed, in units of the source coordinate system.

Since:

3.16

multiply

public static Matrix multiply(Matrix matrix1,
                              Matrix matrix2)

Computes matrix1 × matrix2, reusing one of the given matrices. The two given matrices shall be considered invalid after this method call.

Parameters:

matrix1 - The first matrix to multiply. May be overwritten by the result.

matrix2 - The second matrix to multiply. May be overwritten by the result.

Returns:

The product of the two matrix. May be one of the above objects.

invert

public static Matrix invert(Matrix matrix)
                     throws NoninvertibleTransformException

Inverts the specified matrix, maybe (but not always) in place. If the matrix can't be inverted (for example because of a SingularMatrixException), then the exception is wrapped into a NoninvertibleTransformException.

This method performs a special check for non-square matrix in an attempt to invert them anyway. This is possible only if some columns or rows contain contains only 0 elements.

Parameters:

matrix - The matrix to invert.

Returns:

The inverse of the given matrix. May be matrix itself.

Throws:

NoninvertibleTransformException - if the given matrix is not invertible.

filterRoundingErrors

public static void filterRoundingErrors(XMatrix matrix,
                                        int scale,
                                        double tolerance)

Rounds the coefficients that are relatively close to integers, given a threshold value. "Relatively" means that the given threshold is relative to the magnitude of each vector, assuming that the given matrix define an affine transform. More specifically:

• The last column in the given matrix is assumed to contain translation terms, and will be ignored in the vector magnitude calculation described below.
• For each row:
  • Compute the magnitude of the vector formed by the coefficients in all columns except the last one.
  • Multiply the given tolerance value by the given vector magnitude.
  • For each element in the current row:
    • Compute an adjusted value as adjusted = Math.round(element*scale)/scale.
    • If the difference between the element and the above adjusted value is not greater than the tolerance threshold adjusted for vector magnitude, replace that element by the adjusted value.

In other words, the tolerance argument given to this method is the value that we would use if we knew that the matrix was close to an identity matrix, without worrying about the scale argument. This method will take care of adjusting the tolerance threshold for the actual matrix values. However this algorithm is designed for matrix representing affine transforms (not general matrix).

Parameters:

matrix - The matrix in which to filter rounding errors in-place.

scale - A scale factor by which to multiply each element before to round the scaled value. For example a value of 10 will allow this method to round 0.2000…1 as 0.2.

tolerance - The relative tolerance threshold.

Since:

3.21

equals

public static boolean equals(Matrix m1,
                             Matrix m2,
                             double epsilon,
                             boolean relative)

Compares the given matrices for equality, using the given relative or absolute tolerance threshold. The matrix elements are compared as below:

• Double.NaN 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 threshold described below.

If relative is true, then for any pair of values v1_j,i and v2_j,i to compare, the tolerance threshold is scaled by max(abs(v1), abs(v2)). Otherwise the threshold is used as-is.

Parameters:

m1 - The first matrix to compare, or null.

m2 - The second matrix to compare, or null.

epsilon - The tolerance value.

relative - If true, then the tolerance value is relative to the magnitude of the matrix elements being compared.

Returns:

true if the values of the two matrix do not differ by a quantity greater than the given tolerance threshold.

Since:

3.20 (derived from 2.2)

See Also:

XMatrix.equals(Matrix, double)

equals

public static boolean equals(Matrix m1,
                             Matrix m2,
                             ComparisonMode mode)

Compares the given matrices for equality, using the given comparison strictness level. To be considered equal, the two matrices 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/IGNORE_METADATA: 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).
• APPROXIMATIVE: the two matrixes 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 future Geotk versions.

Parameters:

m1 - The first matrix to compare, or null.

m2 - The second matrix to compare, or null.

mode - The strictness level of the comparison.

Returns:

true if both matrices are equal.

Since:

3.20 (derived from 3.18)

See Also:

XMatrix.equals(Object, ComparisonMode)