jwo.utils.structure
Class JWMatrix

java.lang.Object
  jwo.utils.structure.JWMatrix

public class JWMatrix
extends Object

Class containing Matrix processing operations. Includes general matrix operations such as addition, multiplication, and inverses, dot and cross products. Also includes operations optimised for 3D vectors. Some of these routines (e.g. vMatch) were converted from the vector maths utilities in C, written by Gustav Taxen, 1998.

Version:

2.3, 23rd November, 2003.

Author:

Jo Wood, some original code by Gustav Taxen.

Constructor Summary

JWMatrix()

Method Summary

static double[][]	mCopy(double[][] m) Produces a copy of a given (4x4) matrix.
static float[][]	mCopy(float[][] m) Produces a copy of a given (4x4) matrix.
static void	mDisplay(double[][] m) Displays the contents of a 2D matrix of any size to maximum number of decimal places.
static void	mDisplay(double[][] m, int dp) Displays the contents of a 2D matrix of any size to a given number of decimal places.
static void	mDisplay(float[][] m) Displays the contents of a 2D matrix of any size to maximum number of decimal places.
static void	mDisplay(float[][] m, int dp) Displays the contents of a 2D matrix of any size to a given number of decimal places.
static float[][]	mIdentity() Creates a (4x4) identity matrix.
static double[][]	mIdentityd() Creates a (4x4) identity matrix.
static float[][]	mInverse(float[][] m) Calculates the inverse of a (4x4) matrix.
static float[][]	mmMultiply(float[][] m1, float[][] m2) Multiplies two 2-dimensional matrices (m1 dot m2) of any size.
static double[][]	mMultiply(double[][] m1, double[][] m2) Pre-multiplies two (4x4) homogeneous matrices (m1 dot m2).
static float[][]	mMultiply(float[][] m1, float[][] m2) Pre-multiplies two (4x4) homogeneous matrices (m1 dot m2).
static double[][]	mRotate(double[] axis, double alpha) Calculates the (4x4) homogeneous rotation matrix by a given angle about a given axis.
static float[][]	mRotate(float[] axis, float alpha) Calculates the (4x4) homogeneous rotation matrix by a given angle about a given axis.
static float[][]	mTranspose(float[][] m) Returns the transpose of a 2D matrix of any size.
static float[]	mvMultiply(float[][] m, float[] v) Multiplies a 2-dimensional matrix by a vector (m dot v) of any size.
static double[]	serialise(double[][] m) Returns a 1-dimensional 'serialised' version of a given 2d 4x4 matrix.
static float[]	serialise(float[][] m) Returns a 1-dimensional 'serialised' version of a given 2d 4x4 matrix.
static double[]	vAdd(double[] u, double[] v) Adds one (3D) vector to another.
static float[]	vAdd(float[] u, float[] v) Adds one (3D) vector to another.
static double	vAngle(double[] u, double[] v) Calculates the angle between two (3D) vectors u and v.
static float	vAngle(float[] u, float[] v) Calculates the angle between two (3D) vectors u and v.
static double[]	vCopy(double[] v) Produces a copy of a given (3D) vector.
static float[]	vCopy(float[] v) Produces a copy of a given (3D) vector.
static double[]	vCross(double[] u, double[] v) Calculates the cross product of two (3D) vectors.
static double[]	vCross(double x1, double y1, double z1, double x2, double y2, double z2) Calculates the cross product of two (3D) vectors.
static float[]	vCross(float[] u, float[] v) Calculates the cross product of two (3D) vectors.
static float[]	vCross(float x1, float y1, float z1, float x2, float y2, float z2) Calculates the cross product of two (3D) vectors.
static void	vDisplay(double[] v) Displays the contents of a 1D vector of any size.
static void	vDisplay(float[] v) Displays the contents of a 1D vector of any size.
static double	vDistance(double[] u, double[] v) Calculates the distance between two (3D) points u and v.
static float	vDistance(float[] u, float[] v) Calculates the distance between two (3D) points u and v.
static double	vDistanceSq(double[] u, double[] v) Calculates the squared distance between two (3D) points u and v.
static float	vDistanceSq(float[] u, float[] v) Calculates the squared distance between two (3D) points u and v.
static double	vDot(double[] u, double[] v) Calculates the dot product of two (3D) vectors.
static float	vDot(float[] u, float[] v) Calculates the dot product of two (3D) vectors.
static double	vLength(double[] v) Calculates the length of a (3D) vector.
static float	vLength(float[] v) Calculates the length of a (3D) vector.
static double	vLengthSq(double[] v) Calculates the squared length of a (3D) vector.
static float	vLengthSq(float[] v) Calculates the squared length of a (3D) vector.
static double[]	vMatch(double[] u, double[] v) Calculates the rotation angle R and axis A such that when rotated, (3D) vector u coincides with (3D) vector v.
static float[]	vMatch(float[] u, float[] v) Calculates the rotation angle R and axis A such that when rotated, (3D) vector u coincides with (3D) vector v.
static double[]	vNormalise(double[] v) Normalises a (3D) vector so its length is 1.
static float[]	vNormalise(float[] v) Normalises a (3D) vector so its length is 1.
static double[]	vRotate(double[] v, double[] axis, double alpha) Rotates a (3D) vector by a given angle around a given axis.
static float[]	vRotate(float[] v, float[] axis, float alpha) Rotates a (3D) vector by a given angle around a given axis.
static float[]	vRotateRel(float[] v1, float alpha1, float[] v2, float alpha2) Given two rotation axis vectors and their angles of rotation, returns the relative rotation vector that would rotate the first to the second.
static double[]	vRotateX(double[] v, double alpha) Rotates a (3D) vector by a given angle around the X axis.
static float[]	vRotateX(float[] v, float alpha) Rotates a (3D) vector by a given angle around the X axis.
static double[]	vRotateY(double[] v, double alpha) Rotates a (3D) vector by a given angle around the Y axis.
static float[]	vRotateY(float[] v, float alpha) Rotates a (3D) vector by a given angle around the Y axis.
static double[]	vRotateZ(double[] v, double alpha) Rotates a (3D) vector by a given angle around the Z axis.
static float[]	vRotateZ(float[] v, float alpha) Rotates a (3D) vector by a given angle around the Z axis.
static double[]	vScale(double[] v, double s) Multiplies a (3D) vector by a given scalar constant.
static float[]	vScale(float[] v, float s) Multiplies a (3D) vector by a given scalar constant.
static double[]	vSphere(double phi, double lambda) Finds the (3D) vector represented by given phi and lambda angles in spherical coordinates.
static float[]	vSphere(float phi, float lambda) Finds the (3D) vector represented by given phi and lambda angles in spherical coordinates.
static double[]	vSubtract(double[] u, double[] v) Subtracts a (3D) vector from another.
static float[]	vSubtract(float[] u, float[] v) Subtracts a (3D) vector from another.
static double[]	vTransform(double[][] m, double[] v) Pre-multiplies a (3D) vector by a homogeneous (4x4) transformation matrix.
static float[]	vTransform(float[][] m, float[] v) Pre-multiplies a (3D) vector by a homogeneous (4x4) transformation matrix.

