org.spaceroots.mantissa.geometry

Class Rotation

java.lang.Object

org.spaceroots.mantissa.geometry.Rotation

All Implemented Interfaces:

java.io.Serializable

public class Rotation
extends java.lang.Object
implements java.io.Serializable

This class implements rotations in a three-dimensional space.

Rotations can be represented by several different mathematical entities (matrices, axe and angle, Cardan or Euler angles, quaternions). This class is an higher level abstraction, more user-oriented and hiding this implementation details. Well, for the curious, we use quaternions for the internal representation. The user can build a rotation from any of these representations, and any of these representations can be retrieved from a Rotation instance (see the various constructors and getters). In addition, a rotation can also be built implicitely from a set of vectors before and after it has been applied. This means that this class can be used to convert from one representation to another one. For example, extracting a set of Cardan angles from a rotation matrix can be done using one single line of code:

 double[] angles = new Rotation(matrix, 1.0e-10).getAngles(RotationOrder.XYZ);
 

Focus is more oriented on what a rotation do. Once it has been built, and regardless of its representation, a rotation is an operator which basically transforms three dimensional vectors into other three dimensional vectors. Depending on the application, the meaning of these vectors can vary. For example in an attitude simulation tool, you will often consider the vector is fixed and you transform its coordinates in one frame into its coordinates in another frame. In this case, the rotation implicitely defines the relation between the two frames. Another example could be a telescope control application, where the rotation would transform the sighting direction at rest into the desired observing direction. In this case the frame is the same (probably a topocentric one) and the raw and transformed vectors are different. In many case, both approaches will be combined, in our telescope example, we will probably also need to transform the observing direction in the topocentric frame into the observing direction in inertial frame taking into account the observatory location and the earth rotation.

These examples show that a rotation is what the user wants it to be, so this class does not push the user towards one specific definition. Hence the class does not provide methods like projectVectorIntoDestinationFrame or computeTransformedDirection. It provides simpler and more generic methods: applyTo(Vector3D) and applyInverseTo(Vector3D).

Since a rotation is basically a vectorial operator, several rotations can be composed together to produce new rotations. The composition operation r = r1 o r2 means that for each vector u, r(u) = r1(r2(u)). Hence we can consider that in addition to vectors, a rotation can be applied to other rotations (or to itself). With our previous notations, we would say we can apply r1 to r2 and the result we get is r = r1 o r2. For this purpose, the class provides the methods: applyTo(Rotation) and applyInverseTo(Rotation).

Instances of this class are guaranteed to be immutable.

See Also:

Vector3D, RotationOrder, Serialized Form

Constructor Summary

Constructors

Constructor and Description
Rotation() Build the identity rotation.
Rotation(double[][] m, double threshold) Build a rotation from a 3X3 matrix.
Rotation(double q0, double q1, double q2, double q3) Deprecated. since Mantissa 6.3, this method as been deprecated as it does not properly handles non-normalized quaternions, it should be replaced by Rotation(double, double, double, double, boolean)
Rotation(double q0, double q1, double q2, double q3, boolean needsNormalization) Build a rotation from the quaternion coordinates.
Rotation(RotationOrder order, double alpha1, double alpha2, double alpha3) Build a rotation from three Cardan or Euler elementary rotations.
Rotation(Vector3D axis, double angle) Build a rotation from an axis and an angle.
Rotation(Vector3D u, Vector3D v) Build one of the rotations that transform one vector into another one.
Rotation(Vector3D u1, Vector3D u2, Vector3D v1, Vector3D v2) Build the rotation that transforms a pair of vector into another pair.

Method Summary

Modifier and Type	Method and Description
Rotation	applyInverseTo(Rotation r) Apply the inverse of the instance to another rotation.
Vector3D	applyInverseTo(Vector3D u) Apply the inverse of the rotation to a vector.
Rotation	applyTo(Rotation r) Apply the instance to another rotation.
Vector3D	applyTo(Vector3D u) Apply the rotation to a vector.
double	getAngle() Get the angle of the rotation.
double[]	getAngles(RotationOrder order) Get the Cardan or Euler angles corresponding to the instance.
Vector3D	getAxis() Get the normalized axis of the rotation.
double[][]	getMatrix() Get the 3X3 matrix corresponding to the instance
double	getQ0() Get the scalar coordinate of the quaternion.
double	getQ1() Get the first coordinate of the vectorial part of the quaternion.
double	getQ2() Get the second coordinate of the vectorial part of the quaternion.
double	getQ3() Get the third coordinate of the vectorial part of the quaternion.
Rotation	revert() Revert a rotation.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Rotation

public Rotation()

Build the identity rotation.

