maspack.matrix

Class RotationMatrix3d

• All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, DenseMatrix, LinearTransformNd, Matrix, Clonable

public class RotationMatrix3d
extends Matrix3dBase
A specialized 3 x 3 orthogonal matrix, with determinant 1, that described a three-dimensional rotation.

This is used to rotate a 3 dimensional vector from one coordinate frame into another. If v0 and v1 denote the vector in the original frame 0 and target frame 1, respectively, then the rotation is computed according to

v1 = R v0

where R is the rotation matrix. The columns of R represent the directions of the axes of frame 0 with respect to frame 1.

If R01 is a rotation from frame 0 to frame 1, and R12 is a rotation from frame 1 to frame 2, then the rotation from frame 0 to frame 2 is given by the product

R02 = R12 R01

In this way, a rotation can be created by multiplying a series of sub-rotations.

If R01 is a rotation from frame 0 to frame 1, then the inverse rotation R10 is a rotation from frame 1 to frame 0, and is given by the transpose of R.

Serialized Form
• Field Detail

• IDENTITY

public static final RotationMatrix3d IDENTITY
Global identity rotation. Should not be modified.
• ROT_X_90

public static final RotationMatrix3d ROT_X_90
Global rotation defined by rotating 90 degrees counter-clockwise about the x axis. If used to defined an "eye" to "world" viewing transform, the resulting z direction in eye coordinates is "up". Should not be modified.
• AXIS_ANGLE_STRING

public static final int AXIS_ANGLE_STRING
Specifies a string representation of this rotation as a 4-tuple consisting of a rotation axis and the corresponding angle (in degrees).
Constant Field Values
• MATRIX_STRING

public static final int MATRIX_STRING
Specifies a string representation of this rotation as a 3 x 3 matrix.
Constant Field Values
• Constructor Detail

• RotationMatrix3d

public RotationMatrix3d(double m00,
double m01,
double m02,
double m10,
double m11,
double m12,
double m20,
double m21,
double m22)
Creates a new rotation initialized to the specified entries.

NOTE: the user is responsible for ensuring the that specified matrix is orthogonal.

• RotationMatrix3d

public RotationMatrix3d(double[] m)
Creates a new rotation initialized to the specified entries. Stored in row major.

NOTE: the user is responsible for ensuring the that specified matrix is orthogonal.

• RotationMatrix3d

public RotationMatrix3d()
Creates a new rotation initialized to the identity.
• RotationMatrix3d

public RotationMatrix3d(AxisAngle axisAng)
Creates a new rotation specified by a rotation about an axis.
Parameters:
axisAng - gives the rotation axis and corresponding angle
• RotationMatrix3d

public RotationMatrix3d(Quaternion quat)
Creates a new rotation specified by a quaternion.
Parameters:
quat - quaternion specifying the rotation.
• RotationMatrix3d

public RotationMatrix3d(Vector3d u,
double ang)
Creates a new rotation specified by a rotation about an axis.
Parameters:
u - gives the rotation axis
• RotationMatrix3d

public RotationMatrix3d(double ux,
double uy,
double uz,
double ang)
Creates a new rotation specified by a rotation about an axis.
Parameters:
ux - axis x coordinate
uy - axis y coordinate
uz - axis z coordinate
• RotationMatrix3d

public RotationMatrix3d(RotationMatrix3d R)
Creates a new rotation which is a copy of an existing one.
Parameters:
R - rotation to copy
• Method Detail

• mul

public void mul(RotationMatrix3d R1)
Post-multiplies this rotation by another and places the result in this rotation.
Parameters:
R1 - rotation to multiply by
• mul

public void mul(RotationMatrix3d R1,
RotationMatrix3d R2)
Multiplies rotation R1 by R2 and places the result in this rotation.
Parameters:
R1 - first rotation
R2 - second rotation
• mulInverse

public void mulInverse(RotationMatrix3d R1)
Post-multiplies this rotation by the inverse of rotation R1 and places the result in this rotation.
Parameters:
R1 - right-hand rotation
• mulInverseLeft

