0
# Batch Rotations
1

2
Batch operations on rotations in three dimensions (SO(3)) providing orders of magnitude faster processing compared to individual conversions. All functions operate on n-dimensional arrays where the last dimension (vectors) or last two dimensions (matrices) contain individual rotations.
3

4
## Capabilities
5

6
### Vector Operations
7

8
Utilities for batch vector normalization, angle calculations, and cross product matrices.
9

10
```python { .api }
11
def norm_vectors(V):
12
    """
13
    Normalize vectors.
14
    
15
    Parameters:
16
    - V: array-like, shape (..., 3) - vectors to normalize
17
    
18
    Returns:
19
    - V_normalized: array, shape (..., 3) - normalized vectors
20
    """
21

22
def angles_between_vectors(A, B):
23
    """
24
    Compute angles between corresponding vectors.
25
    
26
    Parameters:
27
    - A: array-like, shape (..., 3) - first vectors
28
    - B: array-like, shape (..., 3) - second vectors
29
    
30
    Returns:
31
    - angles: array, shape (...,) - angles in radians
32
    """
33

34
def cross_product_matrices(V):
35
    """
36
    Generate cross product matrices from vectors.
37
    
38
    Parameters:
39
    - V: array-like, shape (..., 3) - vectors
40
    
41
    Returns:
42
    - matrices: array, shape (..., 3, 3) - cross product matrices
43
    """
44
```
45

46
### Axis-Angle Operations
47

48
Batch operations for axis-angle representations and conversions.
49

50
```python { .api }
51
def norm_axis_angles(A):
52
    """
53
    Normalize axis-angle representations.
54
    
55
    Parameters:
56
    - A: array-like, shape (..., 4) - axis-angle vectors [x, y, z, angle]
57
    
58
    Returns:
59
    - A_normalized: array, shape (..., 4) - normalized axis-angles
60
    """
61

62
def matrices_from_compact_axis_angles(A):
63
    """
64
    Compute rotation matrices from compact axis-angle vectors.
65
    
66
    Parameters:
67
    - A: array-like, shape (..., 3) - compact axis-angles [x*angle, y*angle, z*angle]
68
    
69
    Returns:
70
    - R: array, shape (..., 3, 3) - rotation matrices
71
    """
72

73
def axis_angles_from_matrices(R):
74
    """
75
    Compute axis-angle representations from rotation matrices.
76
    
77
    Parameters:
78
    - R: array-like, shape (..., 3, 3) - rotation matrices
79
    
80
    Returns:
81
    - A: array, shape (..., 4) - axis-angle vectors [x, y, z, angle]
82
    """
83
```
84

85
### Euler Angle Operations
86

87
Batch conversion from Euler angles to rotation matrices with support for both intrinsic and extrinsic conventions.
88

89
```python { .api }
90
def active_matrices_from_intrinsic_euler_angles(e, i, j, k):
91
    """
92
    Compute rotation matrices from intrinsic Euler angles.
93
    
94
    Parameters:
95
    - e: array-like, shape (..., 3) - Euler angles in radians
96
    - i: int - first rotation axis (0=x, 1=y, 2=z)
97
    - j: int - second rotation axis
98
    - k: int - third rotation axis
99
    
100
    Returns:
101
    - R: array, shape (..., 3, 3) - rotation matrices
102
    """
103

104
def active_matrices_from_extrinsic_euler_angles(e, i, j, k):
105
    """
106
    Compute rotation matrices from extrinsic Euler angles.
107
    
108
    Parameters:
109
    - e: array-like, shape (..., 3) - Euler angles in radians  
110
    - i: int - first rotation axis (0=x, 1=y, 2=z)
111
    - j: int - second rotation axis
112
    - k: int - third rotation axis
113
    
114
    Returns:
115
    - R: array, shape (..., 3, 3) - rotation matrices
116
    """
117
```
118

119
### Quaternion Operations
120

121
Batch operations for quaternion representations including concatenation, conjugation, and conversion functions.
122

