# Quaternion Class Reference

The Quaternion class represents 3D rotations and orientations. More...

List of all members.

## Defining a Quaternion
| Quaternion ()
| Quaternion (const Vec &axis, double angle)
| Quaternion (const Vec &from, const Vec &to)
| Quaternion (double q0, double q1, double q2, double q3)
| Quaternion (const Quaternion &Q)
Quaternion & | operator= (const Quaternion &Q)
void | setAxisAngle (const Vec &axis, double angle)
void | setValue (double q0, double q1, double q2, double q3)
void | setFromRotationMatrix (const double m[3][3])
void | setFromRotatedBasis (const Vec &X, const Vec &Y, const Vec &Z)
## Accessing values
Vec | axis () const
float | angle () const
void | getAxisAngle (Vec &axis, float &angle) const
double | operator[] (int i) const
double & | operator[] (int i)
## Rotation computations
Quaternion & | operator*= (const Quaternion &q)
Vec | rotate (const Vec &v) const
Vec | inverseRotate (const Vec &v) const
Quaternion | operator* (const Quaternion &a, const Quaternion &b)
Vec | operator* (const Quaternion &q, const Vec &v)
## Inversion
Quaternion | inverse () const
void | invert ()
void | negate ()
double | normalize ()
Quaternion | normalized () const
## Associated matrix
const GLdouble * | matrix () const
void | getMatrix (GLdouble m[4][4]) const
void | getMatrix (GLdouble m[16]) const
void | getRotationMatrix (float m[3][3]) const
const GLdouble * | inverseMatrix () const
void | getInverseMatrix (GLdouble m[4][4]) const
void | getInverseMatrix (GLdouble m[16]) const
void | getInverseRotationMatrix (float m[3][3]) const
## Slerp interpolation
Quaternion | log ()
Quaternion | exp ()
static Quaternion | slerp (const Quaternion &a, const Quaternion &b, float t, bool allowFlip=true)
static Quaternion | squad (const Quaternion &a, const Quaternion &tgA, const Quaternion &tgB, const Quaternion &b, float t)
static double | dot (const Quaternion &a, const Quaternion &b)
static Quaternion | lnDif (const Quaternion &a, const Quaternion &b)
static Quaternion | squadTangent (const Quaternion &before, const Quaternion &center, const Quaternion &after)
## XML representation
| Quaternion (const QDomElement &element)
QDomElement | domElement (const QString &name, QDomDocument &document) const
void | initFromDOMElement (const QDomElement &element)
## Output stream
std::ostream & | operator<< (std::ostream &o, const qglviewer::Vec &)
## Random Quaternion
static Quaternion | randomQuaternion ()

## Detailed Description

The Quaternion class represents 3D rotations and orientations.

The Quaternion is an appropriate (although not very intuitive) representation for 3D rotations and orientations. Many tools are provided to ease the definition of a Quaternion: see constructors, setAxisAngle(), setFromRotationMatrix(), setFromRotatedBasis().

You can apply the rotation represented by the Quaternion to 3D points using rotate() and inverseRotate(). See also the Frame class that represents a coordinate system and provides other conversion functions like Frame::coordinatesOf() and Frame::transformOf().

You can apply the Quaternion `q` rotation to the OpenGL matrices using:

            glMultMatrixd(q.matrix());
            // equvalent to glRotate(q.angle()*180.0/M_PI, q.axis().x, q.axis().y, q.axis().z);

Quaternion is part of the `qglviewer` namespace, specify `qglviewer::Quaternion` or use the qglviewer namespace:

     using namespace qglviewer;

### Internal representation

The internal representation of a Quaternion corresponding to a rotation around axis `axis`, with an angle `alpha` is made of four doubles q[i]:

            {q[0],q[1],q[2]} = sin(alpha/2) * {axis[0],axis[1],axis[2]}
            q[3] = cos(alpha/2)

Note that certain implementations place the cosine term in first position (instead of last here).

The Quaternion is always normalized, so that its inverse() is actually its conjugate.

See also the Vec and Frame classes' documentations.

## Constructor & Destructor Documentation

Quaternion | ( |  | ) |

Default constructor, builds an identity rotation.

Quaternion | ( | const Vec & | axis,
|  | double | angle |
| ) |  |  |

Constructor from rotation axis (non null) and angle (in radians). See also setAxisAngle().

Quaternion | ( | const Vec & | from,
|  | const Vec & | to |
| ) |  |  |

