# Quaternion

class compas.geometry.Quaternion(w, x, y, z, **kwargs)[source]

Bases: Primitive

A quaternion is defined by 4 components, X, Y, Z, and W.

Parameters
• w (float) – The scalar (real) part of a quaternion.

• x, y, z (float) – Components of the vector (complex, imaginary) part of a quaternion.

Attributes
• w (float) – The W component of the quaternion.

• x (float) – The X component of the quaternion.

• y (float) – The Y component of the quaternion.

• z (float) – The Z component of the quaternion.

• wxyz (list[float], read-only) – Quaternion as a list of float in the ‘wxyz’ convention.

• xyzw (list[float], read-only) – Quaternion as a list of float in the ‘xyzw’ convention.

• norm (float, read-only) – The length (euclidean norm) of the quaternion.

• is_unit (bool, read-only) – True if the quaternion is unit-length. False otherwise.

Notes

The default convention to represent a quaternion $$q$$ in this module is by four real values $$w$$, $$x$$, $$y$$, $$z$$. The first value $$w$$ is the scalar (real) part, and $$x$$, $$y$$, $$z$$ form the vector (complex, imaginary) part 1, so that:

$q = w + xi + yj + zk$

where $$i, j, k$$ are basis components with following multiplication rules 2:

\begin{split}\begin{align} ii &= jj = kk = ijk = -1 \\ ij &= k, \quad ji = -k \\ jk &= i, \quad kj = -i \\ ki &= j, \quad ik = -j \end{align}\end{split}

Quaternions are associative but not commutative.

Quaternion as rotation.

A rotation through an angle $$\theta$$ around an axis defined by a euclidean unit vector $$u = u_{x}i + u_{y}j + u_{z}k$$ can be represented as a quaternion:

$q = cos(\frac{\theta}{2}) + sin(\frac{\theta}{2}) [u_{x}i + u_{y}j + u_{z}k]$

i.e.:

\begin{split}\begin{align} w &= cos(\frac{\theta}{2}) \\ x &= sin(\frac{\theta}{2}) u_{x} \\ y &= sin(\frac{\theta}{2}) u_{y} \\ z &= sin(\frac{\theta}{2}) u_{z} \end{align}\end{split}

For a quaternion to represent a rotation or orientation, it must be unit-length. A quaternion representing a rotation $$p$$ resulting from applying a rotation $$r$$ to a rotation $$q$$, i.e.: $$p = rq$$, is also unit-length.

References

1

http://mathworld.wolfram.com/Quaternion.html

2

http://mathworld.wolfram.com/HamiltonsRules.html

3

https://github.com/matthew-brett/transforms3d/blob/master/transforms3d/quaternions.py

Examples

>>> Q = Quaternion(1.0, 1.0, 1.0, 1.0).unitized()
>>> R = Quaternion(0.0,-0.1, 0.2,-0.3).unitized()
>>> P = R*Q
>>> P.is_unit
True


Methods

 canonize Makes the quaternion canonic. canonized Returns a quaternion in canonic form. conjugate Conjugate the quaternion. conjugated Returns a conjugate quaternion. from_data Construct a quaternion from a data dict. from_frame Creates a quaternion object from a frame. from_matrix Create a Quaternion from a transformation matrix. from_rotation Create a Quaternion from a Rotatation. unitize Scales the quaternion to make it unit-length. unitized Returns a quaternion with a unit-length.

Inherited Methods

 ToString Converts the instance to a string. copy Make an independent copy of the data object. from_json Construct an object from serialized data contained in a JSON file. from_jsonstring Construct an object from serialized data contained in a JSON string. sha256 Compute a hash of the data for comparison during version control using the sha256 algorithm. to_data Convert an object to its native data representation. to_json Serialize the data representation of an object to a JSON file. to_jsonstring Serialize the data representation of an object to a JSON string. transform Transform the geometry. transformed Returns a transformed copy of this geometry. validate_data Validate the object's data against its data schema. validate_json Validate the object's data against its json schema.