Methods inherited from class java.lang.Object

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

Constructor Detail

JWMatrix

public JWMatrix()

Method Detail

mTranspose

public static float[][] mTranspose(float[][] m)

Returns the transpose of a 2D matrix of any size. Useful when creating normal equations for least squares.

Parameters:

m - Input matrix

Returns:

Transpose of the given matrix.

vAdd

public static float[] vAdd(float[] u,
                           float[] v)

Adds one (3D) vector to another.

Parameters:

u - First vector.

v - Second vector.

Returns:

Sum of the two vectors (u+v).

vAdd

public static double[] vAdd(double[] u,
                            double[] v)

Adds one (3D) vector to another. Double precision version.

Parameters:

u - First vector.

v - Second vector.

Returns:

Sum of the two vectors (u+v).

vAngle

public static float vAngle(float[] u,
                           float[] v)

Calculates the angle between two (3D) vectors u and v.

Parameters:

u - First vector.

v - Second vector.

Returns:

Angle between the two vectors in radians.

vAngle

public static double vAngle(double[] u,
                            double[] v)

Calculates the angle between two (3D) vectors u and v. Double precision version.

Parameters:

u - First vector.

v - Second vector.

Returns:

Angle between the two vectors in radians.

mCopy

public static float[][] mCopy(float[][] m)

Produces a copy of a given (4x4) matrix.

Parameters:

m - Matrix to copy.

Returns:

Copy of original matrix.

mCopy

public static double[][] mCopy(double[][] m)

Produces a copy of a given (4x4) matrix. Double precision version

Parameters:

m - Matrix to copy.

Returns:

Copy of original matrix.

vCopy

public static float[] vCopy(float[] v)

Produces a copy of a given (3D) vector.

Parameters:

v - Vector to copy.

Returns:

Copy of original vector.

vCopy

public static double[] vCopy(double[] v)

Produces a copy of a given (3D) vector. Double precision version.

