Class Rotation

java.lang.Object

org.flag4j.linalg.transformations.Rotation

public final class Rotation
extends Object

The Rotation class provides utility methods to compute rotation matrices for 2D and 3D rotations. These matrices are designed to perform rotations of vectors in a counterclockwise direction when viewed from a positive axis perspective in a right-handed coordinate system.

This class supports:

• 2D rotation matrices for rotating column vectors by a specified angle in radians.
• 3D rotation matrices for rotating about the \( x \)-axis, \( y \)-axis, and \( z \)-axis.
• 3D rotation matrices for yaw-pitch-roll rotations.
• 3D rotation matrices for arbitrary axis rotations.
• 3D rotation matrices for proper Euler angle rotations.

Rotation matrices have the following properties:

• A rotation matrix is orthogonal: \( R^{-1} = R^{T} \).
• Rotations preserve the length of vectors (orthogonal transformations).
• The inverse/transpose rotation matrix undoes the rotation: \( x = R^{T}Rx = RR^{T}x \)
• Successive rotations can be composed through matrix multiplication (rotation order is from right to left).

Example Usage

         // Rotate a 2D vector by 45 degrees.
         double theta = Math.toRadians(45.0);
         Matrix rotation2D = Rotation.rotate2D(theta);
         Vector vector2D = new Vector(1, 0);  // A vector along the <span class="latex-inline">x</span>-axis
         Vector rotatedVector2D = rotation2D.mult(vector2D);

         // Rotate a 3D vector about the <span class="latex-inline">x</span>-axis by 90 degrees.
         double thetaX = Math.toRadians(90.0);
         Matrix rotationX3D = Rotation.rotateX3D(thetaX);
         Vector vector3D = new Vector(0, 1, 0);  // A vector along the <span class="latex-inline">y</span>-axis
         Vector rotatedVector3D = rotationX3D.mult(vector3D);

         // Perform a yaw-pitch-roll rotation in 3D.
         double yaw = Math.toRadians(0.0);
         double pitch = Math.toRadians(45.0);
         double roll = Math.toRadians(60.0);
         Matrix yawPitchRoll = Rotation.rotate3D(yaw, pitch, roll);
         vector3D = new Vector(1, 1, 1);  // An arbitrary 3D vector
         Vector rotatedVector = yawPitchRoll.mult(vector3D);

         // Rotate a 3D vector about an arbitrary axis.
         Vector axis = new Vector(1, 1, 0);  // An arbitrary axis.
         double angle = Math.toRadians(45.0);
         Matrix arbitraryAxisRotation = Rotation.rotate3D(angle, axis);
         Vector arbitraryRotatedVector = arbitraryAxisRotation.mult(vector3D);

         // Perform a rotation using proper Euler angles.
         double alpha = Math.PI / 6.0;  // Rotation about <span class="latex-inline">z</span>-axis
         double beta = Math.PI / 4.0;   // Rotation about <span class="latex-inline">x</span>-axis
         double gamma = Math.PI / 3.0;  // Rotation about <span class="latex-inline">z</span>-axis again
         Matrix eulerRotation = Rotation.rotateEuler3D(alpha, beta, gamma);
         Vector eulerRotatedVector = eulerRotation.mult(vector3D);

         // Perform multiple rotations.
         double thetaY = Math.toRadians(90.0);
         double thetaZ = Math.toRadians(-30.0);
         Matrix rotationY3D = Rotation.rotateY3D(thetaY);
         Matrix rotationZ3D = Rotation.rotateZ3D(thetaZ);
         vector3D = new Vector(0, 1, 0);
         // First rotate by thetaY then by thetaZ.
         Matrix combinedRotation3D = rotationZ3D.mult(rotationY3D);
         Vector multiRotatedVector3D = combinedRotation3D.mult(vector3D);
 

Note: Methods involving sequential rotations, such as yaw-pitch-roll or Euler angles, are susceptible to gimbal lock, where two axes align, causing a loss of one degree of rotational freedom. For applications requiring continuous rotations, consider alternative representations such as quaternions.

Method Summary

Modifier and Type	Method	Description
static Matrix	rotate2D(double theta)	Constructs a rotation matrix, \( R\left(\theta \right) \), which rotates 2D column vectors \( \theta \) radians.
static Matrix	rotate3D(double yaw, double pitch, double roll)	Constructs a 3D rotation matrix, \[ \begin{align*} R\left(\alpha , \beta , \gamma \right) \end{align*} \], representing a rotation with yaw, pitch, and roll angles \( \alpha \), \( \beta \), and \( \gamma \) respectively.
static Matrix	rotate3D(double theta, Vector axis)	Constructs a 3D rotation matrix, \( R_{u}\left(\theta \right) \), which representing a rotation of \( \theta \) radians about an axis unit vector u.
static Matrix	rotateEuler(double alpha, double beta, double gamma)	Constructs a 3D rotation matrix, \( R_{E}\left(\alpha , \beta , \gamma \right) \), representing a rotation described by proper Euler angles \( \left(\alpha , \beta , \gamma \right) \).
static Matrix	rotateX3D(double theta)	Constructs a matrix which rotates 3D column vectors about the \( x \)-axis \( \theta \) radians.
static Matrix	rotateY3D(double theta)	Constructs a matrix which rotates 3D column vectors about the \( y \)-axis \( \theta \) radians.
static Matrix	rotateZ3D(double theta)	Constructs a matrix which rotates 3D column vectors about the \( z \)-axis \( \theta \) radians.

