Rotations can be represented by several different mathematical
entities (matrices, axe and angle, Cardan or Euler angles,
quaternions). This class presents 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 implicitly
from a set of vectors and their image.
This implies that this class can be used to convert from one representation to another one. For example, converting a rotation matrix into a set of Cardan angles from can be done using the following single line of code:
double[] angles = new Rotation(matrix, 1.0e-10).getAngles(RotationOrder.XYZ);
Focus is oriented on what a rotation do rather than on its
underlying representation. Once it has been built, and regardless of its
internal 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 may vary and the semantics of the rotation also.
For example in an spacecraft attitude simulation tool, users will often consider the vectors are fixed (say the Earth direction for example) and the frames change. The rotation transforms the coordinates of the vector in inertial frame into the coordinates of the same vector in satellite frame. In this case, the rotation implicitly 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 when the telescope is pointed towards an object of interest. In this case the rotation transforms the direction at rest in a topocentric frame into the sighting direction in the same topocentric frame. This implies in this case the frame is fixed and the vector moves.
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, which would essentially be an application of the first approach.
These examples show that a rotation is what the user wants it to be. This
class does not push the user towards one specific definition and hence 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 and the composite operation r = r1 o
r2 (which means that for each vector u,
r(u) = r1(r2(u))) is also a rotation. Hence
we can consider that in addition to vectors, a rotation can be applied to other
rotations as well (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).
Rotations are guaranteed to be immutable objects.
Vector3D, RotationOrder
| Modifier and Type | Field and Description |
|---|---|
| public static final Rotation | IDENTITY
Identity rotation. |
| private final double | q0
Scalar coordinate of the quaternion. |
| private final double | q1
First coordinate of the vectorial part of the quaternion. |
| private final double | q2
Second coordinate of the vectorial part of the quaternion. |
| private final double | q3
Third coordinate of the vectorial part of the quaternion. |
| private static final long | serialVersionUID
Serializable version identifier |
| Access | Constructor and Description |
|---|---|
| public | Rotation(double
scalar part of the quaternion q0, double first coordinate of the vectorial part of the quaternion q1, double second coordinate of the vectorial part of the quaternion q2, double third coordinate of the vectorial part of the quaternion q3, boolean if true, the coordinates are considered
not to be normalized, a normalization preprocessing step is performed
before using them needsNormalization)Build a rotation from the quaternion coordinates. |
| public | Rotation(Vector3D
axis around which to rotate axis, double rotation angle. angle)
Deprecated
as of 3.6, replaced with
Rotation(Vector3D, double, RotationConvention)
Build a rotation from an axis and an angle. |
| public | Rotation(final Vector3D
axis around which to rotate axis, final double rotation angle angle, final RotationConvention convention to use for the semantics of the angle convention)Build a rotation from an axis and an angle. |
| public | Rotation(double[][]
rotation matrix m, double 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) threshold)Build a rotation from a 3X3 matrix. |
| public | |
| public | |
| public | Rotation(RotationOrder
order of rotations to use order, double angle of the first elementary rotation alpha1, double angle of the second elementary rotation alpha2, double angle of the third elementary rotation alpha3)
Deprecated
as of 3.6, replaced with
Rotation(RotationOrder, RotationConvention, double, double, double)
Build a rotation from three Cardan or Euler elementary rotations. |
| public | Rotation(RotationOrder
order of rotations to compose, from left to right
(i.e. we will use order, RotationConvention r1.compose(r2.compose(r3, convention), convention))convention to use for the semantics of the angle convention, double angle of the first elementary rotation alpha1, double angle of the second elementary rotation alpha2, double angle of the third elementary rotation alpha3)Build a rotation from three Cardan or Euler elementary rotations. |
| Modifier and Type | Method and Description |
|---|---|
| public Vector3D | Returns: a new vector which such that u is its image by the rotationvector to apply the inverse of the rotation to u)Apply the inverse of the rotation to a vector. |
| public void | applyInverseTo(final double[]
an array with three items which stores vector to rotate in, final double[] an array with three items to put result to (it can be the same
array as in) out)Apply the inverse of the rotation to a vector stored in an array. |
| public Rotation | Returns: a new rotation which is the composition of r by the inverse of the instancerotation to apply the rotation to r)Apply the inverse of the instance to another rotation. |
| public Vector3D | |
| public void | applyTo(final double[]
an array with three items which stores vector to rotate in, final double[] an array with three items to put result to (it can be the same
array as in) out)Apply the rotation to a vector stored in an array. |
| public Rotation | |
| public Rotation | Returns: a new rotation which is the composition of r by the instancerotation to apply the rotation to r, final RotationConvention convention to use for the semantics of the angle convention)Compose the instance with another rotation. |
| private Rotation | Returns: a new rotation which is the composition of r by the instance using vector operator conventionrotation to apply the rotation to r)Compose the instance with another rotation using vector operator convention. |
| public Rotation | Returns: a new rotation which is the composition of r by the inverse of the instancerotation to apply the rotation to r, final RotationConvention convention to use for the semantics of the angle convention)Compose the inverse of the instance with another rotation. |
| private Rotation | Returns: a new rotation which is the composition of r by the inverse of the instance using vector operator conventionrotation to apply the rotation to r)Compose the inverse of the instance with another rotation using vector operator convention. |
| public static double | |
| public double | |
| public double[] | Returns: an array of three angles, in the order specified by the setrotation order to use order)
Deprecated
as of 3.6, replaced with
getAngles(RotationOrder, RotationConvention)
Get the Cardan or Euler angles corresponding to the instance. |
| public double[] | Returns: an array of three angles, in the order specified by the setrotation order to use order, RotationConvention convention to use for the semantics of the angle convention)Get the Cardan or Euler angles corresponding to the instance. |
| public Vector3D | Returns: normalized axis of the rotation
Deprecated
as of 3.6, replaced with
getAxis(RotationConvention)
Get the normalized axis of the rotation. |
| public Vector3D | Returns: normalized axis of the rotationconvention to use for the semantics of the angle convention)Get the normalized axis of the rotation. |
| public double[][] | Returns: the matrix corresponding to the instanceGet the 3X3 matrix corresponding to the instance |
| public double | |
| public double | Returns: first coordinate of the vectorial part of the quaternionGet the first coordinate of the vectorial part of the quaternion. |
| public double | Returns: second coordinate of the vectorial part of the quaternionGet the second coordinate of the vectorial part of the quaternion. |
| public double | Returns: third coordinate of the vectorial part of the quaternionGet the third coordinate of the vectorial part of the quaternion. |
| private static double[] | Returns: quaternion corresponding to the matrixorthogonal rotation matrix ort)Convert an orthogonal rotation matrix to a quaternion. |
| private double[][] | Returns: an orthogonal matrix close to minitial matrix (not exactly orthogonal) m, double 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) threshold)Perfect orthogonality on a 3X3 matrix. |
| public Rotation | Returns: a new rotation whose effect is the reverse of the effect of the instanceRevert a rotation. |
| IDENTITY | back to summary |
|---|---|
| public static final Rotation IDENTITY Identity rotation. | |
| q0 | back to summary |
|---|---|
| private final double q0 Scalar coordinate of the quaternion. | |
| q1 | back to summary |
|---|---|
| private final double q1 First coordinate of the vectorial part of the quaternion. | |
| q2 | back to summary |
|---|---|
| private final double q2 Second coordinate of the vectorial part of the quaternion. | |
| q3 | back to summary |
|---|---|
| private final double q3 Third coordinate of the vectorial part of the quaternion. | |
| serialVersionUID | back to summary |
|---|---|
| private static final long serialVersionUID Serializable version identifier | |
| Rotation | back to summary |
|---|---|
| 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 q02 + q12 + q22 + q32 = 1. If the quaternion is not normalized, the constructor can normalize it in a preprocessing step. Note that some conventions put the scalar part of the quaternion as the 4th component and the vector part as the first three components. This is not our convention. We put the scalar part as the first component.
| |
| Rotation | back to summary |
|---|---|
| public Rotation(Vector3D axis, double angle) throws MathIllegalArgumentException
Deprecated as of 3.6, replaced with Build a rotation from an axis and an angle.
Calling this constructor is equivalent to call
| |
| Rotation | back to summary |
|---|---|
| public Rotation(final Vector3D axis, final double angle, final RotationConvention convention) throws MathIllegalArgumentException Build a rotation from an axis and an angle.
| |
| Rotation | back to summary |
|---|---|
| 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.
| |
| Rotation | back to summary |
|---|---|
| public Rotation(Vector3D u1, Vector3D u2, Vector3D v1, Vector3D v2) throws MathArithmeticException Build the rotation that transforms a pair of vectors 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 v'2 will be used rather than v2, the corrected vector will be in the (±v1, +v2) half-plane.
| |
| Rotation | back to summary |
|---|---|
| public Rotation(Vector3D u, Vector3D v) throws MathArithmeticException 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 collinear, an arbitrary rotation axis is chosen.
| |
| Rotation | back to summary |
|---|---|
| public Rotation(RotationOrder order, double alpha1, double alpha2, double alpha3)
Deprecated as of 3.6, replaced with Build a rotation from three Cardan or Euler elementary rotations.
Calling this constructor is equivalent to call
| |
| Rotation | back to summary |
|---|---|
| public Rotation(RotationOrder order, RotationConvention convention, 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 being 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 being 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).
| |
| applyInverseTo | back to summary |
|---|---|
| public Vector3D applyInverseTo(Vector3D u) Apply the inverse of the rotation to a vector. | |
| applyInverseTo | back to summary |
|---|---|
| public void applyInverseTo(final double[] in, final double[] out) Apply the inverse of the rotation to a vector stored in an array.
| |
| applyInverseTo | back to summary |
|---|---|
| public Rotation applyInverseTo(Rotation r) Apply the inverse of the instance to another rotation.
Calling this method is equivalent to call
| |
| applyTo | back to summary |
|---|---|
| public Vector3D applyTo(Vector3D u) Apply the rotation to a vector. | |
| applyTo | back to summary |
|---|---|
| public void applyTo(final double[] in, final double[] out) Apply the rotation to a vector stored in an array.
| |
| applyTo | back to summary |
|---|---|
| public Rotation applyTo(Rotation r) Apply the instance to another rotation.
Calling this method is equivalent to call
| |
| compose | back to summary |
|---|---|
| public Rotation compose(final Rotation r, final RotationConvention convention) Compose the instance with another rotation.
If the semantics of the rotations composition corresponds to a
If the semantics of the rotations composition corresponds to a
| |
| composeInternal | back to summary |
|---|---|
| private Rotation composeInternal(final Rotation r) Compose the instance with another rotation using vector operator convention. | |
| composeInverse | back to summary |
|---|---|
| public Rotation composeInverse(final Rotation r, final RotationConvention convention) Compose the inverse of the instance with another rotation.
If the semantics of the rotations composition corresponds to a
If the semantics of the rotations composition corresponds to a
| |
| composeInverseInternal | back to summary |
|---|---|
| private Rotation composeInverseInternal(Rotation r) Compose the inverse of the instance with another rotation using vector operator convention. | |
| distance | back to summary |
|---|---|
| public static double distance(Rotation r1, Rotation r2) Compute the distance between two rotations. The distance is intended here as a way to check if two rotations are almost similar (i.e. they transform vectors the same way) or very different. It is mathematically defined as the angle of the rotation r that prepended to one of the rotations gives the other one:
r1(r) = r2
This distance is an angle between 0 and π. Its value is the smallest possible upper bound of the angle in radians between r1(v) and r2(v) for all possible vectors v. This upper bound is reached for some v. The distance is equal to 0 if and only if the two rotations are identical. Comparing two rotations should always be done using this value rather than for example comparing the components of the quaternions. It is much more stable, and has a geometric meaning. Also comparing quaternions components is error prone since for example quaternions (0.36, 0.48, -0.48, -0.64) and (-0.36, -0.48, 0.48, 0.64) represent exactly the same rotation despite their components are different (they are exact opposites). | |
| getAngle | back to summary |
|---|---|
| public double getAngle() Get the angle of the rotation.
| |
| getAngles | back to summary |
|---|---|
| public double[] getAngles(RotationOrder order) throws CardanEulerSingularityException
Deprecated as of 3.6, replaced with Get the Cardan or Euler angles corresponding to the instance.
Calling this method is equivalent to call
| |
| getAngles | back to summary |
|---|---|
| public double[] getAngles(RotationOrder order, RotationConvention convention) 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 π + a1, π - a2 and π + a3. This method implements the following arbitrary choices:
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 intrinsic problem with 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 -π/2 or +π/2, for Euler angle singularities occur when the second angle is close to 0 or π, this implies that the identity rotation is always singular for Euler angles!
| |
| getAxis | back to summary |
|---|---|
| public Vector3D getAxis()
Deprecated as of 3.6, replaced with Get the normalized axis of the rotation.
Calling this method is equivalent to call
| |
| getAxis | back to summary |
|---|---|
| public Vector3D getAxis(final RotationConvention convention) Get the normalized axis of the rotation.
Note that as
| |
| getMatrix | back to summary |
|---|---|
| public double[][] getMatrix() Get the 3X3 matrix corresponding to the instance
| |
| getQ0 | back to summary |
|---|---|
| public double getQ0() Get the scalar coordinate of the quaternion.
| |
| getQ1 | back to summary |
|---|---|
| public double getQ1() Get the first coordinate of the vectorial part of the quaternion.
| |
| getQ2 | back to summary |
|---|---|
| public double getQ2() Get the second coordinate of the vectorial part of the quaternion.
| |
| getQ3 | back to summary |
|---|---|
| public double getQ3() Get the third coordinate of the vectorial part of the quaternion.
| |
| mat2quat | back to summary |
|---|---|
| private static double[] mat2quat(final double[][] ort) Convert an orthogonal rotation matrix to a quaternion.
| |
| orthogonalizeMatrix | back to summary |
|---|---|
| private double[][] orthogonalizeMatrix(double[][] m, double threshold) throws NotARotationMatrixException Perfect orthogonality on a 3X3 matrix.
| |
| revert | back to summary |
|---|---|
| public Rotation revert() Revert a rotation. Build a rotation which reverse the effect of another rotation. This means that if r(u) = v, then r.revert(v) = u. The instance is not changed.
| |