Parameters:

v - Vector to copy.

Returns:

Copy of original vector.

vCross

public static float[] vCross(float[] u,
                             float[] v)

Calculates the cross product of two (3D) vectors.

Parameters:

u - First vector.

v - Second vector.

Returns:

Cross product of the two vectors.

vCross

public static float[] vCross(float x1,
                             float y1,
                             float z1,
                             float x2,
                             float y2,
                             float z2)

Calculates the cross product of two (3D) vectors.

Parameters:

x1 - First vector x coordinate.

y1 - First vector y coordinate.

z1 - First vector z coordinate.

x2 - Second vector x coordinate.

y2 - Second vector y coordinate.

z2 - Second vector z coordinate.

Returns:

Cross product of the two vectors.

vCross

public static double[] vCross(double[] u,
                              double[] v)

Calculates the cross product of two (3D) vectors. Double precision version.

Parameters:

u - First vector.

v - Second vector.

Returns:

Cross product of the two vectors.

vCross

public static double[] vCross(double x1,
                              double y1,
                              double z1,
                              double x2,
                              double y2,
                              double z2)

Calculates the cross product of two (3D) vectors. Double precision version.

Parameters:

x1 - First vector x coordinate.

y1 - First vector y coordinate.

z1 - First vector z coordinate.

x2 - Second vector x coordinate.

y2 - Second vector y coordinate.

z2 - Second vector z coordinate.

Returns:

Cross product of the two vectors.

mDisplay

public static void mDisplay(float[][] m)

Displays the contents of a 2D matrix of any size to maximum number of decimal places.

Parameters:

m - Matrix to display.

mDisplay

public static void mDisplay(double[][] m)

Displays the contents of a 2D matrix of any size to maximum number of decimal places.

Parameters:

m - Matrix to display.

mDisplay

public static void mDisplay(float[][] m,
                            int dp)

Displays the contents of a 2D matrix of any size to a given number of decimal places.

Parameters:

m - Matrix to display.

dp - Number of decimal places to display.

mDisplay

public static void mDisplay(double[][] m,
                            int dp)

Displays the contents of a 2D matrix of any size to a given number of decimal places. Double precision version.

Parameters:

m - Matrix to display.

dp - Number of decimal places to display.

vDisplay

public static void vDisplay(float[] v)

Displays the contents of a 1D vector of any size.

Parameters:

v - Vector to display.

vDisplay

public static void vDisplay(double[] v)

Displays the contents of a 1D vector of any size. Double precision version.

Parameters:

v - Vector to display.

vDistance

public static float vDistance(float[] u,
                              float[] v)

Calculates the distance between two (3D) points u and v.

Parameters:

u - First point vector.

v - Second point vector.

Returns:

Distance between the two points.

vDistance

public static double vDistance(double[] u,
                               double[] v)

Calculates the distance between two (3D) points u and v. Double precision version.

Parameters:

u - First point vector.

v - Second point vector.

Returns:

Distance between the two points.

vDistanceSq

public static float vDistanceSq(float[] u,
                                float[] v)

Calculates the squared distance between two (3D) points u and v.

Parameters:

u - First point vector.

v - Second point vector.

Returns:

Squared distance between the two points.

vDistanceSq

public static double vDistanceSq(double[] u,
                                 double[] v)

Calculates the squared distance between two (3D) points u and v. Double precision version.

Parameters:

u - First point vector.

v - Second point vector.

Returns:

Squared distance between the two points.

vDot

public static float vDot(float[] u,
                         float[] v)

Calculates the dot product of two (3D) vectors.

Parameters:

u - First vector.

v - Second vector.

Returns:

Dot product of the two vectors.

vDot

public static double vDot(double[] u,
                          double[] v)

Calculates the dot product of two (3D) vectors. Double precision version.

Parameters:

u - First vector.

v - Second vector.

Returns:

Dot product of the two vectors.

mIdentity

public static float[][] mIdentity()

Creates a (4x4) identity matrix.

Returns:

Identity matrix.

mIdentityd

public static double[][] mIdentityd()

Creates a (4x4) identity matrix. Double precision version.

Returns:

Identity matrix.

mInverse

public static float[][] mInverse(float[][] m)

Calculates the inverse of a (4x4) matrix.

Parameters:

m - Matrix to find inverse of.

Returns:

Inverse of matrix.

vLength

public static float vLength(float[] v)

Calculates the length of a (3D) vector.

Parameters:

v - Vector to measure.

Returns:

Length of the vector.

vLength

public static double vLength(double[] v)

