num-quaternions
A Python library for numerical quaternion operations using NumPy, designed for 3D rotations and transformations.
Description
num-quaternions provides a simple and efficient implementation of quaternions for representing and manipulating 3D rotations. The library is built on top of NumPy using modern ndarray types and follows PEP8 naming conventions. It offers methods for:
- Creating rotation quaternions from axis-angle representation
- Rotating vectors and coordinate bases
- Converting quaternions to rotation matrices
- Quaternion arithmetic (multiplication, conjugation, inversion)
- Vector operations (cross product, norm calculations)
Installation
Install from PyPI:
pip install num-quaternions
Or install from source:
git clone https://github.com/avabr/num-quaternions.git
cd num-quaternions
pip install -e .
Usage
Basic Example
import numpy as np
from num_quaternions import NumQuaternion
# Create a quaternion representing 90-degree rotation around x-axis
q = NumQuaternion(angle=np.pi/2, axis=[1.0, 0.0, 0.0])
# Define a vector
v = np.array([0.0, 1.0, 0.0])
# Rotate the vector
rotated = q.rotate_vector(v)
print(rotated) # Output: [0. 0. 1.]
Creating Quaternions
# Default quaternion (180-degree rotation)
q = NumQuaternion()
# Custom rotation: angle 'angle' around axis 'axis'
q = NumQuaternion(angle=np.pi/4, axis=[0.0, 0.0, 1.0])
# Parameters:
# - angle: rotation angle in radians
# - axis: rotation axis as [x, y, z] (will be normalized)
Rotating Vectors
# Rotate a vector in space
v = np.array([1.0, 0.0, 0.0])
v_rotated = q.rotate_vector(v)
# Rotate the coordinate basis (inverse rotation)
v_basis = q.rotate_basis(v)
Getting Rotation Matrix
# Get the 3x3 rotation matrix
M = q.get_matrix()
print(M)
# The matrix can be used for standard matrix operations
v_matrix = np.array([[1.0], [0.0], [0.0]])
v_rotated = M @ v_matrix
Quaternion Operations
# Quaternion conjugate
q_conj = q._conjugate()
# Quaternion norm (should be 1 for unit quaternions)
norm = q._norma()
# Quaternion inverse
q_inv = q._inv()
# Quaternion multiplication
q1 = NumQuaternion(angle=np.pi/4, axis=[0.0, 0.0, 1.0])
q2 = NumQuaternion(angle=np.pi/4, axis=[0.0, 0.0, 1.0])
q_result = q1._prod_quaternions(q1, q2) # 90-degree rotation
Complete Example
import numpy as np
from num_quaternions import NumQuaternion
# Create a 90-degree rotation around the z-axis
q = NumQuaternion(angle=np.pi/2, axis=[0.0, 0.0, 1.0])
# Rotate a point
point = np.array([1.0, 0.0, 0.0])
rotated_point = q.rotate_vector(point)
print(f"Original: {point}")
print(f"Rotated: {rotated_point}")
# Output:
# Original: [1. 0. 0.]
# Rotated: [ 0. 1. 0.]
# Get the rotation matrix
matrix = q.get_matrix()
print(f"Rotation matrix:\n{matrix}")
# Verify it's a valid rotation matrix
det = np.linalg.det(matrix)
print(f"Determinant: {det}") # Should be 1.0
API Reference
Public Methods
rotate_vector(vector)- Rotate a vector in spacerotate_basis(vector)- Rotate the coordinate basis (inverse rotation)get_matrix()- Get the 3x3 rotation matrix representation
Private Methods (for advanced use)
_conjugate()- Get the quaternion conjugate_norma()- Calculate the quaternion norm_inv()- Get the quaternion inverse_prod_quaternions(q1, q2)- Multiply two quaternions_vector_product(v1, v2)- Calculate vector cross product_abs_vector(vector)- Calculate vector magnitude
Running Tests
To run the test suite:
# Install development dependencies
pip install -r requirements.txt
# Run tests
pytest tests/
# Run tests with verbose output
pytest -v tests/
# Run specific test
pytest tests/test_num_quaternion.py::TestNumQuaternion::test_rotate_vector_90_degrees_x_axis
Requirements
- Python >= 3.7
- numpy >= 1.20.0
License
MIT License - see LICENSE file for details.
Author
Alexander Abramov (extremal.ru@gmail.com)
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Links
Metadata
Release files for num-quaternions 0.1.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| num_quaternions-0.1.4.tar.gz | 6.8 kB | Without provenance | Details for num_quaternions-0.1.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| num_quaternions-0.1.4-py3-none-any.whl | Python 3 | none | any | Details for num_quaternions-0.1.4-py3-none-any.whl |
Total release size: 12.3 kB
Release files / num_quaternions-0.1.4.tar.gz
| Download URL | num_quaternions-0.1.4.tar.gz |
|---|---|
| Size | 6.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b4004c86ca090477e7f0999b561206d1cf0809f210daec8d2c4afa0cdcbfbfcd
|
|
BLAKE2b-256 checksum How to use checksums |
b7902b2fcbc0c1fee345e43f5c035572d2c69dc7efe69436b531df671c932912
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.11
|
Release files / num_quaternions-0.1.4-py3-none-any.whl
| Download URL | num_quaternions-0.1.4-py3-none-any.whl |
|---|---|
| Size | 5.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a0322e5c2d14a806f923b88173e6ada6635d5dcd7fa99883c82c2e44d8ffc774
|
|
BLAKE2b-256 checksum How to use checksums |
70dbf9e2adaaebe355b946e85816803cbcf6dfad40cb8ce465080e79fcdc6e9b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.11
|
Security for num-quaternions 0.1.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.