cz.cuni.jagrlib
Class TrMatrix

java.lang.Object
  extended by cz.cuni.jagrlib.TrMatrix

public class TrMatrix
extends java.lang.Object

2D and 3D transformation matrix - uses homogenous coordinates. Coordinate vectors are treated as row-vectors - matrix multiplications are associated from the left (multiplication from the right side).

Matrix size can be 3x2 or 3x3 (for 2D transformations), 4x3 or 4x4 (for 3D transformations).

Since:
0.09
See Also:
TrMatrix.java, Template

Field Summary
 int height
          Matrix height - number of rows (3 for 2D transformation, 4 for 3D transformation).
 double[][] m
          The matrix itself.
 int width
          Matrix width - number of columns (2 to 3 for 2D transformation, 3 to 4 for 3D transformation).
 
Constructor Summary
TrMatrix()
          Default constructor: creates identical 3D transformation (4x4 matrix size).
TrMatrix(double[] row0, double[] row1, double[] row2, double[] row3)
          Constructs matrix from row vectors.
TrMatrix(int h, int w)
          Identity constructor: creates identical transformation of the given size (3x2, 3x3, 4x3 or 4x4).
TrMatrix(TrMatrix s)
          Copy constructor.
 
Method Summary
 void append(TrMatrix mul)
          Append the given matrix to the actual transform.
 void frustum(double left, double right, double bottom, double top, double near, double far)
          Computes perspective projection matrix.
 void identity(int h, int w)
          Creates identical matrix of the given size.
 void init(int h, int w)
          Initializes the matrix using the given size.
 boolean invert(double[][] src)
          Inverts arbitrary transformation matrix.
 boolean invert(TrMatrix s)
          Matrix assignment with inversion.
 void log(java.lang.String name)
          Logs the matrix using LogFile.
 void lookAt(double[] eye, double[] center, double[] up)
          Computes viewing transformation matrix.
static void main(java.lang.String[] args)
          Self-test.
 void moveToZAxis(double[] origin, double[] direction, TrMatrix inv)
          Append the "move-to-z-axis" transform to the actual transform matrix.
 void ortho(double left, double right, double bottom, double top, double near, double far)
          Computes orthographic projection matrix.
 void perspective(double fov, double aspect, double near, double far)
          Computes perspective projection matrix.
 void perspectiveGL(double fov, double aspect, double near, double far)
          Computes perspective projection matrix.
 void prepend(TrMatrix mul)
          Prepend the given matrix to the actual transform.
 void rotate3D(double[] origin, double[] direction, double angle, TrMatrix inv)
          Append general rotation to the actual transform matrix.
 void rotateAxis3D(int axis, double sina, double cosa, TrMatrix inv)
          Appends the given rotation to the actual transform matrix.
 void rotateAxis3D(int axis, double angle, TrMatrix inv)
          Appends the given rotation to the actual transform matrix.
 void rotateOrigin2D(double sina, double cosa, TrMatrix inv)
          Appends the given rotation to the actual transform matrix.
 void scale3D(double[] origin, double[] direction, double dirScale, double perScale, TrMatrix inv)
          Append general scale to the actual transform matrix.
 void scale3D(double[] origin, double scale, TrMatrix inv)
          Append uniform scale transform to the actual transform matrix.
 void scaleAxes3D(double[] origin, double[] scale, TrMatrix inv)
          Append axes scale transform to the actual transform matrix.
 void scaleAxes3D(double[] origin, double sX, double sY, double sZ, TrMatrix inv)
          Append axes scale transform to the actual transform matrix.
 void set(TrMatrix s)
          Matrix assignment.
 boolean setNormalTransform3D(TrMatrix s)
          Transforms the given matrix to be used on 3D normal vectors.
 double[] toArray(int wid, int hei, boolean rowMajor, double[] result)
          Converts the matrix into 1D array of doubles (with optional OpenGL order).
 java.lang.String toString()
          Returns the actual matrix in readable format.
 void transformPoint2D(double[] src, double[] dest)
          2D linear transformation - processes both Cartesian and homogeneous coordinate vectors.
 void transformPoint2D(double[] src, int srcI, int srcLen, double[] dest, int destI, int destLen)
          2D linear transformation - processes both Cartesian and homogeneous coordinate vectors.
 void transformPoint2D(float[] src, float[] dest)
          2D linear transformation - processes both Cartesian and homogeneous coordinate vectors.
 void transformPoint2D(float[] src, int srcI, int srcLen, float[] dest, int destI, int destLen)
          2D linear transformation - processes both Cartesian and homogeneous coordinate vectors.
 void transformPoint3D(double[] src, double[] dest)
          3D linear transformation - processes both Cartesian and homogeneous coordinate vectors.
 void transformPoint3D(double[] src, int srcI, int srcLen, double[] dest, int destI, int destLen)
          3D linear transformation - processes both Cartesian and homogeneous coordinate vectors.
 void transformPoint3D(float[] src, float[] dest)
          3D linear transformation - processes both Cartesian and homogeneous coordinate vectors.
 void transformPoint3D(float[] src, int srcI, int srcLen, float[] dest, int destI, int destLen)
          3D linear transformation - processes both Cartesian and homogeneous coordinate vectors.
 void transformVector3D(double[] src, double[] dest)
          3D homomorphism - processes both Cartesian and homogeneous coordinate vectors.
 void translate2D(double[] vector, TrMatrix inv)
          Appends the given translation to the actual transform matrix.
 void translate3D(double[] vector, TrMatrix inv)
          Appends the given translation to the actual transform matrix.
 void translate3D(double tx, double ty, double tz, TrMatrix inv)
          Appends the given translation to the actual transform matrix.
 void transpose()
          Transposes the given matrix.
 void viewport(double x0, double y0, double width, double height)
          Computes final scaling 2D transform (viewport transform) mapping NDS (Normalized Device Space) into the given screen coordinate range.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

