org.charvolant.matrix
Class Matrix

java.lang.Object
  org.charvolant.matrix.Matrix

All Implemented Interfaces:

java.lang.Cloneable

public class Matrix

extends java.lang.Object

implements java.lang.Cloneable

Generalised nxm matrix class.

The Matrix class provides a generalised 2-dimensional matrix package. Matrices are treated as values wherever possible, so matrix operations such as multiplication produce a new matrix as the result, rather than operate directly on the matrix.

This package is optimised towards the 4x4 transformation matrices which can be used for 3D projections. There are a number of class methods for generating transformation matrices.

Field Summary

static double	ISOMETRIC Isometric factor.
protected double[][]	matrix
static int	N Normalisation.
static int	TD Transformation size.
static int	X X-axis.
static int	Y Y-axis.
static int	Z Z-axis.

Constructor Summary

Matrix(double[] init)
Initialised matrix.

Matrix(double[][] init)
Initialised matrix.

Matrix(int rows, int cols)
Unit matrix.

Matrix(Matrix copy)
Copied matrix.

Method Summary

Matrix	add(double arg) Constant addition.
Matrix	add(Matrix arg) Matrix addition.
double	at(int i, int j) Get a matrix element.
static Matrix	cabinet(double angle) Cabinet projection.
static Matrix	cavalier(double angle) Cavalier projection.
java.lang.Object	clone() Create a copy of this matrix.
java.lang.Object	clone(int rows, int cols) Create a resized copy.
boolean	equals(java.lang.Object obj) Equality test.
int	getCols() Matrix columns.
int	getRank() The rank of the matrix.
int	getRows() Matrix rows.
int	hashCode() Hash code.
Matrix	inverted() Matrix inversion.
static Matrix	isometric() Isometric matrix.
Matrix	multiply(double arg) Constant multiplication.
double[]	multiply(double[] arg) Matrix multiplication.
Matrix	multiply(Matrix arg) Matrix multiplication.
Matrix	negated() Matrix negation.
static Matrix	permuteXZY() Permutation matrix.
static Matrix	permuteYXZ() Permutation matrix.
static Matrix	permuteYZX() Permutation matrix.
static Matrix	permuteZXY() Permutation matrix.
static Matrix	permuteZYX() Permutation matrix.
static Matrix	perspective(double vz) Perspective matrix.
void	put(int i, int j, double val) Set at matrix element.
static Matrix	reflectX() Reflection matrix.
static Matrix	reflectY() Reflection matrix.
static Matrix	reflectZ() Reflection matrix.
static Matrix	rotateX(double angle) Rotation matrix.
static Matrix	rotateY(double angle) Rotation matrix.
static Matrix	rotateZ(double angle) Rotation matrix.
static Matrix	scaling(double sx, double sy, double sz) Scaling transformation matrix.
protected double[]	specialMultiply(double[] arg) Arithmetic.
Matrix	subtract(double arg) Constant subtraction.
Matrix	subtract(Matrix arg) Matrix subtraction.
java.lang.String	toString() String representation.
double	trace() Matrix trace.
static Matrix	transformation() Unit transformation matrix.
static Matrix	translate(double tx, double ty, double tz) Translation matrix.
Matrix	transposed() Matrix tranposition.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

matrix

protected double[][] matrix

X

public static final int X

X-axis. Position of X-axis data in a transformation matrix.

See Also:

Constant Field Values

Y

public static final int Y

Y-axis. Position of Y-axis data in a transformation matrix.

See Also:

Constant Field Values

Z

public static final int Z

Z-axis. Position of Z-axis data in a transformation matrix.

See Also:

Constant Field Values

N

public static final int N

Normalisation. Position of normalisation data in a transformation matrix.

See Also:

Constant Field Values

TD

public static final int TD

Transformation size. Size of a transformation matrix.

See Also:

Constant Field Values

ISOMETRIC

public static final double ISOMETRIC

Isometric factor. Amount of weight to give to X and Y axes during isometric transformation.

Constructor Detail

Matrix

public Matrix(int rows,
              int cols)

Unit matrix.

Unit matrix of size rows x cols.

Parameters:

rows - Number of rows in matrix.

cols - Number of columns in matrix.

Matrix

public Matrix(double[][] init)

Initialised matrix.

Make a matrix from the 2D array init.

Parameters:

init - An array of arrays containing the initial data.

Throws:

MatrixDimensionException - if init contains rows of differing length.

Matrix

public Matrix(double[] init)

Initialised matrix.