Calculates the length of a (3D) vector. Double precision version.

Parameters:

v - Vector to measure.

Returns:

Length of the vector.

vLengthSq

public static float vLengthSq(float[] v)

Calculates the squared length of a (3D) vector.

Parameters:

v - Vector to measure.

Returns:

Squared length of the vector.

vLengthSq

public static double vLengthSq(double[] v)

Calculates the squared length of a (3D) vector. Double precision version.

Parameters:

v - Vector to measure.

Returns:

Squared length of the vector.

vMatch

public static float[] vMatch(float[] u,
                             float[] v)

Calculates the rotation angle R and axis A such that when rotated, (3D) vector u coincides with (3D) vector v.

Parameters:

u - First normalised vector to compare.

v - Second normalised vector to compare.

Returns:

Axis vector + rotation angle in radians (4th element in array).

vMatch

public static double[] vMatch(double[] u,
                              double[] v)

Calculates the rotation angle R and axis A such that when rotated, (3D) vector u coincides with (3D) vector v. Double precision version.

Parameters:

u - First normalised vector to compare.

v - Second normalised vector to compare.

Returns:

Axis vector + rotation angle in radians (4th element in array).

mMultiply

public static float[][] mMultiply(float[][] m1,
                                  float[][] m2)

Pre-multiplies two (4x4) homogeneous matrices (m1 dot m2).

Parameters:

m1 - First matrix.

m2 - Second matrix.

Returns:

Product of the two matrices.

mmMultiply

public static float[][] mmMultiply(float[][] m1,
                                   float[][] m2)

Multiplies two 2-dimensional matrices (m1 dot m2) of any size.

Parameters:

m1 - First matrix.

m2 - Second matrix.

Returns:

Product of the two matrices or null if the number columns in m1 is not equal to the number of rows in m2.

mvMultiply

public static float[] mvMultiply(float[][] m,
                                 float[] v)

Multiplies a 2-dimensional matrix by a vector (m dot v) of any size.

Parameters:

m - Matrix. This must have the same number of columns as the vector has elements.

v - Vector. This must have the same number of elements as the matrix has columns.

Returns:

m dot v or null if the number columns in m is not equal to the size of v.

mMultiply

public static double[][] mMultiply(double[][] m1,
                                   double[][] m2)

Pre-multiplies two (4x4) homogeneous matrices (m1 dot m2). Double precision version.

Parameters:

m1 - First matrix.

m2 - Second matrix.

Returns:

Product of the two matrices.

vNormalise

public static float[] vNormalise(float[] v)

Normalises a (3D) vector so its length is 1.

Parameters:

v - Vector to normalise.

Returns:

Normalised vector.

vNormalise

public static double[] vNormalise(double[] v)

Normalises a (3D) vector so its length is 1. Double precision version.

Parameters:

v - Vector to normalise.

Returns:

Normalised vector.

mRotate

public static float[][] mRotate(float[] axis,
                                float alpha)

Calculates the (4x4) homogeneous rotation matrix by a given angle about a given axis.

Parameters:

axis - Vector representing normalised rotation axis.

alpha - Angle to rotate by (in radians).

Returns:

Rotation matrix.

mRotate

public static double[][] mRotate(double[] axis,
                                 double alpha)

Calculates the (4x4) homogeneous rotation matrix by a given angle about a given axis. Double precision version.

Parameters:

axis - Vector representing normalised rotation axis.

alpha - Angle to rotate by (in radians).

Returns:

Rotation matrix.

vRotate

public static float[] vRotate(float[] v,
                              float[] axis,
                              float alpha)

Rotates a (3D) vector by a given angle around a given axis.

Parameters:

v - Vector to rotate.

axis - Vector representing normalised rotation axis.

alpha - Angle to rotate by (in radians).

Returns:

Rotated vector.

vRotate

public static double[] vRotate(double[] v,
                               double[] axis,
                               double alpha)

Rotates a (3D) vector by a given angle around a given axis.

Parameters:

v - Vector to rotate. Double precision version.

axis - Vector representing normalised rotation axis.

alpha - Angle to rotate by (in radians).

Returns:

Rotated vector.

vRotateX

public static float[] vRotateX(float[] v,
                               float alpha)

Rotates a (3D) vector by a given angle around the X axis.

Parameters:

v - Vector to rotate.

alpha - Angle to rotate by (in radians).

Returns:

Rotated vector.

vRotateX

public static double[] vRotateX(double[] v,
                                double alpha)

Rotates a (3D) vector by a given angle around the X axis. Double precision version.

Parameters:

v - Vector to rotate.

alpha - Angle to rotate by (in radians).

Returns:

Rotated vector.

vRotateY

public static float[] vRotateY(float[] v,
                               float alpha)

Rotates a (3D) vector by a given angle around the Y axis.

Parameters:

v - Vector to rotate.

alpha - Angle to rotate by (in radians).

Returns:

Rotated vector.

vRotateY

public static double[] vRotateY(double[] v,
                                double alpha)

Rotates a (3D) vector by a given angle around the Y axis. Double precision version.

Parameters:

v - Vector to rotate.

alpha - Angle to rotate by (in radians).

Returns:

Rotated vector.

vRotateZ

public static float[] vRotateZ(float[] v,
                               float alpha)

Rotates a (3D) vector by a given angle around the Z axis.

Parameters:

v - Vector to rotate.

alpha - Angle to rotate by (in radians).

Returns:

Rotated vector.

vRotateZ

public static double[] vRotateZ(double[] v,
                                double alpha)

Rotates a (3D) vector by a given angle around the Z axis. Double precision version.

Parameters:

v - Vector to rotate.

alpha - Angle to rotate by (in radians).

Returns:

Rotated vector.

vRotateRel

public static float[] vRotateRel(float[] v1,
                                 float alpha1,
                                 float[] v2,
                                 float alpha2)

Given two rotation axis vectors and their angles of rotation, returns the relative rotation vector that would rotate the first to the second.

Parameters:

v1 - First rotation axis.

alpha1 - Angle of first rotation (in radians).

v2 - Second rotation axis.

alpha2 - Angle of second rotation (in radians).

Returns:

Relative rotation vector (axis + angle as fourth element in array)

vScale

public static float[] vScale(float[] v,
                             float s)

Multiplies a (3D) vector by a given scalar constant.

Parameters:

v - Vector to scale.

s - Scalar constant.

Returns:

Scaled vector.

vScale

public static double[] vScale(double[] v,
                              double s)

Multiplies a (3D) vector by a given scalar constant. Double precision version.

Parameters:

v - Vector to scale.

s - Scalar constant.

Returns:

Scaled vector.

vSphere

public static float[] vSphere(float phi,
                              float lambda)

Finds the (3D) vector represented by given phi and lambda angles in spherical coordinates.

Parameters:

phi - 'Latitude' in radians from 0 - PI.

lambda - 'Longitude' in radians from 0 - 2*PI.

Returns:

Normalised vector representation of spherical coordinates.

vSphere

public static double[] vSphere(double phi,
                               double lambda)

Finds the (3D) vector represented by given phi and lambda angles in spherical coordinates. Double precision version.

Parameters:

phi - 'Latitude' in radians from 0 - PI.

lambda - 'Longitude' in radians from 0 - 2*PI.

Returns:

Normalised vector representation of spherical coordinates.

vSubtract

public static float[] vSubtract(float[] u,
                                float[] v)

Subtracts a (3D) vector from another.

Parameters:

u - First vector.

v - Second vector.

Returns:

Difference between the two vectors (u-v).

vSubtract

public static double[] vSubtract(double[] u,
                                 double[] v)

Subtracts a (3D) vector from another. Double precision version.

Parameters:

u - First vector.

v - Second vector.

Returns:

Difference between the two vectors (u-v).

vTransform

public static float[] vTransform(float[][] m,
                                 float[] v)

Pre-multiplies a (3D) vector by a homogeneous (4x4) transformation matrix. Will treat the coordinate vector as either a 1x3 matrix, or its 1x4 homogeneous equivalent.

Parameters:

m - Transformation Matrix (4x4).

v - Coordinate vector.

Returns:

Transformed coordinate vector.

vTransform

public static double[] vTransform(double[][] m,
                                  double[] v)

Pre-multiplies a (3D) vector by a homogeneous (4x4) transformation matrix. Will treat the coordinate vector as either a 1x3 matrix, or its 1x4 homogeneous equivalent. Double precision version.

Parameters:

m - Transformation Matrix (4x4).

v - Coordinate vector.

Returns:

Transformed coordinate vector.

serialise

public static float[] serialise(float[][] m)

Returns a 1-dimensional 'serialised' version of a given 2d 4x4 matrix.

Parameters:

m - 4x4 matrix to serialise.

Returns:

16 1d vector representation.

serialise

public static double[] serialise(double[][] m)

Returns a 1-dimensional 'serialised' version of a given 2d 4x4 matrix.

Parameters:

m - 4x4 matrix to serialise.

Returns:

16 1d vector representation.