{"id":2708,"library":"pyquaternion","title":"PyQuaternion","description":"PyQuaternion is a fully featured, pythonic library designed for representing and manipulating quaternions. It provides extensive functionality for 3D animation, geometry, and numerical computations, including operations like rotation, interpolation, differentiation, and integration. The current version is 0.9.9, released in October 2020, suggesting a stable but infrequently updated release cadence.","status":"active","version":"0.9.9","language":"en","source_language":"en","source_url":"https://github.com/KieranWynn/pyquaternion","tags":["quaternion","3D rotation","mathematics","physics","geometry","animation","robotics"],"install":[{"cmd":"pip install pyquaternion","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Required for array and matrix representation and numerical operations, automatically installed.","package":"numpy","optional":false}],"imports":[{"symbol":"Quaternion","correct":"from pyquaternion import Quaternion"}],"quickstart":{"code":"import pyquaternion\nimport numpy as np\n\n# Create a quaternion representing a rotation of +90 degrees about the positive y-axis\nmy_quaternion = pyquaternion.Quaternion(axis=[0, 1, 0], degrees=90)\n\n# Define a vector to rotate\nmy_vector = np.array([0., 0., 4.])\n\n# Rotate the vector\nmy_rotated_vector = my_quaternion.rotate(my_vector)\n\nprint(f\"Original Vector: {my_vector}\")\nprint(f\"Performing rotation of {my_quaternion.degrees:.1f} degrees about {my_quaternion.axis}\")\nprint(f\"Rotated Vector: {my_rotated_vector}\")\n\n# Example of interpolation\nnull_quaternion = pyquaternion.Quaternion(axis=[0, 1, 0], angle=0)\nprint(\"\\nInterpolated Rotations:\")\nfor i, q in enumerate(pyquaternion.Quaternion.intermediates(null_quaternion, my_quaternion, 3, include_endpoints=True)):\n    interpolated_vector = q.rotate(my_vector)\n    print(f\"  Step {i}: rotated by {q.degrees:.1f} deg about {q.axis}, resulting in {interpolated_vector}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"0.9.9 and potentially earlier versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"Potentially all versions up to 0.9.9"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}