num-quaternions 0.1.2

Numerical quaternion implementation for 3D rotations using NumPy

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(hi=np.pi/2, vector=[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 'hi' around axis 'vector'
q = NumQuaternion(hi=np.pi/4, vector=[0.0, 0.0, 1.0])

# Parameters:
# - hi: rotation angle in radians
# - vector: 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(hi=np.pi/4, vector=[0.0, 0.0, 1.0])
q2 = NumQuaternion(hi=np.pi/4, vector=[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(hi=np.pi/2, vector=[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

Migration from Earlier Versions

If you're upgrading from an older version, note the following method name changes to comply with PEP8:

Old Name (camelCase)	New Name (snake_case)
rotateVector()	rotate_vector()
rotateBasis()	rotate_basis()
getMatrix()	get_matrix()
_prodQuaternions()	_prod_quaternions()
_vectorProduct()	_vector_product()
_absVector()	_abs_vector()

The library also now uses np.array (ndarray) instead of the deprecated np.matrix type.

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 ([e-mail])

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Links

• GitHub: https://github.com/avabr/num-quaternions
• PyPI: https://pypi.org/project/num-quaternions/
• Issues: https://github.com/avabr/num-quaternions/issues