Rotation

public Rotation(double q0,
                double q1,
                double q2,
                double q3)

Deprecated. since Mantissa 6.3, this method as been deprecated as it does not properly handles non-normalized quaternions, it should be replaced by Rotation(double, double, double, double, boolean)

Build a rotation from the quaternion coordinates.

Parameters:

q0 - scalar part of the quaternion

q1 - first coordinate of the vectorial part of the quaternion

q2 - second coordinate of the vectorial part of the quaternion

q3 - third coordinate of the vectorial part of the quaternion

Rotation

public Rotation(double q0,
                double q1,
                double q2,
                double q3,
                boolean needsNormalization)

Build a rotation from the quaternion coordinates.

A rotation can be built from a normalized quaternion, i.e. a quaternion for which q₀² + q₁² + q₂² + q₃² = 1. If the quaternion is not normalized, the constructor can normalize it in a preprocessing step.

This method replaces the constructor using only 4 doubles which was deprecated as of version 6.3 of Mantissa.

Parameters:

q0 - scalar part of the quaternion

q1 - first coordinate of the vectorial part of the quaternion

q2 - second coordinate of the vectorial part of the quaternion

q3 - third coordinate of the vectorial part of the quaternion

needsNormalization - if true, the coordinates are considered not to be normalized, a normalization preprocessing step is performed before using them

Rotation

public Rotation(Vector3D axis,
                double angle)

Build a rotation from an axis and an angle.

We use the convention that angles are oriented according to the effect of the rotation on vectors around the axis. That means that if (i, j, k) is a direct frame and if we first provide +k as the axis and PI/2 as the angle to this constructor, and then apply the instance to +i, we will get +j.

Parameters:

axis - axis around which to rotate

angle - rotation angle.

Throws:

java.lang.ArithmeticException - if the axis norm is null

Rotation

public Rotation(double[][] m,
                double threshold)
         throws NotARotationMatrixException

Build a rotation from a 3X3 matrix.

Rotation matrices are orthogonal matrices, i.e. unit matrices (which are matrices for which m.mT = I) with real coefficients. The module of the determinant of unit matrices is 1, among the orthogonal 3X3 matrices, only the ones having a positive determinant (+1) are rotation matrices.

When a rotation is defined by a matrix with truncated values (typically when it is extracted from a technical sheet where only four to five significant digits are available), the matrix is not orthogonal anymore. This constructor handles this case transparently by using a copy of the given matrix and applying a correction to the copy in order to perfect its orthogonality. If the Frobenius norm of the correction needed is above the given threshold, then the matrix is considered to be too far from a true rotation matrix and an exception is thrown.

Parameters:

m - rotation matrix

threshold - convergence threshold for the iterative orthogonality correction (convergence is reached when the difference between two steps of the Frobenius norm of the correction is below this threshold)

Throws:

NotARotationMatrixException - if the matrix is not a 3X3 matrix, or if it cannot be transformed into an orthogonal matrix with the given threshold, or if the determinant of the resulting orthogonal matrix is negative

Rotation

public Rotation(Vector3D u1,
                Vector3D u2,
                Vector3D v1,
                Vector3D v2)

Build the rotation that transforms a pair of vector into another pair.

Except for possible scale factors, if the instance were applied to the pair (u1, u2) it will produce the pair (v1, v2).

If the angular separation between u1 and u2 is not the same as the angular separation between v1 and v2, then a corrected v2' will be used rather than v2, the corrected vector will be in the (v1, v2) plane.

Parameters:

u1 - first vector of the origin pair

u2 - second vector of the origin pair

v1 - desired image of u1 by the rotation

v2 - desired image of u2 by the rotation

Rotation

public Rotation(Vector3D u,
                Vector3D v)

Build one of the rotations that transform one vector into another one.

Except for a possible scale factor, if the instance were applied to the vector u it will produce the vector v. There is an infinite number of such rotations, this constructor choose the one with the smallest associated angle (i.e. the one whose axis is orthogonal to the (u, v) plane). If u and v are colinear, an arbitrary rotation axis is chosen.

Parameters:

u - origin vector

v - desired image of u by the rotation

Throws:

java.lang.ArithmeticException - if the norm of one of the vectors is null

Rotation

public Rotation(RotationOrder order,
                double alpha1,
                double alpha2,
                double alpha3)

Build a rotation from three Cardan or Euler elementary rotations.

