Package com.irurueta.geometry
Class Rotation3D
java.lang.Object
com.irurueta.geometry.Rotation3D
- All Implemented Interfaces:
Serializable
- Direct Known Subclasses:
AxisRotation3D,MatrixRotation3D,Quaternion
Abstract class representing a rotation in 3D space.
Subclasses of this class will implement the interface of this class.
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final doubleDefault threshold to determine if two instances are equal.static final Rotation3DTypeConstant defining default type if none is provided.static final doubleConstant defining threshold to determine whether a matrix is orthogonal or not and has determinant equal to 1.static final intConstant defining number of homogeneous 3D coordinates.static final intConstant defining number of inhomogeneous 3D coordinates.private static final doubleConstant defining minimum allowed comparison threshold.static final doubleConstant defining minimum allowed threshold. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionabstract com.irurueta.algebra.MatrixReturns this 3D rotation instance expressed as a 4x4 homogeneous matrix.abstract voidasHomogeneousMatrix(com.irurueta.algebra.Matrix result) Sets into provided Matrix instance this 3D rotation expressed as a 4x4 homogeneous matrix.abstract com.irurueta.algebra.MatrixReturns this 3D rotation instance expressed as a 3x3 inhomogeneous matrix.abstract voidasInhomogeneousMatrix(com.irurueta.algebra.Matrix result) Sets into provided Matrix instance this 3D rotation expressed as a 3x3 inhomogeneous matrix.abstract voidcombine(Rotation3D rotation) Combines provided rotation into this rotation resulting in the multiplication of the internal matrices of both rotations.abstract Rotation3DcombineAndReturnNew(Rotation3D rotation) Combines provided rotation with this rotation and returns the result as a new Rotation3D instance.static Rotation3Dcreate()Factory method.static Rotation3Dcreate(double[] axis, double theta) Factory method.static Rotation3Dcreate(double[] axis, double theta, Rotation3DType type) Factory method.static Rotation3Dcreate(double axisX, double axisY, double axisZ, double theta) Factory method.static Rotation3Dcreate(double axisX, double axisY, double axisZ, double theta, Rotation3DType type) Factory method.static Rotation3Dcreate(Rotation3DType type) Factory method.booleanequals(Rotation3D other) Determines if two Rotation3D instances are equal or not (i.e. have the same rotation).booleanequals(Rotation3D other, double threshold) Determines if two Rotation3D instances are equal up to provided threshold or not (i.e. have the same rotation).booleanDetermines if two Rotation3D instances are equal or not (i.e. have the same rotation).voidfromHomogeneousMatrix(com.irurueta.algebra.Matrix m) Sets amount of rotation from provided homogeneous rotation matrix.abstract voidfromHomogeneousMatrix(com.irurueta.algebra.Matrix m, double threshold) Sets amount of rotation from provided homogeneous rotation matrix.voidfromInhomogeneousMatrix(com.irurueta.algebra.Matrix m) Sets amount of rotation from provided inhomogeneous rotation matrix.abstract voidfromInhomogeneousMatrix(com.irurueta.algebra.Matrix m, double threshold) Sets amount of rotation from provided inhomogeneous rotation matrix.final voidfromMatrix(com.irurueta.algebra.Matrix m) Sets amount of rotation from provided rotation matrix.final voidfromMatrix(com.irurueta.algebra.Matrix m, double threshold) Sets amount of rotation from provided rotation matrix.voidSets values of this rotation from a 3D axis rotation.voidSets values of this rotation from a 3D matrix rotation.abstract voidSets values of this rotation from a quaternion.voidfromRotation(Rotation3D rot) Sets values of this rotation from another rotation.abstract doubleReturns 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.abstract Rotation3DTypegetType()Returns type of this rotation.inthashCode()Hash code to compare instances.abstract voidReverses the rotation of this instance.abstract voidinverseRotation(Rotation3D result) Sets into provided Rotation3D instance a rotation inverse to this instance.abstract Rotation3DReturns a 3D rotation which is inverse to this instance.static booleanisValidRotationMatrix(com.irurueta.algebra.Matrix m) Returns boolean indicating whether provided matrix is a valid matrix for a rotation.static booleanisValidRotationMatrix(com.irurueta.algebra.Matrix m, double threshold) Returns boolean indicating whether provided matrix is a valid matrix for a rotation.Returns a plane containing a rotated version of provided plane.voidRotates a plane using the origin of coordinates as the axis of rotation.Returns a 3D point containing a rotated version of provided point.abstract voidRotates a 3D point using the origin of coordinates as the axis of rotation.abstract voidrotationAxis(double[] axis) Returns rotation axis corresponding to this instance.final voidsetAxisAndRotation(double[] axis, double theta) Sets the axis and rotation of this instance.abstract voidsetAxisAndRotation(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.voidtoAxisRotation(AxisRotation3D result) 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.voidtoMatrixRotation(MatrixRotation3D result) 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.voidtoQuaternion(Quaternion result) Converts this 3D rotation into a quaternion storing the result into provided instance.
-
Field Details
-
DEFAULT_VALID_THRESHOLD
public static final double DEFAULT_VALID_THRESHOLDConstant 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_THRESHOLDConstant defining minimum allowed threshold.- See Also:
-
INHOM_COORDS
public static final int INHOM_COORDSConstant defining number of inhomogeneous 3D coordinates.- See Also:
-
HOM_COORDS
public static final int HOM_COORDSConstant defining number of homogeneous 3D coordinates.- See Also:
-
DEFAULT_TYPE
Constant defining default type if none is provided. -
DEFAULT_COMPARISON_THRESHOLD
public static final double DEFAULT_COMPARISON_THRESHOLDDefault threshold to determine if two instances are equal.- See Also:
-
MIN_COMPARISON_THRESHOLD
private static final double MIN_COMPARISON_THRESHOLDConstant defining minimum allowed comparison threshold.- See Also:
-
-
Constructor Details
-
Rotation3D
protected Rotation3D()Empty constructor.
-
-
Method Details
-
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
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
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
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
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
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
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
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
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
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
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
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
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
Factory method. Creates a rotation that has no effect on geometric objects using default type.- Returns:
- A 3D rotation.
-
create
Factory method. Creates a rotation that has no effect on geometric objects using provided type.- Parameters:
type- Rotation type.- Returns:
- A 3D rotation.
-
create
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
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
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
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
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
Determines if two Rotation3D instances are equal or not (i.e. have the same rotation). -
hashCode
public int hashCode()Hash code to compare instances. -
fromRotation
Sets values of this rotation from a 3D matrix rotation.- Parameters:
rot- 3D matrix rotation to set values from.
-
fromRotation
Sets values of this rotation from a 3D axis rotation.- Parameters:
rot- an axis rotation to set values from.
-
fromRotation
Sets values of this rotation from a quaternion.- Parameters:
q- a quaternion to set values from.
-
fromRotation
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. OnlyRotation3DType.AXIS_ROTATION3D,Rotation3DType.MATRIX_ROTATION3DandRotation3DType.QUATERNIONare supported.
-
toMatrixRotation
Converts this 3D rotation into a matrix rotation storing the result into provided instance.- Parameters:
result- instance where result wil be stored.
-
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
Converts this 3D rotation into an axis rotation storing the result into provided instance.- Parameters:
result- instance where result will be stored.
-
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
Converts this 3D rotation into a quaternion storing the result into provided instance.- Parameters:
result- instance where result will be stored.
-
toQuaternion
Converts this 3D rotation into a quaternion and returns the result as a new instance.- Returns:
- a new quaternion equivalent to this rotation.
-