PyQuaternion

Warnings

• gotcha The library has not seen a new release since October 2020. While it may be stable, users should be aware that active feature development or rapid bug fixes are unlikely.
  Fix: Review the GitHub issues and pull requests for any pending critical fixes. Consider the project's long-term maintenance status if this is a concern for new projects.
• gotcha When a quaternion represents a null rotation (angle is 0), its rotation axis is geometrically undefined. `pyquaternion` defaults this axis to `[0, 0, 0]`, which might be unexpected or cause issues in downstream calculations if not handled explicitly. The `get_axis(undefined=[...])` method allows specifying a custom default.
  Fix: When dealing with potentially null rotations, explicitly check `my_quaternion.angle` and, if zero, use `my_quaternion.get_axis(undefined=[your_preferred_default])` to control the returned axis vector.
• gotcha Some methods, such as `angle`, `integrate`, and `normalised`, implicitly normalize the Quaternion object to a unit quaternion if it is not already one. While often desirable for rotations, this automatic normalization might be an unexpected side-effect if you are working with non-unit quaternions and expect their norm to be preserved.
  Fix: Be aware of methods that implicitly normalize. If working with non-unit quaternions and their norm is critical, explicitly check the `is_unit` property or re-normalize manually when required, rather than relying on implicit behavior.
• gotcha An older GitHub issue (#21, dating from 2018/2021) indicated potential sign-flipping issues with the i, j, k components during matrix-to-quaternion conversions. While there was a response from the maintainer, the issue's long-standing open status might suggest it was not fully resolved in the latest release or required specific workarounds.
  Fix: Thoroughly validate matrix-to-quaternion conversions, especially if integrating with other libraries or systems that use different quaternion conventions. Cross-verify results with known correct transformations for critical paths. If issues persist, consider manually implementing or adjusting for potential sign differences.

Install

• pip install pyquaternion Install from PyPI

Imports

• Quaternion

  from pyquaternion import Quaternion

Quickstart

This quickstart demonstrates creating a quaternion for a 90-degree rotation around the Y-axis and applying it to a vector. It also shows basic spherical linear interpolation (SLERP) between two quaternions.

import pyquaternion
import numpy as np

# Create a quaternion representing a rotation of +90 degrees about the positive y-axis
my_quaternion = pyquaternion.Quaternion(axis=[0, 1, 0], degrees=90)

# Define a vector to rotate
my_vector = np.array([0., 0., 4.])

# Rotate the vector
my_rotated_vector = my_quaternion.rotate(my_vector)

print(f"Original Vector: {my_vector}")
print(f"Performing rotation of {my_quaternion.degrees:.1f} degrees about {my_quaternion.axis}")
print(f"Rotated Vector: {my_rotated_vector}")

# Example of interpolation
null_quaternion = pyquaternion.Quaternion(axis=[0, 1, 0], angle=0)
print("\nInterpolated Rotations:")
for i, q in enumerate(pyquaternion.Quaternion.intermediates(null_quaternion, my_quaternion, 3, include_endpoints=True)):
    interpolated_vector = q.rotate(my_vector)
    print(f"  Step {i}: rotated by {q.degrees:.1f} deg about {q.axis}, resulting in {interpolated_vector}")