Quaternion#

class orix.quaternion.Quaternion(data=None)[source]#

Bases: Object3d

Quaternions.

Quaternions support the following mathematical operations:

  • Unary negation.

  • Inversion (conjugation).

  • Normalization to obtain unit quaternions.

  • Multiplication with other quaternions and vectors.

A quaternion \(Q\) is defined as a four-component number of the form \(Q = a + ib + jc + kd\), where the imaginary units \((i, j, k)\) satisfy the following relations:

\[\begin{split}i^2 &= j^2 = k^2 = -1;\\ ij &= -ji = k; jk = -kj = i; ki = -ik = j.\end{split}\]

In orix, quaternions are stored with the scalar part first followed by the vector part, denoted \(Q = (a, b, c, d)\).

Multiplication of two quaternions \(Q_1 = (a_1, b_1, c_1, d_1)\) and \(Q_2 = (a_2, b_2, c_2, d_2)\) with \(Q_3 = q1 \cdot q2 = (a_3, b_3, c_3, d_3)\) is performed as:

\[\begin{split}a_3 = a_1 \cdot a_2 - b_1 \cdot b_2 - c_1 \cdot c_2 - d_1 \cdot d_2\\ b_3 = a_1 \cdot b_2 + b_1 \cdot a_2 + c_1 \cdot d_2 - d_1 \cdot c_2\\ c_3 = a_1 \cdot c_2 - b_1 \cdot d_2 + c_1 \cdot a_2 + d_1 \cdot b_2\\ d_3 = a_1 \cdot d_2 + b_1 \cdot c_2 - c_1 \cdot b_2 + d_1 \cdot a_2\end{split}\]

Rotation of a 3D vector \(v = (x, y, z)\) by a quaternion is performed as \(v' = Q \cdot v \cdot Q^{-1}\). Written out:

\[\begin{split}v'_x = x + 2a(cz - dy) - 2d(dx - bz) + 2c(by - cx)\\ v'_y = y + 2d(cz - dy) + 2a(dx - bz) - 2b(by - cx)\\ v'_z = z - 2c(cz - dy) + 2b(dx - bz) + 2a(by - cx)\end{split}\]

The norm of a quaternion is defined as

\[|Q| = \sqrt{a^2 + b^2 + c^2 + d^2}.\]

Unit quaternions have a norm of \(|Q| = 1\) and can always be written on the form

\[Q = \cos\frac{\omega}{2} + \sin\frac{\omega}{2}(bi + cj + dk),\]

where \((b, c, d)\) are the direction cosines of the rotation axis unit vector \(\hat{\mathbf{n}}\). The scalar part \(a = \cos\frac{\omega}{2}\) will always be positive or 0 for rotations with rotation angle \(\omega = \pi\).

Conventions:

  1. Right-handed Cartesian reference frames.

  2. Rotation angles \(\omega\) are taken to be positive for a counter-clockwise rotation when viewing from the end point of the rotation axis unit vector \(\hat{\mathbf{n}}\) towards the origin.

  3. Rotations are interpreted in the passive sense. This means that rotations are interpreted as basis transformations of reference frames, with vectors fixed in space.

  4. Euler angle triplets are implemented using the Bunge convention, with angular ranges as \([0, 2\pi]\), \([0, \pi]\), and \([0, 2\pi]\).

  5. Rotation angles \(\omega\) are limited to \([0, \pi]\).

Attributes

Quaternion.a

Return or set the scalar quaternion component.

Quaternion.angle

Return the angle of rotation \(\omega = 2\arccos{|a|}\).

Quaternion.antipodal

Return the quaternion and its antipodal.

Quaternion.axis

Return the axis of rotation \(\hat{\mathbf{n}} = (b, c, d)\).

Quaternion.b

Return or set the first vector quaternion component.

Quaternion.c

Return or set the second vector quaternion component.

Quaternion.conj

Return the conjugate of the quaternion \(Q^{*} = a - bi - cj - dk\).

Quaternion.d

Return or set the third vector quaternion component.

Quaternion.data

Return the data.

Quaternion.ndim

Return the number of navigation dimensions of the object.

Quaternion.norm

Return the norm of the data.

Quaternion.shape

Return the shape of the object.

Quaternion.size

Return the total number of entries in this object.

Quaternion.unit

Return the unit object.

Methods

Quaternion.dot(other)

Return the dot products of the quaternions and the other quaternions.

Quaternion.dot_outer(other)

Return the dot products of all quaternions to all the other quaternions.

Quaternion.empty()

Return an empty object with the appropriate dimensions.

Quaternion.flatten()

Return a new object with the same data in a single column.

Quaternion.from_align_vectors(other, initial)

Estimate a quaternion to optimally align two sets of vectors.

Quaternion.from_axes_angles(axes, angles[, ...])

Create unit quaternions from axis-angle pairs \((\hat{\mathbf{n}}, \omega)\) [Rowenhorst et al., 2015].

Quaternion.from_euler(euler[, direction, ...])

Create unit quaternions from Euler angle sets [Rowenhorst et al., 2015].

Quaternion.from_homochoric(ho)

Create unit quaternions from homochoric vectors \(\mathbf{h}\) [Rowenhorst et al., 2015].

Quaternion.from_matrix(matrix)

Create unit quaternions from orientation matrices [Rowenhorst et al., 2015].

Quaternion.from_rodrigues(ro[, angles])

Create unit quaternions from three-component Rodrigues vectors \(\hat{\mathbf{n}}\) or four-component Rodrigues-Frank vectors \(\mathbf{\rho}\) [Rowenhorst et al., 2015].

Quaternion.from_scipy_rotation(rotation)

Create unit quaternions from scipy.spatial.transform.Rotation.

Quaternion.get_random_sample([size, ...])

Return a new flattened object from a random sample of a given size.

Quaternion.identity([shape])

Create identity quaternions.

Quaternion.inv()

Return the inverse quaternions \(Q^{-1} = a - bi - cj - dk\).

Quaternion.mean()

Return the mean quaternion with unitary weights.

Quaternion.outer(other[, lazy, chunk_size, ...])

Return the outer products of the quaternions and the other quaternions or vectors.

Quaternion.random([shape])

Create object with random data.

Quaternion.reshape(*shape)

Return a new object with the same data in a new shape.

Quaternion.squeeze()

Return a new object with the same data with length 1-dimensions removed.

Quaternion.stack(sequence)

Return a stacked object from the sequence.

Quaternion.to_axes_angles()

Return the unit quaternions as axis-angle vectors [Rowenhorst et al., 2015].

Quaternion.to_euler([degrees])

Return the unit quaternions as Euler angles in the Bunge convention [Rowenhorst et al., 2015].

Quaternion.to_homochoric()

Return the unit quaternions as homochoric vectors [Rowenhorst et al., 2015].

Quaternion.to_matrix()

Return the unit quaternions as orientation matrices [Rowenhorst et al., 2015].

Quaternion.to_rodrigues([frank])

Return the unit quaternions as Rodrigues or Rodrigues-Frank

Quaternion.transpose(*axes)

Return a new object with the same data transposed.

Quaternion.triple_cross(q1, q2, q3)

Pointwise cross product of three quaternions.

Quaternion.unique([return_index, return_inverse])

Return a new object containing only this object's unique entries.

Examples using Quaternion#

Misorientation from aligning directions

Misorientation from aligning directions