java.lang.Object
org.apache.commons.geometry.euclidean.threed.rotation.AxisAngleSequence

public final class AxisAngleSequence extends Object

Class representing a sequence of axis-angle rotations. These types of rotations are commonly called Euler angles, Tait-Bryan angles, or Cardan angles depending on the properties of the rotation sequence and the particular use case. A sequence of three rotations around at least two different axes is sufficient to represent any rotation or orientation in 3 dimensional space. However, in order to unambiguously represent the rotation, the following information must be provided along with the rotation angles:

  • Axis sequence - The axes that the rotation angles are associated with and in what order they occur.
  • Reference frame - The reference frame used to define the position of the rotation axes. This can either be relative (intrinsic) or absolute (extrinsic). A relative reference frame defines the rotation axes from the point of view of the "thing" being rotated. Thus, each rotation after the first occurs around an axis that very well may have been moved from its original position by a previous rotation. A good example of this is an airplane: the pilot steps through a sequence of rotations, each time moving the airplane around its own up/down, left/right, and front/back axes, regardless of how the airplane is oriented at the time. In contrast, an absolute reference frame is fixed and does not move with each rotation.
  • Rotation direction - This defines the rotation direction that angles are measured in. This library uses right-handed rotations exclusively. This means that the direction of rotation around an axis is the same as the curl of one's fingers when the right hand is placed on the axis with the thumb pointing in the axis direction.

Computations involving multiple rotations are generally very complicated when using axis-angle sequences. Therefore, it is recommended to only use this class to represent angles and orientations when needed in this form, and to use QuaternionRotation for everything else. Quaternions are much easier to work with and avoid many of the problems of axis-angle sequence representations, such as gimbal lock.

See Also:
  • Field Details

    • referenceFrame

      private final AxisReferenceFrame referenceFrame
      Reference frame for defining axis positions.
    • axisSequence

      private final AxisSequence axisSequence
      Axis sequence.
    • angle1

      private final double angle1
      Angle around the first rotation axis, in radians.
    • angle2

      private final double angle2
      Angle around the second rotation axis, in radians.
    • angle3

      private final double angle3
      Angle around the third rotation axis, in radians.
  • Constructor Details

    • AxisAngleSequence

      public AxisAngleSequence(AxisReferenceFrame referenceFrame, AxisSequence axisSequence, double angle1, double angle2, double angle3)
      Construct an instance from its component parts.
      Parameters:
      referenceFrame - the axis reference frame
      axisSequence - the axis rotation sequence
      angle1 - angle around the first axis in radians
      angle2 - angle around the second axis in radians
      angle3 - angle around the third axis in radians
  • Method Details

    • getReferenceFrame

      public AxisReferenceFrame getReferenceFrame()
      Get the axis reference frame. This defines the position of the rotation axes.
      Returns:
      the axis reference frame
    • getAxisSequence

      public AxisSequence getAxisSequence()
      Get the rotation axis sequence.
      Returns:
      the rotation axis sequence
    • getAngle1

      public double getAngle1()
      Get the angle of rotation around the first axis, in radians.
      Returns:
      angle of rotation around the first axis, in radians
    • getAngle2

      public double getAngle2()
      Get the angle of rotation around the second axis, in radians.
      Returns:
      angle of rotation around the second axis, in radians
    • getAngle3

      public double getAngle3()
      Get the angle of rotation around the third axis, in radians.
      Returns:
      angle of rotation around the third axis, in radians
    • getAngles

      public double[] getAngles()
      Get the rotation angles as a 3-element array.
      Returns:
      an array containing the 3 rotation angles
    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object
    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object
    • toString

      public String toString()
      Overrides:
      toString in class Object
    • createRelative

      public static AxisAngleSequence createRelative(AxisSequence axisSequence, double angle1, double angle2, double angle3)
      Create a new instance with a reference frame of AxisReferenceFrame.RELATIVE.
      Parameters:
      axisSequence - the axis rotation sequence
      angle1 - angle around the first axis in radians
      angle2 - angle around the second axis in radians
      angle3 - angle around the third axis in radians
      Returns:
      a new instance with a relative reference frame
    • createAbsolute

      public static AxisAngleSequence createAbsolute(AxisSequence axisSequence, double angle1, double angle2, double angle3)
      Create a new instance with a reference frame of AxisReferenceFrame.ABSOLUTE.
      Parameters:
      axisSequence - the axis rotation sequence
      angle1 - angle around the first axis in radians
      angle2 - angle around the second axis in radians
      angle3 - angle around the third axis in radians
      Returns:
      a new instance with an absolute reference frame