Package com.irurueta.geometry

Class MatrixRotation3D

java.lang.Object
com.irurueta.geometry.Rotation3D
com.irurueta.geometry.MatrixRotation3D
All Implemented Interfaces:
Serializable
public class MatrixRotation3D extends Rotation3D implements Serializable
This class defines the amount of rotation for 3D points or planes. Rotation is defined internally as a matrix.
See Also:

  • Field Details

    • ROTATION3D_INHOM_MATRIX_ROWS

      public static final int ROTATION3D_INHOM_MATRIX_ROWS
      Constant defining the number of rows on a 3D rotation matrix expressed in inhomogeneous coordinates.
      See Also:

    • ROTATION3D_INHOM_MATRIX_COLS

      public static final int ROTATION3D_INHOM_MATRIX_COLS
      Constant defining the number of columns on a 3D rotation matrix expressed in inhomogeneous coordinates.
      See Also:

    • ROTATION3D_HOM_MATRIX_ROWS

      public static final int ROTATION3D_HOM_MATRIX_ROWS
      Constant defining the number of rows on a 3D rotation matrix expressed in homogeneous coordinates.
      See Also:

    • ROTATION3D_HOM_MATRIX_COLS

      public static final int ROTATION3D_HOM_MATRIX_COLS
      Constant defining the number of columns on a 3D rotation matrix expressed in homogeneous coordinates.
      See Also:

    • GIMBAL_THRESHOLD

      public static final double GIMBAL_THRESHOLD
      Threshold to determine that a gimbal locked might have been achieved when trying to find roll, pitch and yaw angles.
      See Also:

    • internalMatrix

      protected com.irurueta.algebra.Matrix internalMatrix
      Internal matrix containing rotation using inhomogeneous coordinates. This matrix will be square, 3x3, orthogonal and will have determinant equal to one.

  • Constructor Details

    • MatrixRotation3D

      public MatrixRotation3D()
      Empty Constructor. Initializes rotation so that no rotation exists (i.e. internal matrix is the identity).

    • MatrixRotation3D

      public MatrixRotation3D(MatrixRotation3D rotation)
      Copy constructor. Copies provided rotation into this instance.
      Parameters:
      rotation - Instance to be copied.

    • MatrixRotation3D

      public MatrixRotation3D(Rotation3D rotation)
      Copy constructor. Copies and converts provided rotation into this instance.
      Parameters:
      rotation - Instance to be copied.

    • MatrixRotation3D

      public MatrixRotation3D(com.irurueta.algebra.Matrix m) throws InvalidRotationMatrixException
      Constructor. Creates a 3D rotation using provided matrix. Provided matrix can be expressed in either homogeneous or inhomogeneous coordinates, and it must also be orthogonal and having determinant equal to 1. The threshold to determine whether provided matrix is orthonormal will be DEFAULT_VALID_THRESHOLD.
      Parameters:
      m - Matrix to create rotation from.
      Throws:
      InvalidRotationMatrixException - Raised if provided matrix is not valid (its size is wrong, or it is not orthonormal). Rotation3D.isValidRotationMatrix(Matrix).

    • MatrixRotation3D

      public MatrixRotation3D(com.irurueta.algebra.Matrix m, double threshold) throws InvalidRotationMatrixException
      Constructor. Creates a 3D rotation using provided matrix. Provided matrix can be expressed in either homogeneous or inhomogeneous coordinates, and it must also be orthogonal up to provided threshold, and must have determinant equal to 1.
      Parameters:
      m - Matrix to create rotation from.
      threshold - Threshold to determine whether matrix is orthonormal.
      Throws:
      InvalidRotationMatrixException - Raised if provided matrix is not valid (its size is wrong, or it is not orthonormal).
      IllegalArgumentException - Raised if provided threshold is negative. Rotation3D.isValidRotationMatrix(Matrix).

    • MatrixRotation3D

      public MatrixRotation3D(double alphaEuler, double betaEuler, double gammaEuler)
      Constructor. Creates a 3D rotation using provided Euler angles expressed in radians.
      Parameters:
      alphaEuler - Alpha Euler angle expressed in radians.
      betaEuler - Beta Euler angle expressed in radians.
      gammaEuler - Gamma Euler angle expressed in radians.

    • MatrixRotation3D

      public MatrixRotation3D(double[] axis, double theta)
      Constructor. Creates a 3D reconstruction using provided rotation axis and rotation angle expressed in radians.
      Parameters:
      axis - Axis of rotation. Axis must be a length-3 array containing the axis vector. For better accuracy axis coordinates should be normalized (norm equal to 1).
      theta - Angle of rotation respect the axis expressed in radians.
      Throws:
      IllegalArgumentException - Raised if provided axis does not have length 3.

    • MatrixRotation3D

      public MatrixRotation3D(double axisX, double axisY, double axisZ, double theta)
      Constructor. Creates a 3D reconstruction using provided rotation axis coordinates and rotation angle expressed in radians. Note: for better accuracy axis coordinates should be normalized (norm equal to 1).
      Parameters:
      axisX - X coordinate of axis.
      axisY - Y coordinate of axis.
      axisZ - Z coordinate of axis.
      theta - Angle of rotation respect the axis expressed in radians.

  • Method Details

    • getType

      public Rotation3DType getType()
      Returns type of this rotation.
      Specified by:
      getType in class Rotation3D
      Returns:
      Type of this rotation.

    • getInternalMatrix

      public com.irurueta.algebra.Matrix getInternalMatrix()
      Returns a copy of the internal matrix so that the internal matrix cannot be modified accidentally. Returned matrix will be 3x3, orthogonal and will have determinant equal to one.
      Returns:
      Internal matrix containing rotation of this instance.

    • setInternalMatrix

      public final void setInternalMatrix(com.irurueta.algebra.Matrix internalMatrix) throws InvalidRotationMatrixException
      Sets the internal matrix of this rotation. Provided matrix must be 3x3 and orthonormal (orthogonal with determinant equal to 1).
      Parameters:
      internalMatrix - Internal matrix to be set.
      Throws:
      InvalidRotationMatrixException - Raised if provided matrix is not 3x3, or it is not orthonormal.

    • setInternalMatrix

      public final void setInternalMatrix(com.irurueta.algebra.Matrix m, double threshold) throws InvalidRotationMatrixException
      Sets the internal matrix of this rotation. Provided matrix must be 3x3 and orthonormal (orthogonal with determinant equal to 1) up to an error equal to provided threshold.
      Parameters:
      m - Internal matrix to be set.
      threshold - Threshold to determine whether matrix is orthonormal or not.
      Throws:
      InvalidRotationMatrixException - Raised if provided matrix is not 3x3, or it is not orthonormal.
      IllegalArgumentException - Raised if provided threshold is negative.

    • getAlphaEulerAngle

      public double getAlphaEulerAngle()
      Returns alpha euler angle within the range -pi and pi.
      Returns:
      Alpha euler angle expressed in radians.

    • getBetaEulerAngle

      public double getBetaEulerAngle()
      Returns beta euler angle within the range -pi/2 and pi/2.
      Returns:
      Beta euler angle expressed in radians.

    • getGammaEulerAngle

      public double getGammaEulerAngle()
      Returns gamma euler angle within the range -pi and pi.
      Returns:
      Gamma euler angle expressed in radians.

    • setEulerAngles

      public final void setEulerAngles(double alphaEuler, double betaEuler, double gammaEuler)
      Sets euler angles of this rotation, expressed in radians.
      Parameters:
      alphaEuler - Alpha euler angle in radians.
      betaEuler - Beta euler angle in radians.
      gammaEuler - Gamma euler angle in radians.

    • getRollAngle

      public double getRollAngle()
      Returns roll angle around x-axis expressed in radians for the 1st possible set of solutions. When obtaining roll, pitch and yaw angles from a rotation matrix, there might be two possible sets of solutions (#getRollAngle(), #getPitchAngle(), #getYawAngle()) or (#getRollAngle2(), #getPitchAngle2(), #getYawAngle2()).
      Returns:
      roll angle around x-axis.
      See Also:

    • getRollAngle2

      public double getRollAngle2()
      Returns roll angle around x-axis expressed in radians for the 2nd possible set of solutions. When obtaining roll, pitch and yaw angles from a rotation matrix, there might be two possible sets of solutions (#getRollAngle(), #getPitchAngle(), #getYawAngle()) or (#getRollAngle2(), #getPitchAngle2(), #getYawAngle2()).
      Returns:
      roll angle around x-axis.
      See Also:

    • getRollAngle

      private double getRollAngle(double pitch)
      Returns roll angle around x-axis expressed in radians corresponding to provided pitch value. This method is used internally.
      Parameters:
      pitch - pitch angle expressed in radians.
      Returns:
      roll angle around x-axis.

    • getPitchAngle

      public double getPitchAngle()
      Returns pitch angle around y-axis expressed in radians for the 1st possible set of solutions. When obtaining roll, pitch and yaw angles from a rotation matrix, there might be two possible sets of solutions (#getRollAngle(), #getPitchAngle(), #getYawAngle()) or (#getRollAngle2(), #getPitchAngle2(), #getYawAngle2()).
      Returns:
      pitch angle around y-axis.
      See Also:

    • getPitchAngle2

      public double getPitchAngle2()
      Returns pitch angle around y-axis expressed in radians for the 2nd possible set of solutions. When obtaining roll, pitch and yaw angles from a rotation matrix, there might be two possible sets of solutions (#getRollAngle(), #getPitchAngle(), #getYawAngle()) or (#getRollAngle2(), #getPitchAngle2(), #getYawAngle2()). When a gimbal lock occurs, both pitch angles are equal because only yaw is undefined, but pitch and roll are unique.
      Returns:
      pitch angle around y-axis.
      See Also:

    • getYawAngle

      public double getYawAngle()
      Returns yaw angle around z axis expressed in radians for the 1st possible set of solutions. When a gimbal lock occurs (pitch angle is close to +- 90 degrees), then yaw angle is undefined, and can be any value, although this method will return 0.0. When obtaining roll, pitch and yaw angles from a rotation matrix, there might be two possible sets of solutions (#getRollAngle(), #getPitchAngle(), #getYawAngle()) or (#getRollAngle2(), #getPitchAngle2(), #getYawAngle2()).
      Returns:
      yaw angle around z axis.
      See Also:

    • getYawAngle2

      public double getYawAngle2()
      Returns yaw angle around z axis expressed in radians for the 2nd possible set of solutions. When a gimbal lock occurs (pitch angle is close to +- 90 degrees), then yaw angle is undefined, and can be any value, although this method will return 0.0. When obtaining roll, pitch and yaw angles from a rotation matrix, there might be two possible sets of solutions (#getRollAngle(), #getPitchAngle(), #getYawAngle()) or (#getRollAngle2(), #getPitchAngle2(), #getYawAngle2()).
      Returns:
      yaw angle around z axis.
      See Also:

    • getYawAngle

      private double getYawAngle(double pitch)
      Returns yaw angle around x-axis expressed in radians corresponding to provided pitch value. This method is used internally.
      Parameters:
      pitch - pitch angle expressed in radians.
      Returns:
      yaw angle around x-axis.

    • hasGimbalLock

      public boolean hasGimbalLock()
      Indicates whether current rotation contains ambiguities (a.k.a. gimbal lock). This situation happens when pitch angle is close to +-90 degrees.
      Returns:
      true if current rotation contains a gimbal lock, false otherwise.
      See Also:

    • setRollPitchYaw

      public void setRollPitchYaw(double roll, double pitch, double yaw)
      Sets rotation angles, expressed in radians.
      Parameters:
      roll - roll angle in radians around x-axis.
      pitch - pitch angle in radians around y-axis.
      yaw - yaw angle in radians around z-axis.
      See Also:

    • setAxisAndRotation

      public final void setAxisAndRotation(double axisX, double axisY, double axisZ, double theta)
      Sets the axis and rotation of this instance. Once set, points will rotate around provided axis an amount equal to provided rotation angle in radians. Note: to avoid numerical instabilities and improve accuracy, axis coordinates should be normalized (e.g. norm equal to 1).
      Specified by:
      setAxisAndRotation in class Rotation3D
      Parameters:
      axisX - X coordinate of rotation axis.
      axisY - Y coordinate of rotation axis.
      axisZ - Z coordinate of rotation axis.
      theta - Amount of rotation in radians.

    • rotationAxis

      public void rotationAxis(double[] axis) throws RotationException
      Returns rotation axis corresponding to this instance. Result is stored in provided axis array, which must have length 3.
      Specified by:
      rotationAxis in class Rotation3D
      Parameters:
      axis - Array where axis coordinates will be stored.
      Throws:
      IllegalArgumentException - Raised if provided array does not have length 3.
      RotationException - Raised if numerical instabilities happen. Because internal matrix will always be well-defined (orthogonal and determinant equal to 1), this exception will rarely happen.

    • getRotationAngle

      public double getRotationAngle() throws RotationException
      Returns rotation amount or angle in radians around the rotation axis associated to this instance.
      Specified by:
      getRotationAngle in class Rotation3D
      Returns:
      Rotation angle in radians.
      Throws:
      RotationException - Raised if numerical instabilities happen. Because internal matrix will always be well-defined (orthogonal and determinant equal to 1), this exception will rarely happen.

    • inverseRotationAndReturnNew

      public MatrixRotation3D inverseRotationAndReturnNew()
      Returns a 3D rotation which is inverse to this instance. In other words, the combination of this rotation with its inverse produces no change.
      Specified by:
      inverseRotationAndReturnNew in class Rotation3D
      Returns:
      Inverse 3D rotation.

    • inverseRotation

      public void inverseRotation(MatrixRotation3D result)
      Sets into provided MatrixRotation3D instance a rotation inverse to this instance. The combination of this rotation with its inverse produces no change.
      Parameters:
      result - Instance where inverse rotation will be set.

    • inverseRotation

      public void inverseRotation(Rotation3D result)
      Sets into provided MatrixRotation3D instance a rotation inverse to this instance. The combination of this rotation with its inverse produces no change.
      Specified by:
      inverseRotation in class Rotation3D
      Parameters:
      result - Instance where inverse rotation will be set.

    • inverseRotation

      public void inverseRotation()
      Reverses the rotation of this instance.
      Specified by:
      inverseRotation in class Rotation3D

    • asInhomogeneousMatrix

      public com.irurueta.algebra.Matrix asInhomogeneousMatrix()
      Returns this 3D rotation instance expressed as a 3x3 inhomogeneous matrix. This is equivalent to call getInternalMatrix().
      Specified by:
      asInhomogeneousMatrix in class Rotation3D
      Returns:
      Rotation matrix expressed in inhomogeneous coordinates.

    • asInhomogeneousMatrix

      public void asInhomogeneousMatrix(com.irurueta.algebra.Matrix result)
      Sets into provided Matrix instance this 3D rotation expressed as a 3x3 inhomogeneous matrix.
      Specified by:
      asInhomogeneousMatrix in class Rotation3D
      Parameters:
      result - Matrix where rotation will be set.
      Throws:
      IllegalArgumentException - Raised if provided instance does not have size 3x3.

    • asHomogeneousMatrix

      public com.irurueta.algebra.Matrix asHomogeneousMatrix()
      Returns this 3D rotation instance expressed as a 4x4 homogeneous matrix.
      Specified by:
      asHomogeneousMatrix in class Rotation3D
      Returns:
      Rotation matrix expressed in homogeneous coordinates.

    • asHomogeneousMatrix

      public void asHomogeneousMatrix(com.irurueta.algebra.Matrix result)
      Sets into provided Matrix instance this 3D rotation expressed as a 4x4 homogeneous matrix.
      Specified by:
      asHomogeneousMatrix in class Rotation3D
      Parameters:
      result - Matrix where rotation will be set.
      Throws:
      IllegalArgumentException - Raised if provided instance does not have size 4x4.

    • fromInhomogeneousMatrix

      public void fromInhomogeneousMatrix(com.irurueta.algebra.Matrix m, double threshold) throws InvalidRotationMatrixException
      Sets amount of rotation from provided inhomogeneous rotation matrix. Provided matrix must be orthogonal (i.e. squared, non-singular, it's transpose must be its inverse) and must have determinant equal to 1. Provided matrix must also have size 3x3.
      Specified by:
      fromInhomogeneousMatrix in class Rotation3D
      Parameters:
      m - Provided rotation matrix.
      threshold - Threshold to determine whether matrix is orthonormal.
      Throws:
      InvalidRotationMatrixException - Raised if provided matrix is not valid (has wrong size, or it is not orthonormal).
      IllegalArgumentException - Raised if provided threshold is negative. Rotation3D.isValidRotationMatrix(Matrix).

    • fromHomogeneousMatrix

      public void fromHomogeneousMatrix(com.irurueta.algebra.Matrix m, double threshold) throws InvalidRotationMatrixException
      Sets amount of rotation from provided homogeneous rotation matrix. Provided matrix must be orthogonal (i.e. squared, non-singular, it's transpose must be its inverse) and must have determinant equal to 1. Provided matrix must also have size 4x4, and its last row and column must be zero, except for element in last row and column which must be 1.
      Specified by:
      fromHomogeneousMatrix in class Rotation3D
      Parameters:
      m - Provided rotation matrix.
      threshold - Threshold to determine whether matrix is orthonormal.
      Throws:
      InvalidRotationMatrixException - Raised if provided matrix is not valid (has wrong size, or it is not orthonormal).
      IllegalArgumentException - Raised if provided threshold is negative. Rotation3D.isValidRotationMatrix(Matrix).

    • rotate

      public void rotate(Point3D inputPoint, Point3D resultPoint)
      Rotates a 3D point using the origin of coordinates as the axis of rotation. Point will be rotated by the amount of rotation contained in this instance.
      Specified by:
      rotate in class Rotation3D
      Parameters:
      inputPoint - Input point to be rotated.
      resultPoint - Rotated point.

    • combineAndReturnNew

      public MatrixRotation3D combineAndReturnNew(MatrixRotation3D rotation)
      Combines provided rotation with this rotation and returns the result as a new MatrixRotation3D instance.
      Parameters:
      rotation - Input rotation to be combined.
      Returns:
      Combined rotation, which is equal to the multiplication of the internal matrix of provided rotation with the internal matrix of this instance.

    • combineAndReturnNew

      public Rotation3D combineAndReturnNew(Rotation3D rotation)
      Combines provided rotation with this rotation and returns the result as a new MatrixRotation3D instance.
      Specified by:
      combineAndReturnNew in class Rotation3D
      Parameters:
      rotation - Input rotation to be combined.
      Returns:
      Combined rotation, which is equal to the multiplication of the internal matrix of provided rotation with the internal matrix of this instance.

    • combine

      public void combine(MatrixRotation3D rotation)
      Combines provided rotation into this rotation resulting in the multiplication of the internal matrices of both rotations.
      Parameters:
      rotation - Input rotation to be combined.

    • combine

      public void combine(Rotation3D rotation)
      Combines provided rotation into this rotation resulting in the multiplication of the internal matrices of both rotations.
      Specified by:
      combine in class Rotation3D
      Parameters:
      rotation - Input rotation to be combined.

    • combine

      public static void combine(MatrixRotation3D rot1, MatrixRotation3D rot2, MatrixRotation3D result)
      Combines the rotation of instances rot1 and rot1 into provided result instance.
      Parameters:
      rot1 - 1st input rotation.
      rot2 - 2nd input rotation.
      result - Combined rotation, which is equal to the multiplication of the internal matrix of provided rotation with the internal matrix of this instance.

    • fromRotation

      public void fromRotation(MatrixRotation3D rot)
      Sets values of this rotation from a 3D matrix rotation.
      Overrides:
      fromRotation in class Rotation3D
      Parameters:
      rot - 3D matrix rotation to set values from.

    • fromRotation

      public void fromRotation(Quaternion q)
      Sets values of this rotation from a quaternion.
      Specified by:
      fromRotation in class Rotation3D
      Parameters:
      q - a quaternion to set values from.

    • toMatrixRotation

      public void toMatrixRotation(MatrixRotation3D result)
      Converts this 3D rotation into a matrix rotation storing the result into provided instance.
      Overrides:
      toMatrixRotation in class Rotation3D
      Parameters:
      result - instance where result wil be stored.

    • toAxisRotation

      public void toAxisRotation(AxisRotation3D result)
      Converts this 3D rotation into an axis rotation storing the result into provided instance.
      Overrides:
      toAxisRotation in class Rotation3D
      Parameters:
      result - instance where result will be stored.

    • toQuaternion

      public void toQuaternion(Quaternion result)
      Converts this 3D rotation into a quaternion storing the result into provided instance.
      Overrides:
      toQuaternion in class Rotation3D
      Parameters:
      result - instance where result will be stored.