{"id":4134,"library":"numpy-quaternion","title":"numpy-quaternion","description":"numpy-quaternion extends NumPy by adding a quaternion dtype, enabling efficient array operations and mathematical functions for handling quaternions. This library is crucial for applications involving 3D rotations, such as animation, robotics, and aerospace. It is actively maintained with frequent releases, with the current version being 2024.0.13.","status":"active","version":"2024.0.13","language":"en","source_language":"en","source_url":"https://github.com/moble/quaternion","tags":["numpy","quaternion","mathematics","rotations","3d graphics","robotics"],"install":[{"cmd":"pip install numpy-quaternion","lang":"bash","label":"Install with pip"},{"cmd":"conda install -c conda-forge quaternion","lang":"bash","label":"Install with conda"}],"dependencies":[{"reason":"Core dependency, provides the array infrastructure for the quaternion dtype.","package":"numpy"},{"reason":"Optional dependency for certain advanced functions like SQUAD interpolation and integration.","package":"scipy","optional":true}],"imports":[{"note":"The `quaternion` module registers its custom dtype with NumPy, allowing creation via `np.quaternion`.","symbol":"quaternion","correct":"import quaternion\nimport numpy as np"}],"quickstart":{"code":"import numpy as np\nimport quaternion\n\n# Create a quaternion\nq_rot = np.quaternion(0.92388, 0, 0.38268, 0) # Example: 45-degree rotation around Y-axis\n\n# Represent a 3D point as a pure-imaginary quaternion\npoint = np.quaternion(0, 1, 0, 0) # Represents point (1, 0, 0)\n\n# Rotate the point using quaternion multiplication\nrotated_point = q_rot * point * q_rot.conjugate()\n\nprint(f\"Original point: ({point.x}, {point.y}, {point.z})\")\nprint(f\"Rotation quaternion: {q_rot}\")\nprint(f\"Rotated point: ({rotated_point.x:.3f}, {rotated_point.y:.3f}, {rotated_point.z:.3f})\")","lang":"python","description":"This quickstart demonstrates how to create a quaternion, represent a 3D point as a pure-imaginary quaternion, and apply a rotation using quaternion multiplication."},"warnings":[{"fix":"Prefer quaternion-based rotation representations (e.g., axis-angle, rotation matrices) and operations where possible, and avoid converting to/from Euler angles unless absolutely necessary.","message":"The library strongly discourages the use of Euler angles for rotations due to issues like gimbal lock and reduced accuracy. Quaternions are presented as a superior alternative.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that operations that might implicitly convert the dtype are handled carefully. If a copy is needed, explicitly re-cast the result to the quaternion dtype or use library-specific copying mechanisms if available.","message":"When performing `numpy.copy()` on an array of `quaternion` dtype, the resulting array might lose its quaternionic nature and become a plain array of floats, leading to incorrect behavior in subsequent quaternion operations.","severity":"gotcha","affected_versions":"All versions (based on GitHub discussion related to `numpy` interaction)"},{"fix":"For optimal performance and precision in vector rotations, consider using dedicated functions like `rotate_vectors` instead of manual multiplication sequences.","message":"While `R * v * R.conjugate()` is a mathematically valid way to rotate a pure-vector quaternion `v` by a rotation quaternion `R`, using the `rotate_vectors` function (if available for your specific use case or a utility function in the broader `quaternion` ecosystem) can often be more efficient and numerically accurate.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify that your `numpy-quaternion` version explicitly supports NumPy 2.x. If you encounter issues, upgrade `numpy-quaternion` to its latest version, which likely includes patches for NumPy 2.x compatibility, or pin your NumPy version to 1.x.","message":"Compatibility with NumPy 2.x (released late 2025) may require updates. NumPy 2.0 introduced significant breaking changes to its ABI, Python, and C APIs, which can affect libraries that deeply integrate with NumPy dtypes like `numpy-quaternion`.","severity":"breaking","affected_versions":"Older versions of numpy-quaternion with NumPy >= 2.0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}