maspack.matrix
Class RotationMatrix3d

java.lang.Object
  maspack.matrix.MatrixObject
      maspack.matrix.Matrix3dObject
          maspack.matrix.RotationMatrix3d

All Implemented Interfaces:

java.io.Serializable

public class RotationMatrix3d

extends Matrix3dObject

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 orginal 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.

See Also:

Serialized Form

Field Summary

static 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).
static int	MATRIX_STRING Specifies a string representation of this rotation as a 3 x 3 matrix.

Fields inherited from class maspack.matrix.Matrix3dObject

m00, m01, m02, m10, m11, m12, m20, m21, m22

Constructor Summary

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

RotationMatrix3d(AxisAngle axisAng)
Creates a new rotation specified by a rotation about an axis.

RotationMatrix3d(double ux, double uy, double uz, double ang)
Creates a new rotation specified by a rotation about an axis.

RotationMatrix3d(Quaternion quat)
Creates a new rotation specified by a quaternion.

RotationMatrix3d(RotationMatrix3d R)
Creates a new rotation which is a copy of an existing one.

Method Summary

void	getAxisAngle(AxisAngle axisAng) Returns the axis-angle parameters corresponding to this rotation.
double	getAxisAngle(Vector3d axis) Gets the rotation axis-angle representation for this rotation.
void	getEuler(double[] angs) Gets the Euler angles corresponding to this rotation.
void	getRpy(double[] angs) Gets the roll-pitch-yaw angles corresponding to this rotation.
boolean	invert() Inverts this rotation in place.
boolean	invert(RotationMatrix3d R1) Inverts rotation R1 and places the result in this rotation.
static void	main(java.lang.String[] args)
void	mul(RotationMatrix3d R1) Post-multiplies this rotation by another and places the result in this rotation.
void	mul(RotationMatrix3d R1, RotationMatrix3d R2) Multiplies rotation R1 by R2 and places the result in this rotation.
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.
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.
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.
void	mulInverse(RotationMatrix3d R1) Post-multiplies this rotation by the inverse of rotation R1 and places the result in this rotation.
boolean	mulInverse(Vector3d vr) Multiplies the column vector vr by the inverse of this matrix and places the result back in vr.
boolean	mulInverse(Vector3d vr, Vector3d v1) Multiplies the column vector v1 by the inverse of this matrix and places the result in vr.
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.
void	mulInverseLeft(RotationMatrix3d R1, RotationMatrix3d R2) Multiplies the inverse of rotation R1 by rotation R2 and places the result in this rotation.
void	mulInverseRight(RotationMatrix3d R1, RotationMatrix3d R2) Multiplies rotation R1 by the inverse of rotation R2 and places the result in this rotation.
boolean	mulInverseTranspose(Vector3d vr) Multiplies vector vr by the inverse transpose of this matrix, in place.
boolean	mulInverseTranspose(Vector3d vr, Vector3d v1) Multiplies the column vector v1 by the inverse transpose of this matrix and places the result in vr.
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.
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.
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.
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.
void	negate() Negates this rotation in place.
void	normalize() Normalizes this rotation, so as to ensure that its its columns are orthonormal.
void	scan(java.io.StreamTokenizer stok) Reads the contents of this rotation from a StreamTokenizer.
void	set(Quaternion q) Sets this rotation to one represented by the quaternion q.
void	setAxisAngle(AxisAngle axisAng) Sets this rotation to one produced by rotating about an axis.
void	setAxisAngle(double ux, double uy, double uz, double ang) Sets the rotation to one produced by rotating about an axis.
void	setEuler(double[] angs) Sets this rotation to one produced by Euler angles.
void	setEuler(double phi, double theta, double psi) Sets this rotation to one produced by Euler angles.
void	setRandom() Sets this rotation to one produced by rotating about a random axis by a random angle.
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.
void	setRotX(double ang) Sets this rotation to one produced by rotating about the x axis.
void	setRotY(double ang) Sets this rotation to one produced by rotating about the y axis.
void	setRotZ(double ang) Sets this rotation to one produced by rotating about the z axis.
void	setRpy(double[] angs) Sets this rotation to one produced by Euler angles.
void	setRpy(double roll, double pitch, double yaw) Sets this rotation to one produced by roll-pitch-yaw angles.
void	setZDirection(Vector3d dirz) Sets this rotation to one in which the z axis points in a specified direction.
java.lang.String	toString() Returns a string representation of this transformation as a 3 x 3 matrix.
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.
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.
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.
void	transpose() Transposes this rotation in place.
void	transpose(RotationMatrix3d R1) Transposes rotation R1 and places the result in this rotation.

Methods inherited from class maspack.matrix.Matrix3dObject

colSize, determinant, epsilonEquals, equals, frobeniusNorm, get, get, getColumn, getColumn, getRow, getRow, infinityNorm, mul, mul, mulTranspose, mulTranspose, oneNorm, rowSize, set, set, set, setColumn, setColumn, setIdentity, setRow, setRow

Methods inherited from class maspack.matrix.MatrixObject

epsilonEquals, equals, equals, get, getColumn, getRow, isFixedSize, set, set, setColumn, setRow, setSize, toString

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

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).

See Also:

Constant Field Values

MATRIX_STRING

public static final int MATRIX_STRING

Specifies a string representation of this rotation as a 3 x 3 matrix.

See Also:

Constant Field Values

Constructor Detail

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(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

ang - angle of rotation about the axis (radians)

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 Matrix3dObject

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 Matrix3dObject

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 Matrix3dObject

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.

Overrides:

mulInverse in class Matrix3dObject

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 Matrix3dObject

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 Matrix3dObject

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 Matrix3dObject

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.

set

public void set(Quaternion q)

Sets this rotation to one represented by the quaternion q.

Parameters:

q - quaternion representing the rotation

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

setAxisAngle

public void setAxisAngle(double ux,
                         double uy,
                         double uz,
                         double ang)

Sets the rotation to one produced by rotating about an axis.

Parameters:

ux - axis x coordinate

uy - axis y coordinate

uz - axis z coordinate

ang - angle of rotation about the axis (radians)

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

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

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

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(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 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:

roll - first angle (radians)

pitch - second angle (radians)

yaw - third angle (radians)

See Also:

getRpy(double[])

setRpy

public void setRpy(double[] angs)

Sets this rotation to one produced by Euler angles.

Parameters:

angs - contains the angles (roll, pitch, and yaw, in that order) in radians.

See Also:

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:

roll - first angle (radians)

pitch - second angle (radians)

yaw - third angle (radians)

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.

See Also:

setRpy(double,double,double)

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 z axis.

Parameters:

phi - first Euler angle (radians)

theta - second Euler angle (radians)

psi - third Euler angle (radians)

See Also:

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.

See Also:

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)

See Also:

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.

See Also:

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. 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.

Parameters:

axis - returns the rotation axis

Returns:

the rotation angle (in radians)

toString

public java.lang.String toString()

Returns a string representation of this transformation as a 3 x 3 matrix.

Overrides:

toString in class MatrixObject

Returns:

String representation of this matrix

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.

Overrides:

toString in class MatrixObject

Parameters:

numberFmtStr - numeric format string (see NumberFormat)

Returns:

String representation of this matrix

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

public void scan(java.io.StreamTokenizer stok)
          throws java.io.IOException

Reads the contents of this rotation from a StreamTokenizer. 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.

Note:This method disables numeric parsing in the StreamTokenizer. This is because the method does its own numeric parsing, in order to handle exponents.

Overrides:

scan in class MatrixObject

Parameters:

stok - StreamTokenizer from which to read the rotation

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)