0
# pyquaternion
1

2
A fully featured, pythonic library for quaternion representation, manipulation, 3D animation and geometry. Provides comprehensive quaternion mathematics designed for 3D rotation representation, manipulation, and animation with efficient NumPy-based computation.
3

4
## Package Information
5

6
- **Package Name**: pyquaternion
7
- **Language**: Python
8
- **Installation**: `pip install pyquaternion`
9
- **Dependencies**: numpy
10

11
## Core Imports
12

13
```python
14
from pyquaternion import Quaternion
15
```
16

17
## Basic Usage
18

19
```python
20
from pyquaternion import Quaternion
21
import numpy as np
22

23
# Create quaternion from axis and angle
24
q1 = Quaternion(axis=[0, 1, 0], degrees=90)  # 90° rotation about Y-axis
25

26
# Create quaternion from components
27
q2 = Quaternion(w=1, x=0, y=0, z=0)  # Identity quaternion
28

29
# Create quaternion from rotation matrix
30
rotation_matrix = np.eye(3)
31
q3 = Quaternion(matrix=rotation_matrix)
32

33
# Rotate a 3D vector
34
vector = [1, 0, 0]
35
rotated_vector = q1.rotate(vector)  # Returns [0, 0, -1]
36

37
# Quaternion arithmetic
38
q4 = q1 * q2  # Quaternion multiplication
39
q5 = q1 + q2  # Quaternion addition
40
q_conjugate = q1.conjugate  # Quaternion conjugate
41
q_inverse = q1.inverse  # Quaternion inverse
42

43
# Interpolation between quaternions
44
intermediate_q = Quaternion.slerp(q1, q2, amount=0.5)
45
```
46

47
## Architecture
48

49
The library is built around a single `Quaternion` class that provides:
50

51
- **Multiple Construction Methods**: Create quaternions from scalars, vectors, axis-angle, rotation matrices, or direct component specification
52
- **Complete Mathematical Operations**: Full support for quaternion algebra including multiplication, addition, exponentiation, and advanced mathematical functions
53
- **3D Rotation Operations**: Vector rotation, conversion to rotation matrices, Euler angles, and axis-angle representations
54
- **Interpolation and Animation**: SLERP (Spherical Linear Interpolation) and intermediate quaternion generation for smooth animations
55
- **Advanced Mathematics**: Exponential/logarithm operations, manifold operations, and Riemannian geometry functions
56
- **Python Integration**: Full operator overloading, type conversion, and pythonic API design
57

58
## Capabilities
59

60
### Quaternion Construction
61

62
Create quaternions from various representations including components, axis-angle, rotation matrices, and other quaternions.
63

64
```python { .api }
65
class Quaternion:
66
    def __init__(self, *args, **kwargs): ...
67
    
68
    @classmethod
69
    def random(cls) -> 'Quaternion': ...
70
```
71

72
[Construction](./construction.md)
73

74
### Basic Operations
75

76
Fundamental quaternion operations including arithmetic, comparison, normalization, and component access.
77

78
```python { .api }
79
# Arithmetic operations
80
def __add__(self, other) -> 'Quaternion': ...
81
def __mul__(self, other) -> 'Quaternion': ...
82
def __pow__(self, exponent) -> 'Quaternion': ...
83

84
# Properties
85
@property
86
def conjugate(self) -> 'Quaternion': ...
87
@property
88
def inverse(self) -> 'Quaternion': ...
89
@property
90
def norm(self) -> float: ...
91
@property
92
def normalised(self) -> 'Quaternion': ...
93

94
# Utility methods
95
def is_unit(self, tolerance=1e-14) -> bool: ...
96

97
# Static conversion methods
98
@staticmethod
99
def to_degrees(angle_rad: float) -> float: ...
100
@staticmethod
101
def to_radians(angle_deg: float) -> float: ...
102
```
103

104
[Basic Operations](./basic-operations.md)
105

106
### 3D Rotation
107

108
Apply quaternion rotations to 3D vectors and convert between different rotation representations.
109

110
```python { .api }
111
def rotate(self, vector) -> Union[list, tuple, np.ndarray, 'Quaternion']: ...
112
def get_axis(self, undefined=np.zeros(3)) -> np.ndarray: ...
113

114
@property
115
def rotation_matrix(self) -> np.ndarray: ...
116
@property
117
def transformation_matrix(self) -> np.ndarray: ...
118
@property
119
def yaw_pitch_roll(self) -> tuple: ...
120
@property
121
def axis(self) -> np.ndarray: ...
122
@property
123
def angle(self) -> float: ...
124
@property
125
def degrees(self) -> float: ...
126
```
127

128
[3D Rotation](./rotation.md)
129

130
### Interpolation and Animation
131

132
Smooth interpolation between quaternion orientations for animation and trajectory planning.
133

