`scipy.spatial.transform._rotation:Rotation.as_quat`

source: build-install/usr/lib/python3.14/site-packages/scipy/spatial/transform/_rotation.py:1003

Signature

def as_quat(self, canonical: bool = False, *, scalar_first: bool = False) → Array

Summary

Represent as quaternions.

Extended Summary

Rotations in 3 dimensions can be represented using unit norm quaternions ^[1].

The 4 components of a quaternion are divided into a scalar part w and a vector part (x, y, z) and can be expressed from the angle theta and the axis n of a rotation as follows

w = cos(theta / 2)
x = sin(theta / 2) * n_x
y = sin(theta / 2) * n_y
z = sin(theta / 2) * n_z

There are 2 conventions to order the components in a quaternion:

scalar-first order -- (w, x, y, z)
scalar-last order -- (x, y, z, w)

The choice is controlled by scalar_first argument. By default, it is False and the scalar-last order is used.

The mapping from quaternions to rotations is two-to-one, i.e. quaternions q and -q, where -q simply reverses the sign of each component, represent the same spatial rotation.

Parameters

canonical : `bool`, default False: Whether to map the redundant double cover of rotation space to a unique "canonical" single cover. If True, then the quaternion is chosen from {q, -q} such that the w term is positive. If the w term is 0, then the quaternion is chosen such that the first nonzero term of the x, y, and z terms is positive.
scalar_first : bool, optional: Whether the scalar component goes first or last. Default is False, i.e. the scalar-last order is used.

Returns

quat : `numpy.ndarray`, shape (..., 4): Shape depends on shape of inputs used for initialization.

Examples

from scipy.spatial.transform import Rotation as R
import numpy as np

✓

A rotation can be represented as a quaternion with either scalar-last (default) or scalar-first component order. This is shown for a single rotation:

r = R.from_matrix(np.eye(3))
r.as_quat()
r.as_quat(scalar_first=True)

✓

array([1., 0., 0., 0.])

The resulting shape of the quaternion is always the shape of the Rotation object with an added last dimension of size 4. E.g. when the `Rotation` object contains an N-dimensional array (N, M, K) of rotations, the result will be a 4-dimensional array:

r = R.from_rotvec(np.ones((2, 3, 4, 3)))
r.as_quat().shape

✓

(2, 3, 4, 4)

Quaternions can be mapped from a redundant double cover of the rotation space to a canonical representation with a positive w term.

r = R.from_quat([0, 0, 0, -1])

✓

r.as_quat()
r.as_quat(canonical=True)

✗

array([-0., -0., -0.,  1.])