m

public double[][] m
The matrix itself.

See Also:
height, width

height

public int height
Matrix height - number of rows (3 for 2D transformation, 4 for 3D transformation).

See Also:
width

width

public int width
Matrix width - number of columns (2 to 3 for 2D transformation, 3 to 4 for 3D transformation).

See Also:
height
Constructor Detail

TrMatrix

public TrMatrix()
Default constructor: creates identical 3D transformation (4x4 matrix size).


TrMatrix

public TrMatrix(int h,
                int w)
Identity constructor: creates identical transformation of the given size (3x2, 3x3, 4x3 or 4x4).

Parameters:
h - Matrix height (number of rows). Should be 3 for 2D transformations and 4 for 3D ones.
w - Matrix width (number of columns). Should be 2 or 3 for 2D transformations, 3 or 4 for 3D ones.

TrMatrix

public TrMatrix(TrMatrix s)
Copy constructor.

Parameters:
s - Source matrix.

TrMatrix

public TrMatrix(double[] row0,
                double[] row1,
                double[] row2,
                double[] row3)
Constructs matrix from row vectors.

Method Detail

log

public void log(java.lang.String name)
Logs the matrix using LogFile.


init

public void init(int h,
                 int w)
Initializes the matrix using the given size. Matrix coefficients are not defined.

Parameters:
h - Matrix height (number of rows). Should be 3 for 2D transformations and 4 for 3D ones.
w - Matrix width (number of columns). Should be 2 or 3 for 2D transformations, 3 or 4 for 3D ones.

identity

public void identity(int h,
                     int w)
Creates identical matrix of the given size.

Parameters:
h - Matrix height (number of rows). Should be 3 for 2D transformations and 4 for 3D ones.
w - Matrix width (number of columns). Should be 2 or 3 for 2D transformations, 3 or 4 for 3D ones.

transpose

public void transpose()
Transposes the given matrix.

See Also:
invert(TrMatrix)

append

public void append(TrMatrix mul)
Append the given matrix to the actual transform.

Parameters:
mul - Matrix to be appended (concatenated) to the actual transform.
See Also:
prepend(cz.cuni.jagrlib.TrMatrix)

prepend

public void prepend(TrMatrix mul)
Prepend the given matrix to the actual transform.

Parameters:
mul - Matrix to be prepended to the actual transform.
See Also:
append(cz.cuni.jagrlib.TrMatrix)

invert

public boolean invert(double[][] src)
Inverts arbitrary transformation matrix.

Parameters:
src - Source transformation matrix (can be m or null).
Returns:
false if the source matrix is singular.
See Also:
invert(TrMatrix)

set

public void set(TrMatrix s)
Matrix assignment.

Parameters:
s - Source transformation matrix (cannot be null).

invert

