viscid.rotation module

Euler angle <-> Rotation matrix <-> quaternion conversions

This module is designed to work with Numpy versions 1.9+

Quaternion functions will work with vanilla Numpy, but they can also make use of this quaternion library. It is probably to your benefit to use a library that explicitly implements quaternion algebra.

Note

If a function in this module has the same name as one in Matlab, the conventions used for the functions are the same.

Conventions:

Rotation matrices and Euler angles are notoriously ambiguous due to competing conventions for order and meaning. Hopefully this section makes it clear which conventions are used in which functions.

  • What is rotating

    Rotations always follow the right hand rule, but can mean two things depending what is rotating.

    • Extrinsic rotations *rot*

      Axes remain fixed, and matrices rotate vectors. This convention is used in functions with rot in their names to mirror Matlab’s Robotics System toolkit. For example:

      >>> e_rot(numpy.pi / 2, 'z') @ [1, 0, 0] = [0, 1, 0]
    • Intrinsic rotations *dcm*

      Vectors remain fixed, but matrices rotate axes. This convention is used in functions with dcm in their names to mirror Matlab’s Aerospace toolkit. For example:

      >>> e_dcm(numpy.pi / 2, 'z') @ [1, 0, 0] = [0, -1, 0]
  • Axis Order

    For functions that deal with Euler angles, their order can be specified in two ways

    • Multiplication order *eul*
      Axes are specified in the same order as the multiplication of the elementary matrices. In other words, the last axis specified is the first rotation applied. This convention is used in functions with eul in their names to mirror Matlab’s Robotics System toolkit.
    • Transformation order *angle*
      Axes are specified in the order that they are applied. In other words, the first axis is the first rotation, or the right-most matrix. This convention is used in functions with angle in their names to mirror Matlab’s Aerospace toolkit.
Functions:
  • angle2rot: Euler angles (transform-order) -> rotation matrix (extrinsic)
  • eul2rot: Euler angles (multiplication-order) -> rotation matrix (extrinsic)
  • angle2dcm: Euler angles (transform-order) -> rotation matrix (intrinsic)
  • eul2dcm: Euler angles (multiplication-order) -> rotation matrix (intrinsic)
  • rot2angle: Rotation matrix (extrinsic) -> Euler angles (transform-order)
  • rot2eul: Rotation matrix (extrinsic) -> Euler angles (multiplication-order)
  • dcm2angle: Rotation matrix (intrinsic) -> Euler angles (transform-order)
  • dcm2eul: Rotation matrix (intrinsic) -> Euler angles (multiplication-order)
  • rot2quat: Rotation matrix (extrinsic) -> quaternion
  • dcm2quat: Rotation matrix (intrinsic) -> quaternion
  • quat2rot: Quaternion -> rotation matrix (extrinsic)
  • quat2dcm: Quaternion -> rotation matrix (intrinsic)
  • rotmul: Multiply rotation matrices together
  • rotate: Rotate R3 vector(s) by one or more matrices
  • quatmul: Multiply quaternions together
  • quat_rotate: Rotate R3 vector(s) by one or more quaternions
  • wxyz2rot: (angle, axis) representation -> rotation matrix
  • axang2rot: axis-angle representation -> rotation matrix
  • rot2wxyz: rotation matrix -> (angle, axis) representation
  • rot2axang: rotation matrix -> axis-angle representation
  • wxyz2quat: (angle, axis) representation -> quaternion
  • axang2quat: axis-angle representation -> quaternion
  • quat2wxyz: quaternion -> (angle, axis) representation
  • quat2axang: quaternion -> axis-angle representation
  • convert_angle: deg <-> rad conversion
  • check_orthonormality: checks that determinant is +1
  • e_rot: elementary rotation matrix (extrinsic)
  • e_dcm: elementary direction cosine matrix (intrinsic)
  • angle_between: angle between two vectors
  • a2b_rot: make rotation matrix that rotates vector a to vector b
  • symbolic_e_dcm: Make symbolic (sympy) elementary DCM
  • symbolic_e_rot: Make symbolic (sympy) elementary rotation matrix
  • symbolic_rot: Make symbolic (sympy) rotation matrix
  • symbolic_dcm: Make symbolic (sympy) DCM
Aliases:

All functions work with stacks of transformations, so “angles” is natural in some contexts,

  • convert_angles = convert_angle
  • angles2rot -> angle2rot
  • angles2dcm -> angle2dcm
  • rot2angles -> rot2angle
  • dcm2angles -> dcm2angle

The Matlab Robotics System Toolbox uses “rotm” for “rotation matrix” (rot)

  • eul2rotm -> eul2rot
  • angle2rotm -> angle2rot
  • angles2rotm -> angles2rot
  • rotm2eul -> rot2eul
  • rotm2angle -> rot2angle
  • rotm2angles -> rot2angles
  • rotm2quat -> rot2quat
  • quat2rotm -> quat2rot
  • a2b_rotm -> a2b_rot
  • axang2rotm -> axang2rot
  • rotm2axang -> rot2axang
  • wxyz2rotm -> wxyz2rot
  • rotm2wxyz -> rot2wxyz

