com.kuka.math.geometry
Class MatrixTransformation

java.lang.Object
  com.kuka.math.geometry.AbstractTransformation
      com.kuka.math.geometry.MatrixTransformation

All Implemented Interfaces:

ITransformation

public final class MatrixTransformation
extends AbstractTransformation

Immutable implementation of a spatial transformation in matrix form, that is the rotation part and the vector part of the homogeneous transformation matrix.

The Robotics API always assumes the translation part to be given in [mm].

Field Summary

static MatrixTransformation

IDENTITY Immutable MatrixTransformation instance representing identity (i.e. unchanging) transformation.

Method Summary

MatrixTransformation	compose(MatrixTransformation other) The effect of A.compose(B) is that of the matrix multiplication A*B.
boolean	equals(Object obj)
void	fillRowFirstArray(double[] elements) Fills a "RowFirst" representation (double[3,4]) Array "Frame34" - represented as 12 element vector.
MatrixRotation	getRotation() Returns the rotation corresponding to this transformation.
Matrix	getRotationMatrix() Returns the rotational part of the transformation as a 3x3 matrix.
Vector3D	getTranslation() Returns the translation part of the transformation, i.e. the upper-right 3x1 part of the corresponding homogeneous transformation matrix.
double	getX() Returns the x element of the translation part of the transformation.
double	getY() Returns the y element of the translation part of the transformation.
double	getZ() Returns the z element of the translation part of the transformation.
int	hashCode()
MatrixTransformation	invert() Returns an inverted transformation, i.e. a transformation that reverses the effect of this one.
static MatrixTransformation	of(double x, double y, double z) Returns an immutable MatrixTransformation instance, consisting of a translational part and no rotation.
static MatrixTransformation	of(ITransformation orig) Returns an immutable MatrixTransformation instance with the same value as the given transformation.
static MatrixTransformation	of(Vector3D translation) Returns an immutable MatrixTransformation instance, consisting of a translational part and no rotation.
static MatrixTransformation	of(Vector3D translation, IRotation rot) Returns an immutable MatrixTransformation instance, consisting of a rotational and a translational part.
static MatrixTransformation	of(Vector3D translation, Matrix rotMatrix) Returns an immutable MatrixTransformation instance, consisting of a rotational and a translational part.
static MatrixTransformation	ofRowFirst(double... elements) Creates a Matrix Transform based on a "row first" matrix 3x4 -> 12 Elements...
double[]	toRowFirstArray() Serialization Support Serialize the MatrixTransform to a linear 12 Vector to support "rowFirstArray" (double[3][4]) Frame34 representations.
String	toString() Returns the transformation value as a homogeneous 4x4 matrix formatted in a way compatible with popular scientific numerical computing applications.
String	toString(NumberFormat fmt) Returns the transformation value as a homogeneous 4x4 matrix formatted in a way similar to popular scientific numerical computing applications.
MatrixTransformation	withRotation(Matrix rotMatrix) Returns an immutable MatrixTransformation instance, consisting of a rotational and a translational part.
MatrixTransformation	withRotation(MatrixRotation rotation) Returns an immutable MatrixTransformation instance, consisting of a rotational and a translational part.
MatrixTransformation	withTranslation(Vector3D translation) Returns a new instance (copy) of the transformation, with the translational part replaced by the given translation.

Methods inherited from class com.kuka.math.geometry.AbstractTransformation

applyTo, applyTo, compose, distanceTo, rotationalDistanceTo, transformationTo, withRotation

Methods inherited from class java.lang.Object

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

Field Detail

IDENTITY

public static final MatrixTransformation IDENTITY

Immutable MatrixTransformation instance representing identity (i.e. unchanging) transformation.

Method Detail

of

public static MatrixTransformation of(Vector3D translation,
                                      Matrix rotMatrix)

Returns an immutable MatrixTransformation instance, consisting of a rotational and a translational part.

Parameters:

translation - the translational part of the transformation (the upper-right 3x1 part of a homogeneous transformation matrix).

rotMatrix - the rotational part of the transformation (the upper-left 3x3 part of a homogeneous transformation matrix).