public void mulInverseLeft(RotationMatrix3d R1,
RotationMatrix3d R2)
Multiplies the inverse of rotation R1 by rotation R2 and places the result in this rotation.
Parameters:
R1 - left-hand rotation
R2 - right-hand rotation
• mulInverseRight

public void mulInverseRight(RotationMatrix3d R1,
RotationMatrix3d R2)
Multiplies rotation R1 by the inverse of rotation R2 and places the result in this rotation.
Parameters:
R1 - left-hand rotation
R2 - right-hand rotation
• mulInverseBoth

public void mulInverseBoth(RotationMatrix3d R1,
RotationMatrix3d R2)
Multiplies the inverse of rotation R1 by the inverse of rotation R2 and places the result in this rotation.
Parameters:
R1 - left-hand rotation
R2 - right-hand rotation
• invert

public boolean invert()
Inverts this rotation in place. This is the same as taking the transpose of the matrix.
Overrides:
invert in class Matrix3dBase
• invert

public boolean invert(RotationMatrix3d R1)
Inverts rotation R1 and places the result in this rotation. This is the same as taking the transpose of R1.
Parameters:
R1 - rotation to invert
• transpose

public void transpose()
Transposes this rotation in place. This is the same as taking the inverse of the matrix.
Overrides:
transpose in class Matrix3dBase
• transpose

public void transpose(RotationMatrix3d R1)
Transposes rotation R1 and places the result in this rotation. This is the same as taking the invesre of R1.
Parameters:
R1 - rotation to transpose
• negate

public void negate()
Negates this rotation in place.
Overrides:
negate in class Matrix3dBase
• mulInverse

public boolean mulInverse(Vector3d vr,
Vector3d v1)
Multiplies the column vector v1 by the inverse of this matrix and places the result in vr. This is equivalent to solve(vr,v1).
Overrides:
mulInverse in class Matrix3dBase
Parameters:
vr - result vector
v1 - vector to multiply by
Returns:
true (matrix is never singular)
• mulInverse

public boolean mulInverse(Vector3d vr)
Multiplies the column vector vr by the inverse of this matrix and places the result back in vr.
Overrides:
mulInverse in class Matrix3dBase
Parameters:
vr - vector to multiply by (in place)
Returns:
true (matrix is never singular)
• mulInverseTranspose

public boolean mulInverseTranspose(Vector3d vr,
Vector3d v1)
Multiplies the column vector v1 by the inverse transpose of this matrix and places the result in vr. For a rotation matrix, this is equivalent to simply multiplying by the matrix.
Overrides:
mulInverseTranspose in class Matrix3dBase
Parameters:
vr - result vector
v1 - vector to multiply by
Returns:
true (matrix is never singular)
• mulInverseTranspose

public boolean mulInverseTranspose(Vector3d vr)
Multiplies vector vr by the inverse transpose of this matrix, in place. For a rotation matrix, this is equivalent to simply multiplying by the matrix.
Overrides:
mulInverseTranspose in class Matrix3dBase
Parameters:
vr - vector to multiply
Returns:
true (matrix is never singular)
• normalize

public void normalize()
Normalizes this rotation, so as to ensure that its its columns are orthonormal. This is done as follows: the third column is renormalized, then the first column is recomputed as the normalized cross product of the second and third columns, and finally the second column is recomputed as the cross product of the third and first columns.
• setXYDirections

public void setXYDirections(Vector3d xdir,
Vector3d ydir)
Sets this rotation using two vectors to indicate the directions of the x and y axes. The z axis is then formed from their cross product. The x, y, and z axes correspond to the first, second, and third matrix columns. xdir and ydir must be non-zero and non-parallel or an exception will be thrown.

xdir and ydir do not need to be perpendicular. The x axis is formed by normalizing xdir. The z axis is then found by normalizing the cross product of x and ydir. Finally, the y axis is determined from the cross product of the z and x axes.

Parameters:
xdir - direction for the x axis
ydir - indicates direction for the y axis (not necessarily perpendicular to xdir)
Throws:
java.lang.IllegalArgumentException - if xdir or ydir are zero, or if they are parallel.
• setYZDirections