This module is completely orthogonal to Viscid, so that it can be ripped out and used more generally. Please note that Viscid is MIT licensed, which requires attribution.

The MIT License (MIT) Copyright (c) 2018 Kristofor Maynard

viscid.rotation.angle2rot(angles, axes='zyx', unit='rad')[source]

Euler angles (transform-order) -> rotation matrix (extrinsic)

Rotations are applied in transform-order, which means the first axis given is the first transform applied. In other words, the matrix multiply is in reverse order, i.e.:

>>> R = (R(angles[..., 2], axis[..., 2]) @
>>>      R(angles[..., 1], axis[..., 1]) @
>>>      R(angles[..., 0], axis[..., 0]))

Example

>>> angle2rot([numpy.pi / 2, 0, 0], 'zyx') @ [1, 0, 0] = [0, 1, 0]
Parameters:
  • angles (sequence) – Euler angles in transform-order; can have shape [Ndim] or [Nmatrices, Ndim] to make stacked transform matrices
  • axes (sequence, str) – rotation axes in transform-order
  • unit (str) – unit of angles, one of (‘deg’, ‘rad’)
Returns:

rotation matrix with shape [Ndim, Ndim] or

[Nmatrices, Ndim, Ndim] depending on the shape of angles
Return type:

ndarray
viscid.rotation.eul2rot(angles, axes='zyx', unit='rad')[source]

Euler angles (multiplication-order) -> rotation matrix (extrinsic)

Rotations are applied in multiplication-order, which means the last axis given is the first transform applied. In other words:

>>> R = (R(angles[..., 0], axis[..., 0]) @
>>>      R(angles[..., 1], axis[..., 1]) @
>>>      R(angles[..., 2], axis[..., 2]))

This function is equivalent (up to a few machine epsilon) to Matlab’s eul2rotm.

Example

>>> eul2rot([numpy.pi / 2, 0, 0], 'zyx') @ [1, 0, 0] = [0, 1, 0]
Parameters:
  • angles (sequence) – Euler angles in multiplication-order; can have shape [Ndim] or [Nmatrices, Ndim] to make stacked transform matrices
  • axes (sequence, str) – rotation axes in multiplication-order
  • unit (str) – unit of angles, one of (‘deg’, ‘rad’)
Returns:

rotation matrix with shape [Ndim, Ndim] or

[Nmatrices, Ndim, Ndim] depending on the shape of angles
Return type:

ndarray
viscid.rotation.angle2dcm(angles, axes='zyx', unit='rad')[source]

Euler angles (transform-order) -> rotation matrix (intrinsic)

Rotations are applied in transform-order, which means the first axis given is the first transform applied. In other words, the matrix multiply is in reverse order, i.e.:

>>> R = (R(angles[..., 2], axis[..., 2]) @
>>>      R(angles[..., 1], axis[..., 1]) @
>>>      R(angles[..., 0], axis[..., 0]))

This function is equivalent (up to a few machine epsilon) to Matlab’s angle2dcm.

Example

>>> angle2dcm([numpy.pi / 2, 0, 0], 'zyx') @ [1, 0, 0] = [0, -1, 0]
Parameters:
  • angles (sequence) – Euler angles in transform-order; can have shape [Ndim] or [Nmatrices, Ndim] to make stacked transform matrices
  • axes (sequence, str) – rotation axes in transform-order
  • unit (str) – unit of angles, one of (‘deg’, ‘rad’)
Returns:

rotation matrix with shape [Ndim, Ndim] or

[Nmatrices, Ndim, Ndim] depending on the shape of angles
Return type:

ndarray
viscid.rotation.eul2dcm(angles, axes='zyx', unit='rad')[source]

Euler angles (multiplication-order) -> rotation matrix (intrinsic)

Rotations are applied in multiplication-order, which means the last axis given is the first transform applied. In other words:

>>> R = (R(angles[..., 0], axis[..., 0]) @
>>>      R(angles[..., 1], axis[..., 1]) @
>>>      R(angles[..., 2], axis[..., 2]))

Example

>>> eul2dcm([numpy.pi / 2, 0, 0], 'zyx') @ [1, 0, 0] = [0, -1, 0]
Parameters:
  • angles (sequence) – Euler angles in multiplication-order; can have shape [Ndim] or [Nmatrices, Ndim] to make stacked transform matrices
  • axes (sequence, str) – rotation axes in multiplication-order
  • unit (str) – unit of angles, one of (‘deg’, ‘rad’)
Returns:

rotation matrix with shape [Ndim, Ndim] or

[Nmatrices, Ndim, Ndim] depending on the shape of angles
Return type:

ndarray
viscid.rotation.rot2angles(R, axes='zyx', unit='rad', bad_matrix='warn')

Rotation matrix (extrinsic) -> Euler angles (transform-order)