public boolean invert(TrMatrix s)
Matrix assignment with inversion.

Parameters:
s - Source transformation matrix (can be null).
Returns:
false if the source matrix is singular.
See Also:
invert(double[][]), transpose(), set(cz.cuni.jagrlib.TrMatrix)

setNormalTransform3D

public boolean setNormalTransform3D(TrMatrix s)
Transforms the given matrix to be used on 3D normal vectors.

Parameters:
s - Source transformation matrix (can be null).
Returns:
false if the source matrix is singular.

transformPoint2D

public void transformPoint2D(double[] src,
                             double[] dest)
2D linear transformation - processes both Cartesian and homogeneous coordinate vectors.

Parameters:
src - Source coordinate vector ([x,y] or [x,y,w]).
dest - Destination coordinate vector ([x,y] or [x,y,w]). Can be the same as src.

transformPoint2D

public void transformPoint2D(float[] src,
                             float[] dest)
2D linear transformation - processes both Cartesian and homogeneous coordinate vectors.

Parameters:
src - Source coordinate vector ([x,y] or [x,y,w]).
dest - Destination coordinate vector ([x,y] or [x,y,w]). Can be the same as src.

transformPoint2D

public void transformPoint2D(double[] src,
                             int srcI,
                             int srcLen,
                             double[] dest,
                             int destI,
                             int destLen)
2D linear transformation - processes both Cartesian and homogeneous coordinate vectors. Source and destination coordinate vectors reside inside bigger double[] arrays.

Parameters:
src - Array holding source coordinate vector.
srcI - Origin of source coordinate vector.
srcLen - Length of source coordinate vector.
dest - Array holding destination coordinate vector. Can be the same as src (including srcI == destI).
destI - Origin of destination coordinate vector.
destLen - Length of destination coordinate vector.

transformPoint2D

public void transformPoint2D(float[] src,
                             int srcI,
                             int srcLen,
                             float[] dest,
                             int destI,
                             int destLen)
2D linear transformation - processes both Cartesian and homogeneous coordinate vectors. Source/destination coordinate vectors reside inside bigger double[]/float[] arrays.

Parameters:
src - Array holding source coordinate vector.
srcI - Origin of source coordinate vector.
srcLen - Length of source coordinate vector.
dest - Array holding destination coordinate vector. Can be the same as src (including srcI == destI).
destI - Origin of destination coordinate vector.
destLen - Length of destination coordinate vector.

transformPoint3D

public void transformPoint3D(double[] src,
                             double[] dest)
3D linear transformation - processes both Cartesian and homogeneous coordinate vectors.

Parameters:
src - Source coordinate vector ([x,y,z] or [x,y,z,w]).
dest - Destination coordinate vector ([x,y,z] or [x,y,z,w]). Can be the same as src.

transformPoint3D

public void transformPoint3D(float[] src,
                             float[] dest)
3D linear transformation - processes both Cartesian and homogeneous coordinate vectors.

Parameters:
src - Source coordinate vector ([x,y,z] or [x,y,z,w]).
dest - Destination coordinate vector ([x,y,z] or [x,y,z,w]). Can be the same as src.

transformPoint3D

public void transformPoint3D(double[] src,
                             int srcI,
                             int srcLen,
                             double[] dest,
                             int destI,
                             int destLen)
3D linear transformation - processes both Cartesian and homogeneous coordinate vectors. Source and destination coordinate vectors reside inside bigger double[] arrays.

Parameters:
src - Array holding source coordinate vector.
srcI - Origin of source coordinate vector.
srcLen - Length of source coordinate vector.
dest - Array holding destination coordinate vector. Can be the same as src (including srcI == destI).
destI - Origin of destination coordinate vector.
destLen - Length of destination coordinate vector.

transformPoint3D

public void transformPoint3D(float[] src,
                             int srcI,
                             int srcLen,
                             float[] dest,
                             int destI,
                             int destLen)
3D linear transformation - processes both Cartesian and homogeneous coordinate vectors. Source and destination coordinate vectors reside inside bigger float[] arrays.

Parameters:
src - Array holding source coordinate vector.
srcI - Origin of source coordinate vector.
srcLen - Length of source coordinate vector.
dest - Array holding destination coordinate vector. Can be the same as src (including srcI == destI).
destI - Origin of destination coordinate vector.
destLen - Length of destination coordinate vector.

transformVector3D