public void setYZDirections(Vector3d ydir,
Vector3d zdir)
Sets this rotation using two vectors to indicate the directions of the y and z axes. The y axis is then formed from their cross product. The x, y, and z axes correspond to the first, second, and third matrix columns. ydir and zdir must be non-zero and non-parallel or an exception will be thrown.

ydir and zdir do not need to be perpendicular. The y axis is formed by normalizing ydir. The x axis is then found by normalizing the cross product of y and zdir. Finally, the z axis is determined from the cross product of the x and y axes.

Parameters:
ydir - direction for the y axis
zdir - indicates direction for the z axis (not necessarily perpendicular to ydir)
Throws:
java.lang.IllegalArgumentException - if ydir or zdir are zero, or if they are parallel.
• setZXDirections

public void setZXDirections(Vector3d zdir,
Vector3d xdir)
Sets this rotation using two vectors to indicate the directions of the z and x axes. The y axis is then formed from their cross product. The x, y, and z axes correspond to the first, second, and third matrix columns. zdir and xdir must be non-zero and non-parallel or an exception will be thrown.

zdir and xdir do not need to be perpendicular. The z axis is formed by normalizing zdir. The y axis is then found by normalizing the cross product of z and xdir. Finally, the x axis is determined from the cross product of the y and z axes.

Parameters:
zdir - direction for the z axis
xdir - indicates direction for the x axis (not necessarily perpendicular to xdir)
Throws:
java.lang.IllegalArgumentException - if zdir or xdir are zero, or if they are parallel.
• set

public void set(Quaternion q)
Sets this rotation to one represented by the quaternion q.
Parameters:
q - quaternion representing the rotation
• set

public void set(double m00,
double m01,
double m02,
double m10,
double m11,
double m12,
double m20,
double m21,
double m22)
Sets this rotation explicitly from the supplied matrix entries. This method calls normalize to ensure that the resulting matrix is orthogonal.
Parameters:
m00 - element (0,0)
m01 - element (0,1)
m02 - element (0,2)
m10 - element (1,0)
m11 - element (1,1)
m12 - element (1,2)
m20 - element (2,0)
m21 - element (2,1)
m22 - element (2,2)
• setAxisAngle

public void setAxisAngle(AxisAngle axisAng)
Sets this rotation to one produced by rotating about an axis.
Parameters:
axisAng - gives the rotation axis and corresponding angle
• setAxisAnglePrecise

public void setAxisAnglePrecise(AxisAngle axisAng)
Sets this rotation to one produced by rotating about an axis. If the angle is an exact multiple of 90 degrees and the axis is a primary axis, create an exact representation.
Parameters:
axisAng - gives the rotation axis and corresponding angle
• setAxisAngle

public void setAxisAngle(Vector3d axis,
double ang)
Sets this rotation to one produced by rotating about an axis.
Parameters:
axis - gives the rotation axis
• setAxisAngle

public void setAxisAngle(double ux,
double uy,
double uz,
double ang)
Sets the rotation to one produced by rotating about an axis. The axis does not have to be of unit length.
Parameters:
ux - axis x coordinate
uy - axis y coordinate
uz - axis z coordinate
• setRotX

public void setRotX(double ang)
Sets this rotation to one produced by rotating about the x axis.
Parameters:
ang - angle of rotation (radians)
• mulRotX

public void mulRotX(double ang)
Post-multiplies this rotation by an implicit second rotation consisting of a rotation about the x axis, and places the result in this rotation.
Parameters:
ang - angle (radians) for the second rotation
• mulRotX90

public void mulRotX90()
Post-multiplies this rotation by an implicit second rotation consisting of a rotation of 90 degrees about the x axis, and places the result in this rotation. This method is supplied in order to provide an exact numerical answer for this special case.
• mulRotX180

public void mulRotX180()
Post-multiplies this rotation by an implicit second rotation consisting of a rotation of 180 degrees about the x axis, and places the result in this rotation. This method is supplied in order to provide an exact numerical answer for this special case.
• mulRotX270