134
```python { .api }
135
@classmethod
136
def slerp(cls, q0, q1, amount=0.5) -> 'Quaternion': ...
137

138
@classmethod
139
def intermediates(cls, q0, q1, n, include_endpoints=False) -> Iterator['Quaternion']: ...
140

141
def derivative(self, rate) -> 'Quaternion': ...
142
def integrate(self, rate, timestep) -> 'Quaternion': ...
143
```
144

145
[Interpolation](./interpolation.md)
146

147
### Advanced Mathematics
148

149
Advanced mathematical operations including exponential/logarithm functions and Riemannian manifold operations.
150

151
```python { .api }
152
@classmethod
153
def exp(cls, q) -> 'Quaternion': ...
154
@classmethod
155
def log(cls, q) -> 'Quaternion': ...
156
@classmethod
157
def exp_map(cls, q, eta) -> 'Quaternion': ...
158
@classmethod
159
def sym_exp_map(cls, q, eta) -> 'Quaternion': ...
160
@classmethod
161
def log_map(cls, q, p) -> 'Quaternion': ...
162
@classmethod
163
def sym_log_map(cls, q, p) -> 'Quaternion': ...
164
@classmethod
165
def distance(cls, q0, q1) -> float: ...
166
@classmethod
167
def absolute_distance(cls, q0, q1) -> float: ...
168
@classmethod
169
def sym_distance(cls, q0, q1) -> float: ...
170
```
171

172
[Advanced Mathematics](./advanced-math.md)
173

174
### Operator Overloading and Type Conversion
175

176
Complete Python integration with operator overloading, type conversion, and container interface.
177

178
```python { .api }
179
# Comparison
180
def __eq__(self, other) -> bool: ...
181

182
# Unary operations
183
def __neg__(self) -> 'Quaternion': ...
184
def __abs__(self) -> float: ...
185
def __invert__(self) -> 'Quaternion': ...
186

187
# Type conversion
188
def __int__(self) -> int: ...
189
def __float__(self) -> float: ...
190
def __complex__(self) -> complex: ...
191
def __bool__(self) -> bool: ...
192

193
# String representation
194
def __str__(self) -> str: ...
195
def __repr__(self) -> str: ...
196
def __format__(self, formatstr) -> str: ...
197
def __hash__(self) -> int: ...
198

199
# In-place arithmetic
200
def __iadd__(self, other) -> 'Quaternion': ...
201
def __isub__(self, other) -> 'Quaternion': ...
202
def __imul__(self, other) -> 'Quaternion': ...
203
def __itruediv__(self, other) -> 'Quaternion': ...
204
def __ipow__(self, other) -> 'Quaternion': ...
205

206
# Matrix multiplication operator (@)
207
def __matmul__(self, other) -> 'Quaternion': ...
208
def __imatmul__(self, other) -> 'Quaternion': ...
209

210
# Copy operations
211
def __copy__(self) -> 'Quaternion': ...
212
def __deepcopy__(self, memo) -> 'Quaternion': ...
213
```
214

215
[Basic Operations](./basic-operations.md)
216

217
## Types
218

219
```python { .api }
220
class Quaternion:
221
    """
222
    Class to represent a 4-dimensional complex number or quaternion.
223
    
224
    Attributes:
225
        q: Quaternion 4-vector represented as a Numpy array
226
    """
227
    
228
    # Component access
229
    @property
230
    def scalar(self) -> float: ...  # Real component (w)
231
    @property
232
    def vector(self) -> np.ndarray: ...  # Imaginary components (x,y,z)
233
    @property
234
    def real(self) -> float: ...  # Alias for scalar
235
    @property
236
    def imaginary(self) -> np.ndarray: ...  # Alias for vector
237
    @property
238
    def w(self) -> float: ...  # Scalar component
239
    @property
240
    def x(self) -> float: ...  # First vector component
241
    @property
242
    def y(self) -> float: ...  # Second vector component
243
    @property
244
    def z(self) -> float: ...  # Third vector component
245
    @property
246
    def elements(self) -> np.ndarray: ...  # All components as array
247
    
248
    # Magnitude properties
249
    @property
250
    def magnitude(self) -> float: ...  # Alias for norm
251
    @property
252
    def unit(self) -> 'Quaternion': ...  # Alias for normalised
253
    
254
    # Angle properties  
255
    @property
256
    def radians(self) -> float: ...  # Alias for angle
257
    
258
    # Polar decomposition
259
    @property
260
    def polar_unit_vector(self) -> np.ndarray: ...
261
    @property
262
    def polar_angle(self) -> float: ...
263
    @property
264
    def polar_decomposition(self) -> tuple: ...
265
    
266
    # Container interface
267
    def __getitem__(self, index: int) -> float: ...
268
    def __setitem__(self, index: int, value: float) -> None: ...
269
```