Registry / data / numpy-quaternion

numpy-quaternion

library2024.0.13pypypi✓ verified 23d ago

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.

data

pip install numpy-quaternion

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · NUMPY-QUATERNION

numpy-quaternion

datapythonv2024.0.13

Install

6.7s avg

Import

1192ms

Disk

180MB

Pass rate

6/ 10

Env Coverage6 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2024.0.13 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✕ build_error

✓ 7.1s

py 3.11

✕ build_error

✓ 7.1s

py 3.12

✕ build_error

✓ 7.2s

py 3.13

✕ build_error

✓ 7.4s

py 3.9

✓ —

✓ 4.5s

180MB installed

● package 180MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

quaternion

✓ import quaternion import numpy as np

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

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})")

Debug

Known issues

gotchaThe 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.

affects: All versions

gotchaWhen 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.

affects: All versions (based on GitHub discussion related to `numpy` interaction)

gotchaWhile `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.

affects: All versions

breakingCompatibility 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.

affects: Older versions of numpy-quaternion with NumPy >= 2.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'quaternion'

This occurs because the package is installed via `pip install numpy-quaternion` or `conda install -c conda-forge quaternion`, but users often try to import it as `import quaternions` or `import Quaternion` (capitalized), or the environment is not correctly configured.

fix

Ensure the package is installed correctly (`python -m pip install numpy-quaternion` or `conda install -c conda-forge quaternion`) and then import it using `import quaternion` (lowercase and singular).

AttributeError: module 'numpy' has no attribute 'object'

This error arises in projects using `numpy-quaternion` when an older version of `numpy-quaternion` (or user code) attempts to use `np.object` with a NumPy version 1.24 or newer, where `np.object` has been deprecated.

fix

Upgrade `numpy-quaternion` to its latest version (`python -m pip install --upgrade numpy-quaternion`). If the error persists in user code, replace `np.object` with Python's built-in `object` type or `np.object_`.

TypeError: ufunc 'arctan2' not supported for the input types, and the inputs could not be safely coerced to any supported types according to the casting rule ''safe''.

This error occurs when attempting to use certain NumPy universal functions (ufuncs) like `np.angle()` directly on `numpy-quaternion` arrays. These NumPy functions often assume real or complex number inputs and do not have specific implementations or overrides for the `quaternion` dtype.

fix

Access the components of the quaternion (e.g., `q.w`, `q.x`, `q.y`, `q.z`) and perform the operation on the float components, or use a quaternion-specific function if available within the `quaternion` module that handles such operations (e.g., `quaternion.arg(q)` for the angle/argument of a quaternion).

AttributeError: type object 'quaternion' has no attribute 'from_axis_angle'

This typically happens when trying to call a top-level function from the `quaternion` module (like `from_axis_angle` or `from_rotation_matrix`) as if it were a method of the `quaternion` data type itself (e.g., `quaternion.quaternion.from_axis_angle()`) or if attempting to use a function from a different quaternion library.

fix

Call these constructors directly from the `quaternion` module, for example: `import quaternion` and then `q = quaternion.from_axis_angle(axis, angle)`.

Upgrade

Version history

2024.0.13latest on PyPI · released Nov 24, 2025

Audit

Dependencies

numpyrequiredCore dependency, provides the array infrastructure for the quaternion dtype.

scipyoptionalOptional dependency for certain advanced functions like SQUAD interpolation and integration.

Agent activity

3 hits · last 30 days

node

Resources

githubhttps://github.com/moble/quaternion ↗

packagehttps://pypi.org/project/numpy-quaternion/ ↗

docshttps://quaternion.readthedocs.io/en/latest ↗