Maven module :un.api : api-math :
Class : un.impl.math.Matrices
Extends/Implements : -
Subclasses : -

author  Johann Sorel
author  Bertrand COTE

Variables : -
Functions : isIdentity, setToIdentity, identity, localAdd, add, localSubtract, subtract, localScale, localScale, scale, scale, power, transpose, localInvert, invert, dot, roundZeros, transformLocal, transformLocal, transform, transform, transform, transform, transform, transform, localMultiply, multiply, createRotation3, createRotation4, fromEuler, toEuler, decomposeMatrix, lookAt, lookAt, ortho2, orthogonal, perspective, projection, focusedOrbit


Checks if the given matrix is the identity matrix.
param  m matrix to test.
return  true if matrix is an Identity matrix.
public boolean isIdentity (double[][] m)


Sets the given matrix to identity matrix.
param  m a square matrix.
throws  IllegalArgumentException when m is not a square matrix.
public void setToIdentity (double[][] m)


Creates a n*n identity matrix.
param  n number of rows and columns.
return  an n*n identity matrix.
public double[][] identity (int n)


Adds m1 and m2, the result is stored in m1, returns m1.
see {@link Matrices#add(un.science.math.Matrix, un.science.math.Matrix, un.science.math.Matrix)}
param  m1 first matrix
param  m2 second matrix
return  m1 + m2 result in m1 matrix.
public double[][] localAdd (double[][] m1, double[][] m2)


Adds m1 and m2 matrices, the result is stored in buffer, returns buffer.
If buffer is null, a new matrix is created.
Matrices must have the same size.
param  m1 first matrix
param  m2 second matrix
param  buffer result buffer, can be null
return  m1 + m2 result in buffer matrix.
throws  IllegalArgumentException when matrices size differ.
public double[][] add (double[][] m1, double[][] m2, double[][] buffer)


Subtracts m2 to m1, the result is stored in m1, returns m1.
see {@link Matrices#subtract(un.science.math.Matrix, un.science.math.Matrix, un.science.math.Matrix)}
param  m1 first matrix
param  m2 second matrix
return  m1 - m2 result in m1 matrix.
public double[][] localSubtract (double[][] m1, double[][] m2)


Subtracts m2 to m2 matrices, result is stored in buffer, returns buffer.
If buffer is null, a new matrix is created.
Matrices must have the same size.
param  m1 first matrix
param  m2 second matrix
param  buffer result buffer, can be null
return  m1 - m2 result in buffer matrix.
throws  IllegalArgumentException when matrices size differ
public double[][] subtract (double[][] m1, double[][] m2, double[][] buffer)


Scales m1 by scaleFactor, result is stored in m1, returns m1.
see {@link Matrices#scale(un.science.math.Matrix, un.science.math.Matrix, double)}
param  m1 input matrix
param  scaleFactor scale factor
return  matrix m1
public double[][] localScale (double[][] m1, double scaleFactor)


Scales matrix by columns.
param  m1 input matrix
param  tuple scale factors (one by columns).
return  matrix m1
public double[][] localScale (double[][] m1, double[] tuple)


Scales matrix by columns.
param  m1 input matrix
param  tuple scale
param  buffer result buffer, can be null
return  scaled matrix
public double[][] scale (double[][] m1, double[] tuple, double[][] buffer)


Scale m1 by scale, result is stored in buffer.
if buffer is null, a new matrix is created.
Matrices must have the same size
param  m1 input matrix
param  scale scale
param  buffer result buffer, can be null
return  scaled matrix
throws  IllegalArgumentException when matrices size differ
public double[][] scale (double[][] m1, double scale, double[][] buffer)


Multiply given matrix by itself the given number of time.
param  m1 input matrix
param  power power value
param  buffer result buffer, can be null
return  result matrix
public double[][] power (double[][] m1, int power, double[][] buffer)


return the transposed matrix.
(flips row/col values)
@param m1 input matrix
@return result matrix
public double[][] transpose (double[][] m1)


Matrix inversion using Gauss.
param  origValues input matrix
return  inverted matrix or null if not possible.
author  Xavier Philippeau
public double[][] localInvert (double[][] origValues)


Matrix inversion using Gauss.
param  origValues input matrix
param  buffer result buffer, can be null
return  inverted matrix or null if not possible.
author  Xavier Philippeau
public double[][] invert (double[][] origValues, double[][] buffer)


Matrices dot product.
param  m1 first matrix
param  m2 second matrix
return  dot product
public double dot (double[][] m1, double[][] m2)


replace valeus close to 0 with zero, removing -0 if present
param  matrix
param  epsilon
public void roundZeros (double[][] matrix, double epsilon)

public Tuple transformLocal (double[][] matrix, Tuple vector)

public Tuple transformLocal (double[][] matrix, Tuple vector, double fillValue)

public Tuple transform (double[][] matrix, Tuple vector, Tuple buffer)

public Tuple transform (double[][] matrix, Tuple vector, Tuple buffer, double fillValue)


Transform given vector.
param  matrix input matrix
param  vector vector to transform
param  buffer result vector buffer, can be null
return  the product of matrix and vector.
public double[] transform (double[][] matrix, double[] vector, double[] buffer)


Transforms given vector.
Returns result as long as vector.
If vector size is too short, the fill value will be used.
This approach is often used in 2D and 3D engine to transform vector or
normal using 0 or 1 as the last vector value.
param  matrix transformation matrix.
param  vector considered as a column matrix.
param  buffer result vector buffer, can be null
param  fillValue fill value if vector is to small
return  the product of matrix and vector.
public double[] transform (double[][] matrix, double[] vector, double[] buffer, double fillValue)


Transforms given vector.
param  matrix transformation matrix.
param  vector considered as a column matrix.
param  buffer result vector buffer, can be null
return  the product of matrix and vector.
public float[] transform (double[][] matrix, float[] vector, float[] buffer)


Transform given vector.
If vector size is too short, the fill value will be used.
This approach is often used in 2D and 3D engine to transform
vector or normal using 0 or 1 as the last vector value.
param  matrix transformation matrix.
param  vector considered as a column matrix.
param  buffer result vector buffer, can be null
param  fillValue fill value if vector is to small
return  the product of matrix and vector.
public float[] transform (double[][] matrix, float[] vector, float[] buffer, float fillValue)


Multiply m1 by m2, result is stored in m1, returns m1.
see {@link Matrices#multiply(un.science.math.Matrix, un.science.math.Matrix, un.science.math.Matrix)}
public double[][] localMultiply (double[][] m1, double[][] m2)


Multiply m1 by m2 matrices, result is stored in buffer.
If buffer is null, a new matrix is created.
public double[][] multiply (double[][] m1, double[][] m2, double[][] buffer)


Create a rotation matrix from given angle and axis.
http://en.wikipedia.org/wiki/Rotation_matrix
param  angle rotation angle in radians
param  rotationAxis Tuple 3
param  buffer Matrix 3x3
return  rotation matrix
public double[][] createRotation3 (double angle, Tuple rotationAxis, double[][] buffer)


Create a rotation matrix from given angle and axis.
http://en.wikipedia.org/wiki/Rotation_matrix
param  angle rotation angle in radians
param  rotationAxis Tuple 3
param  buffer Matrix 4x4
return  rotation matrix
public double[][] createRotation4 (double angle, Tuple rotationAxis, double[][] buffer)


Build rotation matrix from Euler angle.
Sources :
http://en.wikipedia.org/wiki/Axes_conventions
http://jeux.developpez.com/faq/math/?page=transformations#Q36
http://en.wikipedia.org/wiki/Euler_angles
http://mathworld.wolfram.com/EulerAngles.html
http://www.euclideanspace.com/maths/geometry/rotations/conversions/eulerToMatrix/
Euler angle convention is : (Z-Y’-X’’) ISO 1151–2:1985
param  buffer size 4x4 or 3x3
return  matrix, never null
public double[][] fromEuler (double[] euler, double[][] buffer)


Calculate Euler angle of given matrix.
Source :
http://www.soi.city.ac.uk/~sbbh653/publications/euler.pdf
http://jeux.developpez.com/faq/math/?page=transformations#Q37

@param mat input matrix
@param buffer euler buffer, can be null
@return euler angle in radians (heading/yaw , elevation/pitch , bank/roll)
public double[] toEuler (double[][] mat, double[] buffer)


Decompose a matrix in rotation, scale and translation.
The matrix is expected to be orthogonal of size 3x3 or 4x4.
param  trs
param  rotation
param  scale
param  translation
public void decomposeMatrix (Matrix trs, MatrixRW rotation, Tuple scale, Tuple translation)


Calculate a view matrix, often used by rendering engines as the
World to Camera transform.
param  eye : viewer position, Tuple 3
param  center : position looked at, Tuple 3
param  up : up direction, Tuple 3
param  buffer : storage, Matrix 4x4
return  Matrix4x4d
public double[][] lookAt (Tuple eye, Tuple center, Tuple up, double[][] buffer)

public double[][] lookAt (Tuple target, Tuple up, double[][] buffer)

public double[][] ortho2 (double fovy, double aspect, double zNear, double zFar, double[][] buffer)


Calculate a projection matrix, often used by rendering engines as the
Camera to Homogeneous transform.
Matrix as defined here :
http://en.wikipedia.org/wiki/Orthographic_projection_(geometry)
param  left field of view left
param  right field of view right
param  bottom field of view bottom
param  top field of view top
param  near field of view near
param  far field of view far
param  buffer result buffer, can be null
return
public double[][] orthogonal (double left, double right, double bottom, double top, double near, double far, double[][] buffer)


Calculate a perspective matrix.
param  fov : field of view
param  width : canvas width
param  height : canvas height
param  near : frustrum near plan
param  far : frustrum far plan
param  buffer : matrix buffer, can be null
param  rightHand true for right handed coordinate system, false for leftHanded.
return  perspective 4x4 matrix
public double[][] perspective (double fov, double width, double height, double near, double far, double[][] buffer, boolean rightHand)


Calculate a projection matrix, often used by rendering engines as the
Camera to Homogeneous transform.
param  degrees field of view angle
param  aspectRatio screen aspect ratio
param  near near plan
param  far far plan
param  buffer result buffer, can be null
return  Matrix4x4d
public double[][] projection (double degrees, double aspectRatio, double near, double far, double[][] buffer)


Create and orbit matrix 4x4 focus on the root point (0,0,0).
param  xAngle horizontal angle
param  yAngle vertical angle
param  rollAngle roll angle
param  distance distance from base
return  orbit matrix 4x4
public double[][] focusedOrbit (double xAngle, double yAngle, double rollAngle, double distance)