QQuaternion Class

The QQuaternion class represents a quaternion consisting of a vector and scalar. More...

Header: #include <QQuaternion>
qmake: QT += gui
Since: Qt 4.6

This class was introduced in Qt 4.6.

Public Functions

void getAxes(QVector3D *xAxis, QVector3D *yAxis, QVector3D *zAxis) const
void getAxisAndAngle(float *x, float *y, float *z, float *angle) const
void getEulerAngles(float *pitch, float *yaw, float *roll) const
float length() const
float lengthSquared() const
void normalize()
QQuaternion normalized() const
QVector3D rotatedVector(const QVector3D &vector) const
QMatrix3x3 toRotationMatrix() const
QVariant operator QVariant() const

Static Public Members

QQuaternion fromAxes(const QVector3D &xAxis, const QVector3D &yAxis, const QVector3D &zAxis)
QQuaternion fromAxisAndAngle(const QVector3D &axis, float angle)
QQuaternion fromAxisAndAngle(float x, float y, float z, float angle)
QQuaternion fromDirection(const QVector3D &direction, const QVector3D &up)
QQuaternion fromEulerAngles(float pitch, float yaw, float roll)
QQuaternion fromRotationMatrix(const QMatrix3x3 &rot3x3)
QQuaternion nlerp(const QQuaternion &q1, const QQuaternion &q2, float t)
QQuaternion rotationTo(const QVector3D &from, const QVector3D &to)
QQuaternion slerp(const QQuaternion &q1, const QQuaternion &q2, float t)

Detailed Description

Quaternions are used to represent rotations in 3D space, and consist of a 3D rotation axis specified by the x, y, and z coordinates, and a scalar representing the rotation angle.

Member Function Documentation

[static] QQuaternion QQuaternion::fromAxes(const QVector3D &xAxis, const QVector3D &yAxis, const QVector3D &zAxis)

Constructs the quaternion using 3 axes (xAxis, yAxis, zAxis).

Note: The axes are assumed to be orthonormal.

This function was introduced in Qt 5.5.

See also getAxes() and fromRotationMatrix().

[static] QQuaternion QQuaternion::fromAxisAndAngle(const QVector3D &axis, float angle)

Creates a normalized quaternion that corresponds to rotating through angle degrees about the specified 3D axis.

See also getAxisAndAngle().

[static] QQuaternion QQuaternion::fromAxisAndAngle(float x, float y, float z, float angle)

Creates a normalized quaternion that corresponds to rotating through angle degrees about the 3D axis (x, y, z).

See also getAxisAndAngle().

[static] QQuaternion QQuaternion::fromDirection(const QVector3D &direction, const QVector3D &up)

Constructs the quaternion using specified forward direction direction and upward direction up. If the upward direction was not specified or the forward and upward vectors are collinear, a new orthonormal upward direction will be generated.

This function was introduced in Qt 5.5.

See also fromAxes() and rotationTo().

[static] QQuaternion QQuaternion::fromEulerAngles(float pitch, float yaw, float roll)

Creates a quaternion that corresponds to a rotation of roll degrees around the z axis, pitch degrees around the x axis, and yaw degrees around the y axis (in that order).

This function was introduced in Qt 5.5.

See also getEulerAngles().

[static] QQuaternion QQuaternion::fromRotationMatrix(const QMatrix3x3 &rot3x3)

Creates a quaternion that corresponds to a rotation matrix rot3x3.

Note: If a given rotation matrix is not normalized, the resulting quaternion will contain scaling information.

This function was introduced in Qt 5.5.

See also toRotationMatrix() and fromAxes().

void QQuaternion::getAxes(QVector3D *xAxis, QVector3D *yAxis, QVector3D *zAxis) const

Returns the 3 orthonormal axes (xAxis, yAxis, zAxis) defining the quaternion.

This function was introduced in Qt 5.5.

See also fromAxes() and toRotationMatrix().

void QQuaternion::getAxisAndAngle(float *x, float *y, float *z, float *angle) const

Extracts a 3D axis (x, y, z) and a rotating angle angle (in degrees) that corresponds to this quaternion.

This function was introduced in Qt 5.5.

See also fromAxisAndAngle().

void QQuaternion::getEulerAngles(float *pitch, float *yaw, float *roll) const

Calculates roll, pitch, and yaw Euler angles (in degrees) that corresponds to this quaternion.

This function was introduced in Qt 5.5.

See also fromEulerAngles().

float QQuaternion::length() const

Returns the length of the quaternion. This is also called the "norm".

See also lengthSquared(), normalized(), and dotProduct().

float QQuaternion::lengthSquared() const

Returns the squared length of the quaternion.

See also length() and dotProduct().

[static] QQuaternion QQuaternion::nlerp(const QQuaternion &q1, const QQuaternion &q2, float t)

Interpolates along the shortest linear path between the rotational positions q1 and q2. The value t should be between 0 and 1, indicating the distance to travel between q1 and q2. The result will be normalized().

If t is less than or equal to 0, then q1 will be returned. If t is greater than or equal to 1, then q2 will be returned.

The nlerp() function is typically faster than slerp() and will give approximate results to spherical interpolation that are good enough for some applications.

See also slerp().

void QQuaternion::normalize()

Normalizes the current quaternion in place. Nothing happens if this is a null quaternion or the length of the quaternion is very close to 1.

See also length() and normalized().

QQuaternion QQuaternion::normalized() const

Returns the normalized unit form of this quaternion.

If this quaternion is null, then a null quaternion is returned. If the length of the quaternion is very close to 1, then the quaternion will be returned as-is. Otherwise the normalized form of the quaternion of length 1 will be returned.

See also normalize(), length(), and dotProduct().

QVector3D QQuaternion::rotatedVector(const QVector3D &vector) const

Rotates vector with this quaternion to produce a new vector in 3D space. The following code:


      QVector3D result = q.rotatedVector(vector);

is equivalent to the following:


      QVector3D result = (q * QQuaternion(0, vector) * q.conjugated()).vector();

[static] QQuaternion QQuaternion::rotationTo(const QVector3D &from, const QVector3D &to)

Returns the shortest arc quaternion to rotate from the direction described by the vector from to the direction described by the vector to.

This function was introduced in Qt 5.5.

See also fromDirection().

[static] QQuaternion QQuaternion::slerp(const QQuaternion &q1, const QQuaternion &q2, float t)

Interpolates along the shortest spherical path between the rotational positions q1 and q2. The value t should be between 0 and 1, indicating the spherical distance to travel between q1 and q2.

If t is less than or equal to 0, then q1 will be returned. If t is greater than or equal to 1, then q2 will be returned.

See also nlerp().

QMatrix3x3 QQuaternion::toRotationMatrix() const

Creates a rotation matrix that corresponds to this quaternion.

Note: If this quaternion is not normalized, the resulting rotation matrix will contain scaling information.

This function was introduced in Qt 5.5.

See also fromRotationMatrix() and getAxes().

QVariant QQuaternion::operator QVariant() const

Returns the quaternion as a QVariant.