com.tensegrity.generic.math
Class Transform2D

java.lang.Object
  com.tensegrity.generic.math.Transform2D

public final class Transform2D

extends java.lang.Object

The Transform2D class is responsible for implementing affine transformations http://en.wikipedia.org/wiki/Affine_transformation in 2-dimensional space. Affine transformations involve scaling, translating, rotating and sheering.

Any number of affine transformations can be accumulated into a single combined transformation and then applied to any number of coordinates with much lower cost than if all single transformations were applied separately. This is a common and practical scenario. For example, rotating a point P by an angle alpha around an axis of rotation that is not the center of the coordinate system can be achieved by the following sequence of affine transformations:

• Translating P by -Px and -Py so that it is at the origin of the coordinate system.
• Rotating the point around the origin by the angle alpha.
• Translating P by Px and Py so that it is at its original location.

Important properties of affine transformations include:

• Combining several affine transformations into a single transformation is done by concatenating the single transformations in reverse order.
• Transformations can be reversed. In order to find the inverse of a given transformation, invoke the invert() method on a Transform2D instance. The transformation will be inverted by bringing any previously transformed points back to their original positions.
• A matrix with a determinant of 0 is called singular matrix.
• Not all matrices can be inverted. Inversion is not possible if the matrix is singular.
• A matrix with a determinant of 1 or -1 is called orthogonal matrix.
• Transposing a square matrix is a simple process where the values of columns and rows get exchanged. (The matrix is flipped at its diagonal). The resulting matrix is called the transposed matrix.
• As you remember from your math lessons, the inverse of a square matrix is the same as the transposed matrix if and only if the matrix is orthogonal.
• In case you have a Transform2D that is orthogonal (for example it consists only of rotation transformation), you can invert it more efficiently by invoking the transpose() method.
• You can determine whether a Transform2D is orthogonal or not by evaluating the return value of method determinant().

All calculations made are based upon a Matrix33D instance. The main advantages of this class are the many overloaded apply methods offered.

Version:

$Id: Transform2D.java,v 1.45 2006/01/26 17:04:07 MichaelKegel Exp $

Author:

M.Kegel, S. Rutz

See Also:

Matrix33D

Constructor Summary

Transform2D()
Constructs a 2d transform and initializes this transform to the identity transform.

Transform2D(double v00, double v01, double v02, double v10, double v11, double v12)
Contructs an affine transform from only the 6 relevant parameters.

Transform2D(double v00, double v01, double v02, double v10, double v11, double v12, double v20, double v21, double v22)
Contructs an affine transform by means of all 9 parameters.

Transform2D(Matrix33D matrix)
Constructs by copying the values from a given matrix into this transform.

Transform2D(Transform2D transform)
Constructs by copying the values from another transform into this transform.

Method Summary

