numpy-quaternion

Warnings

• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  Fix: For optimal performance and precision in vector rotations, consider using dedicated functions like `rotate_vectors` instead of manual multiplication sequences.
• breaking 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`.
  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.

Install

• pip install numpy-quaternion Install with pip
• conda install -c conda-forge quaternion Install with conda

Imports

• quaternion

  import quaternion
  import numpy as np

  The `quaternion` module registers its custom dtype with NumPy, allowing creation via `np.quaternion`.

Quickstart

This quickstart demonstrates how to create a quaternion, represent a 3D point as a pure-imaginary quaternion, and apply a rotation using quaternion multiplication.

import numpy as np
import quaternion

# Create a quaternion
q_rot = np.quaternion(0.92388, 0, 0.38268, 0) # Example: 45-degree rotation around Y-axis

# Represent a 3D point as a pure-imaginary quaternion
point = np.quaternion(0, 1, 0, 0) # Represents point (1, 0, 0)

# Rotate the point using quaternion multiplication
rotated_point = q_rot * point * q_rot.conjugate()

print(f"Original point: ({point.x}, {point.y}, {point.z})")
print(f"Rotation quaternion: {q_rot}")
print(f"Rotated point: ({rotated_point.x:.3f}, {rotated_point.y:.3f}, {rotated_point.z:.3f})")