Methods inherited from class java.lang.Object

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

Method Details

rotate2D

public static Matrix rotate2D(double theta)

Constructs a rotation matrix, \( R\left(\theta \right) \), which rotates 2D column vectors \( \theta \) radians. When \( \theta > 0 \) the rotation is counterclockwise.

A 2D rotation matrix \( R\left(\theta \right) \), rotates a 2D column vector \( x \), \( \theta \) radians by means of the following matrix-vector multiplication: \[ x' = R\left(\theta \right)x \] The following holds \( R\left(-\theta \right) = R\left(\theta \right)^{-1} = R\left(\theta \right)^{T} \). This means the inverse/transpose may be used to undo a rotation, \[ \begin{align*} x &= R\left(\theta \right)R\left(\theta \right)^{T}x \\ &= R\left(\theta \right)^{T}R\left(\theta \right)x \\ &= Ix \end{align*} \]

Parameters:

theta - The radians to rotate a 2D vector by.

Returns:

A rotation matrix which rotates (counterclockwise) 2D column vectors theta radians.

rotateX3D

public static Matrix rotateX3D(double theta)

Constructs a matrix which rotates 3D column vectors about the \( x \)-axis \( \theta \) radians. The rotation appears counterclockwise when the \( x \)-axis points toward the observer, \( \theta \) and the coordinate system is right-handed.

A 3D rotation matrix, \( R_{x}\left(\theta \right) \), rotates a 3D column vector x about the \( x \)-axis \( \theta \) radians by means of the following matrix-vector multiplication: \[ x' = R_{x}\left(\theta \right)x \] The following holds \( R_{x}\left(-\theta \right) = R_{x}\left(\theta \right)^{-1} = R_{x}\left(\theta \right)^{T} \). This means the inverse/transpose may be used to undo a rotation, \[ \begin{align*} x &= R_{x}\left(\theta \right)R_{x}\left(\theta \right)^{T}x \\ &= R_{x}\left(\theta \right)^{T}R_{x}\left(\theta \right)x \\ &= Ix \end{align*} \]

Parameters:

theta - The radians to rotate a 3D vector about the \( x \)-axis by.

Returns:

matrix which rotates 3D column vectors about the \( x \)-axis theta radians.

rotateY3D

public static Matrix rotateY3D(double theta)

Constructs a matrix which rotates 3D column vectors about the \( y \)-axis \( \theta \) radians. The rotation appears counterclockwise when the \( y \)-axis points toward the observer, \( \theta > 0 \) and the coordinate system is right-handed.

A 3D rotation matrix, \( R_{y}\left(\theta \right) \), rotates a 3D column vector x about the \( y \)-axis \( \theta \) radians by means of the following matrix-vector multiplication: \[ x' = R_{y}\left(\theta \right)x \] The following holds \( R_{y}\left(-\theta \right) = R_{y}\left(\theta \right)^{-1} = R_{y}\left(\theta \right)^{T} \). This means the inverse/transpose may be used to undo a rotation, \[ \begin{align*} x &= R_{y}\left(\theta \right)R_{y}\left(\theta \right)^{T}x \\ &= R_{y}\left(\theta \right)^{T}R_{y}\left(\theta \right)x \\ &= Ix \end{align*} \]

Parameters:

theta - The radians to rotate a 3D vector about the \( y \)-axis by.

Returns:

matrix which rotates 3D column vectors about the \( y \)-axis theta radians.

rotateZ3D

public static Matrix rotateZ3D(double theta)

Constructs a matrix which rotates 3D column vectors about the \( z \)-axis \( \theta \) radians. The rotation appears counterclockwise when the \( z \)-axis points toward the observer, \( \theta > 0 \) and the coordinate system is right-handed.

A 3D rotation matrix, R_z(θ), rotates a 3D column vector x about the \( z \)-axis \( \theta \) radians by means of the following matrix-vector multiplication: \[ x' = R_{z}\left(\theta \right)x \] The following holds \( R_{z}\left(-\theta \right) = R_{z}\left(\theta \right)^{-1} = R_{z}\left(\theta \right)^{T} \). This means the inverse/transpose may be used to undo a rotation, \[ \begin{align*} x &= R_{z}\left(\theta \right)R_{z}\left(\theta \right)^{T}x \\ &= R_{z}\left(\theta \right)^{T}R_{z}\left(\theta \right)x \\ &= Ix \end{align*} \]

Parameters:

theta - The radians to rotate a 3D vector about the \( z \)-axis by.

Returns:

matrix which rotates 3D column vectors about the \( z \)-axis theta radians.

rotate3D

public static Matrix rotate3D(double yaw,
 double pitch,
 double roll)

Constructs a 3D rotation matrix, \[ \begin{align*} R\left(\alpha , \beta , \gamma \right) \end{align*} \], representing a rotation with yaw, pitch, and roll angles \( \alpha \), \( \beta \), and \( \gamma \) respectively. This is equivalent to rotating by \( \alpha \) radians about the \( x \)-axis, β radians about the \( y \)-axis, and \( \gamma \) radians about the \( z \)-axis in that order. Each of the three rotations appear counterclockwise when the axis about which they occur points toward the observer, the rotation angle is positive, and the coordinate system is right-handed.

A 3D rotation matrix, \( R\left(\alpha , \beta , \gamma \right) \), rotates a 3D column vector \( x \), \( \gamma \), \( \beta \), and \( \alpha \) radians about the \( x \)-, \( y \)-, and \( z \)-axes in that order by means of the following matrix multiplication: \[ \begin{align*} x' &= R\left(\alpha , \beta , \gamma \right)x \\ &= R_{z}\left(\gamma \right)R_{y}\left(\beta \right)R_{x}\left(\alpha \right)x \end{align*} \]

Note: This method is susceptible to gimbal lock, a phenomenon where two of the rotation axes align, causing a loss of one degree of rotational freedom. Gimbal lock occurs when the second rotation in the sequence aligns the axes, such as when the pitch angle (for yaw-pitch-roll) or the second Euler angle (for proper Euler angles) is \( \pm 90^{\circ} \). To avoid gimbal lock, consider using rotation representations that do not rely on sequential rotations.

Parameters:

yaw - Radians to rotate about the vertical (yaw) axis (i.e. the \( z \)-axis).

pitch - Radians to rotate about the lateral (pitch) axis (i.e. the \( y \)-axis).

roll - Radians to rotate about the longitudinal (roll) axis (i.e. the \( x \)-axis).

Returns:

a rotation matrix representing a rotation with yaw, pitch, and roll angles \( \alpha \), \( \beta \), and \( \gamma \) respectively.

rotate3D

public static Matrix rotate3D(double theta,
 Vector axis)

Constructs a 3D rotation matrix, \( R_{u}\left(\theta \right) \), which representing a rotation of \( \theta \) radians about an axis unit vector u. The rotation is a counterclockwise rotation when u points towards the observer, \( \theta > 0 \), and the coordinate system is right-handed.

A 3D rotation matrix, \( R_{u}\left(\theta \right) \), rotates a 3D column vector x, \( \theta \) radians about the vector u by means of the following matrix multiplication: \[ x' = R_{u}\left(\theta \right)x \]

Parameters:

theta - The radians to rotate about the vector \( u \).

axis - The axis vector \( u \) to rotate about. This vector will be normalized so it need not be a unit vector. Must satisfy axis.size == 3.

Returns:

A rotation matrix representing a rotation of theta radians about the axis specified by axis.

rotateEuler

public static Matrix rotateEuler(double alpha,
 double beta,
 double gamma)

Constructs a 3D rotation matrix, \( R_{E}\left(\alpha , \beta , \gamma \right) \), representing a rotation described by proper Euler angles \( \left(\alpha , \beta , \gamma \right) \). This is equivalent to performing a rotation about the \( z \)-axis by α radians, then about the \( x \)-axis by β radians, then about the \( z \)-axis again by γ radians.

A 3D rotation matrix, \( R_{E}\left(\alpha , \beta , \gamma \right) \), rotates a 3D column vector x, according to the Euler angles \( \left(\alpha , \beta , \gamma \right) \) by means of the following matrix multiplication: \[ \begin{align*} x' &= R_{E}\left(\alpha , \beta , \gamma \right)x \\ &= R_{z}\left(\gamma \right)R_{x}\left(\beta \right)R_{z}\left(\alpha \right)x \end{align*} \]

Note: This method is susceptible to gimbal lock, a phenomenon where two of the rotation axes align, causing a loss of one degree of rotational freedom. Gimbal lock occurs when the second rotation in the sequence aligns the axes, such as when the pitch angle (for yaw-pitch-roll) or the second Euler angle (for proper Euler angles) is \( \pm 90^{\circ} \). To avoid gimbal lock, consider using rotation representations that do not rely on sequential rotations.

Parameters:

alpha - Radians of first rotation about the \( z \)-axis.

beta - Radians of second rotation about the \( x \)-axis.

gamma - Radians of third rotation about the \( z \)-axis.

Returns:

Constructs a rotation matrix representing a rotation described by proper Euler angles \( \left(\alpha , \beta , \gamma \right) \).