Author: luc
Date: Sun Apr 11 11:54:22 2010
New Revision: 932871
URL: http://svn.apache.org/viewvc?rev=932871&view=rev
Log:
improved javadoc, mainly explaining the underlying conventions with quaternions
Jira: MATH-363
Modified:
commons/proper/math/trunk/src/main/java/org/apache/commons/math/geometry/Rotation.java
Modified:
commons/proper/math/trunk/src/main/java/org/apache/commons/math/geometry/Rotation.java
URL:
http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math/geometry/Rotation.java?rev=932871&r1=932870&r2=932871&view=diff
==============================================================================
---
commons/proper/math/trunk/src/main/java/org/apache/commons/math/geometry/Rotation.java
(original)
+++
commons/proper/math/trunk/src/main/java/org/apache/commons/math/geometry/Rotation.java
Sun Apr 11 11:54:22 2010
@@ -32,12 +32,12 @@ import org.apache.commons.math.MathRunti
* user can build a rotation from any of these representations, and
* any of these representations can be retrieved from a
* <code>Rotation</code> instance (see the various constructors and
- * getters). In addition, a rotation can also be built implicitely
+ * getters). In addition, a rotation can also be built implicitly
* from a set of vectors and their image.</p>
* <p>This implies that this class can be used to convert from one
* representation to another one. For example, converting a rotation
* matrix into a set of Cardan angles from can be done using the
- * followong single line of code:</p>
+ * following single line of code:</p>
* <pre>
* double[] angles = new Rotation(matrix,
1.0e-10).getAngles(RotationOrder.XYZ);
* </pre>
@@ -49,20 +49,22 @@ import org.apache.commons.math.MathRunti
* meaning of these vectors may vary and the semantics of the rotation
also.</p>
* <p>For example in an spacecraft attitude simulation tool, users will often
* consider the vectors are fixed (say the Earth direction for example) and the
- * rotation transforms the coordinates coordinates of this vector in inertial
+ * frames change. The rotation transforms the coordinates of the vector in
inertial
* frame into the coordinates of the same vector in satellite 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
+ * case, the rotation implicitly defines the relation between the two
frames.</p>
+ * <p>Another example could be a telescope control application, where the
rotation
* would transform the sighting direction at rest into the desired observing
* direction when the telescope is pointed towards an object of interest. In
this
- * case the rotation transforms the directionf at rest in a topocentric frame
- * into the sighting direction in the same topocentric frame. 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.</p>
+ * case the rotation transforms the direction at rest in a topocentric frame
+ * into the sighting direction in the same topocentric frame. This implies in
this
+ * case the frame is fixed and the vector moves.</p>
+ * <p>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, which would essentially be an application
of the
+ * first approach.</p>
*
- * <p>These examples show that a rotation is what the user wants it to be, so
this
+ * <p>These examples show that a rotation is what the user wants it to be. This
* class does not push the user towards one specific definition and hence does
not
* provide methods like <code>projectVectorIntoDestinationFrame</code> or
* <code>computeTransformedDirection</code>. It provides simpler and more
generic
@@ -114,6 +116,10 @@ public class Rotation implements Seriali
* q<sub>1</sub><sup>2</sup> + q<sub>2</sub><sup>2</sup> +
* q<sub>3</sub><sup>2</sup> = 1. If the quaternion is not normalized,
* the constructor can normalize it in a preprocessing step.</p>
+ * <p>Note that some conventions put the scalar part of the quaternion
+ * as the 4<sup>th</sup> component and the vector part as the first three
+ * components. This is <em>not</em> our convention. We put the scalar part
+ * as the first component.</p>
* @param q0 scalar part of the quaternion
* @param q1 first coordinate of the vectorial part of the quaternion
* @param q2 second coordinate of the vectorial part of the quaternion
@@ -145,9 +151,19 @@ public class Rotation implements Seriali
* <p>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
+ * the axis and π/2 as the angle to this constructor, and then
* {...@link #applyTo(Vector3D) apply} the instance to +i, we will get
* +j.</p>
+ * <p>Another way to represent our convention is to say that a rotation
+ * of angle θ about the unit vector (x, y, z) is the same as the
+ * rotation build from quaternion components { cos(-θ/2),
+ * x * sin(-θ/2), y * sin(-θ/2), z * sin(-θ/2) }.
+ * Note the minus sign on the angle!</p>
+ * <p>On the one hand this convention is consistent with a vectorial
+ * perspective (moving vectors in fixed frames), on the other hand it
+ * is different from conventions with a frame perspective (fixed vectors
+ * viewed from different frames) like the ones used for example in spacecraft
+ * attitude community or in the graphics community.</p>
* @param axis axis around which to rotate
* @param angle rotation angle.
* @exception ArithmeticException if the axis norm is zero
@@ -528,6 +544,7 @@ public class Rotation implements Seriali
/** Get the normalized axis of the rotation.
* @return normalized axis of the rotation
+ * @see #Rotation(Vector3D, double)
*/
public Vector3D getAxis() {
double squaredSine = q1 * q1 + q2 * q2 + q3 * q3;
@@ -543,6 +560,7 @@ public class Rotation implements Seriali
/** Get the angle of the rotation.
* @return angle of the rotation (between 0 and π)
+ * @see #Rotation(Vector3D, double)
*/
public double getAngle() {
if ((q0 < -0.1) || (q0 > 0.1)) {
