0
# Transformations
1

2
3D transformations combining rotation and translation in three dimensions (SE(3)). Supports homogeneous matrices, position-quaternions, dual quaternions, screw theory, and exponential coordinates with comprehensive conversion and composition operations.
3

4
## Capabilities
5

6
### Homogeneous Transform Operations
7

8
Operations for 4x4 homogeneous transformation matrices combining rotation and translation.
9

10
```python { .api }
11
def check_transform(A2B, tolerance=1e-6, strict_check=True):
12
    """Validate homogeneous transformation matrix."""
13

14
def transform_from(R, p, strict_check=True):
15
    """
16
    Construct transformation matrix from rotation and translation.
17
    
18
    Parameters:
19
    - R: array-like, shape (3, 3) - Rotation matrix
20
    - p: array-like, shape (3,) - Translation vector
21
    - strict_check: bool, optional - Enable strict validation
22
    
23
    Returns:
24
    - A2B: array, shape (4, 4) - Homogeneous transformation matrix
25
    """
26

27
def invert_transform(A2B):
28
    """Invert transformation matrix efficiently."""
29

30
def concat(*transforms):
31
    """
32
    Concatenate multiple transformations.
33
    
34
    Parameters:
35
    - transforms: sequence of arrays, shape (4, 4) - Transformation matrices
36
    
37
    Returns:
38
    - result: array, shape (4, 4) - Composed transformation
39
    """
40

41
def transform(A2B, PA):
42
    """
43
    Transform points from frame A to frame B.
44
    
45
    Parameters:
46
    - A2B: array, shape (4, 4) - Transformation matrix
47
    - PA: array, shape (..., 3 or 4) - Points in frame A
48
    
49
    Returns:
50
    - PB: array, shape (..., 3 or 4) - Points in frame B
51
    """
52

53
def scale_transform(A2B, s_x, s_y, s_z):
54
    """Scale transformation components."""
55

56
def rotate_transform(A2B, R):
57
    """Apply additional rotation to transformation."""
58

59
def translate_transform(A2B, p):
60
    """Apply additional translation to transformation."""
61
```
62

63
### Point and Vector Operations
64

65
Operations for homogeneous points and direction vectors.
66

67
```python { .api }
68
def vector_to_point(v):
69
    """Convert 3D vector to homogeneous point."""
70

71
def vectors_to_points(V):
72
    """Convert array of vectors to homogeneous points."""
73

74
def vector_to_direction(v):
75
    """Convert 3D vector to homogeneous direction."""
76

77
def vectors_to_directions(V):
78
    """Convert array of vectors to homogeneous directions."""
79
```
80

81
### Position-Quaternion Representation
82

83
Operations for compact position-quaternion representation (7 parameters).
84

85
```python { .api }
86
def check_pq(pq, tolerance=1e-6, strict_check=True):
87
    """Validate position-quaternion representation."""
88

89
def pq_from_transform(A2B):
90
    """
91
    Extract position-quaternion from transformation.
92
    
93
    Parameters:
94
    - A2B: array, shape (4, 4) - Transformation matrix
95
    
96
    Returns:
97
    - pq: array, shape (7,) - Position-quaternion [x, y, z, qw, qx, qy, qz]
98
    """
99

100
def transform_from_pq(pq):
101
    """Construct transformation from position-quaternion."""
102

103
def pq_slerp(start, end, t):
104
    """Spherical linear interpolation between position-quaternions."""
105
```
106

107
### Dual Quaternion Operations
108

109
Operations for dual quaternion representation of transformations.
110