Parameters:
  • R (ndarray) – A rotation matrix with shape [Ndim, Ndim] or a stack of matrices with shape [Nmatrices, Ndim, Ndim]
  • axes (sequence, str) – rotation axes in transform-order
  • unit (str) – Unit of angles, one of (‘deg’, ‘rad’)
  • bad_matrix (str) – What to do if numpy.det(R) != 1.0 - can be one of (‘ignore’, ‘warn’, ‘raise’)
Returns:

Euler angles with shape [Ndim] or [Nmatrices, Ndim]

depending on the input. angles[:, i] always corresponds to axes[i].
Return type:

ndarray

See also

viscid.rotation.rot2eul(R, axes='zyx', unit='rad', bad_matrix='warn')[source]

Rotation matrix (extrinsic) -> Euler angles (multiplication-order)

Parameters:
  • R (ndarray) – A rotation matrix with shape [Ndim, Ndim] or a stack of matrices with shape [Nmatrices, Ndim, Ndim]
  • axes (sequence, str) – rotation axes in multiplication-order
  • unit (str) – Unit of angles, one of (‘deg’, ‘rad’)
  • bad_matrix (str) – What to do if numpy.det(R) != 1.0 - can be one of (‘ignore’, ‘warn’, ‘raise’)
Returns:

Euler angles with shape [Ndim] or [Nmatrices, Ndim]

depending on the input. angles[:, i] always corresponds to axes[i].
Return type:

ndarray

See also

  • rot2eul() for more details about axes order.
viscid.rotation.dcm2angles(R, axes='zyx', unit='rad', bad_matrix='warn')

Rotation matrix (intrinsic) -> Euler angles (transform-order)

Parameters:
  • R (ndarray) – A rotation matrix with shape [Ndim, Ndim] or a stack of matrices with shape [Nmatrices, Ndim, Ndim]
  • axes (sequence, str) – rotation axes in transform-order
  • unit (str) – Unit of angles, one of (‘deg’, ‘rad’)
  • bad_matrix (str) – What to do if numpy.det(R) != 1.0 - can be one of (‘ignore’, ‘warn’, ‘raise’)
Returns:

Euler angles with shape [Ndim] or [Nmatrices, Ndim]

depending on the input. angles[:, i] always corresponds to axes[i].
Return type:

ndarray

See also

viscid.rotation.dcm2eul(R, axes='zyx', unit='rad', bad_matrix='warn')[source]

Rotation matrix (intrinsic) -> Euler angles (multiplication-order)

Parameters:
  • R (ndarray) – A rotation matrix with shape [Ndim, Ndim] or a stack of matrices with shape [Nmatrices, Ndim, Ndim]
  • axes (sequence, str) – rotation axes in multiplication-order
  • unit (str) – Unit of angles, one of (‘deg’, ‘rad’)
  • bad_matrix (str) – What to do if numpy.det(R) != 1.0 - can be one of (‘ignore’, ‘warn’, ‘raise’)
Returns:

Euler angles with shape [Ndim] or [Nmatrices, Ndim]

depending on the input. angles[:, i] always corresponds to axes[i].
Return type:

ndarray

See also

  • eul2dcm() for more details about axes order.
viscid.rotation.rot2quat(R)[source]

Rotation matrix (extrinsic) -> quaternion

If this quaternion library is imported, then the results are presented with dtype quaternion, otherwise, as dtype numpy.double (array-of-struct, [scalar, vec0, vec1, vec2]).

Parameters:R (ndarray) – A rotation matrix with shape [Ndim, Ndim] or a stack of matrices with shape [Nmatrices, Ndim, Ndim]
Returns:
quaternions with dtype quaternion with shape
(Nmatrices,) or (); or with dtype numpy.double and shape (Nmatrices, 4) or (4)
Return type:ndarray
viscid.rotation.dcm2quat(R)[source]

Rotation matrix (intrinsic) -> quaternion

If this quaternion library is imported, then the results are presented with dtype quaternion, otherwise, as dtype numpy.double (array-of-struct, [scalar, vec0, vec1, vec2]).

Parameters:R (ndarray) – A rotation matrix with shape [Ndim, Ndim] or a stack of matrices with shape [Nmatrices, Ndim, Ndim]
Returns:
quaternions with dtype quaternion and shape
(Nmatrices,) or (); or with dtype numpy.double and shape (Nmatrices, 4) or (4)
Return type:ndarray
viscid.rotation.quat2rot(q)[source]

Quaternion -> rotation matrix (extrinsic)

Parameters:q (ndarray) – quaternions with dtype quaternion and shape (Nmatrices,) or (); or with dtype numpy.double and shape (Nmatrices, 4) or (4)
Returns:
orthonormal rotation matrix with shape (3, 3)
or (Nmatrices, 3, 3)
Return type:ndarray
viscid.rotation.quat2dcm(q)[source]

Quaternion -> rotation matrix (intrinsic)