123
```python { .api }
124
def matrices_from_quaternions(Q):
125
    """
126
    Compute rotation matrices from quaternions.
127
    
128
    Parameters:
129
    - Q: array-like, shape (..., 4) - quaternions [w, x, y, z] or [x, y, z, w]
130
    
131
    Returns:
132
    - R: array, shape (..., 3, 3) - rotation matrices
133
    """
134

135
def quaternions_from_matrices(R):
136
    """
137
    Compute quaternions from rotation matrices.
138
    
139
    Parameters:
140
    - R: array-like, shape (..., 3, 3) - rotation matrices
141
    
142
    Returns:
143
    - Q: array, shape (..., 4) - quaternions
144
    """
145

146
def batch_concatenate_quaternions(Q1, Q2):
147
    """
148
    Concatenate quaternions (Q1 * Q2).
149
    
150
    Parameters:
151
    - Q1: array-like, shape (..., 4) - first quaternions
152
    - Q2: array-like, shape (..., 4) - second quaternions
153
    
154
    Returns:
155
    - Q: array, shape (..., 4) - concatenated quaternions
156
    """
157

158
def batch_q_conj(Q):
159
    """
160
    Compute quaternion conjugates.
161
    
162
    Parameters:
163
    - Q: array-like, shape (..., 4) - quaternions
164
    
165
    Returns:
166
    - Q_conj: array, shape (..., 4) - conjugated quaternions
167
    """
168

169
def quaternion_slerp_batch(start, end, t):
170
    """
171
    Spherical linear interpolation between quaternions.
172
    
173
    Parameters:
174
    - start: array-like, shape (..., 4) - start quaternions
175
    - end: array-like, shape (..., 4) - end quaternions
176
    - t: array-like, shape (...,) - interpolation parameters [0, 1]
177
    
178
    Returns:
179
    - Q: array, shape (..., 4) - interpolated quaternions
180
    """
181

182
def axis_angles_from_quaternions(Q):
183
    """
184
    Compute axis-angle representations from quaternions.
185
    
186
    Parameters:
187
    - Q: array-like, shape (..., 4) - quaternions
188
    
189
    Returns:
190
    - A: array, shape (..., 4) - axis-angle vectors [x, y, z, angle]
191
    """
192

193
def smooth_quaternion_trajectory(Q):
194
    """
195
    Smooth quaternion trajectory by ensuring shortest path.
196
    
197
    Parameters:
198
    - Q: array-like, shape (n_steps, 4) - quaternion trajectory
199
    
200
    Returns:
201
    - Q_smooth: array, shape (n_steps, 4) - smoothed trajectory
202
    """
203

204
def batch_quaternion_wxyz_from_xyzw(Q):
205
    """
206
    Convert quaternions from [x, y, z, w] to [w, x, y, z] format.
207
    
208
    Parameters:
209
    - Q: array-like, shape (..., 4) - quaternions in [x, y, z, w] format
210
    
211
    Returns:
212
    - Q_wxyz: array, shape (..., 4) - quaternions in [w, x, y, z] format
213
    """
214

215
def batch_quaternion_xyzw_from_wxyz(Q):
216
    """
217
    Convert quaternions from [w, x, y, z] to [x, y, z, w] format.
218
    
219
    Parameters:
220
    - Q: array-like, shape (..., 4) - quaternions in [w, x, y, z] format
221
    
222
    Returns:
223
    - Q_xyzw: array, shape (..., 4) - quaternions in [x, y, z, w] format
224
    """
225
```
226

227
### Angle Operations
228

229
Batch generation of rotation matrices from simple angles.
230

231
```python { .api }
232
def active_matrices_from_angles(angles, axes):
233
    """
234
    Compute rotation matrices from angles around specified axes.
235
    
236
    Parameters:
237
    - angles: array-like, shape (...,) - rotation angles in radians
238
    - axes: int - rotation axis (0=x, 1=y, 2=z)
239
    
240
    Returns:
241
    - R: array, shape (..., 3, 3) - rotation matrices
242
    """
243
```
244

245
## Usage Examples
246

247
### Batch Quaternion Processing
248

249
```python
250
import numpy as np
251
from pytransform3d.batch_rotations import (
252
    matrices_from_quaternions, 
253
    batch_concatenate_quaternions,
254
    quaternion_slerp_batch
255
)
256

257
# Process multiple quaternions at once
258
quaternions = np.array([
259
    [1, 0, 0, 0],     # identity
260
    [0.707, 0, 0, 0.707],  # 90° around z
261
    [0.5, 0.5, 0.5, 0.5]   # complex rotation
262
])
263

264
# Convert all to rotation matrices
265
rotation_matrices = matrices_from_quaternions(quaternions)
266
print(rotation_matrices.shape)  # (3, 3, 3)
267

268
# Interpolate between quaternions
269
start_q = np.array([[1, 0, 0, 0]])
270
end_q = np.array([[0.707, 0, 0, 0.707]])
271
t_values = np.linspace(0, 1, 10)
272

273
interpolated = quaternion_slerp_batch(
274
    np.broadcast_to(start_q, (10, 4)),
275
    np.broadcast_to(end_q, (10, 4)), 
276
    t_values
277
)
278
```
279

280
### Batch Euler Angle Conversion
281

282
```python
283
import numpy as np
284
from pytransform3d.batch_rotations import active_matrices_from_intrinsic_euler_angles
285

286
# Multiple sets of XYZ Euler angles
287
euler_angles = np.array([
288
    [0.1, 0.2, 0.3],
289
    [0.5, -0.1, 0.8],
290
    [-0.3, 0.7, -0.2]
291
])
292

293
# Convert all to rotation matrices (XYZ intrinsic)
294
matrices = active_matrices_from_intrinsic_euler_angles(euler_angles, 0, 1, 2)
295
print(matrices.shape)  # (3, 3, 3)
296
```