Package toxi.geom

Class GMatrix

java.lang.Object
toxi.geom.GMatrix
All Implemented Interfaces:
Serializable, Cloneable
public class GMatrix extends Object implements Serializable, Cloneable
A double precision, row major, general and dynamically-resizable, two-dimensional matrix class. Row and column numbering begins with zero.
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    GMatrix(int nRow, int nCol)
    Constructs an nRow by NCol identity matrix.
    GMatrix(int nRow, int nCol, double[] matrix)
    Constructs an nRow by nCol matrix initialized to the values in the matrix array.
    GMatrix(GMatrix matrix)
    Constructs a new GMatrix and copies the initial values from the parameter matrix.

  • Method Summary

    Modifier and Type
    Method
    Description
    final void
    add(GMatrix m1)
    Sets the value of this matrix to sum of itself and matrix m1.
    final void
    add(GMatrix m1, GMatrix m2)
    Sets the value of this matrix to the matrix sum of matrices m1 and m2.
    static void
    backSubstituteLU(int dim, double[] matrix1, int[] row_perm, double[] matrix2)
    Solves a set of linear equations.
    Object
    clone()
    Creates a new object of the same class as this object.
    final int
    computeLUD(GMatrix LU, GVector permutation)
    LU Decomposition: this matrix must be a square matrix and the LU GMatrix parameter must be the same size as this matrix.
    static void
    computeQR(int start, int end, double[] s, double[] e, GMatrix u, GMatrix v)
     
    final int
    computeSVD(GMatrix U, GMatrix W, GMatrix V)
    Finds the singular value decomposition (SVD) of this matrix such that this = U*W*transpose(V); and returns the rank of this matrix; the values of U,W,V are all overwritten.
    static int
    computeSVD(GMatrix mat, GMatrix U, GMatrix W, GMatrix V)
     
    final void
    copySubMatrix(int rowSource, int colSource, int numRow, int numCol, int rowDest, int colDest, GMatrix target)
    Copies a sub-matrix derived from this matrix into the target matrix.
    static boolean
    decomposeLU(int dim, double[] matrix0, int[] row_perm, int[] even_row_xchg)
    Given a nxn array "matrix0", this function replaces it with the LU decomposition of a row-wise permutation of itself.
    boolean
    epsilonEquals(GMatrix m1, double epsilon)
    Returns true if the L-infinite distance between this matrix and matrix m1 is less than or equal to the epsilon parameter, otherwise returns false.
    boolean
    epsilonEquals(GMatrix m1, float epsilon)
    Deprecated.
    Use epsilonEquals(GMatrix, double) instead
    boolean
    equals(Object o1)
    Returns true if the Object o1 is of type GMatrix and all of the data members of o1 are equal to the corresponding data members in this GMatrix.
    boolean
    equals(GMatrix m1)
    Returns true if all of the data members of GMatrix m1 are equal to the corresponding data members in this GMatrix.
    final void
    get(GMatrix m1)
    Places the values in the this GMatrix into the matrix m1; m1 should be at least as large as this GMatrix.
    final void
    get(Matrix3d m1)
    Places the values in the upper 3x3 of this GMatrix into the matrix m1.
    final void
    get(Matrix4f m1)
    Places the values in the upper 4x4 of this GMatrix into the matrix m1.
    final void
    getColumn(int col, double[] array)
    Places the values of the specified column into the array parameter.
    final void
    getColumn(int col, GVector vector)
    Places the values of the specified column into the vector parameter.
    final double
    getElement(int row, int column)
    Retrieves the value at the specified row and column of this matrix.
    final int
    getNumCol()
    Returns the number of colmuns in this matrix.
    final int
    getNumRow()
    Returns the number of rows in this matrix.
    final void
    getRow(int row, double[] array)
    Places the values of the specified row into the array parameter.
    final void
    getRow(int row, GVector vector)
    Places the values of the specified row into the vector parameter.
    int
    hashCode()
    Returns a hash code value based on the data values in this object.
    final void
    identity()
    Sets this GMatrix to the identity matrix.
    final void
    identityMinus()
    Subtracts this matrix from the identity matrix and puts the values back into this (this = I - this).
    final void
    invert()
    Inverts this matrix in place.
    final void
    invert(GMatrix m1)
    Inverts matrix m1 and places the new values into this matrix.
    final void
    mul(GMatrix m1)
    Sets the value of this matrix to the result of multiplying itself with matrix m1 (this = this * m1).
    final void
    mul(GMatrix m1, GMatrix m2)
    Sets the value of this matrix to the result of multiplying the two argument matrices together (this = m1 * m2).
    final void
    mul(GVector v1, GVector v2)
    Computes the outer product of the two vectors; multiplies the the first vector by the transpose of the second vector and places the matrix result into this matrix.
    final void
    mulTransposeBoth(GMatrix m1, GMatrix m2)
    Multiplies the transpose of matrix m1 times the transpose of matrix m2, and places the result into this.
    final void
    mulTransposeLeft(GMatrix m1, GMatrix m2)
    Multiplies the transpose of matrix m1 times matrix m2, and places the result into this.
    final void
    mulTransposeRight(GMatrix m1, GMatrix m2)
    Multiplies matrix m1 times the transpose of matrix m2, and places the result into this.
    final void
    negate()
    Negates the value of this matrix: this = -this.
    final void
    negate(GMatrix m1)
    Sets the value of this matrix equal to the negation of of the GMatrix parameter.
    final void
    set(double[] matrix)
    Sets the value of this matrix to the values found in the array parameter.
    final void
    set(GMatrix m1)
    Sets the value of this matrix to the values found in matrix m1.
    final void
    set(Matrix3d m1)
    Sets the value of this matrix to that of the Matrix3d provided.
    final void
    set(Matrix4f m1)
    Sets the value of this matrix to that of the Matrix4f provided.
    final void
    setColumn(int col, double[] array)
    Copy the values from the array into the specified column of this matrix.
    final void
    setColumn(int col, GVector vector)
    Copy the values from the vector into the specified column of this matrix.
    final void
    setElement(int row, int column, double value)
    Modifies the value at the specified row and column of this matrix.
    final void
    setRow(int row, double[] array)
    Copy the values from the array into the specified row of this matrix.
    final void
    setRow(int row, GVector vector)
    Copy the values from the vector into the specified row of this matrix.
    final void
    setScale(double scale)
    Sets this matrix to a uniform scale matrix; all of the values are reset.
    final void
    setSize(int nRow, int nCol)
    Changes the size of this matrix dynamically.
    final void
    setZero()
    Sets all the values in this matrix to zero.
    final void
    sub(GMatrix m1)
    Sets the value of this matrix to the matrix difference of itself and matrix m1 (this = this - m1).
    final void
    sub(GMatrix m1, GMatrix m2)
    Sets the value of this matrix to the matrix difference of matrices m1 and m2 (this = m1 - m2).
    String
    toString()
    Returns a string that contains the values of this GMatrix.
    final double
    trace()
    Returns the trace of this matrix.
    final void
    transpose()
    Transposes this matrix in place.
    final void
    transpose(GMatrix m1)
    Places the matrix values of the transpose of matrix m1 into this matrix.

    Methods inherited from class java.lang.Object

    getClass, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • GMatrix

      public GMatrix(GMatrix matrix)
      Constructs a new GMatrix and copies the initial values from the parameter matrix.
      Parameters:
      matrix - the source of the initial values of the new GMatrix

    • GMatrix

      public GMatrix(int nRow, int nCol)
      Constructs an nRow by NCol identity matrix. Note that because row and column numbering begins with zero, nRow and nCol will be one larger than the maximum possible matrix index values.
      Parameters:
      nRow - number of rows in this matrix.
      nCol - number of columns in this matrix.

    • GMatrix

      public GMatrix(int nRow, int nCol, double[] matrix)
      Constructs an nRow by nCol 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 at least nRow*nCol in length. Note that because row and column numbering begins with zero, nRow and nCol will be one larger than the maximum possible matrix index values.
      Parameters:
      nRow - number of rows in this matrix.
      nCol - number of columns in this matrix.
      matrix - a 1D array that specifies a matrix in row major fashion

  • Method Details

    • backSubstituteLU

      public static void backSubstituteLU(int dim, double[] matrix1, int[] row_perm, double[] matrix2)
      Solves a set of linear equations. The input parameters "matrix1", and "row_perm" come from luDecompostion and do not change here. The parameter "matrix2" is a set of column vectors assembled into a nxn matrix of floating-point values. The procedure takes each column of "matrix2" in turn and treats it as the right-hand side of the matrix equation Ax = LUx = b. The solution vector replaces the original column of the matrix. If "matrix2" is the identity matrix, the procedure replaces its contents with the inverse of the matrix from which "matrix1" was originally derived.

    • computeQR

      public static void computeQR(int start, int end, double[] s, double[] e, GMatrix u, GMatrix v)

    • computeSVD

      public static int computeSVD(GMatrix mat, GMatrix U, GMatrix W, GMatrix V)

    • decomposeLU

      public static boolean decomposeLU(int dim, double[] matrix0, int[] row_perm, int[] even_row_xchg)
      Given a nxn array "matrix0", this function replaces it with the LU decomposition of a row-wise permutation of itself. The input parameters are "matrix0" and "dim". The array "matrix0" is also an output parameter. The vector "row_perm[]" is an output parameter that contains the row permutations resulting from partial pivoting. The output parameter "even_row_xchg" is 1 when the number of row exchanges is even, or -1 otherwise. Assumes data type is always double.
      Returns:
      true if the matrix is nonsingular, or false otherwise.

    • add

      public final void add(GMatrix m1)
      Sets the value of this matrix to sum of itself and matrix m1.
      Parameters:
      m1 - the other matrix

    • add

      public final void add(GMatrix m1, GMatrix m2)
      Sets the value of this matrix to the matrix sum of matrices m1 and m2.
      Parameters:
      m1 - the first matrix
      m2 - the second matrix

    • clone

      public Object clone()
      Creates a new object of the same class as this object.
      Returns:
      a clone of this instance.
      Throws:
      OutOfMemoryError - if there is not enough memory.
      Since:
      vecmath 1.3
      See Also:

    • computeLUD

      public final int computeLUD(GMatrix LU, GVector permutation)
      LU Decomposition: this matrix must be a square matrix and the LU GMatrix parameter must be the same size as this matrix. The matrix LU will be overwritten as the combination of a lower diagonal and upper diagonal matrix decompostion of this matrix; the diagonal elements of L (unity) are not stored. The GVector parameter records the row permutation effected by the partial pivoting, and is used as a parameter to the GVector method LUDBackSolve to solve sets of linear equations. This method returns +/- 1 depending on whether the number of row interchanges was even or odd, respectively.
      Parameters:
      LU - The matrix into which the lower and upper decompositions will be placed.
      permutation - The row permutation effected by the partial pivoting
      Returns:
      +-1 depending on whether the number of row interchanges was even or odd respectively

    • computeSVD

      public final int computeSVD(GMatrix U, GMatrix W, GMatrix V)
      Finds the singular value decomposition (SVD) of this matrix such that this = U*W*transpose(V); and returns the rank of this matrix; the values of U,W,V are all overwritten. Note that the matrix V is output as V, and not transpose(V). If this matrix is mxn, then U is mxm, W is a diagonal matrix that is mxn, and V is nxn. Using the notation W = diag(w), then the inverse of this matrix is: inverse(this) = V*diag(1/w)*tranpose(U), where diag(1/w) is the same matrix as W except that the reciprocal of each of the diagonal components is used.
      Parameters:
      U - The computed U matrix in the equation this = U*W*transpose(V)
      W - The computed W matrix in the equation this = U*W*transpose(V)
      V - The computed V matrix in the equation this = U*W*transpose(V)
      Returns:
      The rank of this matrix.

    • copySubMatrix

      public final void copySubMatrix(int rowSource, int colSource, int numRow, int numCol, int rowDest, int colDest, GMatrix target)
      Copies a sub-matrix derived from this matrix into the target matrix. The upper left of the sub-matrix is located at (rowSource, colSource); the lower right of the sub-matrix is located at (lastRowSource,lastColSource). The sub-matrix is copied into the the target matrix starting at (rowDest, colDest).
      Parameters:
      rowSource - the top-most row of the sub-matrix
      colSource - the left-most column of the sub-matrix
      numRow - the number of rows in the sub-matrix
      numCol - the number of columns in the sub-matrix
      rowDest - the top-most row of the position of the copied sub-matrix within the target matrix
      colDest - the left-most column of the position of the copied sub-matrix within the target matrix
      target - the matrix into which the sub-matrix will be copied

    • epsilonEquals

      public boolean epsilonEquals(GMatrix m1, double epsilon)
      Returns true if the L-infinite distance between this matrix and matrix m1 is less than or equal to the epsilon parameter, otherwise returns false. The L-infinite distance is equal to MAX[i=0,1,2, . . .n ; j=0,1,2, . . .n ; abs(this.m(i,j) - m1.m(i,j)]
      Parameters:
      m1 - The matrix to be compared to this matrix
      epsilon - the threshold value

    • epsilonEquals

      @Deprecated public boolean epsilonEquals(GMatrix m1, float epsilon)
      Deprecated.
      Use epsilonEquals(GMatrix, double) instead

    • equals

      public boolean equals(GMatrix m1)
      Returns true if all of the data members of GMatrix m1 are equal to the corresponding data members in this GMatrix.
      Parameters:
      m1 - The matrix with which the comparison is made.
      Returns:
      true or false

    • equals

      public boolean equals(Object o1)
      Returns true if the Object o1 is of type GMatrix and all of the data members of o1 are equal to the corresponding data members in this GMatrix.
      Overrides:
      equals in class Object
      Parameters:
      o1 - The object with which the comparison is made.
      Returns:
      true or false

    • get

      public final void get(GMatrix m1)
      Places the values in the this GMatrix into the matrix m1; m1 should be at least as large as this GMatrix.
      Parameters:
      m1 - The matrix that will hold the new values

    • get

      public final void get(Matrix3d m1)
      Places the values in the upper 3x3 of this GMatrix into the matrix m1.
      Parameters:
      m1 - The matrix that will hold the new values

    • get

      public final void get(Matrix4f m1)
      Places the values in the upper 4x4 of this GMatrix into the matrix m1.
      Parameters:
      m1 - The matrix that will hold the new values

    • getColumn

      public final void getColumn(int col, double[] array)
      Places the values of the specified column into the array parameter.
      Parameters:
      col - the target column number
      array - the array into which the column values will be placed

    • getColumn

      public final void getColumn(int col, GVector vector)
      Places the values of the specified column into the vector parameter.
      Parameters:
      col - the target column number
      vector - the vector into which the column values will be placed

    • getElement

      public final double getElement(int row, int column)
      Retrieves the value at the specified row and column of this matrix.
      Parameters:
      row - the row number to be retrieved (zero indexed)
      column - the column number to be retrieved (zero indexed)
      Returns:
      the value at the indexed element

    • getNumCol

      public final int getNumCol()
      Returns the number of colmuns in this matrix.
      Returns:
      number of columns in this matrix

    • getNumRow

      public final int getNumRow()
      Returns the number of rows in this matrix.
      Returns:
      number of rows in this matrix

    • getRow

      public final void getRow(int row, double[] array)
      Places the values of the specified row into the array parameter.
      Parameters:
      row - the target row number
      array - the array into which the row values will be placed

    • getRow

      public final void getRow(int row, GVector vector)
      Places the values of the specified row into the vector parameter.
      Parameters:
      row - the target row number
      vector - the vector into which the row values will be placed

    • hashCode

      public int hashCode()
      Returns a hash code value based on the data values in this object. Two different GMatrix objects with identical data values (i.e., GMatrix.equals returns true) will return the same hash number. Two GMatrix objects with different data members may return the same hash value, although this is not likely.
      Overrides:
      hashCode in class Object
      Returns:
      the integer hash code value

    • identity

      public final void identity()
      Sets this GMatrix to the identity matrix.

    • identityMinus

      public final void identityMinus()
      Subtracts this matrix from the identity matrix and puts the values back into this (this = I - this).

    • invert

      public final void invert()
      Inverts this matrix in place.

    • invert

      public final void invert(GMatrix m1)
      Inverts matrix m1 and places the new values into this matrix. Matrix m1 is not modified.
      Parameters:
      m1 - the matrix to be inverted

    • mul

      public final void mul(GMatrix m1)
      Sets the value of this matrix to the result of multiplying itself with matrix m1 (this = this * m1).
      Parameters:
      m1 - the other matrix

    • mul

      public final void mul(GMatrix m1, GMatrix m2)
      Sets the value of this matrix to the result of multiplying the two argument matrices together (this = m1 * m2).
      Parameters:
      m1 - the first matrix
      m2 - the second matrix

    • mul

      public final void mul(GVector v1, GVector v2)
      Computes the outer product of the two vectors; multiplies the the first vector by the transpose of the second vector and places the matrix result into this matrix. This matrix must be be as big or bigger than getSize(v1)xgetSize(v2).
      Parameters:
      v1 - the first vector, treated as a row vector
      v2 - the second vector, treated as a column vector

    • mulTransposeBoth

      public final void mulTransposeBoth(GMatrix m1, GMatrix m2)
      Multiplies the transpose of matrix m1 times the transpose of matrix m2, and places the result into this.
      Parameters:
      m1 - The matrix on the left hand side of the multiplication
      m2 - The matrix on the right hand side of the multiplication

    • mulTransposeLeft

      public final void mulTransposeLeft(GMatrix m1, GMatrix m2)
      Multiplies the transpose of matrix m1 times matrix m2, and places the result into this.
      Parameters:
      m1 - The matrix on the left hand side of the multiplication
      m2 - The matrix on the right hand side of the multiplication

    • mulTransposeRight

      public final void mulTransposeRight(GMatrix m1, GMatrix m2)
      Multiplies matrix m1 times the transpose of matrix m2, and places the result into this.
      Parameters:
      m1 - The matrix on the left hand side of the multiplication
      m2 - The matrix on the right hand side of the multiplication

    • negate

      public final void negate()
      Negates the value of this matrix: this = -this.

    • negate

      public final void negate(GMatrix m1)
      Sets the value of this matrix equal to the negation of of the GMatrix parameter.
      Parameters:
      m1 - The source matrix

    • set

      public final void set(double[] matrix)
      Sets the value of this matrix to the values found in the array parameter. The values are copied in one row at a time, in row major fashion. The array should be at least equal in length to the number of matrix rows times the number of matrix columns in this matrix.
      Parameters:
      matrix - the row major source array

    • set

      public final void set(GMatrix m1)
      Sets the value of this matrix to the values found in matrix m1.
      Parameters:
      m1 - the source matrix

    • set

      public final void set(Matrix3d m1)
      Sets the value of this matrix to that of the Matrix3d provided.
      Parameters:
      m1 - the matrix

    • set

      public final void set(Matrix4f m1)
      Sets the value of this matrix to that of the Matrix4f provided.
      Parameters:
      m1 - the matrix

    • setColumn

      public final void setColumn(int col, double[] array)
      Copy the values from the array into the specified column of this matrix.
      Parameters:
      col - the column of this matrix into which the array values will be copied
      array - the source array

    • setColumn

      public final void setColumn(int col, GVector vector)
      Copy the values from the vector into the specified column of this matrix.
      Parameters:
      col - the column of this matrix into which the array values will be copied
      vector - the source vector

    • setElement

      public final void setElement(int row, int column, double value)
      Modifies the value at the specified row and column of this matrix.
      Parameters:
      row - the row number to be modified (zero indexed)
      column - the column number to be modified (zero indexed)
      value - the new matrix element value

    • setRow

      public final void setRow(int row, double[] array)
      Copy the values from the array into the specified row of this matrix.
      Parameters:
      row - the row of this matrix into which the array values will be copied.
      array - the source array

    • setRow

      public final void setRow(int row, GVector vector)
      Copy the values from the vector into the specified row of this matrix.
      Parameters:
      row - the row of this matrix into which the array values will be copied
      vector - the source vector

    • setScale

      public final void setScale(double scale)
      Sets this matrix to a uniform scale matrix; all of the values are reset.
      Parameters:
      scale - The new scale value

    • setSize

      public final void setSize(int nRow, int nCol)
      Changes the size of this matrix dynamically. If the size is increased no data values will be lost. If the size is decreased, only those data values whose matrix positions were eliminated will be lost.
      Parameters:
      nRow - number of desired rows in this matrix
      nCol - number of desired columns in this matrix

    • setZero

      public final void setZero()
      Sets all the values in this matrix to zero.

    • sub

      public final void sub(GMatrix m1)
      Sets the value of this matrix to the matrix difference of itself and matrix m1 (this = this - m1).
      Parameters:
      m1 - the other matrix

    • sub

      public final void sub(GMatrix m1, GMatrix m2)
      Sets the value of this matrix to the matrix difference of matrices m1 and m2 (this = m1 - m2).
      Parameters:
      m1 - the first matrix
      m2 - the second matrix

    • toString

      public String toString()
      Returns a string that contains the values of this GMatrix.
      Overrides:
      toString in class Object
      Returns:
      the String representation

    • trace

      public final double trace()
      Returns the trace of this matrix.
      Returns:
      the trace of this matrix

    • transpose

      public final void transpose()
      Transposes this matrix in place.

    • transpose

      public final void transpose(GMatrix m1)
      Places the matrix values of the transpose of matrix m1 into this matrix.
      Parameters:
      m1 - the matrix to be transposed (but not modified)