com.kuka.math.geometry
Class Transformation

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

All Implemented Interfaces:

ITransformation

public final class Transformation
extends AbstractTransformation

An immutable representation of a spatial transformation.

A spatial transformation is used to describe a displacement of rigid bodies or coordinate systems in space. The displacement consists of a pure translation of the object along a line in space, plus a rotation of the object. In mathematics, a transformation is commonly identified by a homogeneous 4x4 transformation matrix, but different representations also exist. Common in robotics is the X-Y-Z-A-B-C representation, which defines one value for each of the six degrees of freedom for rigid objects in space.

A transformation only defines the relative displacement of one object or coordinate system to another. If you need to specify the location and orientation of an object with respect to a distinct location, you can use a Frame, which lets you construct a graph of objects in space.

This class is a suitable representation of a transformation for general purpose calculations. Internally it consists of matrix and x, y, z, α, β, γ representations of the same transformation. You can access those representations directly without having to convert the transformation into another representation via the different get...() or with...() functions.

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

To create an instance of this class, use one of the provided static constructor methods, for example:

Transformation trafo = Transformation.ofDeg(20, 0, -100, 90, 0, -90);

The identity transformation is available as preinitialized static constant IDENTITY.

You can do the following computations with a transformation:

• compose it with another transformation using compose(ITransformation)
• transform a point using AbstractTransformation.applyTo(Point3D)
• transform a vector using AbstractTransformation.applyTo(Vector3D)
• calculate the inverse with invert()

This type is immutable, which means that once you have created an instance of a transformation, that instance will never change. This makes it suitable to be shared between application modules, or between threads without the need for locking or synchronization. Use the provided with...() methods to create new instances of Transformation based on an existing instance.

You can convert a transformation from one form to another by using the static of(...) methods defined on each class.

If you need to make a large number of computations on transformations, consider using MatrixTransformation, which only performs the matrix operations without conversion to Euler angles.

See Also:

MatrixTransformation, XyzAbcTransformation, AbstractFrame

Field Summary

static Transformation

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

Method Summary

Transformation	compose(ITransformation other) If the transformations A and B are represented as homogeneous matrices, then the effect of A.compose(B) is that of the matrix multiplication A*B.
boolean	equals(Object obj)
double	getAlphaRad() Returns the α (alpha) angle of the rotation part of the transformation in [rad].
double	getBetaRad() Returns the β (beta) angle of the rotation part of the transformation in [rad].
double	getGammaRad() Returns the γ (gamma) angle of the rotation part of the transformation in [rad].
Rotation	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.
Vector3D	getUnitVectorX() Returns the x unit vector after it has been rotated by this rotation.
Vector3D	getUnitVectorY() Returns the y unit vector after it has been rotated by this rotation.
Vector3D	getUnitVectorZ() Returns the z unit vector after it has been rotated by this rotation.
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()
Transformation	invert() Returns an inverted transformation, i.e. a transformation that reverses the effect of this one.
static Transformation	of(double x, double y, double z) Returns an immutable Transformation instance, consisting of a translational part and no rotation.
static Transformation	of(IRotation rotation) Returns an immutable Transformation instance, consisting of a rotational part only.
static Transformation	of(ITransformation orig) Returns an immutable Transformation instance with the same value as the given transformation.
static Transformation	of(Vector3D translation) Returns an immutable Transformation instance, consisting of a translational part and no rotation.
static Transformation	of(Vector3D translation, IRotation rotation) Returns an immutable Transformation instance, consisting of a rotational and a translational part.
static Transformation	of(Vector3D translation, Matrix rotMatrix) Returns an immutable Transformation instance, consisting of a rotational and a translational part.
static Transformation	ofDeg(double alpha, double beta, double gamma) Returns an immutable Transformation instance, consisting of a rotational part only.
static Transformation	ofDeg(double x, double y, double z, double alpha, double beta, double gamma) Returns an immutable Transformation instance, consisting of a translational and a rotational part.
static Transformation	ofRad(double alpha, double beta, double gamma) Returns an immutable Transformation instance, consisting of a rotational part only.
static Transformation	ofRad(double x, double y, double z, double alpha, double beta, double gamma) Returns an immutable Transformation instance, consisting of a translational and a rotational part.
String	toString() Returns a textual description of the transformation.
String	toString(NumberFormat fmt) Returns a textual description of the transformation.
Transformation	transformationTo(ITransformation other) Calculates the transformation needed to move this transformation into the other transformation.
Transformation	withAlphaRad(double value) Returns a new instance (copy) of the transformation, with the α (alpha) angle replaced by the new value.
Transformation	withBetaRad(double value) Returns a new instance (copy) of the transformation, with the β (beta) angle replaced by the new value.
Transformation	withGammaRad(double value) Returns a new instance (copy) of the transformation, with the γ (gamma) angle replaced by the new value.
Transformation	withRotation(IRotation rotation) Returns a new instance (copy) of the transformation, with the rotational part replaced by the given rotation.
Transformation	withRotation(Matrix matrix) Returns a new instance (copy) of the transformation, with the rotational part replaced by the given rotation in matrix form.
Transformation	withRotationDeg(double alpha, double beta, double gamma) Returns a new instance (copy) of the transformation, with the rotational part set to the given Euler Z-Y-X angles α, β, γ in degrees.
Transformation	withRotationRad(double alpha, double beta, double gamma) Returns a new instance (copy) of the transformation, with the rotational part set to the given Euler Z-Y-X angles α, β, γ in radians.
Transformation	withTranslation(double x, double y, double z) Returns a new instance (copy) of the transformation, with the translational part replaced by the given three cartesian vector elements x, y, z.
Transformation	withTranslation(Vector3D translation) Returns a new instance (copy) of the transformation, with the translational part replaced by the given translation.
Transformation	withX(double value) Returns a new instance (copy) of this transformation where the x element of the translation part of the is replaced by the given value.
Transformation	withY(double value) Returns a new instance (copy) of this transformation where the y element of the translation part of the is replaced by the given value.
Transformation	withZ(double value) Returns a new instance (copy) of this transformation where the z element of the translation part of the is replaced by the given value.

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