The matrix must be a rotation matrix, i.e. it must fulfill the following conditions:

equal(matrix.determinant(), 1, epsilon);
equal(matrix.transpose(), matrix.invert(), epsilon);

where equal(a, b, epsilon) is an element-wise test of approximate equality (small epsilon test). The epsilon used is 1e-3.

Returns:

an immutable MatrixTransformation instance

of

public static MatrixTransformation of(Vector3D translation,
                                      IRotation rot)

Returns an immutable MatrixTransformation instance, consisting of a rotational and a translational part.

Parameters:

translation - the translational part of the transformation (the upper-right 3x1 part of a homogeneous transformation matrix).

rot - the rotational part of the transformation (the upper-left 3x3 part of a homogeneous transformation matrix).

Returns:

an immutable MatrixTransformation instance

of

public static MatrixTransformation of(Vector3D translation)

Returns an immutable MatrixTransformation instance, consisting of a translational part and no rotation.

Parameters:

translation - the translational part of the transformation (the upper-right 3x1 part of a homogeneous transformation matrix).

Returns:

an immutable MatrixTransformation instance

of

public static MatrixTransformation of(double x,
                                      double y,
                                      double z)

Returns an immutable MatrixTransformation instance, consisting of a translational part and no rotation. The translation is given by the three cartesian vector elements x, y, z.

Parameters:

x - x element of translation

y - y element of translation

z - z element of translation

Returns:

an immutable MatrixTransformation instance

of

public static MatrixTransformation of(ITransformation orig)

Returns an immutable MatrixTransformation instance with the same value as the given transformation. If the given transformation already is of a known immutable type then it is returned unchanged.

Parameters:

orig - The transformation whose value should be taken over.

Returns:

an immutable MatrixTransformation instance

Throws:

IllegalArgumentException - if orig is null

getRotation

public MatrixRotation getRotation()

Description copied from interface: ITransformation

Returns the rotation corresponding to this transformation.

Specified by:

getRotation in interface ITransformation

Specified by:

getRotation in class AbstractTransformation

Returns:

the rotation part of the transformation

getTranslation

public Vector3D getTranslation()

Description copied from interface: ITransformation

Returns the translation part of the transformation, i.e. the upper-right 3x1 part of the corresponding homogeneous transformation matrix.

Specified by:

getTranslation in interface ITransformation

Specified by:

getTranslation in class AbstractTransformation

Returns:

the translation part of the transformation

withRotation

public MatrixTransformation withRotation(Matrix rotMatrix)

Returns an immutable MatrixTransformation instance, consisting of a rotational and a translational part.

Parameters:

rotMatrix - the rotational part of the transformation (the upper-left 3x3 part of a homogeneous transformation matrix).

The matrix must be a rotation matrix, i.e. it must fulfill the following conditions:

equal(matrix.determinant(), 1, epsilon);
equal(matrix.transpose(), matrix.invert(), epsilon);

where equal(a, b, epsilon) is an element-wise test of approximate equality (small epsilon test). The epsilon used is 1e-3.

Returns:

an immutable MatrixTransformation instance

withRotation

public MatrixTransformation withRotation(MatrixRotation rotation)

Returns an immutable MatrixTransformation instance, consisting of a rotational and a translational part.

Parameters:

rotation - the rotational part of the transformation (the upper-left 3x3 part of a homogeneous transformation matrix).

Returns:

an immutable MatrixTransformation instance

withTranslation

public MatrixTransformation withTranslation(Vector3D translation)

Description copied from class: AbstractTransformation

Returns a new instance (copy) of the transformation, with the translational part replaced by the given translation.

Overrides:

withTranslation in class AbstractTransformation

Parameters:

translation - the translational part of the transformation (the upper-right 3x1 part of a homogeneous transformation matrix).

Returns:

a new instance of the class

getX

public double getX()

Returns the x element of the translation part of the transformation.

Returns:

the x element of the translation part of the transformation

getY

public double getY()

Returns the y element of the translation part of the transformation.

Returns:

the y element of the translation part of the transformation

getZ

public double getZ()

Returns the z element of the translation part of the transformation.

Returns:

the z element of the translation part of the transformation

getRotationMatrix

public Matrix getRotationMatrix()

Returns the rotational part of the transformation as a 3x3 matrix.

Returns:

the rotational part of the transformation as a 3x3 matrix

compose

public MatrixTransformation compose(MatrixTransformation other)

The effect of A.compose(B) is that of the matrix multiplication A*B.

Parameters:

other - the transformation to combine with this one

Returns:

the combined matrix transformation

invert

public MatrixTransformation invert()

Description copied from interface: ITransformation

Returns an inverted transformation, i.e. a transformation that reverses the effect of this one.

Specified by:

invert in interface ITransformation

Overrides:

invert in class AbstractTransformation

Returns:

the inverted transformation.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

ofRowFirst

public static MatrixTransformation ofRowFirst(double... elements)

Creates a Matrix Transform based on a "row first" matrix 3x4 -> 12 Elements... Serialization Support Serialize the MatrixTransform from a linear 12 Vector to support Frame34 Represenations

Parameters:

elements - a double Array (row major) with exactly 12 Elements of the sequence: [rot00, rot01, rot02, transX, rot10, rot11, rot12, transY, rot20,rot21,rot22,transZ]

Note: Elements of the rotational part (the upper-left 3x3 part of a homogeneous transformation matrix) represent a rotational matrix, which must fulfill the following conditions:

equal(matrix.determinant(), 1, epsilon);
equal(matrix.transpose(), matrix.invert(), epsilon);

where equal(a, b, epsilon) is an element-wise test of approximate equality (small epsilon test). The epsilon used is 1e-3.

Returns:

a new Instance of the MatrixTransformation.

toRowFirstArray

public double[] toRowFirstArray()

Serialization Support Serialize the MatrixTransform to a linear 12 Vector to support "rowFirstArray" (double[3][4]) Frame34 representations.

Returns:

newly created 12 Element Vector (to support a row-first 3x4 Array). The sequence of the elements is [rot00, rot01, rot02, transX, rot10, rot11, rot12, transY, rot20,rot21,rot22,transZ].

fillRowFirstArray

public void fillRowFirstArray(double[] elements)

Fills a "RowFirst" representation (double[3,4]) Array "Frame34" - represented as 12 element vector. In contrast to @see toRowFirstArray(), the memory of the "elements" vector is already considered to be existent and of the length 12.

Parameters:

elements - - a double vector with exactly 12 Elements It will be filled with the elements of the transformation in the following sequence: [rot00, rot01, rot02, transX, rot10, rot11, rot12, transY, rot20,rot21,rot22,transZ]

toString

public String toString()

Returns the transformation value as a homogeneous 4x4 matrix formatted in a way compatible with popular scientific numerical computing applications. The matrix values will be printed in row-first order. The numerical values will be printed with the default format as returned by MathUtils.getDefaultNumberFormat().

The following string can be regarded as typical:

[[0.0 0.0 -1.0 10.0]; [0.0 -1.0 0.0 20.0]; [-1.0 0.0 0.0 30.0]; [0.0 0.0 0.0 1.0]]

Overrides:

toString in class AbstractTransformation

Returns:

a textual representation of the matrix as a 4x4 matrix

toString

public String toString(NumberFormat fmt)

Returns the transformation value as a homogeneous 4x4 matrix formatted in a way similar to popular scientific numerical computing applications. The matrix values will be printed in row-first order. The numerical values will be printed using the NumberFormat.format(double) method of the given formatter.

Example: The following code snippet, used on a given MatrixTransformation trafo

 NumberFormat fmt = NumberFormat.getNumberInstance(Locale.US);
 fmt.setMinimumFractionDigits(1);
 fmt.setMaximumFractionDigits(3);
 System.out.println(trafo.toString(fmt));

might give the following output:

 [[0.707 -0.707 0.0 10.0]; [0.707 0.707 0.0 -10.0]; [0.0 0.0 1.0 50.0]; [0.0 0.0 0.0 1.0]]

Parameters:

fmt - the NumberFormat used to format the number values

Returns:

a textual representation of the matrix as a 4x4 matrix