public void mulRotX270()
Post-multiplies this rotation by an implicit second rotation consisting of a rotation of 270 degrees about the x axis, and places the result in this rotation. This method is supplied in order to provide an exact numerical answer for this special case.
• setRotY

public void setRotY(double ang)
Sets this rotation to one produced by rotating about the y axis.
Parameters:
ang - angle of rotation (radians)
• mulRotY

public void mulRotY(double ang)
Post-multiplies this rotation by an implicit second rotation consisting of a rotation about the y axis, and places the result in this rotation.
Parameters:
ang - angle (radians) for the second rotation
• mulRotY90

public void mulRotY90()
Post-multiplies this rotation by an implicit second rotation consisting of a rotation of 90 degrees about the x axis, and places the result in this rotation. This method is supplied in order to provide an exact numerical answer for this special case.
• mulRotY180

public void mulRotY180()
Post-multiplies this rotation by an implicit second rotation consisting of a rotation of 180 degrees about the x axis, and places the result in this rotation. This method is supplied in order to provide an exact numerical answer for this special case.
• mulRotY270

public void mulRotY270()
Post-multiplies this rotation by an implicit second rotation consisting of a rotation of 270 degrees about the x axis, and places the result in this rotation. This method is supplied in order to provide an exact numerical answer for this special case.
• setRotZ

public void setRotZ(double ang)
Sets this rotation to one produced by rotating about the z axis.
Parameters:
ang - angle of rotation (radians)
• mulRotZ

public void mulRotZ(double ang)
Post-multiplies this rotation by an implicit second rotation consisting of a rotation about the z axis, and places the result in this rotation.
Parameters:
ang - angle (radians) for the second rotation
• mulRotZ90

public void mulRotZ90()
Post-multiplies this rotation by an implicit second rotation consisting of a rotation of 90 degrees about the x axis, and places the result in this rotation. This method is supplied in order to provide an exact numerical answer for this special case.
• mulRotZ180

public void mulRotZ180()
Post-multiplies this rotation by an implicit second rotation consisting of a rotation of 180 degrees about the x axis, and places the result in this rotation. This method is supplied in order to provide an exact numerical answer for this special case.
• mulRotZ270

public void mulRotZ270()
Post-multiplies this rotation by an implicit second rotation consisting of a rotation of 270 degrees about the x axis, and places the result in this rotation. This method is supplied in order to provide an exact numerical answer for this special case.
• mulAxisAngle

public void mulAxisAngle(double ux,
double uy,
double uz,
double ang)
Post-multiplies this rotation by an implicit second rotation expressed as an axis-angle, and places the result in this rotation.
Parameters:
ux - rotation axis x component
uy - rotation axis y component
uz - rotation axis z component
ang - rotation angle (in radians)
• mulAxisAngle

public void mulAxisAngle(Vector3d u,
double ang)
Post-multiplies this rotation by an implicit second rotation expressed as an axis-angle, and places the result in this rotation.
Parameters:
u - rotation axis
ang - rotation angle (in radians)
• mulAxisAngle

public void mulAxisAngle(AxisAngle axisAng)
Post-multiplies this rotation by an implicit second rotation expressed as an axis-angle, and places the result in this rotation.
Parameters:
axisAng - axis-angle representation of the rotation
• getAxisAngle

public AxisAngle getAxisAngle()
Returns the axis-angle parameters corresponding to this rotation.
Returns:
axis-angle parameters
• getAxisAngle

public void getAxisAngle(AxisAngle axisAng)
Returns the axis-angle parameters corresponding to this rotation.
Parameters:
axisAng - axis-angle parameters
• setRpy

public void setRpy(double roll,
double pitch,
double yaw)
Sets this rotation to one produced by roll-pitch-yaw angles. The coordinate frame corresponding to these angles is produced by a rotation of roll about the z axis, followed by a rotation of pitch about the new y axis, and finally a rotation of yaw about the new x axis.
Parameters:
getRpy(double[])
• setRpy

