Quaternion

class compas.geometry.Quaternion[source]

Bases: Geometry

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

Parameters:

wfloat: The scalar (real) part of a quaternion.
xfloat: X component of the vector (complex, imaginary) part of a quaternion.
yfloat: Y component of the vector (complex, imaginary) part of a quaternion.
zfloat: Z component of the vector (complex, imaginary) part of a quaternion.
namestr, optional: The name of the transformation.

Attributes:

wfloat: The W component of the quaternion.
xfloat: The X component of the quaternion.
yfloat: The Y component of the quaternion.
zfloat: The Z component of the quaternion.
wxyzlist[float], read-only: Quaternion as a list of float in the ‘wxyz’ convention.
xyzwlist[float], read-only: Quaternion as a list of float in the ‘xyzw’ convention.
normfloat, read-only: The length (euclidean norm) of the quaternion.
is_unitbool, 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]

matthew-brett/transforms3d

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.
`dot`	Computes the cosine of the angle between the two quaternions
`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.
`slerp`	Slerp: spherical interpolation of two quaternions.
`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.
`compute_aabb`	Compute the axis-aligned bounding box of the geometry.
`compute_obb`	Compute the oriented bounding box of the geometry.
`copy`	Make an independent copy of the data object.
`from_json`	Construct an object of this type from a JSON file.
`from_jsonstring`	Construct an object of this type from a JSON string.
`rotate`	Rotate the geometry.
`rotated`	Returns a rotated copy of this geometry.
`scale`	Scale the geometry.
`scaled`	Returns a scaled copy of this geometry.
`sha256`	Compute a hash of the data for comparison during version control using the sha256 algorithm.
`to_json`	Convert an object to its native data representation and save it to a JSON file.
`to_jsonstring`	Convert an object to its native data representation and save it to a JSON string.
`transform`	Transform the geometry.
`transformed`	Returns a transformed copy of this geometry.
`translate`	Translate the geometry.
`translated`	Returns a translated copy of this geometry.
`validate_data`	Validate the data against the object's data schema.