Make a vector matrix from the 1D array init.

Parameters:

init - Array to initialize the matrix.

Matrix

public Matrix(Matrix copy)

Copied matrix. Make a copy of copy. This also makes an internal copy of the matrix data, to avoid later clashes.

Parameters:

copy - The matrix to copy from.

Method Detail

transformation

public static Matrix transformation()

Unit transformation matrix.

Returns:

A transformation matrix.

scaling

public static Matrix scaling(double sx,
                             double sy,
                             double sz)

Scaling transformation matrix.

Parameters:

sx - Scaling factor for X axis.

sy - Scaling factor for Y axis.

sz - Scaling factor for Z axis.

Returns:

A transformation matrix.

rotateX

public static Matrix rotateX(double angle)

Rotation matrix. Transformation matrix for a rotation about the X axis.

Parameters:

angle - Number of radians to rotate about the axis.

Returns:

A transformation matrix.

rotateY

public static Matrix rotateY(double angle)

Rotation matrix. Transformation matrix for a rotation about the Y axis.

Parameters:

angle - Number of radians to rotate about the axis.

Returns:

A transformation matrix.

rotateZ

public static Matrix rotateZ(double angle)

Rotation matrix. Transformation matrix for a rotation about the Z axis.

Parameters:

angle - Number of radians to rotate about the axis.

Returns:

A transformation matrix.

translate

public static Matrix translate(double tx,
                               double ty,
                               double tz)

Translation matrix. Translation transformation matrix.

Parameters:

tx - Amount to translate a point along the X axis by.

ty - Amount to translate a point along the Y axis by.

tz - Amount to translate a point along the Z axis by.

Returns:

A transformation matrix.

reflectX

public static Matrix reflectX()

Reflection matrix. Reflect coordinates about the X axis.

Returns:

A transformation matrix.

reflectY

public static Matrix reflectY()

Reflection matrix. Reflect coordinates about the Y axis.

Returns:

A transformation matrix.

reflectZ

public static Matrix reflectZ()

Reflection matrix. Reflect coordinates about the Z axis.

Returns:

A transformation matrix.

permuteYZX

public static Matrix permuteYZX()

Permutation matrix. Permute coordinates (x, y, z) -> (y, z, x)

Returns:

A transformation matrix.

permuteZXY

public static Matrix permuteZXY()

Permutation matrix. Permute coordinates (x, y, z) -> (z, x, y)

Returns:

A transformation matrix.

permuteYXZ

public static Matrix permuteYXZ()

Permutation matrix. Permute coordinates (x, y, z) -> (y, x, z)

Returns:

A transformation matrix.

permuteXZY

public static Matrix permuteXZY()

Permutation matrix. Permute coordinates (x, y, z) -> (x, z, y)

Returns:

A transformation matrix.

permuteZYX

public static Matrix permuteZYX()

Permutation matrix. Permute coordinates (x, y, z) -> (z, y, x)

Returns:

A transformation matrix.

isometric

public static Matrix isometric()

Isometric matrix. Isometric transform along the Z axis.

Returns:

A transformation matrix.

cavalier

public static Matrix cavalier(double angle)

Cavalier projection. Cavalier projection onto the X-Y plane at angle

Parameters:

angle - Angle of rotation in radians

Returns:

A transformation matrix.

cabinet

public static Matrix cabinet(double angle)

Cabinet projection. Cabinet projection onto the X-Y plane at angle

Parameters:

angle - Angle of rotation in radians

Returns:

A transformation matrix.

perspective

public static Matrix perspective(double vz)

Perspective matrix. Perspective transformation along the Z axis, with a vanishing point at (0, 0, vz).

Parameters:

vz - Z coordinate of vanishing point.

Returns:

A transformation matrix.

getRank

public int getRank()

The rank of the matrix.

The rank of the matrix is the number of dimensions it has.

Returns:

Matrix rank (2).

getRows

public int getRows()

Matrix rows.

Returns:

Number of rows in matrix.

getCols

public int getCols()

Matrix columns.

Returns:

Number of columns in matrix.

at

public double at(int i,
                 int j)

Get a matrix element.

Parameters:

i - Row number of element.

j - Column number of element.

Returns:

Element at (i, j).

put

public void put(int i,
                int j,
                double val)

Set at matrix element.

Parameters:

i - Row number of element.

j - Column number of element.

val - Value to set (i, j) to.

clone

public java.lang.Object clone()

Create a copy of this matrix.

Returns:

Cloned matrix.

clone