public void setRpy(double[] angs)
Sets this rotation to one produced by roll-pitch-yaw angles.
Parameters:
angs - contains the angles (roll, pitch, and yaw, in that order) in radians.
setRpy(double,double,double)
• mulRpy

public void mulRpy(double roll,
double pitch,
double yaw)
Post-multiplies this rotation by an implicit second rotation expressed by roll-pitch-yaw angles, and places the result in this rotation.
Parameters:
• getRpy

public void getRpy(double[] angs)
Gets the roll-pitch-yaw angles corresponding to this rotation.
Parameters:
angs - returns the angles (roll, pitch, and yaw, in that order) in radians.
setRpy(double,double,double)
• setXyz

public void setXyz(double rx,
double ry,
double rz)
Sets this rotation to one produced by a sequence of intrinsic rotations about the x-y-z axes. More specifically, the rotation is produced by a rotation rx about the x axis, followed by a rotation ry about the new y axis, and finally a rotation rz about the new z axis.
Parameters:
getXyz(double[])
• setXyz

public void setXyz(double[] angs)
Sets this rotation to one produced by a sequence of successive rotations about the x-y-z axes.
Parameters:
angs - contains the angles (rx, ry, and rz, in that order) in radians.
setXyz(double,double,double)
• mulXyz

public void mulXyz(double rx,
double ry,
double rz)
Post-multiplies this rotation by an implicit second rotation expressed by a sequence of intrinsic rotations about the x-y-z axes.
Parameters:
setXyz(double,double,double)
• getXyz

public void getXyz(double[] angs)
Gets the x-y-z rotation angles corresponding to this rotation. This is the inverse of setXyz(double,double,double).
Parameters:
angs - returns the x-y-z angles (rx, ry, and rz, in that order) in radians.
• setEuler

public void setEuler(double phi,
double theta,
double psi)
Sets this rotation to one produced by Euler angles. The coordinate frame corresponding to Euler angles is produced by a rotation of phi about the z axis, followed by a rotation of theta about the new y axis, and finally a rotation of psi about the new x axis.
Parameters:
phi - first Euler angle (radians)
theta - second Euler angle (radians)
psi - third Euler angle (radians)
getEuler(double[])
• setEuler

public void setEuler(double[] angs)
Sets this rotation to one produced by Euler angles.
Parameters:
angs - contains the Euler angles (phi, theta, and psi, in that order) in radians.
setEuler(double,double,double)
• mulEuler

public void mulEuler(double phi,
double theta,
double psi)
Post-multiplies this rotation by an implicit second rotation described by Euler angles, and places the result in this rotation.
Parameters:
phi - first Euler angle (radians)
theta - second Euler angle (radians)
psi - third Euler angle (radians)
setEuler(double,double,double)
• getEuler

public void getEuler(double[] angs)
Gets the Euler angles corresponding to this rotation.
Parameters:
angs - returns the Euler angles (phi, theta, and psi, in that order) in radians.
setEuler(double,double,double)
• setZDirection

public void setZDirection(Vector3d dirz)
Sets this rotation to one in which the z axis points in a specified direction. The x and y axes are set to corresponding values that are ``nearest'' to the identity. If dirz is zero, the rotation is set the identity.
Parameters:
dirz - direction for the new z axis. Does not need to be normalized.
• setXDirection

public void setXDirection(Vector3d dirx)
Sets this rotation to one in which the x axis points in a specified direction. The y and z axes are set to corresponding values that are ``nearest'' to the identity. If dirx is zero, the rotation is set the identity.
Parameters:
dirx - direction for the new x axis. Does not need to be normalized.
• setYDirection

public void setYDirection(Vector3d diry)
Sets this rotation to one in which the y axis points in a specified direction. The z and x axes are set to corresponding values that are ``nearest'' to the identity. If diry is zero, the rotation is set the identity.
Parameters:
diry - direction for the new y axis. Does not need to be normalized.
• rotateZDirection

public void rotateZDirection(Vector3d dirz)
Rotates this rotation so that the z axis points in a specified direction. This is done by rotating about an axis perpendicular to the orginal and new z axes.
Parameters:
dirz - direction for the new z axis
• setRandom