applyTo, applyTo, distanceTo, rotationalDistanceTo

Methods inherited from class java.lang.Object

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

Field Detail

IDENTITY

public static final Transformation IDENTITY

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

Method Detail

ofRad

public static Transformation ofRad(double x,
                                   double y,
                                   double z,
                                   double alpha,
                                   double beta,
                                   double gamma)

Returns an immutable Transformation instance, consisting of a translational and a rotational part. The translation is given by the three cartesian vector elements x, y, z. The rotation is given by the three Euler Z-Y-X angles α, β, γ in [rad].

Parameters:

x - x element of translation

y - y element of translation

z - z element of translation

alpha - the α (alpha) angle of the rotation in [rad]. Note: This is the same as the angle A in KUKA notation.

beta - the β (beta) angle of the rotation in [rad]. Note: This is the same as the angle B in KUKA notation.

gamma - the γ (gamma) angle of the rotation in [rad]. Note: This is the same as the angle C in KUKA notation.

Returns:

an immutable Transformation instance

ofRad

public static Transformation ofRad(double alpha,
                                   double beta,
                                   double gamma)

Returns an immutable Transformation instance, consisting of a rotational part only. The rotation is given by the three Euler Z-Y-X angles α, β, γ in [rad].

Parameters:

alpha - the α (alpha) angle of the rotation in [rad]. Note: This is the same as the angle A in KUKA notation.

beta - the β (beta) angle of the rotation in [rad]. Note: This is the same as the angle B in KUKA notation.

gamma - the γ (gamma) angle of the rotation in [rad]. Note: This is the same as the angle C in KUKA notation.

Returns:

an immutable Transformation instance

ofDeg

public static Transformation ofDeg(double x,
                                   double y,
                                   double z,
                                   double alpha,
                                   double beta,
                                   double gamma)

Returns an immutable Transformation instance, consisting of a translational and a rotational part. The translation is given by the three cartesian vector elements x, y, z. The rotation is given by the three Euler Z-Y-X angles α, β, γ in degrees.

Parameters:

x - x element of translation

y - y element of translation

z - z element of translation

alpha - the α (alpha) angle of the rotation in degrees. Note: This is the same as the angle A in KUKA notation.

beta - the β (beta) angle of the rotation in degrees. Note: This is the same as the angle B in KUKA notation.

gamma - the γ (gamma) angle of the rotation in degrees. Note: This is the same as the angle C in KUKA notation.

Returns:

an immutable Transformation instance

ofDeg

public static Transformation ofDeg(double alpha,
                                   double beta,
                                   double gamma)