Constructs a Quaternion that will rotate from the `from` direction to the `to` direction.

Note that this rotation is not uniquely defined. The selected axis is usually orthogonal to `from` and `to`, minimizing the rotation angle. This method is robust and can handle small or almost identical vectors.

Quaternion | ( | double | q0,
|  | double | q1,
|  | double | q2,
|  | double | q3 |
| ) |  |  |

Constructor from the four values of a Quaternion. First three values are axis*sin(angle/2) and last one is cos(angle/2).

Attention:
  The identity Quaternion is Quaternion(0,0,0,1) and not Quaternion(0,0,0,0) (which is not unitary). The default Quaternion() creates such identity Quaternion.

Quaternion | ( | const Quaternion & | Q | ) |

Copy constructor.

Quaternion | ( | const QDomElement & | element | ) | `[explicit]`

Constructs a Quaternion from a `QDomElement` representing an XML code of the form

     < anyTagName q0=".." q1=".." q2=".." q3=".." />

If one of these attributes is missing or is not a number, a warning is displayed and the associated value is respectively set to 0, 0, 0 and 1 (identity Quaternion).

See also domElement() and initFromDOMElement().

## Member Function Documentation

float angle | ( |  | ) | const

Returns the angle (in radians) of the rotation represented by the Quaternion.

This value is always in the range [0-pi]. Larger rotational angles are obtained by inverting the axis() direction.

See also axis() and getAxisAngle().

Vec axis | ( |  | ) | const

Returns the normalized axis direction of the rotation represented by the Quaternion.

It is null for an identity Quaternion. See also angle() and getAxisAngle().

QDomElement domElement | ( | const QString & | name,
|  | QDomDocument & | document |
| ) |  |  | const

Returns an XML `QDomElement` that represents the Quaternion.

`name` is the name of the QDomElement tag. `doc` is the `QDomDocument` factory used to create QDomElement.

When output to a file, the resulting QDomElement will look like:

     <name q0=".." q1=".." q2=".." q3=".." />

Use initFromDOMElement() to restore the Quaternion state from the resulting `QDomElement`. See also the Quaternion(const QDomElement&) constructor.

See the Vec::domElement() documentation for a complete QDomDocument creation and saving example.

See also Frame::domElement(), Camera::domElement(), KeyFrameInterpolator::domElement()...

static double dot | ( | const Quaternion & | a,
|  | const Quaternion & | b |
| ) |  |  | `[static]`

Returns the "dot" product of `a` and `b:` a[0]*b[0] + a[1]*b[1] + a[2]*b[2] + a[3]*b[3].

Quaternion exp | ( |  | ) |

Returns the exponential of the Quaternion. See also log().

void getAxisAngle | ( | Vec & | axis,
|  | float & | angle |
| ) |  |  | const

Returns the axis vector and the angle (in radians) of the rotation represented by the Quaternion. See the axis() and angle() documentations.

void getInverseMatrix | ( | GLdouble | m[16] | ) | const

Same as getInverseMatrix(), but with a `GLdouble`[16] parameter. See also getMatrix().

void getInverseMatrix | ( | GLdouble | m[4][4] | ) | const

Fills `m` with the OpenGL matrix corresponding to the inverse() rotation.

Use inverseMatrix() if you do not need to store this matrix and simply want to alter the current OpenGL matrix. See also getMatrix().

void getInverseRotationMatrix | ( | float | m[3][3] | ) | const

`m` is set to the 3x3 inverse rotation matrix associated with the Quaternion.

Attention:
  This is the classical mathematical rotation matrix. The OpenGL format uses its transposed version. See inverseMatrix() and getInverseMatrix().

void getMatrix | ( | GLdouble | m[16] | ) | const

Same as getMatrix(), but with a `GLdouble`[16] parameter. See also getInverseMatrix() and Frame::getMatrix().

void getMatrix | ( | GLdouble | m[4][4] | ) | const

Fills `m` with the OpenGL representation of the Quaternion rotation.

Use matrix() if you do not need to store this matrix and simply want to alter the current OpenGL matrix. See also getInverseMatrix() and Frame::getMatrix().

void getRotationMatrix | ( | float | m[3][3] | ) | const

Fills `m` with the 3x3 rotation matrix associated with the Quaternion.

See also getInverseRotationMatrix().