111
```python { .api }
112
def check_dual_quaternion(dq, unit=True, tolerance=1e-6, strict_check=True):
113
    """Validate dual quaternion representation."""
114

115
def norm_dual_quaternion(dq):
116
    """Normalize dual quaternion."""
117

118
def dual_quaternion_from_transform(A2B):
119
    """Convert transformation to dual quaternion."""
120

121
def transform_from_dual_quaternion(dq):
122
    """Convert dual quaternion to transformation."""
123

124
def dual_quaternion_from_pq(pq):
125
    """Convert position-quaternion to dual quaternion."""
126

127
def pq_from_dual_quaternion(dq):
128
    """Convert dual quaternion to position-quaternion."""
129

130
def concatenate_dual_quaternions(dq1, dq2):
131
    """Compose dual quaternions."""
132

133
def dual_quaternion_sclerp(start, end, t):
134
    """Screw linear interpolation between dual quaternions."""
135

136
def dual_quaternion_power(dq, t):
137
    """Dual quaternion power operation."""
138

139
def dq_conj(dq):
140
    """Full conjugate of dual quaternion."""
141

142
def dq_q_conj(dq):
143
    """Quaternion conjugate of dual quaternion."""
144

145
def dq_prod_vector(dq, v):
146
    """Transform vector using dual quaternion."""
147
```
148

149
### Screw Theory Operations
150

151
Operations based on screw theory for describing rigid body motions.
152

153
```python { .api }
154
def check_screw_parameters(s, tolerance=1e-6, strict_check=True):
155
    """Validate screw parameters."""
156

157
def check_screw_axis(S, tolerance=1e-6, strict_check=True):
158
    """Validate screw axis representation."""
159

160
def check_exponential_coordinates(Stheta, tolerance=1e-6, strict_check=True):
161
    """Validate exponential coordinates."""
162

163
def transform_from_exponential_coordinates(Stheta):
164
    """
165
    Convert exponential coordinates to transformation.
166
    
167
    Parameters:
168
    - Stheta: array, shape (6,) - Exponential coordinates
169
    
170
    Returns:
171
    - A2B: array, shape (4, 4) - Transformation matrix
172
    """
173

174
def exponential_coordinates_from_transform(A2B):
175
    """Extract exponential coordinates from transformation."""
176

177
def screw_parameters_from_screw_axis(S, theta):
178
    """Convert screw axis and angle to screw parameters."""
179

180
def screw_axis_from_screw_parameters(s):
181
    """Extract screw axis from screw parameters."""
182

183
def screw_matrix_from_screw_axis(S):
184
    """Convert screw axis to screw matrix."""
185

186
def screw_axis_from_screw_matrix(S_hat):
187
    """Convert screw matrix to screw axis."""
188

189
def dual_quaternion_from_screw_parameters(s):
190
    """Convert screw parameters to dual quaternion."""
191

192
def screw_parameters_from_dual_quaternion(dq):
193
    """Convert dual quaternion to screw parameters."""
194
```
195

196
### Transform Interpolation
197

198
Interpolation operations for smooth transformation transitions.
199

200
```python { .api }
201
def transform_sclerp(start, end, t):
202
    """
203
    Screw linear interpolation between transformations.
204
    
205
    Parameters:
206
    - start: array, shape (4, 4) - Start transformation
207
    - end: array, shape (4, 4) - End transformation  
208
    - t: float - Interpolation parameter [0, 1]
209
    
210
    Returns:
211
    - interp: array, shape (4, 4) - Interpolated transformation
212
    """
213

214
def transform_power(A2B, t):
215
    """Transformation power operation."""
216
```
217

218
### Random Generation
219

220
Functions for generating random transformations.
221

222
```python { .api }
223
def random_transform(random_state=None):
224
    """Generate random transformation matrix."""
225

226
def random_screw_axis(random_state=None):
227
    """Generate random screw axis."""
228

229
def random_exponential_coordinates(random_state=None):
230
    """Generate random exponential coordinates."""
231
```
232

233
### Mathematical Operations
234

235
Advanced mathematical operations for transformation analysis.
236