Returns an immutable Transformation instance, consisting of a rotational part only. The rotation is given by the three Euler Z-Y-X angles α, β, γ in degrees.

Parameters:

alpha - the α (alpha) angle of the rotation in degrees. Note: This is the same as the angle A in KUKA notation.

beta - the β (beta) angle of the rotation in degrees. Note: This is the same as the angle B in KUKA notation.

gamma - the γ (gamma) angle of the rotation in degrees. Note: This is the same as the angle C in KUKA notation.

Returns:

an immutable Transformation instance

of

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

Returns an immutable Transformation 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 Transformation instance

of

public static Transformation of(Vector3D translation)

Returns an immutable Transformation 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 Transformation instance

Throws:

IllegalArgumentException - if translation is null

of

public static Transformation of(IRotation rotation)

Returns an immutable Transformation instance, consisting of a rotational part only.

Parameters:

rotation - the rotational part of the transformation.

Returns:

an immutable Transformation instance

Throws:

IllegalArgumentException - if rotation or translation is null

of

public static Transformation of(Vector3D translation,
                                IRotation rotation)

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

Parameters:

translation - the translational part of the transformation.

rotation - the rotational part of the transformation.

Returns:

an immutable Transformation instance

Throws:

IllegalArgumentException - if rotation or translation is null

of

public static Transformation of(Vector3D translation,
                                Matrix rotMatrix)

Returns an immutable Transformation 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 Transformation instance

Throws:

IllegalArgumentException - if rotation or translation is null

of

public static Transformation of(ITransformation orig)

Returns an immutable Transformation 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 Transformation instance

Throws:

IllegalArgumentException - if orig is null

compose

public Transformation compose(ITransformation other)

Description copied from interface: ITransformation

If the transformations A and B are represented as homogeneous matrices, then the effect of A.compose(B) is that of the matrix multiplication A*B.

Specified by:

compose in interface ITransformation

Overrides:

compose in class AbstractTransformation

Parameters:

other - the transformation to combine with this one

Returns:

the combined transformation

invert

public Transformation 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.

transformationTo

public Transformation transformationTo(ITransformation other)

Description copied from interface: ITransformation

Calculates the transformation needed to move this transformation into the other transformation. The following holds true:

trafo1.compose(trafo1.rotationTo(trafo2)) is equal to trafo2

Specified by:

transformationTo in interface ITransformation

Overrides:

transformationTo in class AbstractTransformation

Parameters:

other - another transformation

Returns:

the difference transformation between this and the other transformation.

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

getAlphaRad

public double getAlphaRad()

Returns the α (alpha) angle of the rotation part of the transformation in [rad].

Note: This is the same as the angle A in KUKA notation.

Returns:

the α (alpha) angle of the rotation part of the transformation in [rad]

getBetaRad

public double getBetaRad()

Returns the β (beta) angle of the rotation part of the transformation in [rad].

Note: This is the same as the angle B in KUKA notation.

Returns:

the β (beta) angle of the rotation part of the transformation in [rad]

getGammaRad

public double getGammaRad()

Returns the γ (gamma) angle of the rotation part of the transformation in [rad].

Note: This is the same as the angle C in KUKA notation.

Returns:

the γ (gamma) angle of the rotation part of the transformation in [rad]

getUnitVectorX

public Vector3D getUnitVectorX()

Returns the x unit vector after it has been rotated by this rotation. The unit vectors returned by the corresponding methods of this rotation span a right-handed orthogonal rotated coordinate system.

Returns:

x unit vector after the rotation.

See Also:

getUnitVectorY(), getUnitVectorZ()

getUnitVectorY

public Vector3D getUnitVectorY()

Returns the y unit vector after it has been rotated by this rotation. The unit vectors returned by the corresponding methods of this rotation span a right-handed orthogonal rotated coordinate system.

Returns:

y unit vector after the rotation.

See Also:

getUnitVectorX(), getUnitVectorZ()

getUnitVectorZ

public Vector3D getUnitVectorZ()

Returns the z unit vector after it has been rotated by this rotation. The unit vectors returned by the corresponding methods of this rotation span a right-handed orthogonal rotated coordinate system.

Returns:

z unit vector after the rotation.

See Also:

getUnitVectorX(), getUnitVectorY()

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

getRotation

public Rotation 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

withX

public Transformation withX(double value)

