com.kuka.math.geometry
Class Rotation

java.lang.Object
  com.kuka.math.geometry.AbstractRotation
      com.kuka.math.geometry.Rotation

All Implemented Interfaces:

IRotation

public final class Rotation
extends AbstractRotation

Immutable representation of a spatial rotation as Z-Y-X Euler angles and/or 3x3 rotation matrix.

Note: The angles α (alpha), β (beta), γ (gamma) are the same as the angles A, B, C in KUKA notation, respectively.

Field Summary

static Rotation

NONE Immutable Rotation instance representing no rotation.

Method Summary

Rotation	compose(IRotation other) If the rotations A and B are represented as matrices, then the effect of A.compose(B) is corresponding to the matrix multiplication A*B.
boolean	equals(Object obj)
double	getAlphaRad() Returns the α (alpha) angle of the rotation in [rad].
double	getBetaRad() Returns the β (beta) angle of the rotation in [rad].
double	getGammaRad() Returns the γ (gamma) angle of the rotation in [rad].
Matrix	getMatrix() Returns a matrix representing this rotation.
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.
int	hashCode()
Rotation	invert() Returns an inverted rotation, i.e. a rotation that reverses the effect of this one.
static Rotation	of(IRotation orig) Returns an immutable Rotation instance from the values of the provided rotation.
static Rotation	of(Matrix matrix) Checked creation of a Rotation from a given rotation matrix.
static Rotation	ofDeg(double alpha, double beta, double gamma) Returns an immutable Rotation instance with the given angle values.
static Rotation	ofRad(double alpha, double beta, double gamma) Returns an immutable Rotation instance with the given angle values.
static Rotation	ofUnchecked(Matrix matrix) Unchecked creation of a Rotation from a given rotation matrix.
Rotation	rotationTo(IRotation other) Calculates the rotation needed to turn this rotation into the other rotation.
String	toString() Returns a textual description of the rotation.
String	toString(NumberFormat fmt) Returns a textual description of the rotation.
Rotation	withAlphaRad(double value) Returns a new instance (copy) of the rotation, with the α (alpha) angle replaced by the new value.
Rotation	withBetaRad(double value) Returns a new instance (copy) of the rotation, with the β (beta) angle replaced by the new value.
Rotation	withGammaRad(double value) Returns a new instance (copy) of the rotation, with the γ (gamma) angle replaced by the new value.

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

applyTo, applyTo, rotationalDistanceTo

Methods inherited from class java.lang.Object

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

Field Detail

NONE

public static final Rotation NONE

Immutable Rotation instance representing no rotation.

Method Detail

ofRad

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

Returns an immutable Rotation instance with the given angle values.

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 rotation instance

ofDeg

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

Returns an immutable Rotation instance with the given angle values.

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 rotation instance

of

public static Rotation of(Matrix matrix)

Checked creation of a Rotation from a given rotation 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.

The above conditions will be checked upon creation of the rotation.

Parameters:

matrix - a rotation matrix. Will be checked.

Returns:

the rotation instance

Throws:

IllegalArgumentException - if the matrix is null or not a rotation matrix

ofUnchecked

public static Rotation ofUnchecked(Matrix matrix)

Unchecked creation of a Rotation from a given rotation 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).

Caution: Don't use this method unless you are absolutely sure that the matrix is a valid rotation matrix! If in doubt, use of(Matrix).

Parameters:

matrix - a rotation matrix. Will be checked if (and only if) assertions are enabled in the VM.

Returns:

the instance

Throws:

IllegalArgumentException - if matrix is null

of

public static Rotation of(IRotation orig)

Returns an immutable Rotation instance from the values of the provided rotation.

Parameters:

orig - the instance from which to take over the rotation

Returns:

an immutable rotation instance

Throws:

IllegalArgumentException - if orig is null

getMatrix

public Matrix getMatrix()

Description copied from interface: IRotation

Returns a matrix representing this rotation. This is potentially a costly conversion.

Specified by:

getMatrix in interface IRotation

Specified by:

getMatrix in class AbstractRotation

Returns:

a Matrix representing this rotation. This is potentially a costly conversion

compose

public Rotation compose(IRotation other)

Description copied from interface: IRotation

If the rotations A and B are represented as matrices, then the effect of A.compose(B) is corresponding to the matrix multiplication A*B.

Specified by:

compose in interface IRotation

Overrides:

compose in class AbstractRotation

Parameters:

other - the rotation to combine with this one

Returns:

the combined rotation

invert

public Rotation invert()

Description copied from interface: IRotation

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

Specified by:

invert in interface IRotation

Overrides:

invert in class AbstractRotation

Returns:

the inverted rotation.

rotationTo

public Rotation rotationTo(IRotation other)

Description copied from interface: IRotation

Calculates the rotation needed to turn this rotation into the other rotation. The following holds true:

rot1.compose(rot1.rotationTo(rot2)) is equal to rot2

Specified by:

rotationTo in interface IRotation

Overrides:

rotationTo in class AbstractRotation

Parameters:

other - another rotation

Returns:

the difference rotation between this and the other rotation.

getAlphaRad

public double getAlphaRad()

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

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

Returns:

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

getBetaRad

public double getBetaRad()

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

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

Returns:

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

getGammaRad

public double getGammaRad()

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

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

Returns:

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

withAlphaRad

public Rotation withAlphaRad(double value)

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

Parameters:

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

Returns:

a new instance of the class

withBetaRad

public Rotation withBetaRad(double value)

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

Parameters:

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

Returns:

a new instance of the class

withGammaRad

public Rotation withGammaRad(double value)

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

Parameters:

value - 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

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()

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 rotation. 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:

[A=0.0 B=3.141592653589793 C=0.0]

Overrides:

toString in class AbstractRotation

Returns:

a textual description of the rotation with angle values in rad

toString

public String toString(NumberFormat fmt)

Returns a textual description of the rotation. 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 Rotation rot

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

might give the following output:

 [A=1.235 B=3.142 C=0.0]

Parameters:

fmt - the NumberFormat used to format the number values

Returns:

a textual description of the rotation with angle values in rad