Parameters:q (ndarray) – quaternions with dtype quaternion and shape (Nmatrices,) or (); or with dtype numpy.double and shape (Nmatrices, 4) or (4)
Returns:
rotation matrix with shape [Ndim, Ndim] or
[Nmatrices, Ndim, Ndim] depending on the shape of q
Return type:ndarray
viscid.rotation.rotmul(*rmats)[source]

Multiply rotation matrices together

Parameters:*rmats (ndarrays) – rotation matrices with shape (3, 3) or (nmats, 3, 3)
Returns:rotation matrix with shape (3, 3) or (nmats, 3, 3)
Return type:ndarray
viscid.rotation.rotate(vec, *rmats)[source]

Rotate R3 vector(s) by one or more matrices

Parameters:
  • vec (ndarray) – R3 vectors with shape (3,) or (nvecs, 3)
  • *rmats (ndarrays) – rotation matrices with shape (3, 3) or (nmats, 3, 3)
Returns:

rotated vectors with shape (3,) or (nvecs, 3)
Return type:

ndarray
viscid.rotation.quatmul(*quats)[source]

Multiply quaternions together

Parameters:*quats (ndarrays) – quaternions with dtype quaternion and shape () or (nquat,); or with dtype np.double and shape (4,) or (nquat, 4)
Returns:
with dtype quaternion and shape () or (nquat,); or
with dtype np.double and shape (4,) or (nquat, 4)
Return type:ndarray
viscid.rotation.quat_rotate(vec, *quats)[source]

Rotate R3 vector(s) by one or more quaternions

Parameters:
  • vec (ndarray) – R3 vectors with shape (3,) or (nvecs, 3)
  • *quats (ndarrays) – quaternions with dtype quaternion and shape () or (nquat,); or with dtype np.double and shape (4,) or (nquat, 4)
Returns:

rotated vectors with shape (3,) or (nvecs, 3)
Return type:

ndarray
viscid.rotation.wxyz2rot(angle, vector, unit='rad')[source]

Make a matrix (matrices) that rotates around vector by angle

Parameters:
  • angle (sequence) – angle(s) of rotation(s) with shape (), (1,), or (Nmatrices)
  • vector (sequence) – 3d vector(s) that is (are) axis of rotation(s) with shape (3,) or (Nmatrices, 3)
  • unit (str) – unit of angle, one of (‘deg’, ‘rad’)
Returns:

orthonormal rotation matrix with shape (3, 3)

or (Nmatrices, 3, 3)
Return type:

ndarray
viscid.rotation.axang2rot(axang, unit='rad')[source]

Make a matrix (matrices) that rotates around vector by angle

Parameters:
  • axang (ndarray) – axis(es) / angle(s) of rotation(s) put together like {x, y, z, angle}; shape should be (4,), or (Nmatrices, 4)
  • unit (str) – unit of angle, one of (‘deg’, ‘rad’)
Returns:

orthonormal rotation matrix with shape (3, 3)

or (Nmatrices, 3, 3)
Return type:

ndarray
viscid.rotation.rot2wxyz(R, unit='rad', quick=True, bad_matrix='warn')[source]

Find axis / angle representation of rotation matrix (matrices)

Parameters:
  • R (ndarray) – Rotation matrix with shape (3, 3) determinant +1, or matrices with shape (Nmatrices, 3, 3)
  • unit (str) – unit of angle in results, one of (‘deg’, ‘rad’)
  • quick (bool) – Try a quicker, less well tested method
  • bad_matrix (str) – What to do if numpy.det(R) != 1.0 - can be one of (‘ignore’, ‘warn’, ‘raise’)
Returns:

w is rotation angle with shape () or (Nmatrices),

and xyz are normalized rotation axes with shape (3,) or (Nmatrices, 3)
Return type:

(w, xyz)
viscid.rotation.rot2axang(R, unit='rad', quick=True, bad_matrix='warn')[source]

Find axis / angle representation of rotation matrix (matrices)

Parameters:
  • R (ndarray) – Rotation matrix with shape (3, 3) determinant +1, or matrices with shape (Nmatrices, 3, 3)
  • unit (str) – unit of angle in results, one of (‘deg’, ‘rad’)
  • quick (bool) – Try a quicker, less well tested method
  • bad_matrix (str) – What to do if numpy.det(R) != 1.0 - can be one of (‘ignore’, ‘warn’, ‘raise’)
Returns:

{x, y, z, angle} axis / angle values with shape (4,)

or (Nmatrices, 4)
Return type:

(ndarray)
viscid.rotation.wxyz2quat(angle, vector, unit='rad')[source]

(angle, axis) representation -> quaternion

Parameters:
  • angle (sequence) – angle(s) of rotation(s) with shape (), (1,), or (Nmatrices)
  • vector (sequence) – 3d vector(s) that is (are) axis of rotation(s) with shape (3,) or (Nmatrices, 3)
  • unit (str) – unit of angle, one of (‘deg’, ‘rad’)
Returns:

quaternions with dtype quaternion and shape

(Nmatrices,) or (); or with dtype numpy.double and shape (Nmatrices, 4) or (4)
Return type:

ndarray
viscid.rotation.axang2quat(axang, unit='rad')[source]

axis-angle representation -> quaternion

Parameters:
  • axang (ndarray) – axis(es) / angle(s) of rotation(s) put together like {x, y, z, angle}; shape should be (4,), or (Nmatrices, 4)
  • unit (str) – unit of angle, one of (‘deg’, ‘rad’)
Returns:

quaternions with dtype quaternion and shape

(Nmatrices,) or (); or with dtype numpy.double and shape (Nmatrices, 4) or (4)
Return type:

ndarray
viscid.rotation.quat2wxyz(q, unit='rad')[source]

quaternion -> (angle, axis) representation

Parameters:
  • q (ndarray) – quaternions with dtype quaternion and shape (Nmatrices,) or (); or with dtype numpy.double and shape (Nmatrices, 4) or (4)
  • unit (str) – unit of angle in results, one of (‘deg’, ‘rad’)
Returns:

w is rotation angle with shape () or (Nmatrices),

and xyz are normalized rotation axes with shape (3,) or (Nmatrices, 3)
Return type:

(w, xyz)
viscid.rotation.quat2axang(q, unit='rad')[source]

quaternion -> axis-angle representation

Parameters:
  • q (ndarray) – quaternions with dtype quaternion and shape (Nmatrices,) or (); or with dtype numpy.double and shape (Nmatrices, 4) or (4)
  • unit (str) – unit of angle in results, one of (‘deg’, ‘rad’)
Returns:

{x, y, z, angle} axis / angle values with shape (4,)

or (Nmatrices, 4)
Return type:

(ndarray)
viscid.rotation.convert_angle(angle, from_unit, to_unit)[source]

convert angle(s) from rad/deg to rad/deg

Parameters:
  • angle (float, sequence) – angle in from_unit
  • from_unit (str) – unit of angle, one of (‘rad’, ‘deg’)
  • to_unit (str) – unit of result, one of (‘rad’, ‘deg’)
Returns:

angle converted to to_unit
Return type:

float or ndarray
viscid.rotation.check_orthonormality(mat, bad_matrix='warn')[source]

Check that a matrix or stack of matrices is orthonormal

Parameters:
  • mat (ndarray) – A matrix with shape [Ndim, Ndim] or a stack of matrices with shape [Nmatrices, Ndim, Ndim]
  • bad_matrix (str) – What to do if numpy.det(R) != 1.0 - can be one of (‘ignore’, ‘warn’, ‘raise’)
viscid.rotation.e_rot(theta, axis='z', unit='rad')[source]

Make elementary rotation matrices (extrinsic) of theta around axis

Example

>>> e_rot(numpy.pi / 2, 'z') @ [1, 0, 0] = [0, 1, 0]
Parameters:
  • theta (float, sequence) – angle or angles
  • axis (int, str) – one of (0, ‘x’, 1, ‘y’, 2, ‘z’)
  • unit (str) – unit of theta, one of (‘deg’, ‘rad’)
Returns:

rotation matrix with shape [ndim, ndim] or

matrices with shape [Nmatrices, Ndim, Ndim]
Return type:

ndarray
Raises:

ValueError – invalid axis
viscid.rotation.e_dcm(theta, axis='z', unit='rad')[source]

Make elementary rotation matrices (intrinsic) of theta around axis

Example

>>> e_dcm(numpy.pi / 2, 'z') @ [1, 0, 0] = [0, -1, 0]
Parameters:
  • theta (float, sequence) – angle or angles
  • axis (int, str) – one of (0, ‘x’, 1, ‘y’, 2, ‘z’)
  • unit (str) – unit of theta, one of (‘deg’, ‘rad’)
Returns:

rotation matrix with shape [ndim, ndim] or

matrices with shape [Nmatrices, Ndim, Ndim]
Return type:

ndarray
Raises:

ValueError – invalid axis
viscid.rotation.angle_between(a, b, unit='rad')[source]

Get angle(s) between two (sets of) vectors

Parameters:
  • a (sequence) – first vector, shape [Ndim] or [Nvectors, Ndim]
  • b (sequence) – second vector, shape [Ndim] or [Nvectors, Ndim]
  • unit (str) – unit of result, one of (‘deg’, ‘rad’)
Returns:

angle(s)
Return type:

float or ndarray
viscid.rotation.a2b_rot(a, b, roll=0.0, unit='rad', new_x=None)[source]

Make a matrix that rotates vector a to vector b

Parameters:
  • a (ndarray) – starting vector with shape [Ndim] or [Nvectors, Ndim]
  • b (ndarray) – destination vector with shape [Ndim] or [Nvectors, Ndim]
  • roll (float) – angle of roll around the b vector
  • unit (str) – unit of roll, one of (‘deg’, ‘rad’)
  • new_x (ndarray) – If given, then roll is set such that the x axis (phi = 0) new_x is projected in the plane perpendicular to origin-p1
Returns:

orthonormal rotation matrix with shape [Ndim, Ndim]

