Skip to main content

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 space
  • rotate_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.

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)

Source distribution for num-quaternions 0.1.4
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)

Table of built distributions (wheels) for num-quaternions 0.1.4
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page