Returns a new instance (copy) of this transformation where the x element of the translation part of the is replaced by the given value.

Parameters:

value - the x element of the translation part of the transformation

Returns:

a new instance of the class

withY

public Transformation withY(double value)

Returns a new instance (copy) of this transformation where the y element of the translation part of the is replaced by the given value.

Parameters:

value - the y element of the translation part of the transformation

Returns:

a new instance of the class

withZ

public Transformation withZ(double value)

Returns a new instance (copy) of this transformation where the z element of the translation part of the is replaced by the given value.

Parameters:

value - the z element of the translation part of the transformation

Returns:

a new instance of the class

withAlphaRad

public Transformation withAlphaRad(double value)

Returns a new instance (copy) of the transformation, with the α (alpha) angle replaced by the new value.

Parameters:

value - the α (alpha) angle of the transformation in [rad]. Note: This is the same as the angle A in KUKA notation.

Returns:

a new instance of the class

withBetaRad

public Transformation withBetaRad(double value)

Returns a new instance (copy) of the transformation, with the β (beta) angle replaced by the new value.

Parameters:

value - the β (beta) angle of the transformation in [rad]. Note: This is the same as the angle B in KUKA notation.

Returns:

a new instance of the class

withGammaRad

public Transformation withGammaRad(double value)

Returns a new instance (copy) of the transformation, with the γ (gamma) angle replaced by the new value.

Parameters:

value - the γ (gamma) angle of the transformation in [rad]. Note: This is the same as the angle C in KUKA notation.

Returns:

a new instance of the class

withRotation

public Transformation withRotation(IRotation rotation)

Description copied from class: AbstractTransformation

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

Overrides:

withRotation in class AbstractTransformation

Parameters:

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

Returns:

a new instance of the class

withRotationRad

public Transformation withRotationRad(double alpha,
                                      double beta,
                                      double gamma)

Returns a new instance (copy) of the transformation, with the rotational part set to the given Euler Z-Y-X angles α, β, γ in radians.

Parameters:

alpha - the α (alpha) angle of the rotation in [rad]. Note: This is the same as the angle A in KUKA notation.

beta - the β (beta) angle of the rotation in [rad]. Note: This is the same as the angle B in KUKA notation.

gamma - the γ (gamma) angle of the rotation in [rad]. Note: This is the same as the angle C in KUKA notation.

Returns:

a new instance of the class

withRotationDeg

public Transformation withRotationDeg(double alpha,
                                      double beta,
                                      double gamma)

Returns a new instance (copy) of the transformation, with the rotational part set to the given Euler Z-Y-X angles α, β, γ in degrees.

Parameters:

alpha - the α (alpha) angle of the rotation in [degrees]. Note: This is the same as the angle A in KUKA notation.

beta - the β (beta) angle of the rotation in [degrees]. Note: This is the same as the angle B in KUKA notation.

gamma - the γ (gamma) angle of the rotation in [degrees]. Note: This is the same as the angle C in KUKA notation.

Returns:

a new instance of the class

withRotation

public Transformation withRotation(Matrix matrix)

Returns a new instance (copy) of the transformation, with the rotational part replaced by the given rotation in matrix form.

Parameters:

matrix - 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:

a new instance of the class

Throws:

IllegalArgumentException - if the matrix is not a rotation matrix

withTranslation

public Transformation 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

withTranslation

public Transformation withTranslation(double x,
                                      double y,
                                      double z)

Returns a new instance (copy) of the transformation, with the translational part replaced by the given 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 new instance

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

toString

public String toString()

Returns a textual description of the transformation. The representation is subject to change.

This implementation will print all angle values in rad. The numerical values will be printed in the same format as defined in Double.toString(double). The following string can be regarded as typical:

[X=10.0 Y=-20.5 Z=3.0 A=0.0 B=1.5707963267948966 C=0.0]

Overrides:

toString in class AbstractTransformation

Returns:

a textual description of the transformation with angle values in rad

toString

public String toString(NumberFormat fmt)

Returns a textual description of the transformation. The representation is subject to change.

This implementation will print all angle values in rad. 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 Transformation trafo

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

might give the following output:

 [X=100.0 Y=-1.235 Z=3.0 A=-1.047 B=1.571 C=0.785]

Parameters:

fmt - the NumberFormat used to format the number values

Returns:

a textual description of the transformation with angle values in rad