Cardan rotations are three successive rotations around the canonical axes X, Y and Z, each axis beeing used once. There are 6 such sets of rotations (XYZ, XZY, YXZ, YZX, ZXY and ZYX). Euler rotations are three successive rotations around the canonical axes X, Y and Z, the first and last rotations beeing around the same axis. There are 6 such sets of rotations (XYX, XZX, YXY, YZY, ZXZ and ZYZ), the most popular one being ZXZ. Beware that many people routinely use the term Euler angles even for what really are Cardan angles (this confusion is especially widespread in the aerospace business where Roll, Pitch and Yaw angles are often wrongly tagged as Euler angles).

Parameters:

order - order of rotations to use

alpha1 - angle of the first elementary rotation

alpha2 - angle of the second elementary rotation

alpha3 - angle of the third elementary rotation

Method Detail

revert

public Rotation revert()

Revert a rotation. Build a rotation which reverse the effect of another rotation. This means that is r(u) = v, then r.revert (v) = u. The instance is not changed.

Returns:

a new rotation whose effect is the reverse of the effect of the instance

getQ0

public double getQ0()

Get the scalar coordinate of the quaternion.

Returns:

scalar coordinate of the quaternion

getQ1

public double getQ1()

Get the first coordinate of the vectorial part of the quaternion.

Returns:

first coordinate of the vectorial part of the quaternion

getQ2

public double getQ2()

Get the second coordinate of the vectorial part of the quaternion.

Returns:

second coordinate of the vectorial part of the quaternion

getQ3

public double getQ3()

Get the third coordinate of the vectorial part of the quaternion.

Returns:

third coordinate of the vectorial part of the quaternion

getAxis

public Vector3D getAxis()

Get the normalized axis of the rotation.

Returns:

normalized axis of the rotation

getAngle

public double getAngle()

Get the angle of the rotation.

Returns:

angle of the rotation (between 0 and PI)

getAngles

public double[] getAngles(RotationOrder order)
                   throws CardanEulerSingularityException

Get the Cardan or Euler angles corresponding to the instance.

The equations show that each rotation can be defined by two different values of the Cardan or Euler angles set. For example if Cardan angles are used, the rotation defined by the angles a1, a2 and a3 is the same as the rotation defined by the angles PI + a1, PI - a2 and PI + a3. This method implements the following arbitrary choices. For Cardan angles, the chosen set is the one for which the second angle is between -PI/2 and PI/2 (i.e its cosine is positive). For Euler angles, the chosen set is the one for which the second angle is between 0 and PI (i.e its sine is positive).

Cardan and Euler angle have a very disappointing drawback: all of them have singularities. This means that if the instance is too close to the singularities corresponding to the given rotation order, it will be impossible to retrieve the angles. For Cardan angles, this is often called gimbal lock. There is nothing to do to prevent this, it is an intrisic problem of Cardan and Euler representation (but not a problem with the rotation itself, which is perfectly well defined). For Cardan angles, singularities occur when the second angle is close to -PI/2 or +PI/2, for Euler angle singularities occur when the second angle is close to 0 or PI, this means that the identity rotation is always singular for Euler angles !

Parameters:

order - rotation order to use

Returns:

an array of three angles, in the order specified by the set

Throws:

CardanEulerSingularityException - if the rotation is singular with respect to the angles set specified

getMatrix

public double[][] getMatrix()

Get the 3X3 matrix corresponding to the instance

Returns:

the matrix corresponding to the instance

applyTo

public Vector3D applyTo(Vector3D u)

Apply the rotation to a vector.

Parameters:

u - vector to apply the rotation to

Returns:

a new vector which is the image of u by the rotation

applyInverseTo

public Vector3D applyInverseTo(Vector3D u)

Apply the inverse of the rotation to a vector.

Parameters:

u - vector to apply the inverse of the rotation to

Returns:

a new vector which such that u is its image by the rotation

applyTo

public Rotation applyTo(Rotation r)

Apply the instance to another rotation. Applying the instance to a rotation is computing the composition in an order compliant with the following rule : let u be any vector and v its image by r (i.e. r.applyTo(u) = v), let w be the image of v by the instance (i.e. applyTo(v) = w), then w = comp.applyTo(u), where comp = applyTo(r).

Parameters:

r - rotation to apply the rotation to

Returns:

a new rotation which is the composition of r by the instance

applyInverseTo

public Rotation applyInverseTo(Rotation r)

Apply the inverse of the instance to another rotation. Applying the inverse of the instance to a rotation is computing the composition in an order compliant with the following rule : let u be any vector and v its image by r (i.e. r.applyTo(u) = v), let w be the inverse image of v by the instance (i.e. applyInverseTo(v) = w), then w = comp.applyTo(u), where comp = applyInverseTo(r).

Parameters:

r - rotation to apply the rotation to

Returns:

a new rotation which is the composition of r by the inverse of the instance