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

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

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

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

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