public void setRandom()
Sets this rotation to one produced by rotating about a random axis by a random angle.
• setRandom

public void setRandom(java.util.Random generator)
Sets this rotation to one produced by rotating about a random axis by a random angle, using a supplied random number generator.
Parameters:
generator - random number generator
• getAxisAngle

public double getAxisAngle(Vector3d axis)
Gets the rotation axis-angle representation for this rotation. To keep the representation unique, the axis is normalized and the angle is kept in the range 0 <= angle < Math.PI.
Parameters:
axis - returns the rotation axis
Returns:
• isAxisAligned

public boolean isAxisAligned(double tol)
Returns true if this rotation transformtion is axis-aligned - that is, if all entries consist of either 1, -1, or 0. Entries must equal these values within a tolerance specified by tol. The implementation for this method assumes that the entries are properly formed for a rotation matrix.
Parameters:
tol - tolerance to test whether entries are zero or one.
Returns:
true if this rotation is axis-aligned.
• checkOrthonormality

public void checkOrthonormality()
• isAxisAligned

public boolean isAxisAligned()
Returns true if this rotation transformtion is axis-aligned - that is, if all entries consist of either 1, -1, or 0.
Returns:
true if this rotation is axis-aligned.
• toString

public java.lang.String toString()
Returns a string representation of this transformation as a 3 x 3 matrix.
Overrides:
toString in class MatrixBase
Returns:
String representation of this matrix
MatrixBase.toString(String)
• toString

public java.lang.String toString(java.lang.String numberFmtStr)
Returns a string representation of this transformation as a 3 x 3 matrix, with each number formatted according to a supplied numeric format.
Specified by:
toString in interface Matrix
Overrides:
toString in class MatrixBase
Parameters:
numberFmtStr - numeric format string (see NumberFormat)
Returns:
String representation of this vector
NumberFormat
• toString

public java.lang.String toString(java.lang.String numberFmtStr,
int outputCode)
Returns a specified string representation of this transformation, with each number formatted according to the a supplied numeric format.
Parameters:
numberFmtStr - numeric format string (see NumberFormat)
outputCode - desired representation, which should be either AXIS_ANGLE_STRING or MATRIX_STRING
• toString

public java.lang.String toString(NumberFormat numberFmt,
int outputCode)
Returns a specified string representation of this transformation, with each number formatted according to the a supplied numeric format.
Parameters:
numberFmt - numeric format
outputCode - desired representation, which should be either AXIS_ANGLE_STRING or MATRIX_STRING
• scan

throws java.io.IOException
Reads the contents of this rotation from a ReaderTokenizer. There are two allowed formats, each of which is delimited by square brackets.

The first format is a set of 4 numbers describing the rotation in axis-angle notation. The rotation axis is given first, followed by the rotation angle, in degrees. The axis does not need to be normalized. For example,

[ 0 1 0 90 ]

defines a rotation of 90 degrees about the y axis.

The second format format is a set of 9 numbers describing the elements of the rotation matrix in row-major order. For example,

[ 0  -1  0
1   0  0
0   0  1 ]

defines a rotation of 90 degrees about the z axis.

The third format consists of a series of simple rotations, which are the multiplied together to form a final rotation. The following simple rotations may be specified:

rotX ang
A rotation of "ang" degrees about the x axis;
rotY ang
A rotation of "ang" degrees about the y axis;
rotZ ang
A rotation of "ang" degrees about the z axis;
For example, the string
[ rotX 45 rotZ 90 ]

describes a rotation which is the product of a rotation of 45 degrees about the y axis and rotation of 90 degrees about the z axis.
Specified by:
scan in interface Matrix
Overrides:
scan in class MatrixBase
Parameters:
rtok - ReaderTokenizer from which to read the rotation. Number parsing should be enabled.
Throws:
java.io.IOException - if an I/O error occured or if the rotation description is not consistent with one of the above formats.
• main

public static void main(java.lang.String[] args)