org.geotools.referencing.operation.matrix
Class GeneralMatrix

Object
  extended by GMatrix
      extended by GeneralMatrix
All Implemented Interfaces:
Serializable, Cloneable, XMatrix, Matrix

public class GeneralMatrix
extends GMatrix
implements XMatrix

A two dimensional array of numbers. Row and column numbering begins with zero.

Since:
2.2
Author:
Martin Desruisseaux (IRD), Simone Giannecchini
See Also:
GMatrix, AffineTransform, PerspectiveTransform, Transform3D, Jama matrix, JSR-83 Multiarray package, Serialized Form
Module:
modules/library/referencing (gt-referencing.jar)

Constructor Summary
GeneralMatrix(AffineTransform transform)
          Constructs a 3×3 matrix from the specified affine transform.
GeneralMatrix(AxisDirection[] srcAxis, AxisDirection[] dstAxis)
          Constructs a transform changing axis order and/or direction.
GeneralMatrix(double[][] matrix)
          Constructs a new matrix from a two-dimensional array of doubles.
GeneralMatrix(Envelope srcRegion, AxisDirection[] srcAxis, Envelope dstRegion, AxisDirection[] dstAxis)
          Constructs a transform mapping a source region to a destination region.
GeneralMatrix(Envelope srcRegion, Envelope dstRegion)
          Constructs a transform that maps a source region to a destination region.
GeneralMatrix(GMatrix matrix)
          Constructs a new matrix and copies the initial values from the parameter matrix.
GeneralMatrix(int size)
          Constructs a square identity matrix of size size × size.
GeneralMatrix(int numRow, int numCol)
          Creates a matrix of size numRow × numCol.
GeneralMatrix(int numRow, int numCol, double[] matrix)
          Constructs a numRow × numCol matrix initialized to the values in the matrix array.
GeneralMatrix(Matrix matrix)
          Constructs a new matrix and copies the initial values from the parameter matrix.
 
Method Summary
 GeneralMatrix clone()
          Returns a clone of this matrix.
 boolean equals(Matrix matrix, double tolerance)
          Compares the element values regardless the object class.
 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.
 boolean isAffine()
          Returns true if this matrix is an affine transform.
 boolean isIdentity()
          Returns true if this matrix is an identity matrix.
 boolean isIdentity(double tolerance)
          Returns true 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 multiply(Matrix matrix)
          Sets the value of this matrix to the result of multiplying itself with the specified matrix.
 AffineTransform toAffineTransform2D()
          Returns an affine transform for this matrix.
 String toString()
          Returns a string representation of this matrix.
 
Methods inherited from class GMatrix
add, add, copySubMatrix, epsilonEquals, epsilonEquals, equals, equals, get, get, get, get, get, getColumn, getColumn, getElement, getNumCol, getNumRow, getRow, getRow, hashCode, identityMinus, invert, invert, LUD, mul, mul, mul, mulTransposeBoth, mulTransposeLeft, mulTransposeRight, negate, negate, set, set, set, set, set, set, setColumn, setColumn, setElement, setIdentity, setRow, setRow, setScale, setSize, setZero, sub, sub, SVD, trace, transpose, transpose
 
Methods inherited from class Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface XMatrix
getElement, getNumCol, getNumRow, invert, negate, setElement, setIdentity, setZero, transpose
 

Constructor Detail

GeneralMatrix

public GeneralMatrix(int size)
Constructs a square identity matrix of size size × size.

Parameters:
size - The number of rows and columns.

GeneralMatrix

public GeneralMatrix(int numRow,
                     int numCol)
Creates a matrix of size numRow × 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 a numRow × numCol matrix initialized to the values in the matrix array. The array values are copied in one row at a time in row major fashion. The array should be exactly numRow*numCol in length. Note that because row and column numbering begins with zero, numRow and numCol will be one larger than the maximum possible matrix index values.

Parameters:
numRow - Number of rows.
numCol - Number of columns.
matrix - Initial values.

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(GMatrix 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(Envelope srcRegion,
                     Envelope 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:

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:


Parameters:
srcAxis - The set of axis direction for source coordinate system.
dstAxis - The set of axis direction for destination coordinate system.
Throws:
IllegalArgumentException - If dstAxis contains some axis not found in srcAxis, or if some colinear axis were found.

GeneralMatrix

public GeneralMatrix(Envelope srcRegion,
                     AxisDirection[] srcAxis,
                     Envelope 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:


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 - If dstAxis contains some axis not found in srcAxis, 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()
Returns true 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.

Specified by:
isAffine in interface XMatrix
Returns:
true if this matrix is affine.

isIdentity

public final boolean isIdentity()
Returns true if this matrix is an identity matrix.

Specified by:
isIdentity in interface XMatrix
Specified by:
isIdentity in interface Matrix

isIdentity

public final boolean isIdentity(double tolerance)
Returns true 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 returning true if and only if all differences are smaller than or equal to tolerance.

Specified by:
isIdentity in interface XMatrix
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, performs this = this × matrix. In the context of coordinate transformations, this is equivalent to AffineTransform.concatenate: first transforms by the supplied transform and then transform the result by the original transform.

Specified by:
multiply in interface XMatrix
Parameters:
matrix - The matrix to multiply to this matrix.

equals

public boolean equals(Matrix matrix,
                      double tolerance)
Compares the element values regardless the object class. This is similar to a call to GMatrix.epsilonEquals(matrix, tolerance). The method name is intentionally different in order to avoid ambiguities at compile-time.

Specified by:
equals in interface XMatrix
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.

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.

Overrides:
toString in class GMatrix

clone

public GeneralMatrix clone()
Returns a clone of this matrix.

Specified by:
clone in interface Matrix
Overrides:
clone in class GMatrix


Copyright © 1996-2009 Geotools. All Rights Reserved.