Quaternion

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

Bases: compas.geometry.primitives._primitive.Primitive

Creates a Quaternion object.

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

wxyz (list of float, read-only) – Quaternion data listing the real part first.
xyzw (list of float, read-only) – Quaternion data listing the real part last.
norm (float, read-only) – The length of the quaternion.
is_unit (bool, read-only) – True if the quaternion has unit length.

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

`__init__`(w, x, y, z)	Initialize self.
`canonize`()	Makes the quaternion canonic.
`canonized`()	Returns a quaternion in canonic form.
`conjugate`()	Conjugate the quaternion.
`conjugated`()	Returns a conjugate quaternion.
`copy`()	Makes a copy of this primitive.
`from_data`(data)	Construct a quaternion from a data dict.
`from_frame`(frame)	Creates a quaternion object from a frame.
`from_json`(filepath)	Construct a primitive from structured data contained in a json file.
`from_matrix`(M)	Create a `Quaternion` from a transformation matrix.
`from_rotation`(R)	Create a `Quaternion` from a `compas.geometry.Rotatation`.
`to_data`()	Returns the data dictionary that represents the primitive.
`to_json`(filepath)	Serialise the structured data representing the primitive to json.
`transform`(transformation)	Transform the primitive.
`transformed`(transformation)	Returns a transformed copy of this primitive.
`unitize`()	Scales the quaternion to make it unit-length.
`unitized`()	Returns a quaternion with a unit-length.
`validate_data`()	Validate the data of this object against its data schema (self.DATASCHEMA).
`validate_json`()	Validate the data loaded from a JSON representation of the data of this object against its data schema (self.DATASCHEMA).

Quaternion

COMPAS