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 degrees.
• 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^TRx = RR^Tx
• 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 = 45.0;
         Matrix rotation2D = Rotation.rotate2D(theta);
         Vector vector2D = new Vector(1, 0);  // A vector along the x-axis
         Vector rotatedVector2D = rotation2D.mult(vector2D);

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

         // Perform a yaw-pitch-roll rotation in 3D.
         double yaw = 30.0;
         double pitch = 45.0;
         double roll = 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 = 45.0;
         Matrix arbitraryAxisRotation = Rotation.rotate3D(angle, axis);
         Vector arbitraryRotatedVector = arbitraryAxisRotation.mult(vector3D);

         // Perform a rotation using proper Euler angles.
         double alpha = 30.0;  // Rotation about z-axis
         double beta = 45.0;   // Rotation about x-axis
         double gamma = 60.0;  // Rotation about z-axis again
         Matrix eulerRotation = Rotation.rotateEuler3D(alpha, beta, gamma);
         Vector eulerRotatedVector = eulerRotation.mult(vector3D);

         // Perform multiple rotations.
         double thetaY = 90.0;
         double thetaZ = -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(θ), which rotates 2D column vectors theta degrees.
static Matrix	rotate3D(double yaw, double pitch, double roll)	Constructs a 3D rotation matrix, R(α, β, γ), representing a rotation with yaw, pitch, and roll angles α, β, and γ respectively.
static Matrix	rotate3D(double theta, Vector axis)	Constructs a 3D rotation matrix, Ru(θ), which representing a rotation of θ degrees about an axis unit vector u.
static Matrix	rotateEuler(double alpha, double beta, double gamma)	Constructs a 3D rotation matrix, RE(α, β, γ), representing a rotation described by proper Euler angles (α, β, γ).
static Matrix	rotateX3D(double theta)	Constructs a matrix which rotates 3D column vectors about the x-axis theta degrees.
static Matrix	rotateY3D(double theta)	Constructs a matrix which rotates 3D column vectors about the y-axis theta degrees.
static Matrix	rotateZ3D(double theta)	Constructs a matrix which rotates 3D column vectors about the z-axis theta degrees.

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(θ), which rotates 2D column vectors theta degrees. When theta > 0 the rotation is counterclockwise. When

A 2D rotation matrix R(θ), rotates a 2D column vector x, θ degrees by means of the following matrix-vector multiplication:

     x' = R(θ)x

The following holds R(-θ) = R(θ)^-1 = R(θ)^T. This means the inverse/transpose may be used to undo a rotation,

     x = R(θ)R(θ)Tx
       = R(θ)TR(θ)x
       = Ix

Parameters:

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

Returns:

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

rotateX3D

public static Matrix rotateX3D(double theta)

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

A 3D rotation matrix, R_X(θ), rotates a 3D column vector x about the x-axis θ degrees by means of the following matrix-vector multiplication:

     x' = RX(θ)x

The following holds R_X(-θ) = R_X(θ)^-1 = R_X(θ)^T. This means the inverse/transpose may be used to undo a rotation,

     x = RX(θ)RX(θ)Tx
       = RX(θ)TRX(θ)x
       = Ix

Parameters:

theta - The degrees to rotate a 3D vector about the x-axis by.

Returns:

matrix which rotates 3D column vectors about the x-axis theta degrees.

rotateY3D

public static Matrix rotateY3D(double theta)

Constructs a matrix which rotates 3D column vectors about the y-axis theta degrees. 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(θ), rotates a 3D column vector x about the y-axis θ degrees by means of the following matrix-vector multiplication:

     x' = RY(θ)x

The following holds R_Y(-θ) = R_Y(θ)^-1 = R_Y(θ)^T. This means the inverse/transpose may be used to undo a rotation,

     x = RY(θ)RY(θ)Tx
       = RY(θ)TRY(θ)x
       = Ix

Parameters:

theta - The degrees to rotate a 3D vector about the y-axis by.

Returns:

matrix which rotates 3D column vectors about the y-axis theta degrees.

rotateZ3D

public static Matrix rotateZ3D(double theta)

Constructs a matrix which rotates 3D column vectors about the z-axis theta degrees. 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 θ degrees by means of the following matrix-vector multiplication:

     x' = RZ(θ)x

The following holds R_Z(-θ) = R_Z(θ)^-1 = R_Z(θ)^T. This means the inverse/transpose may be used to undo a rotation,

     x = RZ(θ)RZ(θ)Tx
       = RZ(θ)TRZ(θ)x
       = Ix

Parameters:

theta - The degrees to rotate a 3D vector about the z-axis by.

Returns:

matrix which rotates 3D column vectors about the z-axis theta degrees.

rotate3D

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

Constructs a 3D rotation matrix, R(α, β, γ), representing a rotation with yaw, pitch, and roll angles α, β, and γ respectively. This is equivalent to rotating by α degrees about the x-axis, β degrees about the y-axis, and γ degrees 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(α, β, γ), rotates a 3D column vector x, γ, β, and α degrees about the x-, y-, and z-axes in that order by means of the following matrix multiplication:

     x' = R(α, β, γ)x
        = RZ(γ)RY(β)RX(α)x

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 ±90°. To avoid gimbal lock, consider using rotation representations that do not rely on sequential rotations.

Parameters:

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

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

roll - Degrees 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 α, β, and γ respectively.

rotate3D

public static Matrix rotate3D(double theta,
 Vector axis)

Constructs a 3D rotation matrix, R_u(θ), which representing a rotation of θ degrees about an axis unit vector u. The rotation is a counterclockwise rotation when u points towards the observer, θ> 0, and the coordinate system is right-handed.

A 3D rotation matrix, R_u(θ), rotates a 3D column vector x, θ degrees about the vector u by means of the following matrix multiplication:

     x' = Ru(θ)x

Parameters:

theta - The degrees 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:

rotateEuler

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

Constructs a 3D rotation matrix, R_E(α, β, γ), representing a rotation described by proper Euler angles (α, β, γ). This is equivalent to performing a rotation about the z-axis by α degrees, then about the x-axis by β degrees, then about the z-axis again by γ degrees.

A 3D rotation matrix, R_E(α, β, γ), rotates a 3D column vector x, according to the Euler angles (α, β, γ) by means of the following matrix multiplication:

     x' = RE(α, β, γ)x
        = RZ(γ)RX(β)RZ(α)x

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 ±90°. To avoid gimbal lock, consider using rotation representations that do not rely on sequential rotations.

Parameters:

alpha - Degrees of first rotation about the z-axis.

beta - Degrees of second rotation about the x-axis.

gamma - Degrees of third rotation about the z-axis.

Returns:

Constructs a rotation matrix representing a rotation described by proper Euler angles (α, β, γ).