# Quaternion

Provide functions for the creation and manipulation of Quaternions.

pyrr.quaternion.apply_to_vector(quat, vec)

  Rotates a vector by a quaternion.

  Parameters:

    - quat (numpy.array) – The quaternion.

    - vec (numpy.array) – The vector.

  Return type:

    numpy.array

  Returns:

    The vector rotated by the quaternion.

  Raises:

    ValueError – raised if the vector is an unsupported size

pyrr.quaternion.conjugate(quat)

  Calculates a quaternion with the opposite rotation.

  Parameters:

    quat (numpy.array) – The quaternion.

  Return type:

    numpy.array.

  Returns:

    A quaternion representing the conjugate.

pyrr.quaternion.create(x=0.0, y=0.0, z=0.0, w=1.0, dtype=None)

pyrr.quaternion.create_from_axis(axis, dtype=None)

pyrr.quaternion.create_from_axis_rotation(axis, theta, dtype=None)

pyrr.quaternion.create_from_eulers(eulers, dtype=None)

  Creates a quaternion from a set of Euler angles.

  Eulers are an array of length 3 in the following order:

    [roll, pitch, yaw]

pyrr.quaternion.create_from_inverse_of_eulers(eulers, dtype=None)

  Creates a quaternion from the inverse of a set of Euler angles.

  Eulers are an array of length 3 in the following order:

    [roll, pitch, yaw]

pyrr.quaternion.create_from_matrix(mat, dtype=None)

pyrr.quaternion.create_from_x_rotation(theta, dtype=None)

pyrr.quaternion.create_from_y_rotation(theta, dtype=None)

pyrr.quaternion.create_from_z_rotation(theta, dtype=None)

pyrr.quaternion.cross(quat1, quat2)

  Returns the cross-product of the two quaternions.

  Quaternions are not communicative. Therefore, order is important.

  This is NOT the same as a vector cross-product. Quaternion cross-product is the equivalent of matrix multiplication.

pyrr.quaternion.dot(quat1, quat2)

  Calculate the dot product of quaternions.

  This is the same as a vector dot product.

  Parameters:

    - quat1 (numpy.array) – The first quaternion(s).

    - quat2 (numpy.array) – The second quaternion(s).

  Return type:

    float, numpy.array

  Returns:

    If a 1d array was passed, it will be a scalar. Otherwise the result will be an array of scalars with shape vec.ndim with the last dimension being size 1.

pyrr.quaternion.exp(quat)

  Calculate the exponential of the quaternion

  Parameters:

    quat (numpy.array) – The quaternion.

  Return type:

    numpy.array.

  Returns:

    The exponential of the quaternion

class pyrr.quaternion.index
  w = 3

    The index of the W value within the quaternion

  x = 0

    The index of the X value within the quaternion

  y = 1

    The index of the Y value within the quaternion

  z = 2

    The index of the Z value within the quaternion

pyrr.quaternion.inverse(quat)

  Calculates the inverse quaternion.

  The inverse of a quaternion is defined as the conjugate of the quaternion divided by the magnitude of the original quaternion.

  Parameters:

    quat (numpy.array) – The quaternion to invert.

  Return type:

    numpy.array.

  Returns:

    The inverse of the quaternion.

pyrr.quaternion.is_identity(quat)

pyrr.quaternion.is_non_zero_length(quat)

  Checks if a quaternion is not zero length.

  This is the opposite to ‘is_zero_length’. This is provided for readability.

  Parameters:

    quat (numpy.array) – The quaternion to check.

  Return type:

    boolean

  Returns:

    False if the quaternion is zero length, otherwise True.

  See also

  is_zero_length

pyrr.quaternion.is_zero_length(quat)

  Checks if a quaternion is zero length.

  Parameters:

    quat (numpy.array) – The quaternion to check.

  Return type:

    boolean.

  Returns:

    True if the quaternion is zero length, otherwise False.

pyrr.quaternion.length(quat)

  Calculates the length of a quaternion.

  Parameters:

    quat (numpy.array) – The quaternion to measure.

  Return type:

    float, numpy.array

  Returns:

    If a 1d array was passed, it will be a scalar. Otherwise the result will be an array of scalars with shape vec.ndim with the last dimension being size 1.

pyrr.quaternion.lerp(quat1, quat2, t)

  Interpolates between quat1 and quat2 by t. The parameter t is clamped to the range [0, 1]

pyrr.quaternion.negate(quat)

  Calculates the negated quaternion.

  This is essentially the quaternion * -1.0.

  Parameters:

    quat (numpy.array) – The quaternion.

  Return type:

    numpy.array

  Returns:

    The negated quaternion.

pyrr.quaternion.normalise(quat)

  Ensure a quaternion is unit length (length ~= 1.0).

  The quaternion is not changed in place.

  Parameters:

    quat (numpy.array) – The quaternion to normalize.

  Return type:

    numpy.array

  Returns:

    The normalized quaternion(s).

pyrr.quaternion.normalize(quat)

  Ensure a quaternion is unit length (length ~= 1.0).

  The quaternion is not changed in place.

  Parameters:

    quat (numpy.array) – The quaternion to normalize.

  Return type:

    numpy.array

  Returns:

    The normalized quaternion(s).

pyrr.quaternion.power(quat, exponent)

  Multiplies the quaternion by the exponent.

  The quaternion is not changed in place.

  Parameters:

    - quat (numpy.array) – The quaternion.

    - scalar (float) – The exponent.

  Return type:

    numpy.array.

  Returns:

    A quaternion representing the original quaternion to the specified power.

pyrr.quaternion.rotation_angle(quat)

  Calculates the rotation around the quaternion’s axis.

  Parameters:

    quat (numpy.array) – The quaternion.

  Return type:

    float.

  Returns:

    The quaternion’s rotation about the its axis in radians.

pyrr.quaternion.rotation_axis(quat)

  Calculates the axis of the quaternion’s rotation.

  Parameters:

    quat (numpy.array) – The quaternion.

  Return type:

    numpy.array.

  Returns:

    The quaternion’s rotation axis.

pyrr.quaternion.slerp(quat1, quat2, t)

  Spherically interpolates between quat1 and quat2 by t. The parameter t is clamped to the range [0, 1]

pyrr.quaternion.squared_length(quat)

  Calculates the squared length of a quaternion.

  Useful for avoiding the performanc penalty of the square root function.

  Parameters:

    quat (numpy.array) – The quaternion to measure.

  Return type:

    float, numpy.array

  Returns:

    If a 1d array was passed, it will be a scalar. Otherwise the result will be an array of scalars with shape vec.ndim with the last dimension being size 1.