237
```python { .api }
238
def adjoint_from_transform(A2B):
239
    """
240
    Compute adjoint matrix from transformation.
241
    
242
    Parameters:
243
    - A2B: array, shape (4, 4) - Transformation matrix
244
    
245
    Returns:
246
    - adj: array, shape (6, 6) - Adjoint matrix
247
    """
248

249
def transform_log_from_transform(A2B):
250
    """Convert transformation to matrix logarithm."""
251

252
def transform_from_transform_log(T_log):
253
    """Convert matrix logarithm to transformation."""
254

255
def left_jacobian_SE3(Stheta):
256
    """Left Jacobian for SE(3) group."""
257

258
def left_jacobian_SE3_inv(Stheta):
259
    """Inverse left Jacobian for SE(3)."""
260
```
261

262
## Usage Examples
263

264
### Basic Transform Operations
265

266
```python
267
import numpy as np
268
import pytransform3d.transformations as pt
269
import pytransform3d.rotations as pr
270

271
# Create transformation from rotation and translation
272
R = pr.matrix_from_euler([0.1, 0.2, 0.3], "xyz", extrinsic=True)
273
p = [1.0, 2.0, 3.0]
274
T1 = pt.transform_from(R=R, p=p)
275

276
# Create another transformation (pure translation)
277
T2 = pt.transform_from(np.eye(3), [0.5, 0, 0])
278

279
# Compose transformations
280
T_composed = pt.concat(T1, T2)
281

282
# Transform points
283
points = np.array([[0, 0, 0], [1, 0, 0], [0, 1, 0]])
284
points_transformed = pt.transform(T_composed, points)
285
```
286

287
### Position-Quaternion Operations
288

289
```python
290
import pytransform3d.transformations as pt
291

292
# Convert transformation to position-quaternion
293
T = pt.transform_from(np.eye(3), [1, 2, 3])
294
pq = pt.pq_from_transform(T)
295
print(f"Position-quaternion: {pq}")
296

297
# Interpolate between poses
298
pq1 = pt.pq_from_transform(pt.transform_from(np.eye(3), [0, 0, 0]))
299
pq2 = pt.pq_from_transform(pt.transform_from(np.eye(3), [1, 1, 1]))
300
pq_mid = pt.pq_slerp(pq1, pq2, 0.5)
301

302
# Convert back to transformation
303
T_mid = pt.transform_from_pq(pq_mid)
304
```
305

306
### Screw Theory
307

308
```python
309
import numpy as np
310
import pytransform3d.transformations as pt
311

312
# Define screw motion (pure translation along x-axis)
313
screw_axis = np.array([0, 0, 0, 1, 0, 0])  # [omega_x, omega_y, omega_z, v_x, v_y, v_z]
314
theta = 1.0  # motion magnitude
315

316
# Convert to exponential coordinates
317
Stheta = screw_axis * theta
318

319
# Get transformation matrix
320
T = pt.transform_from_exponential_coordinates(Stheta)
321
print(f"Transformation from screw motion:\n{T}")
322

323
# Convert back to verify
324
Stheta_recovered = pt.exponential_coordinates_from_transform(T)
325
print(f"Recovered exponential coordinates: {Stheta_recovered}")
326
```
327

328
### Dual Quaternion Operations
329

330
```python
331
import pytransform3d.transformations as pt
332
import pytransform3d.rotations as pr
333

334
# Create transformation
335
R = pr.matrix_from_euler([0, 0, np.pi/4], "xyz", extrinsic=True)
336
T = pt.transform_from(R=R, p=[1, 0, 0])
337

338
# Convert to dual quaternion
339
dq = pt.dual_quaternion_from_transform(T)
340

341
# Compose with another transformation
342
T2 = pt.transform_from(np.eye(3), [0, 1, 0])
343
dq2 = pt.dual_quaternion_from_transform(T2)
344
dq_composed = pt.concatenate_dual_quaternions(dq, dq2)
345

346
# Convert back to transformation
347
T_composed = pt.transform_from_dual_quaternion(dq_composed)
348
```