# 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{align}\begin{aligned}i^2 = j^2 = k^2 = -1;\\ij = -ji = k; jk = -kj = i; ki = -ik = j.\end{aligned}\end{align}

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{align}\begin{aligned}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{aligned}\end{align}

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{align}\begin{aligned}v'_x = x(a^2 + b^2 - c^2 - d^2) + 2[z(a \cdot c + b \cdot d) + y(b \cdot c - a \cdot d)]\\v'_y = y(a^2 - b^2 + c^2 - d^2) + 2[x(a \cdot d + b \cdot c) + z(c \cdot d - a \cdot b)]\\v'_z = z(a^2 - b^2 - c^2 + d^2) + 2[y(a \cdot b + c \cdot d) + x(b \cdot d - a \cdot c)]\end{aligned}\end{align}

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. Return the dot products of all quaternions to all the other quaternions. Return an empty object with the appropriate dimensions. 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)$$ . Quaternion.from_euler(euler[, direction, ...]) Create unit quaternions from Euler angle sets . Create unit quaternions from homochoric vectors $$\mathbf{h}$$ . Quaternion.from_matrix(matrix) Create unit quaternions from orientation matrices . Quaternion.from_neo_euler(neo_euler) [Deprecated] Create unit quaternion(s) from a neo-euler (vector) representation. Quaternion.from_rodrigues(ro[, angles]) Create unit quaternions from three-component Rodrigues vectors $$\hat{\mathbf{n}}$$ or four-component Rodrigues-Frank vectors $$\mathbf{\rho}$$ . 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. Return the inverse quaternions $$Q^{-1} = a - bi - cj - dk$$. 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. Return a new object with the same data with length 1-dimensions removed. Quaternion.stack(sequence) Return a stacked object from the sequence. Return the unit quaternions as axis-angle vectors . Quaternion.to_euler([degrees]) Return the unit quaternions as Euler angles in the Bunge convention . Return the unit quaternions as homochoric vectors . Return the unit quaternions as orientation matrices . Quaternion.to_rodrigues([frank]) Return the unit quaternions as Rodrigues or Rodrigues-Frank 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