void	apply(double[] points) Applies this transform inplace to a number of points which are stored in an array of doubles.
void	apply(double[] in, double[] out) Applies this transform to a number of points which are stored in an array of doubles.
void	apply(float[] points) Applies this transform inplace to a number of points which are stored in an array of doubles.
void	apply(float[] in, float[] out) Applies this transform to a number of points which are stored in an array of doubles.
void	apply(int[] points) Applies this transform inplace to a number of points which are stored in an array of integers.
void	apply(int[] in, int[] out) Applies this transform to a number of points which are stored in an array of integers.
void	apply(Vector2 vector) Applies this transform in place to a vector2.
void	apply(Vector2 in, Vector2 out) Applies this transform to a Vector2.
void	apply2(double[] inOutX, double[] inOutY) Applies this transform inplace to a number of points whose X and Y coordinates are stored in two arrays.
void	apply2(double[] inX, double[] inY, double[] outX, double[] outY) Applies this transform to a number of points whose X and Y coordinates are stored in two arrays.
void	apply2(float[] inX, float[] inY) Applies this transform inplace to a number of points whose X and Y coordinates are stored in two arrays.
void	apply2(float[] inX, float[] inY, float[] outX, float[] outY) Applies this transform to a number of points whose X and Y coordinates are stored in two arrays.
void	apply2(int[] inX, int[] inY) Applies this transform inplace to a number of points whose X and Y coordinates are stored in two arrays.
void	apply2(int[] inX, int[] inY, int[] outX, int[] outY) Applies this transform to a number of points whose X and Y coordinates are stored in two arrays.
void	combine(Transform2D transform) Multiplies another transform onto this transform, thereby combined the affine transforms into an accumulated form.
static Transform2D	combine(Transform2D xform1, Transform2D xform2) Combines the two given transformations to one transformation.
static Transform2D	combineInverse(Transform2D xform1, Transform2D xform2) Combines the inverse transformations of the two given transformations to one transformation.
static Transform2D	createRotation(double angle) Conveniece method that creates a new rotation transform.
static Transform2D	createScale(double sx, double sy) Conveniece method that creates a new scaling transform.
static Transform2D	createTranslation(double dx, double dy) Conveniece method that creates a new translation transform.
double	determinant() Returns the determinant of the matrix of this transform.
boolean	equalsTransform(Transform2D transform) Returns true, if the two transforms contain the same elements (Object.equals wasn't overridden to prevent unexpected behavior)
Matrix33D	getMatrix33D() Returns the matrix 33d of this transform.
void	getSpecifiableMatrix(double[] flatmatrix) Retrieves the 6 specifiable values of the transformation.
void	invert() Inverts this transform.
void	rotate(double angle) Concatenates a rotation transform onto this transform
void	scale(double sx, double sy) Concatenates a scaling transform onto this transform
void	set(double v00, double v01, double v02, double v10, double v11, double v12) Sets an affine transform from only the 6 relevant parameters.
void	set(Matrix33D matrix) Sets this transform to the specified matrix.
void	set(Transform2D transform) Sets this transform to the specified transform.
void	setToIdentity() Sets this instance to the identity-transform.
void	setToRotation(double angle) Sets transform to rotation transform.
void	setToScale(double sx, double sy) Sets transform to a scaling transform.
void	setToTranslation(double dx, double dy) Sets transform to a translation transform.
java.lang.String	toString() Returns a string representation of this transform in flat matrix like structure.
java.lang.String	toStringMatrixLike(java.lang.String indent) Returns a string representation of this transform in matrix like structure.
void	translate(double tx, double ty) Concatenates a translation transform onto this transform
void	transpose() Transposes this transform.

Methods inherited from class java.lang.Object

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

Constructor Detail

Transform2D

public Transform2D()

Constructs a 2d transform and initializes this transform to the identity transform.

Transform2D

public Transform2D(Matrix33D matrix)

Constructs by copying the values from a given matrix into this transform.

Parameters:

matrix - the source-matrix to be copied.

Transform2D

public Transform2D(Transform2D transform)

Constructs by copying the values from another transform into this transform.

Parameters:

transform - the source-transform to be copied.

Transform2D

public Transform2D(double v00,
                   double v01,
                   double v02,
                   double v10,
                   double v11,
                   double v12,
                   double v20,
                   double v21,
                   double v22)

Contructs an affine transform by means of all 9 parameters.

Parameters:

v00 - value for row 0, column 0

v01 - value for row 0, column 1

v02 - value for row 0, column 2

v10 - value for row 1, column 0

v11 - value for row 1, column 1

v12 - value for row 1, column 2

v20 - value for row 2, column 0

v21 - value for row 2, column 1

v22 - value for row 2, column 2

Transform2D

public Transform2D(double v00,
                   double v01,
                   double v02,
                   double v10,
                   double v11,
                   double v12)

Contructs an affine transform from only the 6 relevant parameters. The last row of the transform is set to the identity matrix values.

Parameters:

v00 - value for row 0, column 0

v01 - value for row 0, column 1

v02 - value for row 0, column 2

v10 - value for row 1, column 0

v11 - value for row 1, column 1

v12 - value for row 1, column 2

Method Detail

set

public final void set(double v00,
                      double v01,
                      double v02,
                      double v10,
                      double v11,
                      double v12)

Sets an affine transform from only the 6 relevant parameters. The last row of the transform is set to the identity matrix values.

Parameters:

v00 - value for row 0, column 0

v01 - value for row 0, column 1

v02 - value for row 0, column 2

v10 - value for row 1, column 0

v11 - value for row 1, column 1

v12 - value for row 1, column 2

set

public final void set(Matrix33D matrix)

Sets this transform to the specified matrix.

Parameters:

matrix - the matrix to set this transform to.

getSpecifiableMatrix

public final void getSpecifiableMatrix(double[] flatmatrix)

Retrieves the 6 specifiable values of the transformation. The values are stored in the array as { m00 m01 m02 m10 m11 m12 }.

Parameters:

flatmatrix - the double array used to store the returned values.

set

public final void set(Transform2D transform)

Sets this transform to the specified transform.

Parameters:

transform - the transform to copy into this instance.

setToIdentity

public final void setToIdentity()

Sets this instance to the identity-transform.

setToTranslation

public final void setToTranslation(double dx,
                                   double dy)

Sets transform to a translation transform.

Parameters:

dx - translation in direction.

dy - translation in y direction.

setToScale

public final void setToScale(double sx,
                             double sy)

Sets transform to a scaling transform.

Parameters:

sx - scaling in x direction.

sy - scaling in y direction.

setToRotation

public final void setToRotation(double angle)

Sets transform to rotation transform.

Parameters:

angle - rotation in degrees in counter clockwise direction.

translate

public final void translate(double tx,
                            double ty)

Concatenates a translation transform onto this transform

Parameters:

tx - translation in direction.

ty - translation in y direction.

scale

public final void scale(double sx,
                        double sy)

Concatenates a scaling transform onto this transform

Parameters:

sx - scaling in x direction.

sy - scaling in y direction.

rotate

public final void rotate(double angle)

Concatenates a rotation transform onto this transform

Parameters:

angle - rotation in degrees in counter clockwise direction.

combine

public final void combine(Transform2D transform)

Multiplies another transform onto this transform, thereby combined the affine transforms into an accumulated form.

Parameters:

transform - the transform to combine with this one.

determinant

public final double determinant()

Returns the determinant of the matrix of this transform.

Returns:

the determinant of the matrix of this transform.

invert

public final void invert()
                  throws MathException

Inverts this transform.

Throws:

MathException - thrown if this transform is not invertible.

transpose

public final void transpose()

Transposes this transform.

apply

public final void apply(int[] in,
                        int[] out)

Applies this transform to a number of points which are stored in an array of integers. The results are computed with double precision floating point arithmetics and then rounded to fit into integer coordinates.

Parameters:

in - the array of points to transform, where x-coordinates are stored at even positions and y-coordinates are stored at odd positions.

out - the array in which to store the transformed points.

apply

public final void apply(int[] points)

Applies this transform inplace to a number of points which are stored in an array of integers.

Parameters:

points - the array of points to transform, where x coordinates are stored at even positions and y coordinates are stored at odd positions.

apply

public final void apply(float[] in,
                        float[] out)

Applies this transform to a number of points which are stored in an array of doubles.

Parameters:

in - the array of points to transform, where x coordinates are stored at even positions and y coordinates are stored at odd positions.

out - the array where to store the transformed points.

apply

public final void apply(float[] points)

Applies this transform inplace to a number of points which are stored in an array of doubles.

Parameters:

points - the array of points to transform, where x coordinates are stored at even positions and y coordinates are stored at odd positions.

apply

public final void apply(double[] in,
                        double[] out)

Applies this transform to a number of points which are stored in an array of doubles.

Parameters:

in - the array of points to transform, where x coordinates are stored at even positions and y coordinates are stored at odd positions.

out - the array where to store the transformed points.

apply

public final void apply(double[] points)

Applies this transform inplace to a number of points which are stored in an array of doubles.

Parameters:

points - the array of points to transform, where x coordinates are stored at even positions and y coordinates are stored at odd positions.

apply2

public final void apply2(int[] inX,
                         int[] inY,
                         int[] outX,
                         int[] outY)

Applies this transform to a number of points whose X and Y coordinates are stored in two arrays. The results are computed with double precision floating point arithmetics and then rounded to fit into integer coordinates.

Parameters:

inX - the array of X coordinates of the points to transform.

inY - the array of Y coordinates of the points to transform.

outX - the array where to store the transformed X coordinates.

outY - the array where to store the transformed Y coordinates.

apply2

public final void apply2(int[] inX,
                         int[] inY)

Applies this transform inplace to a number of points whose X and Y coordinates are stored in two arrays.

Parameters:

inX - the array of X coordinates of the points to transform.

inY - the array of Y coordinates of the points to transform.

apply2

public final void apply2(float[] inX,
                         float[] inY,
                         float[] outX,
                         float[] outY)

Applies this transform to a number of points whose X and Y coordinates are stored in two arrays.

Parameters:

inX - the array of X coordinates of the points to transform.

inY - the array of Y coordinates of the points to transform.

outX - the array where to store the transformed X coordinates.

outY - the array where to store the transformed Y coordinates.

apply2

public final void apply2(float[] inX,
                         float[] inY)

Applies this transform inplace to a number of points whose X and Y coordinates are stored in two arrays.

Parameters:

inX - the array of X coordinates of the points to transform.

inY - the array of Y coordinates of the points to transform.

apply2

public final void apply2(double[] inX,
                         double[] inY,
                         double[] outX,
                         double[] outY)

Applies this transform to a number of points whose X and Y coordinates are stored in two arrays.

Parameters:

inX - the array of X coordinates of the points to transform.

inY - the array of Y coordinates of the points to transform.

outX - the array where to store the transformed X coordinates.

outY - the array where to store the transformed Y coordinates.

apply2

public final void apply2(double[] inOutX,
                         double[] inOutY)

Applies this transform inplace to a number of points whose X and Y coordinates are stored in two arrays.

Parameters:

inOutX - the array of X coordinates of the points to transform.

inOutY - the array of Y coordinates of the points to transform.

apply

public final void apply(Vector2 in,
                        Vector2 out)

Applies this transform to a Vector2.

Parameters:

in - the source Vector2.

out - the target Vector2.

apply

public final void apply(Vector2 vector)

Applies this transform in place to a vector2.

Parameters:

vector - the Vector2.

createTranslation

public static final Transform2D createTranslation(double dx,
                                                  double dy)

Conveniece method that creates a new translation transform.

Parameters:

dx - translation in direction.

dy - translation in y direction.

Returns:

the newly created translation transform

createScale

public static final Transform2D createScale(double sx,
                                            double sy)

Conveniece method that creates a new scaling transform.

Parameters:

sx - scaling in x direction.

sy - scaling in y direction.

Returns:

the newly created scaling transform

createRotation

public static final Transform2D createRotation(double angle)

Conveniece method that creates a new rotation transform.

Parameters:

angle - rotation in degrees in counter clockwise direction.

Returns:

the newly created rotation transform

combine

public static Transform2D combine(Transform2D xform1,
                                  Transform2D xform2)

Combines the two given transformations to one transformation. The two given transformations are not changed. It returns
- a new Transform2D instance if both given transformations are not null
- the first transformation if only the second transformation is null
- the second transformation if only the first transformation is null
- null if both transformations are null

Parameters:

xform1 - the first transform

xform2 - the second transform

Returns:

Transform2D the combined transform

combineInverse

public static Transform2D combineInverse(Transform2D xform1,
                                         Transform2D xform2)
                                  throws MathException

Combines the inverse transformations of the two given transformations to one transformation. The two given transformations are not changed. It returns
- a new Transform2D instance if both given transformations are not null
- the inverse of the first transformation if only the second transformation is null
- the inverse of the second transformation if only the first transformation is null
- null if both transformations are null

Parameters:

xform1 - the first transform

xform2 - the second transform

Returns:

Transform2D the combined transform of the inverted given transforms

Throws:

MathException - thrown if this transform is not invertible.

getMatrix33D

public Matrix33D getMatrix33D()

Returns the matrix 33d of this transform.

Returns:

the matrix 33d of this transform.

equalsTransform

public boolean equalsTransform(Transform2D transform)

Returns true, if the two transforms contain the same elements (Object.equals wasn't overridden to prevent unexpected behavior)

Parameters:

transform - the Transform2D to check

Returns:

boolean if both are inhabited with the same values.

toString

public java.lang.String toString()

Returns a string representation of this transform in flat matrix like structure.

Returns:

a string representation of this transform.

toStringMatrixLike

public java.lang.String toStringMatrixLike(java.lang.String indent)

Returns a string representation of this transform in matrix like structure.

Parameters:

indent - optional indent for the matrix like representation

Returns:

a string representation of this object.