Class Rotation3D

java.lang.Object
com.irurueta.geometry.Rotation3D
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
AxisRotation3D, MatrixRotation3D, Quaternion

public abstract class Rotation3D extends Object implements Serializable
Abstract class representing a rotation in 3D space. Subclasses of this class will implement the interface of this class.
See Also:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final double
    Default threshold to determine if two instances are equal.
    static final Rotation3DType
    Constant defining default type if none is provided.
    static final double
    Constant defining threshold to determine whether a matrix is orthogonal or not and has determinant equal to 1.
    static final int
    Constant defining number of homogeneous 3D coordinates.
    static final int
    Constant defining number of inhomogeneous 3D coordinates.
    private static final double
    Constant defining minimum allowed comparison threshold.
    static final double
    Constant defining minimum allowed threshold.
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Empty constructor.
  • Method Summary

    Modifier and Type
    Method
    Description
    abstract com.irurueta.algebra.Matrix
    Returns this 3D rotation instance expressed as a 4x4 homogeneous matrix.
    abstract void
    asHomogeneousMatrix(com.irurueta.algebra.Matrix result)
    Sets into provided Matrix instance this 3D rotation expressed as a 4x4 homogeneous matrix.
    abstract com.irurueta.algebra.Matrix
    Returns this 3D rotation instance expressed as a 3x3 inhomogeneous matrix.
    abstract void
    asInhomogeneousMatrix(com.irurueta.algebra.Matrix result)
    Sets into provided Matrix instance this 3D rotation expressed as a 3x3 inhomogeneous matrix.
    abstract void
    combine(Rotation3D rotation)
    Combines provided rotation into this rotation resulting in the multiplication of the internal matrices of both rotations.
    abstract Rotation3D
    Combines provided rotation with this rotation and returns the result as a new Rotation3D instance.
    static Rotation3D
    Factory method.
    static Rotation3D
    create(double[] axis, double theta)
    Factory method.
    static Rotation3D
    create(double[] axis, double theta, Rotation3DType type)
    Factory method.
    static Rotation3D
    create(double axisX, double axisY, double axisZ, double theta)
    Factory method.
    static Rotation3D
    create(double axisX, double axisY, double axisZ, double theta, Rotation3DType type)
    Factory method.
    static Rotation3D
    Factory method.
    boolean
    Determines if two Rotation3D instances are equal or not (i.e. have the same rotation).
    boolean
    equals(Rotation3D other, double threshold)
    Determines if two Rotation3D instances are equal up to provided threshold or not (i.e. have the same rotation).
    boolean
    Determines if two Rotation3D instances are equal or not (i.e. have the same rotation).
    void
    fromHomogeneousMatrix(com.irurueta.algebra.Matrix m)
    Sets amount of rotation from provided homogeneous rotation matrix.
    abstract void
    fromHomogeneousMatrix(com.irurueta.algebra.Matrix m, double threshold)
    Sets amount of rotation from provided homogeneous rotation matrix.
    void
    fromInhomogeneousMatrix(com.irurueta.algebra.Matrix m)
    Sets amount of rotation from provided inhomogeneous rotation matrix.
    abstract void
    fromInhomogeneousMatrix(com.irurueta.algebra.Matrix m, double threshold)
    Sets amount of rotation from provided inhomogeneous rotation matrix.
    final void
    fromMatrix(com.irurueta.algebra.Matrix m)
    Sets amount of rotation from provided rotation matrix.
    final void
    fromMatrix(com.irurueta.algebra.Matrix m, double threshold)
    Sets amount of rotation from provided rotation matrix.
    void
    Sets values of this rotation from a 3D axis rotation.
    void
    Sets values of this rotation from a 3D matrix rotation.
    abstract void
    Sets values of this rotation from a quaternion.
    void
    Sets values of this rotation from another rotation.
    abstract double
    Returns rotation amount or angle in radians around the rotation axis associated to this instance.
    double[]
    Returns rotation axis corresponding to this instance as a new array containing axis coordinates.
    Returns type of this rotation.
    int
    Hash code to compare instances.
    abstract void
    Reverses the rotation of this instance.
    abstract void
    Sets into provided Rotation3D instance a rotation inverse to this instance.
    abstract Rotation3D
    Returns a 3D rotation which is inverse to this instance.
    static boolean
    isValidRotationMatrix(com.irurueta.algebra.Matrix m)
    Returns boolean indicating whether provided matrix is a valid matrix for a rotation.
    static boolean
    isValidRotationMatrix(com.irurueta.algebra.Matrix m, double threshold)
    Returns boolean indicating whether provided matrix is a valid matrix for a rotation.
    rotate(Plane plane)
    Returns a plane containing a rotated version of provided plane.
    void
    rotate(Plane inputPlane, Plane resultPlane)
    Rotates a plane using the origin of coordinates as the axis of rotation.
    rotate(Point3D point)
    Returns a 3D point containing a rotated version of provided point.
    abstract void
    rotate(Point3D inputPoint, Point3D resultPoint)
    Rotates a 3D point using the origin of coordinates as the axis of rotation.
    abstract void
    rotationAxis(double[] axis)
    Returns rotation axis corresponding to this instance.
    final void
    setAxisAndRotation(double[] axis, double theta)
    Sets the axis and rotation of this instance.
    abstract void
    setAxisAndRotation(double axisX, double axisY, double axisZ, double theta)
    Sets the axis and rotation of this instance.
    Converts this 3D rotation into an axis rotation and returns the result as a new instance.
    void
    Converts this 3D rotation into an axis rotation storing the result into provided instance.
    Converts this 3D rotation into a matrix rotation and returns the result as a new instance.
    void
    Converts this 3D rotation into a matrix rotation storing the result into provided instance.
    Converts this 3D rotation into a quaternion and returns the result as a new instance.
    void
    Converts this 3D rotation into a quaternion storing the result into provided instance.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • DEFAULT_VALID_THRESHOLD

      public static final double DEFAULT_VALID_THRESHOLD
      Constant defining threshold to determine whether a matrix is orthogonal or not and has determinant equal to 1. Rotation matrices must fulfill those requirements.
      See Also:
    • MIN_THRESHOLD

      public static final double MIN_THRESHOLD
      Constant defining minimum allowed threshold.
      See Also:
    • INHOM_COORDS

      public static final int INHOM_COORDS
      Constant defining number of inhomogeneous 3D coordinates.
      See Also:
    • HOM_COORDS

      public static final int HOM_COORDS
      Constant defining number of homogeneous 3D coordinates.
      See Also:
    • DEFAULT_TYPE

      public static final Rotation3DType DEFAULT_TYPE
      Constant defining default type if none is provided.
    • DEFAULT_COMPARISON_THRESHOLD

      public static final double DEFAULT_COMPARISON_THRESHOLD
      Default threshold to determine if two instances are equal.
      See Also:
    • MIN_COMPARISON_THRESHOLD

      private static final double MIN_COMPARISON_THRESHOLD
      Constant defining minimum allowed comparison threshold.
      See Also:
  • Constructor Details

    • Rotation3D

      protected Rotation3D()
      Empty constructor.
  • Method Details

    • getType

      public abstract Rotation3DType getType()
      Returns type of this rotation.
      Returns:
      Type of this rotation.
    • setAxisAndRotation

      public final void setAxisAndRotation(double[] axis, 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).
      Parameters:
      axis - Array of length 3 containing axis coordinates.
      theta - Amount of rotation in radians.
      Throws:
      IllegalArgumentException - Raised if provided axis array does not have length 3.
    • setAxisAndRotation

      public abstract 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).
      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.
    • getRotationAxis

      public double[] getRotationAxis() throws RotationException
      Returns rotation axis corresponding to this instance as a new array containing axis coordinates.
      Returns:
      Rotation axis coordinates.
      Throws:
      RotationException - Raised if numerical instabilities happen.
    • rotationAxis

      public abstract 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.
      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.
    • getRotationAngle

      public abstract double getRotationAngle() throws RotationException
      Returns rotation amount or angle in radians around the rotation axis associated to this instance.
      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 abstract Rotation3D 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.
      Returns:
      Inverse 3D rotation.
    • inverseRotation

      public abstract void inverseRotation(Rotation3D result)
      Sets into provided Rotation3D 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 abstract void inverseRotation()
      Reverses the rotation of this instance.
    • asInhomogeneousMatrix

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

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

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

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

      public final void fromMatrix(com.irurueta.algebra.Matrix m, double threshold) throws InvalidRotationMatrixException
      Sets amount of rotation from provided 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 can be expressed in either inhomogeneous (3x3) or homogeneous (4x4) coordinates.
      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. isValidRotationMatrix(Matrix)
    • fromMatrix

      public final void fromMatrix(com.irurueta.algebra.Matrix m) throws InvalidRotationMatrixException
      Sets amount of rotation from provided 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 can be expressed in either inhomogeneous (3x3) or homogeneous (4x4) coordinates. Because threshold is not provided it is used DEFAULT_VALID_THRESHOLD instead.
      Parameters:
      m - Provided rotation matrix.
      Throws:
      InvalidRotationMatrixException - Raised if provided matrix is not valid (has wrong size, or it is not orthonormal). isValidRotationMatrix(Matrix)
    • fromInhomogeneousMatrix

      public abstract 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.
      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. isValidRotationMatrix(Matrix)
    • fromInhomogeneousMatrix

      public void fromInhomogeneousMatrix(com.irurueta.algebra.Matrix m) 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. Because threshold is not provided it is used DEFAULT_VALID_THRESHOLD instead.
      Parameters:
      m - Provided rotation matrix.
      Throws:
      InvalidRotationMatrixException - Raised if provided matrix is not valid (has wrong size, or it is not orthonormal). isValidRotationMatrix(Matrix)
    • fromHomogeneousMatrix

      public abstract 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.
      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. isValidRotationMatrix(Matrix)
    • fromHomogeneousMatrix

      public void fromHomogeneousMatrix(com.irurueta.algebra.Matrix m) throws InvalidRotationMatrixException
      Sets amount of rotation from provided homogeneous rotation matrix. Provided matrix must be orthogonal (i.e. squared, non-singular), its transpose must be its inverse and must have determinant equal to 1. Provided matrix must also have size exe, and its last row and column must be zero, except for element in last row and column which must be 1 Because threshold is not provided it is used DEFAULT_VALID_THRESHOLD instead.
      Parameters:
      m - Provided rotation matrix.
      Throws:
      InvalidRotationMatrixException - Raised if provided matrix is not valid (has wrong size, or it is not orthonormal). isValidRotationMatrix(Matrix)
    • rotate

      public abstract 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.
      Parameters:
      inputPoint - Input point to be rotated.
      resultPoint - Rotated point.
    • rotate

      public Point3D rotate(Point3D point)
      Returns a 3D point containing a rotated version of provided point. Point will be rotated using the origin of the coordinates as the axis of rotation. Point will be rotated by the amount of rotation contained in this instance.
      Parameters:
      point - Point to be rotated.
      Returns:
      Rotated point.
    • rotate

      public void rotate(Plane inputPlane, Plane resultPlane)
      Rotates a plane using the origin of coordinates as the axis of rotation. Plane will be rotated by the amount of rotation contained in this instance.
      Parameters:
      inputPlane - Input plane to be rotated.
      resultPlane - plane where result is stored.
    • rotate

      public Plane rotate(Plane plane)
      Returns a plane containing a rotated version of provided plane. Plane will be rotated using the origin of the coordinates as the axis of rotation. Plane will be rotated by the amount of rotation contained in this instance.
      Parameters:
      plane - Plane to be rotated.
      Returns:
      Rotated plane.
    • isValidRotationMatrix

      public static boolean isValidRotationMatrix(com.irurueta.algebra.Matrix m, double threshold)
      Returns boolean indicating whether provided matrix is a valid matrix for a rotation. Rotation matrices must be orthogonal and must have determinant equal to 1.
      Parameters:
      m - Input matrix to be checked.
      threshold - Threshold to determine whether matrix is orthogonal and whether determinant is one.
      Returns:
      True if matrix is valid, false otherwise.
      Throws:
      IllegalArgumentException - Raised if provided threshold is negative.
    • isValidRotationMatrix

      public static boolean isValidRotationMatrix(com.irurueta.algebra.Matrix m)
      Returns boolean indicating whether provided matrix is a valid matrix for a rotation. Rotation matrices must be orthogonal and must have determinant equal to 1 Because threshold is not provided, it is used DEFAULT_VALID_THRESHOLD instead.
      Parameters:
      m - Input matrix to be checked.
      Returns:
      True if matrix is valid, false otherwise.
      Throws:
      IllegalArgumentException - Raised if provided threshold is negative.
    • combineAndReturnNew

      public abstract Rotation3D combineAndReturnNew(Rotation3D rotation)
      Combines provided rotation with this rotation and returns the result as a new Rotation3D 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.
    • combine

      public abstract void combine(Rotation3D 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.
    • create

      public static Rotation3D create()
      Factory method. Creates a rotation that has no effect on geometric objects using default type.
      Returns:
      A 3D rotation.
    • create

      public static Rotation3D create(Rotation3DType type)
      Factory method. Creates a rotation that has no effect on geometric objects using provided type.
      Parameters:
      type - Rotation type.
      Returns:
      A 3D rotation.
    • create

      public static Rotation3D create(double[] axis, double theta)
      Factory method. Creates a 3D rotation using provided axis and rotation angle. Note: to increase accuracy axis coordinates should be normalized.
      Parameters:
      axis - Array containing rotation axis coordinates.
      theta - Rotation angle around axis expressed in radians.
      Returns:
      A 3D rotation instance.
      Throws:
      IllegalArgumentException - Raised if provided axis array does not have length 3.
    • create

      public static Rotation3D create(double[] axis, double theta, Rotation3DType type)
      Factory method. Creates a 3D rotation using provided axis, rotation angle and rotation type. Note: to increase accuracy axis coordinates should be normalized.
      Parameters:
      axis - Array containing rotation axis coordinates.
      theta - Rotation angle around axis expressed in radians.
      type - Rotation type.
      Returns:
      A 3D rotation instance.
      Throws:
      IllegalArgumentException - Raised if provided axis array does not have length 3.
    • create

      public static Rotation3D create(double axisX, double axisY, double axisZ, double theta)
      Factory method. Creates a 3D rotation using provided axis coordinates and rotation angle. Note: to increase accuracy axis coordinates should be normalized.
      Parameters:
      axisX - X coordinate of axis.
      axisY - Y coordinate of axis.
      axisZ - Z coordinate of axis.
      theta - Rotation angle around axis expressed in radians.
      Returns:
      A 3D rotation instance.
    • create

      public static Rotation3D create(double axisX, double axisY, double axisZ, double theta, Rotation3DType type)
      Factory method. Creates a 3D rotation using provided axis coordinates, rotation angle and rotation type. Note: to increase accuracy axis coordinates should be normalized.
      Parameters:
      axisX - X coordinate of axis.
      axisY - Y coordinate of axis.
      axisZ - Z coordinate of axis.
      theta - Rotation angle around axis expressed in radians.
      type - Rotation type.
      Returns:
      A 3D rotation instance.
    • equals

      public boolean equals(Rotation3D other, double threshold) throws RotationException
      Determines if two Rotation3D instances are equal up to provided threshold or not (i.e. have the same rotation).
      Parameters:
      other - other rotation to compare.
      threshold - threshold to determine if they are equal.
      Returns:
      true if they are equal, false otherwise.
      Throws:
      IllegalArgumentException - if threshold is negative.
      RotationException - if rotation angle or axis cannot be determined.
    • equals

      public boolean equals(Rotation3D other)
      Determines if two Rotation3D instances are equal or not (i.e. have the same rotation).
      Parameters:
      other - other object to compare.
      Returns:
      true if they are equal, false otherwise.
    • equals

      public boolean equals(Object obj)
      Determines if two Rotation3D instances are equal or not (i.e. have the same rotation).
      Overrides:
      equals in class Object
      Parameters:
      obj - other object to compare.
      Returns:
      true if they are equal, false otherwise.
    • hashCode

      public int hashCode()
      Hash code to compare instances.
      Overrides:
      hashCode in class Object
      Returns:
      hash code to compare instances.
    • fromRotation

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

      public void fromRotation(AxisRotation3D rot)
      Sets values of this rotation from a 3D axis rotation.
      Parameters:
      rot - an axis rotation to set values from.
    • fromRotation

      public abstract void fromRotation(Quaternion q)
      Sets values of this rotation from a quaternion.
      Parameters:
      q - a quaternion to set values from.
    • fromRotation

      public void fromRotation(Rotation3D rot)
      Sets values of this rotation from another rotation.
      Parameters:
      rot - a 3D rotation to set values from.
      Throws:
      IllegalArgumentException - if provided rotation type is not supported. Only Rotation3DType.AXIS_ROTATION3D, Rotation3DType.MATRIX_ROTATION3D and Rotation3DType.QUATERNION are supported.
    • toMatrixRotation

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

      public MatrixRotation3D toMatrixRotation()
      Converts this 3D rotation into a matrix rotation and returns the result as a new instance.
      Returns:
      a new 3D matrix rotation equivalent to this rotation.
    • toAxisRotation

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

      public AxisRotation3D toAxisRotation()
      Converts this 3D rotation into an axis rotation and returns the result as a new instance.
      Returns:
      a new axis rotation equivalent to this rotation.
    • toQuaternion

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

      public Quaternion toQuaternion()
      Converts this 3D rotation into a quaternion and returns the result as a new instance.
      Returns:
      a new quaternion equivalent to this rotation.