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

# apply

Rotation.apply(vectors, inverse=False)

  Apply this rotation to a set of vectors.

  If the original frame rotates to the final frame by this rotation, then its application to a vector can be seen in two ways:

  > - As a projection of vector components expressed in the final frame to the original frame.

  > - As the physical rotation of a vector being glued to the original frame as it rotates. In this case the vector components are expressed in the original frame before and after the rotation.

  In terms of rotation matrices, this application is the same as `self.as_matrix() @ vectors`.

  Parameters:
    vectors array_like, shape (…, 3)

      Each vectors[…, :] represents a vector in 3D space. The shape of rotations and shape of vectors given must follow standard numpy broadcasting rules: either one of them equals unity or they both equal each other.

    inverse boolean, optional

      If True then the inverse of the rotation(s) is applied to the input vectors. Default is False.

  Returns:
    rotated_vectors ndarray, shape (…, 3)

      Result of applying rotation on input vectors. Shape is determined according to numpy broadcasting rules. I.e., the result will have the shape np.broadcast_shapes(r.shape, v.shape[:-1]) + (3,)

  Notes

  Array API Standard Support

  `apply` has experimental support for Python Array API Standard compatible backends in addition to NumPy. Please consider testing these features by setting an environment variable `SCIPY_ARRAY_API=1` and providing CuPy, PyTorch, JAX, or Dask arrays as array arguments. The following combinations of backend and device (or other capability) are supported.

  Library | CPU | GPU
  --- | --- | ---
  NumPy | ✅ | n/a
  CuPy | n/a | ⛔
  PyTorch | ✅ | ✅
  JAX | ✅ | ✅
  Dask | ⛔ | n/a

  > See Support for the array API standard for more information.

  Examples

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

  Single rotation applied on a single vector:

      >>> vector = np.array([1, 0, 0])
      >>> r = R.from_rotvec([0, 0, np.pi/2])
      >>> r.as_matrix()
      array([[ 2.22044605e-16, -1.00000000e+00,  0.00000000e+00],
             [ 1.00000000e+00,  2.22044605e-16,  0.00000000e+00],
             [ 0.00000000e+00,  0.00000000e+00,  1.00000000e+00]])
      >>> r.apply(vector)
      array([2.22044605e-16, 1.00000000e+00, 0.00000000e+00])
      >>> r.apply(vector).shape
      (3,)

  Single rotation applied on multiple vectors:

      >>> vectors = np.array([
      ... [1, 0, 0],
      ... [1, 2, 3]])
      >>> r = R.from_rotvec([0, 0, np.pi/4])
      >>> r.as_matrix()
      array([[ 0.70710678, -0.70710678,  0.        ],
             [ 0.70710678,  0.70710678,  0.        ],
             [ 0.        ,  0.        ,  1.        ]])
      >>> r.apply(vectors)
      array([[ 0.70710678,  0.70710678,  0.        ],
             [-0.70710678,  2.12132034,  3.        ]])
      >>> r.apply(vectors).shape
      (2, 3)

  Multiple rotations on a single vector:

      >>> r = R.from_rotvec([[0, 0, np.pi/4], [np.pi/2, 0, 0]])
      >>> vector = np.array([1,2,3])
      >>> r.as_matrix()
      array([[[ 7.07106781e-01, -7.07106781e-01,  0.00000000e+00],
              [ 7.07106781e-01,  7.07106781e-01,  0.00000000e+00],
              [ 0.00000000e+00,  0.00000000e+00,  1.00000000e+00]],
             [[ 1.00000000e+00,  0.00000000e+00,  0.00000000e+00],
              [ 0.00000000e+00,  2.22044605e-16, -1.00000000e+00],
              [ 0.00000000e+00,  1.00000000e+00,  2.22044605e-16]]])
      >>> r.apply(vector)
      array([[-0.70710678,  2.12132034,  3.        ],
             [ 1.        , -3.        ,  2.        ]])
      >>> r.apply(vector).shape
      (2, 3)

  Multiple rotations on multiple vectors. Each rotation is applied on the corresponding vector:

      >>> r = R.from_euler('zxy', [
      ... [0, 0, 90],
      ... [45, 30, 60]], degrees=True)
      >>> vectors = [
      ... [1, 2, 3],
      ... [1, 0, -1]]
      >>> r.apply(vectors)
      array([[ 3.        ,  2.        , -1.        ],
             [-0.09026039,  1.11237244, -0.86860844]])
      >>> r.apply(vectors).shape
      (2, 3)

  Broadcasting rules apply:

      >>> r = R.from_rotvec(np.tile([0, 0, np.pi/4], (5, 1, 4, 1)))
      >>> vectors = np.ones((3, 4, 3))
      >>> r.shape, vectors.shape
      ((5, 1, 4), (3, 4, 3))
      >>> r.apply(vectors).shape
      (5, 3, 4, 3)

  It is also possible to apply the inverse rotation:

      >>> r = R.from_euler('zxy', [
      ... [0, 0, 90],
      ... [45, 30, 60]], degrees=True)
      >>> vectors = [
      ... [1, 2, 3],
      ... [1, 0, -1]]
      >>> r.apply(vectors, inverse=True)
      array([[-3.        ,  2.        ,  1.        ],
             [ 1.09533535, -0.8365163 ,  0.3169873 ]])