or [Nvectors, Ndim, Ndim]
Return type:

ndarray
viscid.rotation.symbolic_e_dcm(axis='z', angle=None)[source]

Make elementary matrix that rotate axes, not vectors (sympy)

viscid.rotation.symbolic_e_rot(axis='z', angle=None)[source]

Make elementary matrix that rotate vectors, not the axes (sympy)

viscid.rotation.symbolic_rot(axes='zyx', angles=None)[source]

Make a symbolic rotation matrix (sympy)

viscid.rotation.symbolic_dcm(axes='zyx', angles=None)[source]

Make a symbolic direction cosine matrix (sympy)

viscid.rotation.convert_angles(angle, from_unit, to_unit)

convert angle(s) from rad/deg to rad/deg

Parameters:
  • angle (float, sequence) – angle in from_unit
  • from_unit (str) – unit of angle, one of (‘rad’, ‘deg’)
  • to_unit (str) – unit of result, one of (‘rad’, ‘deg’)
Returns:

angle converted to to_unit
Return type:

float or ndarray
viscid.rotation.angles2rot(angles, axes='zyx', unit='rad')

Euler angles (transform-order) -> rotation matrix (extrinsic)

Rotations are applied in transform-order, which means the first axis given is the first transform applied. In other words, the matrix multiply is in reverse order, i.e.:

>>> R = (R(angles[..., 2], axis[..., 2]) @
>>>      R(angles[..., 1], axis[..., 1]) @
>>>      R(angles[..., 0], axis[..., 0]))

Example

>>> angle2rot([numpy.pi / 2, 0, 0], 'zyx') @ [1, 0, 0] = [0, 1, 0]
Parameters:
  • angles (sequence) – Euler angles in transform-order; can have shape [Ndim] or [Nmatrices, Ndim] to make stacked transform matrices
  • axes (sequence, str) – rotation axes in transform-order
  • unit (str) – unit of angles, one of (‘deg’, ‘rad’)
Returns:

rotation matrix with shape [Ndim, Ndim] or

[Nmatrices, Ndim, Ndim] depending on the shape of angles
Return type:

ndarray
viscid.rotation.angles2dcm(angles, axes='zyx', unit='rad')

Euler angles (transform-order) -> rotation matrix (intrinsic)

Rotations are applied in transform-order, which means the first axis given is the first transform applied. In other words, the matrix multiply is in reverse order, i.e.:

>>> R = (R(angles[..., 2], axis[..., 2]) @
>>>      R(angles[..., 1], axis[..., 1]) @
>>>      R(angles[..., 0], axis[..., 0]))

This function is equivalent (up to a few machine epsilon) to Matlab’s angle2dcm.

Example

>>> angle2dcm([numpy.pi / 2, 0, 0], 'zyx') @ [1, 0, 0] = [0, -1, 0]
Parameters:
  • angles (sequence) – Euler angles in transform-order; can have shape [Ndim] or [Nmatrices, Ndim] to make stacked transform matrices
  • axes (sequence, str) – rotation axes in transform-order
  • unit (str) – unit of angles, one of (‘deg’, ‘rad’)
Returns:

rotation matrix with shape [Ndim, Ndim] or

[Nmatrices, Ndim, Ndim] depending on the shape of angles
Return type:

ndarray
viscid.rotation.rot2angles(R, axes='zyx', unit='rad', bad_matrix='warn')

Rotation matrix (extrinsic) -> Euler angles (transform-order)

Parameters:
  • R (ndarray) – A rotation matrix with shape [Ndim, Ndim] or a stack of matrices with shape [Nmatrices, Ndim, Ndim]
  • axes (sequence, str) – rotation axes in transform-order
  • unit (str) – Unit of angles, one of (‘deg’, ‘rad’)
  • bad_matrix (str) – What to do if numpy.det(R) != 1.0 - can be one of (‘ignore’, ‘warn’, ‘raise’)
Returns:

Euler angles with shape [Ndim] or [Nmatrices, Ndim]

depending on the input. angles[:, i] always corresponds to axes[i].
Return type:

ndarray

See also

viscid.rotation.dcm2angles(R, axes='zyx', unit='rad', bad_matrix='warn')

Rotation matrix (intrinsic) -> Euler angles (transform-order)

Parameters:
  • R (ndarray) – A rotation matrix with shape [Ndim, Ndim] or a stack of matrices with shape [Nmatrices, Ndim, Ndim]
  • axes (sequence, str) – rotation axes in transform-order
  • unit (str) – Unit of angles, one of (‘deg’, ‘rad’)
  • bad_matrix (str) – What to do if numpy.det(R) != 1.0 - can be one of (‘ignore’, ‘warn’, ‘raise’)
Returns:

Euler angles with shape [Ndim] or [Nmatrices, Ndim]

depending on the input. angles[:, i] always corresponds to axes[i].
Return type:

ndarray

See also

viscid.rotation.eul2rotm(angles, axes='zyx', unit='rad')

