Metadata-Version: 2.4
Name: num-quaternions
Version: 0.1.1
Summary: Numerical quaternion implementation for 3D rotations using NumPy
Author-email: Alexander Abramov <extremal.ru@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/avabr/num-quaternions
Project-URL: Repository, https://github.com/avabr/num-quaternions
Project-URL: Issues, https://github.com/avabr/num-quaternions/issues
Keywords: quaternion,rotation,3d,numpy,mathematics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Dynamic: license-file

# 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:

```bash
pip install num-quaternions
```

Or install from source:

```bash
git clone https://github.com/avabr/num-quaternions.git
cd num-quaternions
pip install -e .
```

## Usage

### Basic Example

```python
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

```python
# 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

```python
# 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

```python
# 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

```python
# 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

```python
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:

```bash
# 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

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