

PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 
java.lang.Object org.jscience.mathematics.geometry.Rotation3D
public class Rotation3D
This class implements rotations in a threedimensional space.
Rotations can be represented by several different mathematical
entities (matrices, axe and angle, Cardan or Euler angles,
quaternions). This class is an higher level abstraction, more
useroriented and hiding this implementation detail. Well, for the
curious, we use quaternions for the internal representation. The
user can build a rotation from any of these representations, and
any of these representations can be retrieved from a
Rotation
instance (see the various constructors and
getters). In addition, a rotation can also be built implicitely
from a set of vectors before and after it has been applied. This
means that this class can be used to compute transformations from
one representation to another one. For example, extracting a set of
Cardan angles from a rotation matrix can be done using one single
line of code:
double[] angles = new Rotation(matrix, 1.0e10).getAngles(RotationOrder.XYZ);
Focus is more oriented on what a rotation do. Once it
has been built, and regardless of its representation, a rotation is
an operator which basically transforms three dimensional
vectors
into other three dimensional vectors
. Depending on the application, the meaning of
these vectors can vary. For example in an attitude simulation tool,
you will often consider the vector is fixed and you transform its
coordinates in one frame into its coordinates in another frame. In
this case, the rotation implicitely defines the relation between
the two frames. Another example could be a telescope control application,
where the rotation would transform the sighting direction at rest
into the desired observing direction. In this case the frame is the
same (probably a topocentric one) and the raw and transformed
vectors are different. In many case, both approaches will be
combined, in our telescope example, we will probably also need to
transform the observing direction in the topocentric frame into the
observing direction in inertial frame taking into account the
observatory location and the earth rotation.
These examples show that a rotation is what the user wants it to
be, so this class does not push the user towards one specific
definition and hence does not provide methods like
projectVectorIntoDestinationFrame
or
computeTransformedDirection
. It provides simpler and
more generic methods: applyTo(Vector3D)
and applyInverseTo(Vector3D)
.
Since a rotation is basically a vectorial operator, several
rotations can be composed together and the composite operation
r = r1 o r2
(which means that for each vector
u
, r(u) = r1(r2(u))
) is also a
rotation. Hence we can consider that in addition to vectors, a
rotation can be applied to other rotations (or to itself). With our
previous notations, we would say we can apply r1
to
r2
and the result we get is r = r1 o
r2
. For this purpose, the class provides the methods: applyTo(Rotation)
and applyInverseTo(Rotation)
.
Vector3D
,
Rotation3DOrder
,
Serialized FormConstructor Summary  

Rotation3D()
Build the identity rotation. 

Rotation3D(double[][] m,
double threshold)
Build a rotation from a 3X3 matrix. 

Rotation3D(double q0,
double q1,
double q2,
double q3)
Build a rotation from the quaternion coordinates. 

Rotation3D(Rotation3D r)
Copy constructor. 

Rotation3D(Rotation3DOrder order,
double alpha1,
double alpha2,
double alpha3)
Build a rotation from three Cardan or Euler elementary rotations. 

Rotation3D(Vector3D axis,
double angle)
Build a rotation from an axis and an angle. 

Rotation3D(Vector3D u,
Vector3D v)
Build one of the rotations that transform one vector into another one. 

Rotation3D(Vector3D u1,
Vector3D u2,
Vector3D v1,
Vector3D v2)
Build the rotation that transforms a pair of vector into another pair. 
Method Summary  

Rotation3D 
applyInverseTo(Rotation3D r)
Apply the inverse of the instance to another rotation. 
Vector3D 
applyInverseTo(Vector3D u)
Apply the inverse of the rotation to a vector. 
Rotation3D 
applyTo(Rotation3D r)
Apply the instance to another rotation. 
Vector3D 
applyTo(Vector3D u)
Apply the rotation to a vector. 
double 
getAngle()
Get the angle of the rotation. 
double[] 
getAngles(Rotation3DOrder order)
Get the Cardan or Euler angles corresponding to the instance. 
Vector3D 
getAxis()
Get the normalized axis of the rotation. 
double[][] 
getMatrix()
Get the 3X3 matrix corresponding to the instance 
double 
getQ0()
Get the scalar coordinate of the quaternion. 
double 
getQ1()
Get the first coordinate of the vectorial part of the quaternion. 
double 
getQ2()
Get the second coordinate of the vectorial part of the quaternion. 
double 
getQ3()
Get the third coordinate of the vectorial part of the quaternion. 
Rotation3D 
revert()
Revert a rotation. 
Methods inherited from class java.lang.Object 

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait 
Constructor Detail 

public Rotation3D()
public Rotation3D(double q0, double q1, double q2, double q3)
q0
 scalar part of the quaternionq1
 first coordinate of the vectorial part of the quaternionq2
 second coordinate of the vectorial part of the quaternionq3
 third coordinate of the vectorial part of the quaternionpublic Rotation3D(Vector3D axis, double angle)
We use the convention that angles are oriented according to
the effect of the rotation on vectors around the axis. That means
that if (i, j, k) is a direct frame and if we first provide +k as
the axis and PI/2 as the angle to this constructor, and then
apply
the instance to +i, we will get
+j.
axis
 axis around which to rotateangle
 rotation angle.