public java.lang.Object clone(int rows,
                              int cols)

Create a resized copy.

Clone this matrix with a new size of rows x cols. As much of the matrix that can be copied will be copied, with excess parts being discarded, and remaining parts of the copy filled with a unit matrix.

Parameters:

rows - New number of rows.

cols - New number of columns.

Returns:

Cloned matrix.

equals

public boolean equals(java.lang.Object obj)

Equality test.

Two matrices are equal if they have the same size and equal elements.

Parameters:

obj - Object to test matrix against.

Returns:

Boolean equality value.

hashCode

public int hashCode()

Hash code.

Hash value for insertion into hash tables. The hash is based on the trace of the matrix.

Returns:

Hash value.

trace

public double trace()

Matrix trace.

The trace of a matrix is the sum of the elements along it's major diagonal: M.trace() = Sum_i=0ⁿ M_ii.

Returns:

Trace.

add

public Matrix add(Matrix arg)

Matrix addition.

Add two matrices together using the rules of matrix arithmetic: M.add(N)_ij = M_ij + N_ij.

Parameters:

arg - Matrix to add to this matrix.

Returns:

A new matrix which is the sum of this matrix and arg.

Throws:

MatrixDimensionException - if the two matrices do not have the same size.

add

public Matrix add(double arg)

Constant addition.

Add arg to each element of the main diagonal. Similar to adding a diagonal matrix of arg.

Parameters:

arg - The value to add to this matrix.

Returns:

A new matrix which is the sum of this and arg.

See Also:

add(Matrix)

subtract

public Matrix subtract(Matrix arg)

Matrix subtraction.

Subtract two matrices using the rules of matrix arithmetic: M.subtract(N)_ij = M_ij - N_ij.

Parameters:

arg - Matrix to subtract from this matrix.

Returns:

A new matrix which is the difference between this matrix and arg.

Throws:

MatrixDimensionException - if the two matrices do not have the same size.

subtract

public Matrix subtract(double arg)

Constant subtraction.

Subtract arg from each element of the main diagonal. Similar to subtracting a diagonal matrix of arg.

Parameters:

arg - The value to subtract from this matrix.

Returns:

A new matrix which is the difference between this and arg.

See Also:

subtract(Matrix)

multiply

public Matrix multiply(Matrix arg)

Matrix multiplication.

Multiply this matrix by arg using the rules of matrix arithmetic: M.multiply(N)_ij = Sum_{k = 0}ⁿ M_ik * N_kj.

Parameters:

arg - The matrix to multiply this matrix by.

Returns:

A new matrix which is the product of this matrix and arg

Throws:

MatrixDimensionException - if arg does not have the same number of rows as this matrix has columns.

multiply

public double[] multiply(double[] arg)

Matrix multiplication.

Multiply this matrix by arg using the rules of matrix arithmetic. arg is treated as a n x 1 vector for this purpose.

Parameters:

arg - The matrix to multiply this matrix by.

Returns:

An array containing the resultant vector.

Throws:

MatrixDimensionException - if arg does not have the same number of rows as this matrix has columns.

See Also:

multiply(Matrix)

specialMultiply

protected double[] specialMultiply(double[] arg)

Arithmetic. Special case multiplication for transformation matrices and vectors. This method is automatically invoked by multiply when needed.

See Also:

multiply(double[])

multiply

public Matrix multiply(double arg)

Constant multiplication.

Multiply a matrix by a scalar: M.multiply(a)_ij = M_ij * a.

Parameters:

arg - The scalar to multiply by.

Returns:

A new matrix with each element of this matrix multiplied by arg.

See Also:

multiply(Matrix)

transposed

public Matrix transposed()

Matrix tranposition.

Transpose a matrix: M.transposed()_ij = M_ji

Returns:

A new matrix which is this matrix transposed.

negated

public Matrix negated()

Matrix negation.

Negate a matrix: M.negated()_ij = -M_ij.

Returns:

A new matrix which is this matrix with each element negated.

inverted

public Matrix inverted()

Matrix inversion.

Invert a square matrix: M * M.inverted() = I.

Returns:

A new matrix which is the inverse of this matrix.

Throws:

MatrixDimensionException - if the matrix is not a sqaure matrix.

MatrixSingularException - if the matrix cannot be inverted (is singular).

toString

public java.lang.String toString()

String representation.

Converts the matrix into a string of form [[m₀₀, ..., m_0c], ..., [m_r0, ..., m_cc]]

Returns:

The string representation of this matrix.