public void transformVector3D(double[] src,
                              double[] dest)
3D homomorphism - processes both Cartesian and homogeneous coordinate vectors.

Parameters:
src - Source coordinate vector ([x,y,z] or [x,y,z,w]).
dest - Destination coordinate vector ([x,y,z] or [x,y,z,w]). Can be the same as src.
See Also:
transformPoint3D(double[],double[])

translate3D

public void translate3D(double[] vector,
                        TrMatrix inv)
Appends the given translation to the actual transform matrix. Optionally updates the inverse matrix, too.

Parameters:
vector - Translation vector (double[3] or double[4]).
inv - Optional inverse matrix.

translate3D

public void translate3D(double tx,
                        double ty,
                        double tz,
                        TrMatrix inv)
Appends the given translation to the actual transform matrix. Optionally updates the inverse matrix, too.

Parameters:
tx - X-component of the translation vector.
ty - Y-component of the translation vector.
tz - Z-component of the translation vector.
inv - Optional inverse matrix.

rotateAxis3D

public void rotateAxis3D(int axis,
                         double sina,
                         double cosa,
                         TrMatrix inv)
Appends the given rotation to the actual transform matrix. Optionally updates the inverse matrix, too.

Parameters:
axis - Axis index (0 .. X, 1 .. Y, 2 .. Z).
sina - Sine of the rotation angle.
cosa - Cosine of the rotation angle.
inv - Optional inverse matrix.
See Also:
rotateAxis3D(int,double,TrMatrix), rotate3D(double[],double[],double,TrMatrix)

rotateAxis3D

public void rotateAxis3D(int axis,
                         double angle,
                         TrMatrix inv)
Appends the given rotation to the actual transform matrix. Optionally updates the inverse matrix, too.

Parameters:
axis - Axis index (0 .. X, 1 .. Y, 2 .. Z).
angle - Rotation angle in radians.
inv - Optional inverse matrix.
See Also:
rotateAxis3D(int,double,double,TrMatrix), rotate3D(double[],double[],double,TrMatrix)

rotate3D

public void rotate3D(double[] origin,
                     double[] direction,
                     double angle,
                     TrMatrix inv)
Append general rotation to the actual transform matrix. Optionally updates the inverse matrix, too.

Parameters:
origin - Origin of the axis.
direction - Directional vector of the axis.
angle - Rotation angle in radians.
inv - Optional inverse matrix.
See Also:
rotateAxis3D(int,double,TrMatrix), rotateAxis3D(int,double,double,TrMatrix)

moveToZAxis

public void moveToZAxis(double[] origin,
                        double[] direction,
                        TrMatrix inv)
Append the "move-to-z-axis" transform to the actual transform matrix. Optionally updates the inverse matrix, too.

Parameters:
origin - Origin of the vector.
direction - Directional vector.
inv - Optional inverse matrix.

scaleAxes3D

public void scaleAxes3D(double[] origin,
                        double sX,
                        double sY,
                        double sZ,
                        TrMatrix inv)
Append axes scale transform to the actual transform matrix. Optionally updates the inverse matrix, too.

Parameters:
origin - Scale origin or null for [0,0,0].
sX - Scale coefficient for X-axis.
sY - Scale coefficient for Y-axis.
sZ - Scale coefficient for Z-axis.
inv - Optional inverse matrix.
See Also:
scale3D(double[],double,TrMatrix), scale3D(double[],double[],double,double,TrMatrix), scaleAxes3D(double[],double[],TrMatrix)

scaleAxes3D

public void scaleAxes3D(double[] origin,
                        double[] scale,
                        TrMatrix inv)
Append axes scale transform to the actual transform matrix. Optionally updates the inverse matrix, too.

Parameters:
origin - Scale origin or null for [0,0,0].
scale - Non-uniform scale vector.
inv - Optional inverse matrix.
See Also:
scale3D(double[],double,TrMatrix), scale3D(double[],double[],double,double,TrMatrix), scaleAxes3D(double[],double,double,double,TrMatrix)

scale3D

public void scale3D(double[] origin,
                    double scale,
                    TrMatrix inv)
Append uniform scale transform to the actual transform matrix. Optionally updates the inverse matrix, too.

Parameters:
origin - Scale origin or null for [0,0,0].
scale - Uniform scale vector.
inv - Optional inverse matrix.
See Also:
scaleAxes3D(double[],double[],TrMatrix), scaleAxes3D(double[],double,double,double,TrMatrix), scale3D(double[],double[],double,double,TrMatrix)

