Class GeneralMatrix
- Object
-
- GeneralMatrix
-
- All Implemented Interfaces:
Serializable
,Cloneable
,Matrix
,Cloneable
,XMatrix
- Direct Known Subclasses:
Matrix4
public class GeneralMatrix extends Object implements XMatrix, Serializable
A two dimensional array of numbers. Row and column numbering begins with zero.- Since:
- 2.2
- Author:
- Martin Desruisseaux (IRD), Simone Giannecchini
- See Also:
AffineTransform
, Serialized Form
-
-
Constructor Summary
Constructors Constructor Description GeneralMatrix(double[][] matrix)
Constructs a new matrix from a two-dimensional array of doubles.GeneralMatrix(int size)
Constructs a square identity matrix of sizesize
×size
.GeneralMatrix(int numRow, int numCol)
Creates a matrix of sizenumRow
×numCol
.GeneralMatrix(int numRow, int numCol, double... matrix)
Constructs anumRow
×numCol
matrix initialized to the values in thematrix
array.GeneralMatrix(int numRow, int numCol, Matrix matrix)
Constructs anumRow
×numCol
matrix initialized to the values in thematrix
array.GeneralMatrix(AffineTransform transform)
Constructs a 3×3 matrix from the specified affine transform.GeneralMatrix(Bounds srcRegion, Bounds dstRegion)
Constructs a transform that maps a source region to a destination region.GeneralMatrix(Bounds srcRegion, AxisDirection[] srcAxis, Bounds dstRegion, AxisDirection[] dstAxis)
Constructs a transform mapping a source region to a destination region.GeneralMatrix(AxisDirection[] srcAxis, AxisDirection[] dstAxis)
Constructs a transform changing axis order and/or direction.GeneralMatrix(Matrix matrix)
Constructs a new matrix and copies the initial values from the parameter matrix.GeneralMatrix(GeneralMatrix matrix)
Constructs a new matrix and copies the initial values from the parameter matrix.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
add(double scalar)
Performs an in-place scalar addition.void
add(double scalar, XMatrix matrix)
Set to the scalar addition ofscalar+matrix
void
add(XMatrix matrix)
Set to the matrix addition ofthis+matrix
.void
add(XMatrix matrix1, XMatrix matrix2)
Set to the matrix addition ofmatrix1+matrix2
.GeneralMatrix
clone()
Returns a clone of this matrix.void
copySubMatrix(int rowSource, int colSource, int numRows, int numCol, int rowDest, int colDest, GeneralMatrix target)
Extract a subMatrix to the provided targetdouble
determinate()
Computes the determinantboolean
equals(Object obj)
boolean
equals(Matrix matrix, double tolerance)
Compares the element values.void
getColumn(int col, double[] array)
Extract col to provided array.double
getElement(int row, int column)
Returns the value at the row, column position in the matrix.double[][]
getElements()
Retrieves the specifiable values in the transformation matrix into a 2-dimensional array of double precision values.static double[][]
getElements(Matrix matrix)
Retrieves the specifiable values in the transformation matrix into a 2-dimensional array of double precision values.int
getNumCol()
Gets the number of columns in the matrix.int
getNumRow()
Gets the number of rows in the matrix.void
getRow(int row, double[] array)
Extract row to provided arrayint
hashCode()
void
invert()
Inverts this matrix in place.void
invert(Matrix matrix)
Set to the inverse of the provided matrix.boolean
isAffine()
Returnstrue
if this matrix is an affine transform.boolean
isIdentity()
Returnstrue
if this matrix is an identity matrix.boolean
isIdentity(double tolerance)
Returnstrue
if this matrix is an identity matrix using the provided tolerance.static GeneralMatrix
load(BufferedReader in, Locale locale)
Loads data from the specified streal until the first blank line or end of stream.static GeneralMatrix
load(File file)
Loads data from the specified file until the first blank line or end of file.void
mul(double scalar)
Sets this matrix to the result of multiplying itself with the provided scalar.void
mul(double scalar, Matrix matrix)
Sets the value of this matrix to the result of multiplying the provided scalar and matrix.void
mul(Matrix matrix)
In-place multiply with provided matrix.void
mul(Matrix matrix1, Matrix matrix2)
In-place update from matrix1 * matrix2.void
multiply(Matrix matrix)
Sets the value of this matrix to the result of multiplying itself with the specified matrix.void
negate()
Changes the sign of each element in the matrix.void
negate(Matrix matrix)
Negates the value of this matrix:this = -matrix
.void
set(double[] matrix)
Update in place to the provided matrix (row-order).void
setColumn(int column, double... values)
Sets the value of the column using an array of values.void
setElement(int row, int column, double value)
Sets the value of the row, column position in the matrix.void
setIdentity()
Sets the main diagonal of this matrix to be 1.0.void
setRow(int row, double... values)
Sets the value of the row using an array of values.void
setSize(int numRows, int numCols)
Resize the matrix to the specified number of rows and columns (preserving remaining elements).void
setZero()
Sets each value of the matrix to 0.0.void
sub(double scalar)
In-place matrix subtraction:this - scalar
.void
sub(double scalar, Matrix matrix)
Set to the difference ofscalar - matrix2
.void
sub(Matrix matrix)
In-place matrix subtraction:this - matrix
.void
sub(Matrix matrix1, Matrix matrix2)
Set to the difference ofmatrix1 - matrix2
.AffineTransform
toAffineTransform2D()
Returns an affine transform for this matrix.String
toString()
Returns a string representation of this matrix.void
transpose()
Transposes the matrix.void
transpose(Matrix matrix)
Set to the transpose of the provided matrix.
-
-
-
Constructor Detail
-
GeneralMatrix
public GeneralMatrix(int size)
Constructs a square identity matrix of sizesize
×size
.- Parameters:
size
- The number of rows and columns.
-
GeneralMatrix
public GeneralMatrix(int numRow, int numCol)
Creates a matrix of sizenumRow
×numCol
. Elements on the diagonal j==i are set to 1.- Parameters:
numRow
- Number of rows.numCol
- Number of columns.
-
GeneralMatrix
public GeneralMatrix(int numRow, int numCol, double... matrix)
Constructs anumRow
×numCol
matrix initialized to the values in thematrix
array. The array values are copied in one row at a time in row major fashion. The array should be exactlynumRow*numCol
in length. Note that because row and column numbering begins with zero,numRow
andnumCol
will be one larger than the maximum possible matrix index values.- Parameters:
numRow
- Number of rows.numCol
- Number of columns.matrix
- Initial values in row order
-
GeneralMatrix
public GeneralMatrix(int numRow, int numCol, Matrix matrix)
Constructs anumRow
×numCol
matrix initialized to the values in thematrix
array. The array values are copied in one row at a time in row major fashion. The array should be exactlynumRow*numCol
in length. Note that because row and column numbering begins with zero,numRow
andnumCol
will be one larger than the maximum possible matrix index values.- Parameters:
numRow
- Number of rows.numCol
- Number of columns.matrix
- Initial values in row order
-
GeneralMatrix
public GeneralMatrix(double[][] matrix) throws IllegalArgumentException
Constructs a new matrix from a two-dimensional array of doubles.- Parameters:
matrix
- Array of rows. Each row must have the same length.- Throws:
IllegalArgumentException
- if the specified matrix is not regular (i.e. if all rows doesn't have the same length).
-
GeneralMatrix
public GeneralMatrix(Matrix matrix)
Constructs a new matrix and copies the initial values from the parameter matrix.- Parameters:
matrix
- The matrix to copy.
-
GeneralMatrix
public GeneralMatrix(GeneralMatrix matrix)
Constructs a new matrix and copies the initial values from the parameter matrix.- Parameters:
matrix
- The matrix to copy.
-
GeneralMatrix
public GeneralMatrix(AffineTransform transform)
Constructs a 3×3 matrix from the specified affine transform.- Parameters:
transform
- The matrix to copy.
-
GeneralMatrix
public GeneralMatrix(Bounds srcRegion, Bounds dstRegion)
Constructs a transform that maps a source region to a destination region. Axis order and direction are left unchanged.If the source dimension is equals to the destination dimension, then the transform is affine. However, the following special cases are also handled:
- If the target dimension is smaller than the source dimension, then extra dimensions are dropped.
- If the target dimension is greater than the source dimension, then the coordinates in the new dimensions are set to 0.
- Parameters:
srcRegion
- The source region.dstRegion
- The destination region.
-
GeneralMatrix
public GeneralMatrix(AxisDirection[] srcAxis, AxisDirection[] dstAxis)
Constructs a transform changing axis order and/or direction. For example, the transform may converts (NORTH,WEST) coordinates into (EAST,NORTH). Axis direction can be inversed only. For example, it is illegal to transform (NORTH,WEST) coordinates into (NORTH,DOWN).If the source dimension is equals to the destination dimension, then the transform is affine. However, the following special cases are also handled:
- If the target dimension is smaller than the source dimension, extra axis are dropped. An exception is thrown if the target contains some axis not found in the source.
- Parameters:
srcAxis
- The set of axis direction for source coordinate system.dstAxis
- The set of axis direction for destination coordinate system.- Throws:
IllegalArgumentException
- IfdstAxis
contains some axis not found insrcAxis
, or if some colinear axis were found.
-
GeneralMatrix
public GeneralMatrix(Bounds srcRegion, AxisDirection[] srcAxis, Bounds dstRegion, AxisDirection[] dstAxis)
Constructs a transform mapping a source region to a destination region. Axis order and/or direction can be changed during the process. For example, the transform may convert (NORTH,WEST) coordinates into (EAST,NORTH). Axis direction can be inversed only. For example, it is illegal to transform (NORTH,WEST) coordinates into (NORTH,DOWN).If the source dimension is equals to the destination dimension, then the transform is affine. However, the following special cases are also handled:
- If the target dimension is smaller than the source dimension, extra axis are dropped. An exception is thrown if the target contains some axis not found in the source.
- Parameters:
srcRegion
- The source region.srcAxis
- Axis direction for each dimension of the source region.dstRegion
- The destination region.dstAxis
- Axis direction for each dimension of the destination region.- Throws:
MismatchedDimensionException
- if the envelope dimension doesn't matches the axis direction array length.IllegalArgumentException
- IfdstAxis
contains some axis not found insrcAxis
, or if some colinear axis were found.
-
-
Method Detail
-
getElements
public static double[][] getElements(Matrix matrix)
Retrieves the specifiable values in the transformation matrix into a 2-dimensional array of double precision values. The values are stored into the 2-dimensional array using the row index as the first subscript and the column index as the second. Values are copied; changes to the returned array will not change this matrix.- Parameters:
matrix
- The matrix to extract elements from.- Returns:
- The matrix elements.
-
getElements
public final double[][] getElements()
Retrieves the specifiable values in the transformation matrix into a 2-dimensional array of double precision values. The values are stored into the 2-dimensional array using the row index as the first subscript and the column index as the second. Values are copied; changes to the returned array will not change this matrix.- Returns:
- The matrix elements.
-
isAffine
public final boolean isAffine()
Returnstrue
if this matrix is an affine transform. A transform is affine if the matrix is square and last row contains only zeros, except in the last column which contains 1.
-
negate
public void negate()
Changes the sign of each element in the matrix.
-
negate
public void negate(Matrix matrix)
Description copied from interface:XMatrix
Negates the value of this matrix:this = -matrix
.
-
transpose
public void transpose()
Transposes the matrix.
-
transpose
public void transpose(Matrix matrix)
Description copied from interface:XMatrix
Set to the transpose of the provided matrix.
-
invert
public void invert()
Description copied from interface:XMatrix
Inverts this matrix in place.
-
invert
public void invert(Matrix matrix) throws SingularMatrixException
Description copied from interface:XMatrix
Set to the inverse of the provided matrix.- Specified by:
invert
in interfaceXMatrix
- Parameters:
matrix
- The matrix that is to be inverted. Not modified.- Throws:
SingularMatrixException
- if this matrix is not invertible.
-
getNumRow
public int getNumRow()
Gets the number of rows in the matrix.
-
getNumCol
public int getNumCol()
Gets the number of columns in the matrix.
-
getElement
public double getElement(int row, int column)
Returns the value at the row, column position in the matrix.- Specified by:
getElement
in interfaceMatrix
- Specified by:
getElement
in interfaceXMatrix
- Parameters:
row
- The row number to be retrieved (zero indexed).column
- The column number to be retrieved (zero indexed).- Returns:
- Matrix value at the given row and column.
-
setColumn
public void setColumn(int column, double... values)
Description copied from interface:XMatrix
Sets the value of the column using an array of values.
-
setRow
public void setRow(int row, double... values)
Description copied from interface:XMatrix
Sets the value of the row using an array of values.
-
setElement
public void setElement(int row, int column, double value)
Sets the value of the row, column position in the matrix.- Specified by:
setElement
in interfaceMatrix
- Parameters:
row
- The row number to be retrieved (zero indexed).column
- The column number to be retrieved (zero indexed).value
- The new matrix element value.
-
setZero
public void setZero()
Sets each value of the matrix to 0.0.
-
setIdentity
public void setIdentity()
Sets the main diagonal of this matrix to be 1.0.- Specified by:
setIdentity
in interfaceXMatrix
-
isIdentity
public final boolean isIdentity()
Returnstrue
if this matrix is an identity matrix.- Specified by:
isIdentity
in interfaceMatrix
- Returns:
true
if this matrix is an identity matrix.
-
isIdentity
public final boolean isIdentity(double tolerance)
Returnstrue
if this matrix is an identity matrix using the provided tolerance. This method is equivalent to computing the difference between this matrix and an identity matrix of identical size, and returningtrue
if and only if all differences are smaller than or equal totolerance
.- Specified by:
isIdentity
in interfaceXMatrix
- Parameters:
tolerance
- The tolerance value.- Returns:
true
if this matrix is close enough to the identity matrix given the tolerance value.- Since:
- 2.3.1
-
multiply
public final void multiply(Matrix matrix)
Sets the value of this matrix to the result of multiplying itself with the specified matrix. In other words, performsthis
=this
×matrix
. In the context of coordinate transformations, this is equivalent toAffineTransform.concatenate
: first transforms by the supplied transform and then transform the result by the original transform.
-
equals
public boolean equals(Matrix matrix, double tolerance)
Description copied from interface:XMatrix
Compares the element values.
-
toAffineTransform2D
public final AffineTransform toAffineTransform2D() throws IllegalStateException
Returns an affine transform for this matrix. This is a convenience method for interoperability with Java2D.- Returns:
- The affine transform for this matrix.
- Throws:
IllegalStateException
- if this matrix is not 3×3, or if the last row is not[0 0 1]
.
-
load
public static GeneralMatrix load(File file) throws IOException
Loads data from the specified file until the first blank line or end of file.- Parameters:
file
- The file to read.- Returns:
- The matrix parsed from the file.
- Throws:
IOException
- if an error occured while reading the file.- Since:
- 2.2
-
load
public static GeneralMatrix load(BufferedReader in, Locale locale) throws IOException
Loads data from the specified streal until the first blank line or end of stream.- Parameters:
in
- The stream to read.locale
- The locale for the numbers to be parsed.- Returns:
- The matrix parsed from the stream.
- Throws:
IOException
- if an error occured while reading the stream.- Since:
- 2.2
-
toString
public String toString()
Returns a string representation of this matrix. The returned string is implementation dependent. It is usually provided for debugging purposes only.
-
clone
public GeneralMatrix clone()
Returns a clone of this matrix.
-
copySubMatrix
public void copySubMatrix(int rowSource, int colSource, int numRows, int numCol, int rowDest, int colDest, GeneralMatrix target)
Extract a subMatrix to the provided target
-
getColumn
public void getColumn(int col, double[] array)
Extract col to provided array.
-
mul
public void mul(double scalar)
Description copied from interface:XMatrix
Sets this matrix to the result of multiplying itself with the provided scalar.
-
mul
public void mul(double scalar, Matrix matrix)
Description copied from interface:XMatrix
Sets the value of this matrix to the result of multiplying the provided scalar and matrix.
-
getRow
public void getRow(int row, double[] array)
Extract row to provided array
-
mul
public final void mul(Matrix matrix)
In-place multiply with provided matrix.
-
sub
public void sub(double scalar)
Description copied from interface:XMatrix
In-place matrix subtraction:this - scalar
.
-
sub
public void sub(double scalar, Matrix matrix)
Description copied from interface:XMatrix
Set to the difference ofscalar - matrix2
.
-
sub
public void sub(Matrix matrix)
Description copied from interface:XMatrix
In-place matrix subtraction:this - matrix
.
-
sub
public void sub(Matrix matrix1, Matrix matrix2)
Description copied from interface:XMatrix
Set to the difference ofmatrix1 - matrix2
.
-
set
public void set(double[] matrix)
Update in place to the provided matrix (row-order).
-
setSize
public void setSize(int numRows, int numCols)
Resize the matrix to the specified number of rows and columns (preserving remaining elements).- Parameters:
numRows
- The new number of rows in the matrix.numCols
- The new number of columns in the matrix.
-
add
public void add(double scalar)
Description copied from interface:XMatrix
Performs an in-place scalar addition.
-
add
public void add(double scalar, XMatrix matrix)
Description copied from interface:XMatrix
Set to the scalar addition ofscalar+matrix
-
add
public void add(XMatrix matrix)
Description copied from interface:XMatrix
Set to the matrix addition ofthis+matrix
.
-
add
public void add(XMatrix matrix1, XMatrix matrix2)
Description copied from interface:XMatrix
Set to the matrix addition ofmatrix1+matrix2
.
-
determinate
public double determinate()
Description copied from interface:XMatrix
Computes the determinant- Specified by:
determinate
in interfaceXMatrix
-
-