org.apache.commons.geometry.euclidean.threed.rotation

Class AxisAngleSequence

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:

Euler Angles, QuaternionRotation

Constructor Summary

Constructors

Constructor and Description
AxisAngleSequence(AxisReferenceFrame referenceFrame, AxisSequence axisSequence, double angle1, double angle2, double angle3) Construct an instance from its component parts.

Method Summary

Modifier and Type	Method and Description
static AxisAngleSequence	createAbsolute(AxisSequence axisSequence, double angle1, double angle2, double angle3) Create a new instance with a reference frame of AxisReferenceFrame.ABSOLUTE.
static AxisAngleSequence	createRelative(AxisSequence axisSequence, double angle1, double angle2, double angle3) Create a new instance with a reference frame of AxisReferenceFrame.RELATIVE.
boolean	equals(Object obj)
double	getAngle1() Get the angle of rotation around the first axis, in radians.
double	getAngle2() Get the angle of rotation around the second axis, in radians.
double	getAngle3() Get the angle of rotation around the third axis, in radians.
double[]	getAngles() Get the rotation angles as a 3-element array.
AxisSequence	getAxisSequence() Get the rotation axis sequence.
AxisReferenceFrame	getReferenceFrame() Get the axis reference frame.
int	hashCode()
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

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 Detail

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