scale3D

public void scale3D(double[] origin,
                    double[] direction,
                    double dirScale,
                    double perScale,
                    TrMatrix inv)
Append general scale to the actual transform matrix. Optionally updates the inverse matrix, too.

Parameters:
origin - Origin of scale.
direction - Directional vector to be scaled.
dirScale - Scale factor for the given direction.
perScale - Scale factor for perpendicular directions.
inv - Optional inverse matrix.
See Also:
scaleAxes3D(double[],double[],TrMatrix), scale3D(double[],double,TrMatrix)

toString

public java.lang.String toString()
Returns the actual matrix in readable format.

Overrides:
toString in class java.lang.Object

toArray

public double[] toArray(int wid,
                        int hei,
                        boolean rowMajor,
                        double[] result)
Converts the matrix into 1D array of doubles (with optional OpenGL order).


translate2D

public void translate2D(double[] vector,
                        TrMatrix inv)
Appends the given translation to the actual transform matrix. Optionally updates the inverse matrix, too.

Parameters:
vector - Translation vector (double[2] or double[3]).
inv - Optional inverse matrix.

rotateOrigin2D

public void rotateOrigin2D(double sina,
                           double cosa,
                           TrMatrix inv)
Appends the given rotation to the actual transform matrix. Optionally updates the inverse matrix, too.

Parameters:
sina - Sine of the rotation angle.
cosa - Cosine of the rotation angle.
inv - Optional inverse matrix.

lookAt

public void lookAt(double[] eye,
                   double[] center,
                   double[] up)
Computes viewing transformation matrix. Similar to glLookAt(). Accumulates the viewing transform into the current matrix (uses append(cz.cuni.jagrlib.TrMatrix)).

Parameters:
eye - Eye position in the world space.
center - Point at which the camera points.
up - The up-vector (will be transformed to vertical direction in the projection plane).

frustum

public void frustum(double left,
                    double right,
                    double bottom,
                    double top,
                    double near,
                    double far)
Computes perspective projection matrix. Similar to glFrustum(). Accumulates the viewing transform into the current matrix (uses append(cz.cuni.jagrlib.TrMatrix)).
Accepts far == Double.MAX_VALUE.


perspective

public void perspective(double fov,
                        double aspect,
                        double near,
                        double far)
Computes perspective projection matrix. Similar to gluPerspective(). Accumulates the viewing transform into the current matrix (uses append(cz.cuni.jagrlib.TrMatrix)).
Accepts far == Double.MAX_VALUE.

Parameters:
fov - Horizontal field-of-view angle in degrees.
aspect - Aspect ratio (width / height of the screen device).
near - Near Z-coordinate (must be positive).
far - Far Z-coordinate (must be greater than near, can be infinite == Double.MAX_VALUE).

perspectiveGL

public void perspectiveGL(double fov,
                          double aspect,
                          double near,
                          double far)
Computes perspective projection matrix. Accurate gluPerspective() code. Accumulates the viewing transform into the current matrix (uses append(cz.cuni.jagrlib.TrMatrix)).
Accepts far = Double.MAX_VALUE.

Parameters:
fov - Horizontal field-of-view angle in degrees.
aspect - Aspect ratio (width / height of the screen device).
near - Near Z-coordinate (must be positive).
far - Far Z-coordinate (must be greater than near, can be infinite == Double.MAX_VALUE).

ortho

public void ortho(double left,
                  double right,
                  double bottom,
                  double top,
                  double near,
                  double far)
Computes orthographic projection matrix. Similar to glOrtho(). Accumulates the viewing transform into the current matrix (uses append(cz.cuni.jagrlib.TrMatrix)).
Accepts far == Double.MAX_VALUE.


viewport

public void viewport(double x0,
                     double y0,
                     double width,
                     double height)
Computes final scaling 2D transform (viewport transform) mapping NDS (Normalized Device Space) into the given screen coordinate range. Similar to glViewport(). Accumulates the scaling transform into the current matrix (uses append(cz.cuni.jagrlib.TrMatrix)).

Z-coordinate (depth) is transformed into [ 0.0, 1.0 ] range, 0.0 corresponds to the far clipping plane.


main

public static void main(java.lang.String[] args)
Self-test.