Euler angles (multiplication-order) -> rotation matrix (extrinsic)

Rotations are applied in multiplication-order, which means the last axis given is the first transform applied. In other words:

>>> R = (R(angles[..., 0], axis[..., 0]) @
>>>      R(angles[..., 1], axis[..., 1]) @
>>>      R(angles[..., 2], axis[..., 2]))

This function is equivalent (up to a few machine epsilon) to Matlab’s eul2rotm.

Example

>>> eul2rot([numpy.pi / 2, 0, 0], 'zyx') @ [1, 0, 0] = [0, 1, 0]
Parameters:
  • angles (sequence) – Euler angles in multiplication-order; can have shape [Ndim] or [Nmatrices, Ndim] to make stacked transform matrices
  • axes (sequence, str) – rotation axes in multiplication-order
  • unit (str) – unit of angles, one of (‘deg’, ‘rad’)
Returns:

rotation matrix with shape [Ndim, Ndim] or

[Nmatrices, Ndim, Ndim] depending on the shape of angles
Return type:

ndarray
viscid.rotation.angle2rotm(angles, axes='zyx', unit='rad')

Euler angles (transform-order) -> rotation matrix (extrinsic)

Rotations are applied in transform-order, which means the first axis given is the first transform applied. In other words, the matrix multiply is in reverse order, i.e.:

>>> R = (R(angles[..., 2], axis[..., 2]) @
>>>      R(angles[..., 1], axis[..., 1]) @
>>>      R(angles[..., 0], axis[..., 0]))

Example

>>> angle2rot([numpy.pi / 2, 0, 0], 'zyx') @ [1, 0, 0] = [0, 1, 0]
Parameters:
  • angles (sequence) – Euler angles in transform-order; can have shape [Ndim] or [Nmatrices, Ndim] to make stacked transform matrices
  • axes (sequence, str) – rotation axes in transform-order
  • unit (str) – unit of angles, one of (‘deg’, ‘rad’)
Returns:

rotation matrix with shape [Ndim, Ndim] or

[Nmatrices, Ndim, Ndim] depending on the shape of angles
Return type:

ndarray
viscid.rotation.angles2rotm(angles, axes='zyx', unit='rad')

Euler angles (transform-order) -> rotation matrix (extrinsic)

Rotations are applied in transform-order, which means the first axis given is the first transform applied. In other words, the matrix multiply is in reverse order, i.e.:

>>> R = (R(angles[..., 2], axis[..., 2]) @
>>>      R(angles[..., 1], axis[..., 1]) @
>>>      R(angles[..., 0], axis[..., 0]))

Example

>>> angle2rot([numpy.pi / 2, 0, 0], 'zyx') @ [1, 0, 0] = [0, 1, 0]
Parameters:
  • angles (sequence) – Euler angles in transform-order; can have shape [Ndim] or [Nmatrices, Ndim] to make stacked transform matrices
  • axes (sequence, str) – rotation axes in transform-order
  • unit (str) – unit of angles, one of (‘deg’, ‘rad’)
Returns:

rotation matrix with shape [Ndim, Ndim] or

[Nmatrices, Ndim, Ndim] depending on the shape of angles
Return type:

ndarray
viscid.rotation.rotm2eul(R, axes='zyx', unit='rad', bad_matrix='warn')

Rotation matrix (extrinsic) -> Euler angles (multiplication-order)

Parameters:
  • R (ndarray) – A rotation matrix with shape [Ndim, Ndim] or a stack of matrices with shape [Nmatrices, Ndim, Ndim]
  • axes (sequence, str) – rotation axes in multiplication-order
  • unit (str) – Unit of angles, one of (‘deg’, ‘rad’)
  • bad_matrix (str) – What to do if numpy.det(R) != 1.0 - can be one of (‘ignore’, ‘warn’, ‘raise’)
Returns:

Euler angles with shape [Ndim] or [Nmatrices, Ndim]

depending on the input. angles[:, i] always corresponds to axes[i].
Return type:

ndarray

See also

  • rot2eul() for more details about axes order.
viscid.rotation.rotm2angle(R, axes='zyx', unit='rad', bad_matrix='warn')

Rotation matrix (extrinsic) -> Euler angles (transform-order)

Parameters:
  • R (ndarray) – A rotation matrix with shape [Ndim, Ndim] or a stack of matrices with shape [Nmatrices, Ndim, Ndim]
  • axes (sequence, str) – rotation axes in transform-order
  • unit (str) – Unit of angles, one of (‘deg’, ‘rad’)
  • bad_matrix (str) – What to do if numpy.det(R) != 1.0 - can be one of (‘ignore’, ‘warn’, ‘raise’)
Returns:

Euler angles with shape [Ndim] or [Nmatrices, Ndim]

depending on the input. angles[:, i] always corresponds to axes[i].
Return type:

ndarray

See also

viscid.rotation.rotm2angles(R, axes='zyx', unit='rad', bad_matrix='warn')

Rotation matrix (extrinsic) -> Euler angles (transform-order)

