org.apache.commons.math3.geometry.euclidean.threed

## Class Rotation

- java.lang.Object
- - org.apache.commons.math3.geometry.euclidean.threed.Rotation

- All Implemented Interfaces:
    Serializable

      public class Rotation
      extends Object
      implements 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 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.

  Since:
    1.2
  Version:
    $Id: Rotation.java 1416643 2012-12-03 19:37:14Z tn $
  See Also:
    `Vector3D`, `RotationOrder`, Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Rotation` | `IDENTITY` Identity rotation.
    `private double` | `q0` Scalar coordinate of the quaternion.
    `private double` | `q1` First coordinate of the vectorial part of the quaternion.
    `private double` | `q2` Second coordinate of the vectorial part of the quaternion.
    `private double` | `q3` Third coordinate of the vectorial part of the quaternion.
    `private static long` | `serialVersionUID` Serializable version identifier

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Rotation(double[][] m, double threshold)` Build a rotation from a 3X3 matrix.
    `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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `applyInverseTo(double[] in, double[] out)` Apply the inverse of the rotation to a vector stored in an array.
    `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.
    `void` | `applyTo(double[] in, double[] out)` Apply the rotation to a vector stored in an array.
    `Rotation` | `applyTo(Rotation r)` Apply the instance to another rotation.
    `Vector3D` | `applyTo(Vector3D u)` Apply the rotation to a vector.
    `static double` | `distance(Rotation r1, Rotation r2)` Compute the distance between two rotations.
    `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.
    `private static double[]` | `mat2quat(double[][] ort)` Convert an orthogonal rotation matrix to a quaternion.
    `private double[][]` | `orthogonalizeMatrix(double[][] m, double threshold)` Perfect orthogonality on a 3X3 matrix.
    `Rotation` | `revert()` Revert a rotation.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### IDENTITY

          public static final Rotation IDENTITY

      Identity rotation.

    - #### serialVersionUID

          private static final long serialVersionUID

      Serializable version identifier
      See Also:
        Constant Field Values

    - #### q0

          private final double q0

      Scalar coordinate of the quaternion.

    - #### q1

          private final double q1

      First coordinate of the vectorial part of the quaternion.

    - #### q2

          private final double q2

      Second coordinate of the vectorial part of the quaternion.

    - #### q3

          private final double q3

      Third coordinate of the vectorial part of the quaternion.

  - ### Constructor Detail

    - #### 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 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.

      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)
                   throws MathIllegalArgumentException

      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 π/2 as the angle to this constructor, and then `apply` the instance to +i, we will get +j.

      Another way to represent our convention is to say that a rotation of angle θ about the unit vector (x, y, z) is the same as the rotation build from quaternion components { cos(-θ/2), x * sin(-θ/2), y * sin(-θ/2), z * sin(-θ/2) }. Note the minus sign on the angle!

      On the one hand this convention is consistent with a vectorial perspective (moving vectors in fixed frames), on the other hand it is different from conventions with a frame perspective (fixed vectors viewed from different frames) like the ones used for example in spacecraft attitude community or in the graphics community.

      Parameters:
        `axis` - axis around which to rotate
        `angle` - rotation angle.
      Throws:
        `MathIllegalArgumentException` - if the axis norm is zero

    - #### 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)
                   throws MathArithmeticException

      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 v'2 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
      Throws:
        `MathArithmeticException` - if the norm of one of the vectors is zero, or if one of the pair is degenerated (i.e. the vectors of the pair are colinear)

    - #### Rotation

          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 colinear, an arbitrary rotation axis is chosen.

      Parameters:
        `u` - origin vector
        `v` - desired image of u by the rotation
      Throws:
        `MathArithmeticException` - if the norm of one of the vectors is zero

    - #### 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 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).

      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

    - #### mat2quat

          private static double[] mat2quat(double[][] ort)

      Convert an orthogonal rotation matrix to a quaternion.
      Parameters:
        `ort` - orthogonal rotation matrix
      Returns:
        quaternion corresponding to the matrix

    - #### revert

          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.
      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
      See Also:
        `Rotation(Vector3D, double)`

    - #### getAngle

          public double getAngle()

      Get the angle of the rotation.
      Returns:
        angle of the rotation (between 0 and π)
      See Also:
        `Rotation(Vector3D, double)`

    - #### 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 π + a1, π - a2 and π + a3. This method implements the following arbitrary choices:

      - for Cardan angles, the chosen set is the one for which the second angle is between -π/2 and π/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 π (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 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!

      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

    - #### applyTo

          public void applyTo(double[] in,
                     double[] out)

      Apply the rotation to a vector stored in an array.
      Parameters:
        `in` - an array with three items which stores vector to rotate
        `out` - an array with three items to put result to (it can be the same array as in)

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

    - #### applyInverseTo

          public void applyInverseTo(double[] in,
                            double[] out)

      Apply the inverse of the rotation to a vector stored in an array.
      Parameters:
        `in` - an array with three items which stores vector to rotate
        `out` - an array with three items to put result to (it can be the same array as in)

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

    - #### orthogonalizeMatrix

          private double[][] orthogonalizeMatrix(double[][] m,
                                       double threshold)
                                          throws NotARotationMatrixException

      Perfect orthogonality on a 3X3 matrix.
      Parameters:
        `m` - initial matrix (not exactly orthogonal)
        `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)
      Returns:
        an orthogonal matrix close to m
      Throws:
        `NotARotationMatrixException` - if the matrix cannot be orthogonalized with the given threshold after 10 iterations

    - #### distance

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

      Parameters:
        `r1` - first rotation
        `r2` - second rotation
      Returns:
        distance between r1 and r2

Copyright (c) 2003-2013 Apache Software Foundation