0
# Quaternion Construction
1

2
Methods for creating `Quaternion` objects from various representations including components, axis-angle pairs, rotation matrices, and other formats.
3

4
## Capabilities
5

6
### Constructor
7

8
Create quaternions using flexible constructor that accepts multiple input formats.
9

10
```python { .api }
11
def __init__(self, *args, **kwargs):
12
    """
13
    Initialize a new Quaternion object.
14
    
15
    Supports multiple initialization methods:
16
    - No arguments: Identity quaternion (1, 0, 0, 0)
17
    - Single scalar: Real quaternion (scalar, 0, 0, 0)
18
    - Four scalars: Direct component specification (w, x, y, z)
19
    - Single sequence: Four-element array [w, x, y, z]
20
    - Another Quaternion: Copy constructor
21
    
22
    Keyword arguments:
23
    - scalar/vector: Separate real and imaginary parts
24
    - real/imaginary: Alternative names for scalar/vector
25
    - axis/angle or axis/radians or axis/degrees: Axis-angle representation
26
    - array: Four-element sequence [w, x, y, z]
27
    - matrix: 3x3 or 4x4 rotation/transformation matrix
28
    """
29
```
30

31
**Usage Examples:**
32

33
```python
34
# Identity quaternion
35
q = Quaternion()  # (1, 0, 0, 0)
36

37
# From components
38
q = Quaternion(1, 0, 0, 0)  # (w, x, y, z)
39
q = Quaternion([1, 0, 0, 0])  # From array
40

41
# From scalar and vector parts
42
q = Quaternion(scalar=1, vector=[0, 0, 0])
43
q = Quaternion(real=1, imaginary=[0, 0, 0])
44

45
# From axis and angle
46
q = Quaternion(axis=[0, 1, 0], angle=1.57)  # Radians
47
q = Quaternion(axis=[0, 1, 0], radians=1.57)
48
q = Quaternion(axis=[0, 1, 0], degrees=90)
49

50
# From rotation matrix
51
import numpy as np
52
matrix = np.eye(3)
53
q = Quaternion(matrix=matrix)
54

55
# Copy constructor
56
q1 = Quaternion(1, 0, 0, 0)
57
q2 = Quaternion(q1)
58
```
59

60
### Random Quaternion Generation
61

62
Generate uniformly distributed random unit quaternions.
63

64
```python { .api }
65
@classmethod
66
def random(cls):
67
    """
68
    Generate a random unit quaternion.
69
    
70
    Uniformly distributed across the rotation space using method from:
71
    http://planning.cs.uiuc.edu/node198.html
72
    
73
    Returns:
74
        Quaternion: Random unit quaternion
75
    """
76
```
77

78
**Usage Example:**
79

80
```python
81
# Generate random rotation
82
random_q = Quaternion.random()
83
print(f"Random quaternion: {random_q}")
84
print(f"Is unit: {random_q.is_unit()}")
85
```
86

87
### Internal Construction Methods
88

89
Advanced construction methods primarily for internal use.
90

91
```python { .api }
92
@classmethod
93
def _from_matrix(cls, matrix, rtol=1e-05, atol=1e-08):
94
    """
95
    Create quaternion from 3x3 rotation or 4x4 transformation matrix.
96
    
97
    Parameters:
98
        matrix: numpy array, 3x3 or 4x4 matrix
99
        rtol: relative tolerance for orthogonality check
100
        atol: absolute tolerance for orthogonality check
101
    
102
    Returns:
103
        Quaternion: Quaternion representing the same rotation
104
    
105
    Raises:
106
        ValueError: If matrix is not orthogonal or determinant != 1
107
        TypeError: If matrix is not numpy array
108
    """
109

110
@classmethod
111
def _from_axis_angle(cls, axis, angle):
112
    """
113
    Create quaternion from axis and angle representation.
114
    
115
    Parameters:
116
        axis: array-like, 3-vector rotation axis (will be normalized)
117
        angle: float, rotation angle in radians
118
    
119
    Returns:
120
        Quaternion: Quaternion representing the rotation
121
    
122
    Raises:
123
        ZeroDivisionError: If axis has zero length
124
    """
125
```
126

127
## Validation and Utility
128

129
### Number Sequence Validation
130

131
Internal validation method for ensuring proper input format.
132

133
```python { .api }
134
def _validate_number_sequence(self, seq, n):
135
    """
136
    Validate a sequence to be of a certain length and ensure it's a numpy array of floats.
137
    
138
    Parameters:
139
        seq: sequence to validate
140
        n: expected length
141
    
142
    Returns:
143
        numpy.ndarray: Validated array of floats
144
    
145
    Raises:
146
        ValueError: Invalid length or non-numeric value
147
    """
148
```
149

150
## Static Utility Functions
151

152
### Angle Conversion
153

154
Convert between degrees and radians.
155

156
```python { .api }
157
@staticmethod
158
def to_degrees(angle_rad):
159
    """
160
    Convert angle from radians to degrees.
161
    
162
    Parameters:
163
        angle_rad: float or None, angle in radians
164
    
165
    Returns:
166
        float or None: angle in degrees
167
    """
168

169
@staticmethod
170
def to_radians(angle_deg):
171
    """
172
    Convert angle from degrees to radians.
173
    
174
    Parameters:
175
        angle_deg: float or None, angle in degrees
176
    
177
    Returns:
178
        float or None: angle in radians
179
    """
180
```
181

182
**Usage Example:**
183

184
```python
185
# Angle conversion
186
degrees = Quaternion.to_degrees(3.14159)  # ~180.0
187
radians = Quaternion.to_radians(90)       # ~1.5708
188
```