class QQuaternion

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

Added in version 4.6.

Synopsis

Methods

Static functions

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

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.

__init__()

Constructs an identity quaternion (1, 0, 0, 0), i.e. with the vector (0, 0, 0) and scalar 1.

__init__(vector)
Parameters:

vectorQVector4D

Constructs a quaternion from the components of vector.

__init__(scalar, vector)
Parameters:

Constructs a quaternion vector from the specified vector and scalar.

See also

vector() scalar()

__init__(scalar, xpos, ypos, zpos)
Parameters:
  • scalar – float

  • xpos – float

  • ypos – float

  • zpos – float

Constructs a quaternion with the vector (xpos, ypos, zpos) and scalar.

__reduce__()
Return type:

str

__repr__()
Return type:

str

conjugated()
Return type:

QQuaternion

Returns the conjugate of this quaternion, which is (-x, -y, -z, scalar).

static dotProduct(q1, q2)
Parameters:
Return type:

float

Returns the dot product of q1 and q2.

See also

length()

static fromAxes(xAxis, yAxis, zAxis)
Parameters:
Return type:

QQuaternion

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

Note

The axes are assumed to be orthonormal.

static fromAxisAndAngle(axis, angle)
Parameters:
Return type:

QQuaternion

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

static fromAxisAndAngle(x, y, z, angle)
Parameters:
  • x – float

  • y – float

  • z – float

  • angle – float

Return type:

QQuaternion

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

static fromDirection(direction, up)
Parameters:
Return type:

QQuaternion

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.

static fromEulerAngles(eulerAngles)
Parameters:

eulerAnglesQVector3D

Return type:

QQuaternion

This is an overloaded function.

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

See also

toEulerAngles()

static fromEulerAngles(pitch, yaw, roll)
Parameters:
  • pitch – float

  • yaw – float

  • roll – float

Return type:

QQuaternion

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

See also

getEulerAngles()

static fromRotationMatrix(rot3x3)
Parameters:

rot3x3QMatrix3x3

Return type:

QQuaternion

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.

getAxes(xAxis, yAxis, zAxis)
Parameters:

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

getAxisAndAngle()
Return type:

(QVector3D, float)

This is an overloaded function.

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

getEulerAngles()
Return type:

(float, float, float)

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

inverted()
Return type:

QQuaternion

Returns the inverse of this quaternion. If this quaternion is null, then a null quaternion is returned.

See also

isNull() length()

isIdentity()
Return type:

bool

Returns true if the x, y, and z components of this quaternion are set to 0.0, and the scalar component is set to 1.0; otherwise returns false.

isNull()
Return type:

bool

Returns true if the x, y, z, and scalar components of this quaternion are set to 0.0; otherwise returns false.

length()
Return type:

float

Returns the length of the quaternion. This is also called the “norm”.

lengthSquared()
Return type:

float

Returns the squared length of the quaternion.

Note

Though cheap to compute, this is susceptible to overflow and underflow that length() avoids in many cases.

static nlerp(q1, q2, t)
Parameters:
Return type:

QQuaternion

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

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.

normalized()
Return type:

QQuaternion

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.

__ne__(q2)
Parameters:

q2QQuaternion

Return type:

bool

Returns true if q1 is not equal to q2; otherwise returns false. This operator uses an exact floating-point comparison.

__mul__(q2)
Parameters:

q2QQuaternion

Return type:

QQuaternion

Multiplies q1 and q2 using quaternion multiplication. The result corresponds to applying both of the rotations specified by q1 and q2.

See also

operator*=()

__mul__(factor)
Parameters:

factor – float

Return type:

QQuaternion

Returns a copy of the given quaternion, multiplied by the given factor.

See also

operator*=()

__mul__(factor)
Parameters:

factor – float

Return type:

QQuaternion

Returns a copy of the given quaternion, multiplied by the given factor.

See also

operator*=()

__imul__(quaternion)
Parameters:

quaternionQQuaternion