Attention:
  `m` uses the European mathematical representation of the rotation matrix. Use matrix() and getMatrix() to retrieve the OpenGL transposed version.

void initFromDOMElement | ( | const QDomElement & | element | ) |

Restores the Quaternion state from a `QDomElement` created by domElement().

The `QDomElement` should contain the `q0`, `q1` , `q2` and `q3` attributes. If one of these attributes is missing or is not a number, a warning is displayed and these fields are respectively set to 0.0, 0.0, 0.0 and 1.0 (identity Quaternion).

See also the Quaternion(const QDomElement&) constructor.

Quaternion inverse | ( |  | ) | const

Returns the inverse Quaternion (inverse rotation).

Result has a negated axis() direction and the same angle(). A composition (see operator*()) of a Quaternion and its inverse() results in an identity function.

Use invert() to actually modify the Quaternion.

const GLdouble * inverseMatrix | ( |  | ) | const

Returns the associated 4x4 OpenGL inverse rotation matrix. This is simply the matrix() of the inverse().

Attention:
  The result is only valid until the next call to inverseMatrix(). Use it immediately (as in `glMultMatrixd`(q.inverseMatrix())) or use getInverseMatrix() instead.
  The matrix is given in OpenGL format (row-major order) and is the transpose of the actual mathematical European representation. Consider using getInverseRotationMatrix() instead.

Vec inverseRotate | ( | const Vec & | v | ) | const

Returns the image of `v` by the Quaternion inverse() rotation.

rotate() performs an inverse transformation. Same as inverse().rotate(v).

void invert | ( |  | ) |

Inverses the Quaternion (same rotation angle(), but negated axis()).

See also inverse().

Quaternion lnDif | ( | const Quaternion & | a,
|  | const Quaternion & | b |
| ) |  |  | `[static]`

Returns log(a. inverse() * b). Useful for squadTangent().

Quaternion log | ( |  | ) |

Returns the logarithm of the Quaternion. See also exp().

const GLdouble * matrix | ( |  | ) | const

Returns the Quaternion associated 4x4 OpenGL rotation matrix.

Use `glMultMatrixd`(q.matrix()) to apply the rotation represented by Quaternion `q` to the current OpenGL matrix.

See also getMatrix(), getRotationMatrix() and inverseMatrix().

Attention:
  The result is only valid until the next call to matrix(). Use it immediately (as shown above) or consider using getMatrix() instead.
  The matrix is given in OpenGL format (row-major order) and is the transpose of the actual mathematical European representation. Consider using getRotationMatrix() instead.

void negate | ( |  | ) |

Negates all the coefficients of the Quaternion.

This results in an other representation of the same rotation (opposite rotation angle, but with a negated axis direction: the two cancel out). However, note that the results of axis() and angle() are unchanged after a call to this method since angle() always returns a value in [0,pi].

This method is mainly useful for Quaternion interpolation, so that the spherical interpolation takes the shortest path on the unit sphere. See slerp() for details.

double normalize | ( |  | ) |

Normalizes the Quaternion coefficients.

This method should not need to be called since we only deal with unit Quaternions. This is however useful to prevent numerical drifts, especially with small rotational increments. See also normalized().

Quaternion normalized | ( |  | ) | const

Returns a normalized version of the Quaternion.

See also normalize().

Quaternion& operator*= | ( | const Quaternion & | q | ) |

Quaternion rotation is composed with `q`.

See operator*(), since this is equivalent to `this` = `this` * `q`.

Note:
  For efficiency reasons, the resulting Quaternion is not normalized. You may normalize() it after each application in case of numerical drift.

std::ostream& operator<< | ( | std::ostream & | o,
|  | const qglviewer::Vec & |  |
| ) |  |  |

Output stream operator. Enables debugging code like:

                    Quaternion rot(...);
                    cout << "Rotation=" << rot << endl;

Quaternion& operator= | ( | const Quaternion & | Q | ) |

Equal operator.

double& operator[] | ( | int | i | ) |

Bracket operator returning an l-value. `i` must range in [0..3]. See the Quaternion(double, double, double, double) documentation.

double operator[] | ( | int | i | ) | const

Bracket operator, with a constant return value. `i` must range in [0..3]. See the Quaternion(double, double, double, double) documentation.

Quaternion randomQuaternion | ( |  | ) | `[static]`

Returns a random unit Quaternion.

You can create a randomly directed unit vector using:

    Vec randomDir = Quaternion::randomQuaternion() * Vec(1.0, 0.0, 0.0); // or any other Vec