java.lang.ArithmeticException
 if the axis norm is nullpublic Rotation3D(double[][] m, double threshold) throws NotARotationMatrixException
Rotation matrices are orthogonal matrices, i.e. unit matrices (which are matrices for which m.mT = I) with real coefficients. The module of the determinant of unit matrices is 1, among the orthogonal 3X3 matrices, only the ones having a positive determinant (+1) are rotation matrices.
When a rotation is defined by a matrix with truncated values (typically when it is extracted from a technical sheet where only four to five significant digits are available), the matrix is not orthogonal anymore. This constructor handles this case transparently by using a copy of the given matrix and applying a correction to the copy in order to perfect its orthogonality. If the Frobenius norm of the correction needed is above the given threshold, then the matrix is considered to be too far from a true rotation matrix and an exception is thrown.
m
 rotation matrixthreshold
 convergence threshold for the iterative
orthogonality correction (convergence is reached when the
difference between two steps of the Frobenius norm of the
correction is below this threshold)
NotARotationMatrixException
 if the matrix is not a 3X3
matrix, or if it cannot be transformed into an orthogonal matrix
with the given threshold, or if the determinant of the resulting
orthogonal matrix is negativepublic Rotation3D(Vector3D u1, Vector3D u2, Vector3D v1, Vector3D v2)
Except for possible scale factors, if the instance were applied to the pair (u1, u2) it will produce the pair (v1, v2).
If the angular separation between u1 and u2 is not the same as the angular separation between v1 and v2, then a corrected v2' will be used rather than v2, the corrected vector will be in the (v1, v2) plane.
u1
 first vector of the origin pairu2
 second vector of the origin pairv1
 desired image of u1 by the rotationv2
 desired image of u2 by the rotationpublic Rotation3D(Vector3D u, Vector3D v)
Except for a possible scale factor, if the instance were applied to the vector u it will produce the vector v. There is an infinite number of such rotations, this constructor choose the one with the smallest associated angle (i.e. the one whose axis is orthogonal to the (u, v) plane). If u and v are colinear, an arbitrary rotation axis is chosen.
u
 origin vectorv
 desired image of u by the rotation
java.lang.ArithmeticException
 if the norm of one of the vectors is nullpublic Rotation3D(Rotation3DOrder order, double alpha1, double alpha2, double alpha3)
Cardan rotations are three successive rotations around the canonical axes X, Y and Z, each axis beeing used once. There are 6 such sets of rotations (XYZ, XZY, YXZ, YZX, ZXY and ZYX). Euler rotations are three successive rotations around the canonical axes X, Y and Z, the first and last rotations beeing around the same axis. There are 6 such sets of rotations (XYX, XZX, YXY, YZY, ZXZ and ZYZ), the most popular one being ZXZ. Beware that many people routinely use the term Euler angles even for what really are Cardan angles (this confusion is especially widespread in the aerospace business where Roll, Pitch and Yaw angles are often tagged as Euler angles).
order
 order of rotations to usealpha1
 angle of the first elementary rotationalpha2
 angle of the second elementary rotationalpha3
 angle of the third elementary rotationpublic Rotation3D(Rotation3D r)
r
 rotation to copyMethod Detail 

public Rotation3D revert()
public double getQ0()
public double getQ1()
public double getQ2()
public double getQ3()
public Vector3D getAxis()
public double getAngle()
public double[] getAngles(Rotation3DOrder order) throws CardanEulerSingularityException
The equations show that each rotation can be defined by two different values of the Cardan or Euler angles set. For example if Cardan angles are used, the rotation defined by the angles a1, a2 and a3 is the same as the rotation defined by the angles PI + a1, PI  a2 and PI + a3. This method implements the following arbitrary choices. For Cardan angles, the chosen set is the one for which the second angle is between PI/2 and PI/2 (i.e its cosine is positive). For Euler angles, the chosen set is the one for which the second angle is between 0 and PI (i.e its sine is positive).
Cardan and Euler angle have a very disappointing drawback: all of them have singularities. This means that if the instance is too close to the singularities corresponding to the given rotation order, it will be impossible to retrieve the angles. For Cardan angles, this is often called gimbal lock. There is nothing to do to prevent this, it is an intrisic problem of Cardan and Euler representation (but not a problem with the rotation itself, which is perfectly well defined). For Cardan angles, singularities occur when the second angle is close to PI/2 or +PI/2, for Euler angle singularities occur when the second angle is close to 0 or PI, this means that the identity rotation is always singular for Euler angles !
order
 rotation order to use
CardanEulerSingularityException
 if the rotation is
singular with respect to the angles set specifiedpublic double[][] getMatrix()
public Vector3D applyTo(Vector3D u)
u
 vector to apply the rotation to
public Vector3D applyInverseTo(Vector3D u)
u
 vector to apply the inverse of the rotation to
public Rotation3D applyTo(Rotation3D r)
r
 rotation to apply the rotation to
public Rotation3D applyInverseTo(Rotation3D r)
r
 rotation to apply the rotation to


PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 