Return type:

QQuaternion

Multiplies this quaternion by quaternion and returns a reference to this quaternion.

__imul__(factor)
Parameters:

factor – float

Return type:

QQuaternion

Multiplies this quaternion’s components by the given factor, and returns a reference to this quaternion.

See also

operator/=()

__add__(q2)
Parameters:

q2QQuaternion

Return type:

QQuaternion

Returns a QQuaternion object that is the sum of the given quaternions, q1 and q2; each component is added separately.

See also

operator+=()

__iadd__(quaternion)
Parameters:

quaternionQQuaternion

Return type:

QQuaternion

Adds the given quaternion to this quaternion and returns a reference to this quaternion.

See also

operator-=()

__sub__()
Return type:

QQuaternion

This is an overloaded function.

Returns a QQuaternion object that is formed by changing the sign of all three components of the given quaternion.

Equivalent to QQuaternion(0,0,0,0) - quaternion.

__sub__(q2)
Parameters:

q2QQuaternion

Return type:

QQuaternion

Returns a QQuaternion object that is formed by subtracting q2 from q1; each component is subtracted separately.

See also

operator-=()

__isub__(quaternion)
Parameters:

quaternionQQuaternion

Return type:

QQuaternion

Subtracts the given quaternion from this quaternion and returns a reference to this quaternion.

See also

operator+=()

__div__(divisor)
Parameters:

divisor – float

Return type:

QQuaternion

Returns the QQuaternion object formed by dividing all components of the given quaternion by the given divisor.

See also

operator/=()

operator/=(divisor)
Parameters:

divisor – float

Return type:

QQuaternion

Divides this quaternion’s components by the given divisor, and returns a reference to this quaternion.

See also

operator*=()

__eq__(q2)
Parameters:

q2QQuaternion

Return type:

bool

Returns true if q1 is equal to q2; otherwise returns false. This operator uses an exact floating-point comparison.

rotatedVector(vector)
Parameters:

vectorQVector3D

Return type:

QVector3D

Warning

This section contains snippets that were automatically translated from C++ to Python and may contain errors.

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

result = q.rotatedVector(vector)

is equivalent to the following:

result = (q * QQuaternion(0, vector) * q.conjugated()).vector()
static rotationTo(from, to)
Parameters:
Return type:

QQuaternion

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

See also

fromDirection()

scalar()
Return type:

float

Returns the scalar component of this quaternion.

See also

setScalar() x() y() z()

setScalar(scalar)
Parameters:

scalar – float

Sets the scalar component of this quaternion to scalar.

setVector(vector)
Parameters:

vectorQVector3D

Sets the vector component of this quaternion to vector.

setVector(x, y, z)
Parameters:
  • x – float

  • y – float

  • z – float

Sets the vector component of this quaternion to (x, y, z).

setX(x)
Parameters:

x – float

Sets the x coordinate of this quaternion’s vector to the given x coordinate.

setY(y)
Parameters:

y – float

Sets the y coordinate of this quaternion’s vector to the given y coordinate.

setZ(z)
Parameters:

z – float

Sets the z coordinate of this quaternion’s vector to the given z coordinate.

static slerp(q1, q2, t)
Parameters:
Return type:

QQuaternion

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

toEulerAngles()
Return type:

QVector3D

This is an overloaded function.

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

toRotationMatrix()
Return type:

QMatrix3x3

Creates a rotation matrix that corresponds to this quaternion.

Note

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

toVector4D()
Return type:

QVector4D

Returns this quaternion as a 4D vector.

vector()
Return type:

QVector3D

Returns the vector component of this quaternion.

x()
Return type:

float

Returns the x coordinate of this quaternion’s vector.

See also

setX() y() z() scalar()

y()
Return type:

float

Returns the y coordinate of this quaternion’s vector.

See also

setY() x() z() scalar()

z()
Return type:

float

Returns the z coordinate of this quaternion’s vector.

See also

setZ() x() y() scalar()