Note:
  This function uses rand() to create pseudo-random numbers and the random number generator can be initialized using srand().

Vec rotate | ( | const Vec & | v | ) | const

Returns the image of `v` by the Quaternion rotation.

See also inverseRotate() and operator*(const Quaternion&, const Vec&).

void setAxisAngle | ( | const Vec & | axis,
|  | double | angle |
| ) |  |  |

Sets the Quaternion as a rotation of axis `axis` and angle `angle` (in radians).

`axis` does not need to be normalized. A null `axis` will result in an identity Quaternion.

void setFromRotatedBasis | ( | const Vec & | X,
|  | const Vec & | Y,
|  | const Vec & | Z |
| ) |  |  |

Sets the Quaternion from the three rotated vectors of an orthogonal basis.

The three vectors do not have to be normalized but must be orthogonal and direct (X^Y=k*Z, with k>0).

      Quaternion q;
      q.setFromRotatedBasis(X, Y, Z);
      // Now q.rotate(Vec(1,0,0)) == X and q.inverseRotate(X) == Vec(1,0,0)
      // Same goes for Y and Z with Vec(0,1,0) and Vec(0,0,1).

See also setFromRotationMatrix() and Quaternion(const Vec&, const Vec&).

void setFromRotationMatrix | ( | const double | m[3][3] | ) |

Set the Quaternion from a (supposedly correct) 3x3 rotation matrix.

The matrix is expressed in European format: its three columns are the images by the rotation of the three vectors of an orthogonal basis. Note that OpenGL uses a symmetric representation for its matrices.

setFromRotatedBasis() sets a Quaternion from the three axis of a rotated frame. It actually fills the three columns of a matrix with these rotated basis vectors and calls this method.

void setValue | ( | double | q0,
|  | double | q1,
|  | double | q2,
|  | double | q3 |
| ) |  |  |

Sets the Quaternion value. See the Quaternion(double, double, double, double) constructor documentation.

Quaternion slerp | ( | const Quaternion & | a,
|  | const Quaternion & | b,
|  | float | t,
|  | bool | allowFlip = `true` |
| ) |  |  | `[static]`

Returns the slerp interpolation of Quaternions `a` and `b`, at time `t`.

`t` should range in [0,1]. Result is `a` when `t=0` and `b` when `t=1`.

When `allowFlip` is `true` (default) the slerp interpolation will always use the "shortest path" between the Quaternions' orientations, by "flipping" the source Quaternion if needed (see negate()).

Quaternion squad | ( | const Quaternion & | a,
|  | const Quaternion & | tgA,
|  | const Quaternion & | tgB,
|  | const Quaternion & | b,
|  | float | t |
| ) |  |  | `[static]`

Returns the slerp interpolation of the two Quaternions `a` and `b`, at time `t`, using tangents `tgA` and `tgB`.

The resulting Quaternion is "between" `a` and `b` (result is `a` when `t=0` and `b` for `t=1`).

Use squadTangent() to define the Quaternion tangents `tgA` and `tgB`.

Quaternion squadTangent | ( | const Quaternion & | before,
|  | const Quaternion & | center,
|  | const Quaternion & | after |
| ) |  |  | `[static]`

Returns a tangent Quaternion for `center`, defined by `before` and `after` Quaternions.

Useful for smooth spline interpolation of Quaternion with squad() and slerp().

## Friends And Related Function Documentation

Vec operator* | ( | const Quaternion & | q,
|  | const Vec & | v |
| ) |  |  | `[friend]`

Returns the image of `v` by the rotation `q`.

Same as q.rotate(v). See rotate() and inverseRotate().

Quaternion operator* | ( | const Quaternion & | a,
|  | const Quaternion & | b |
| ) |  |  | `[friend]`

Returns the composition of the `a` and `b` rotations.

The order is important. When applied to a Vec `v` (see operator*(const Quaternion&, const Vec&) and rotate()) the resulting Quaternion acts as if `b` was applied first and then `a` was applied. This is obvious since the image `v'` of `v` by the composited rotation satisfies:

                    v'= (a*b) * v = a * (b*v)

Note that a*b usually differs from b*a.

Attention:
  For efficiency reasons, the resulting Quaternion is not normalized. Use normalize() in case of numerical drift with small rotation composition.

All Classes Namespaces Files Functions Variables Enumerations Enumerator Friends Defines