Parameters:
  • R (ndarray) – A rotation matrix with shape [Ndim, Ndim] or a stack of matrices with shape [Nmatrices, Ndim, Ndim]
  • axes (sequence, str) – rotation axes in transform-order
  • unit (str) – Unit of angles, one of (‘deg’, ‘rad’)
  • bad_matrix (str) – What to do if numpy.det(R) != 1.0 - can be one of (‘ignore’, ‘warn’, ‘raise’)
Returns:

Euler angles with shape [Ndim] or [Nmatrices, Ndim]

depending on the input. angles[:, i] always corresponds to axes[i].
Return type:

ndarray

See also

viscid.rotation.rotm2quat(R)

Rotation matrix (extrinsic) -> quaternion

If this quaternion library is imported, then the results are presented with dtype quaternion, otherwise, as dtype numpy.double (array-of-struct, [scalar, vec0, vec1, vec2]).

Parameters:R (ndarray) – A rotation matrix with shape [Ndim, Ndim] or a stack of matrices with shape [Nmatrices, Ndim, Ndim]
Returns:
quaternions with dtype quaternion with shape
(Nmatrices,) or (); or with dtype numpy.double and shape (Nmatrices, 4) or (4)
Return type:ndarray
viscid.rotation.quat2rotm(q)

Quaternion -> rotation matrix (extrinsic)

Parameters:q (ndarray) – quaternions with dtype quaternion and shape (Nmatrices,) or (); or with dtype numpy.double and shape (Nmatrices, 4) or (4)
Returns:
orthonormal rotation matrix with shape (3, 3)
or (Nmatrices, 3, 3)
Return type:ndarray
viscid.rotation.a2b_rotm(a, b, roll=0.0, unit='rad', new_x=None)

Make a matrix that rotates vector a to vector b

Parameters:
  • a (ndarray) – starting vector with shape [Ndim] or [Nvectors, Ndim]
  • b (ndarray) – destination vector with shape [Ndim] or [Nvectors, Ndim]
  • roll (float) – angle of roll around the b vector
  • unit (str) – unit of roll, one of (‘deg’, ‘rad’)
  • new_x (ndarray) – If given, then roll is set such that the x axis (phi = 0) new_x is projected in the plane perpendicular to origin-p1
Returns:

orthonormal rotation matrix with shape [Ndim, Ndim]

or [Nvectors, Ndim, Ndim]
Return type:

ndarray
viscid.rotation.axang2rotm(axang, unit='rad')

Make a matrix (matrices) that rotates around vector by angle

Parameters:
  • axang (ndarray) – axis(es) / angle(s) of rotation(s) put together like {x, y, z, angle}; shape should be (4,), or (Nmatrices, 4)
  • unit (str) – unit of angle, one of (‘deg’, ‘rad’)
Returns:

orthonormal rotation matrix with shape (3, 3)

or (Nmatrices, 3, 3)
Return type:

ndarray
viscid.rotation.rotm2axang(R, unit='rad', quick=True, bad_matrix='warn')

Find axis / angle representation of rotation matrix (matrices)

Parameters:
  • R (ndarray) – Rotation matrix with shape (3, 3) determinant +1, or matrices with shape (Nmatrices, 3, 3)
  • unit (str) – unit of angle in results, one of (‘deg’, ‘rad’)
  • quick (bool) – Try a quicker, less well tested method
  • bad_matrix (str) – What to do if numpy.det(R) != 1.0 - can be one of (‘ignore’, ‘warn’, ‘raise’)
Returns:

{x, y, z, angle} axis / angle values with shape (4,)

or (Nmatrices, 4)
Return type:

(ndarray)
viscid.rotation.wxyz2rotm(angle, vector, unit='rad')

Make a matrix (matrices) that rotates around vector by angle

Parameters:
  • angle (sequence) – angle(s) of rotation(s) with shape (), (1,), or (Nmatrices)
  • vector (sequence) – 3d vector(s) that is (are) axis of rotation(s) with shape (3,) or (Nmatrices, 3)
  • unit (str) – unit of angle, one of (‘deg’, ‘rad’)
Returns:

orthonormal rotation matrix with shape (3, 3)

or (Nmatrices, 3, 3)
Return type:

ndarray
viscid.rotation.rotm2wxyz(R, unit='rad', quick=True, bad_matrix='warn')

Find axis / angle representation of rotation matrix (matrices)

Parameters:
  • R (ndarray) – Rotation matrix with shape (3, 3) determinant +1, or matrices with shape (Nmatrices, 3, 3)
  • unit (str) – unit of angle in results, one of (‘deg’, ‘rad’)
  • quick (bool) – Try a quicker, less well tested method
  • bad_matrix (str) – What to do if numpy.det(R) != 1.0 - can be one of (‘ignore’, ‘warn’, ‘raise’)
Returns:

w is rotation angle with shape () or (Nmatrices),

and xyz are normalized rotation axes with shape (3,) or (Nmatrices, 3)
Return type:

(w, xyz)