Skip to main content
`Ctrl`+`K`
scipy.spatial.transform.Rotation.

# as_quat

Rotation.as_quat(canonical=False, *, scalar_first=False)

  Represent as quaternions.

  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.

  References

  [1]

  https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation

  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()
      array([0., 0., 0., 1.])
      >>> 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()
      array([0. , 0. , 0. , -1.])
      >>> r.as_quat(canonical=True)
      array([0. , 0. , 0. , 1.])