0
# pytransform3d
1

2
A comprehensive Python library for 3D transformations including rotations, translations, and coordinate conversions. pytransform3d provides complete mathematical support for spatial transformations with multiple representation formats, batch processing capabilities, uncertainty handling, and visualization tools for robotics, computer vision, and 3D graphics applications.
3

4
## Package Information
5

6
- **Package Name**: pytransform3d
7
- **Language**: Python
8
- **Installation**: `pip install pytransform3d` or `pip install 'pytransform3d[all]'` for all optional dependencies
9

10
## Core Imports
11

12
```python
13
import pytransform3d
14
```
15

16
For working with rotations:
17

18
```python
19
import pytransform3d.rotations as pr
20
from pytransform3d.rotations import matrix_from_euler, quaternion_from_matrix
21
```
22

23
For working with transformations:
24

25
```python
26
import pytransform3d.transformations as pt
27
from pytransform3d.transformations import transform_from, concat
28
```
29

30
For transform management:
31

32
```python
33
from pytransform3d.transform_manager import TransformManager
34
```
35

36
## Basic Usage
37

38
```python
39
import numpy as np
40
import pytransform3d.rotations as pr
41
import pytransform3d.transformations as pt
42
from pytransform3d.transform_manager import TransformManager
43

44
# Create rotation from Euler angles (XYZ convention)
45
euler_angles = [0.1, 0.2, 0.3]  # roll, pitch, yaw in radians
46
R = pr.matrix_from_euler(euler_angles, 0, 1, 2, True)  # XYZ extrinsic
47

48
# Convert rotation matrix to quaternion
49
q = pr.quaternion_from_matrix(R)
50

51
# Create transformation matrix from rotation and translation
52
p = [1.0, 2.0, 3.0]  # translation vector
53
T = pt.transform_from(R, p)
54

55
# Use TransformManager for complex transformation chains
56
tm = TransformManager()
57
tm.add_transform("base", "link1", T)
58
tm.add_transform("link1", "end_effector", pt.transform_from(np.eye(3), [0.5, 0, 0]))
59

60
# Get transformation from base to end effector
61
base_to_end = tm.get_transform("base", "end_effector")
62
```
63

64
## Architecture
65

66
pytransform3d is organized around mathematical foundations for 3D transformations:
67

68
- **Rotations (SO(3))**: Complete rotation representation system supporting matrices, quaternions, axis-angles, Euler angles, Modified Rodrigues Parameters, and geometric algebra rotors
69
- **Transformations (SE(3))**: 3D transformations combining rotation and translation with support for homogeneous matrices, position-quaternions, dual quaternions, and screw theory
70
- **Batch Operations**: Optimized vectorized operations for processing arrays of rotations and transformations
71
- **Transform Management**: Graph-based system for managing complex transformation chains with automatic path finding
72
- **Uncertainty Handling**: Statistical operations on uncertain transformations with covariance propagation
73
- **Visualization**: Integration with matplotlib and Open3D for 3D plotting and interactive visualization
74

75
The library provides extensive conversion functions between all representation formats and maintains mathematical precision for robotics and computer vision applications.
76

77
## Capabilities
78

79
### Rotation Representations
80

81
Complete system for representing and converting between rotation formats including matrices, quaternions, axis-angles, Euler angles, Modified Rodrigues Parameters, and geometric algebra rotors.
82

83
```python { .api }
84
def matrix_from_euler(e, i, j, k, extrinsic): ...
85
def quaternion_from_matrix(R): ...
86
def axis_angle_from_quaternion(q): ...
87
def euler_from_matrix(R, i, j, k, extrinsic, strict_check=True): ...
88
```
89

90
[Rotations](./rotations.md)
91

92
### 3D Transformations
93

94
Homogeneous transformations combining rotation and translation with support for multiple representations and composition operations.
95

96
```python { .api }
97
def transform_from(R, p, strict_check=True): ...
98
def concat(*transforms): ...
99
def invert_transform(A2B): ...
100
def transform(A2B, PA): ...
101
```
102

103
[Transformations](./transformations.md)
104

105
### Batch Operations
106

107
Optimized vectorized operations for processing arrays of rotations and transformations with significant performance improvements over iterative approaches.
108

109
```python { .api }
110
def matrices_from_quaternions(Q): ...
111
def batch_concatenate_quaternions(Q1, Q2): ...
112
def transforms_from_pqs(pqs): ...
113
def invert_transforms(A2B): ...
114
```
115

116
[Batch Operations](./batch-operations.md)
117

118
### Batch Rotations
119

120
Optimized batch operations specifically for rotation representations with significant performance improvements for processing arrays of orientations.
121

122
```python { .api }
123
def matrices_from_quaternions(Q): ...
124
def batch_concatenate_quaternions(Q1, Q2): ...
125
def active_matrices_from_intrinsic_euler_angles(e, i, j, k): ...
126
def quaternion_slerp_batch(start, end, t): ...
127
```
128

129
[Batch Rotations](./batch-rotations.md)
130

131
### Trajectories
132

133
Batch operations on 3D trajectories (SE(3)) using dual quaternions, position-quaternions, and exponential coordinates for high-performance trajectory processing.
134

135
```python { .api }
136
def invert_transforms(A2B): ...
137
def concat_many_to_many(A2B, B2C): ...
138
def dual_quaternions_sclerp(start, end, t): ...
139
def transforms_from_pqs(pqs): ...
140
```
141

142
[Trajectories](./trajectories.md)
143

144
### Transform Management
145

146
Graph-based system for managing complex transformation chains with automatic path finding and temporal support.
147

148
```python { .api }
149
class TransformManager:
150
    def add_transform(self, from_frame, to_frame, A2B): ...
151
    def get_transform(self, from_frame, to_frame): ...
152
    def plot_frames_in(self, frame, ax=None, **kwargs): ...
153
```
154

155
[Transform Manager](./transform-manager.md)
156

157
### Camera Projections
158

159
Camera-related transformations including world-to-image projection, coordinate system conversions, and camera pose visualization.
160

161
```python { .api }
162
def world2image(P_world, cam2world, sensor_size, image_size, focal_length, **kwargs): ...
163
def cam2sensor(P_cam, focal_length, kappa=0.0): ...
164
def plot_camera(ax=None, cam2world=None, **kwargs): ...
165
```
166

167
[Camera](./camera.md)
168

169
### Coordinate Systems
170

171
Conversions between Cartesian, cylindrical, and spherical coordinate systems for position representation.
172

173
```python { .api }
174
def cartesian_from_spherical(p): ...
175
def spherical_from_cartesian(p): ...
176
def cylindrical_from_cartesian(p): ...
177
```
178

179
[Coordinates](./coordinates.md)
180

181
### URDF and Robot Kinematics
182

183
Loading and managing robot kinematic chains from URDF files with joint control and visualization.
184

185
```python { .api }
186
class UrdfTransformManager(TransformManager):
187
    def load_urdf(self, urdf_xml, mesh_path=None, package_dir=None): ...
188
    def set_joint(self, joint_name, value): ...
189
    def plot_visuals(self, frame, ax=None, **kwargs): ...
190
```
191

192
[URDF](./urdf.md)
193

194
### Uncertainty
195

196
Operations on uncertain transformations with statistical estimation, covariance propagation, and sensor fusion.
197

198
```python { .api }
199
def pose_fusion(poses, covariances, check_inputs=True): ...
200
def concat_uncertain_transforms(A2B, cov_A2B, B2C, cov_B2C): ...
201
def frechet_mean(poses, weights=None, **kwargs): ...
202
```
203

204
[Uncertainty](./uncertainty.md)
205

206
### Visualization
207

208
3D plotting and visualization tools using matplotlib and Open3D backends for transformations, trajectories, and geometric objects.
209

210
```python { .api }
211
def plot_transform(ax=None, A2B=None, s=1.0, **kwargs): ...
212
def plot_trajectory(P=None, show_direction=True, **kwargs): ...
213
class Figure:  # Open3D-based 3D visualization
214
    def add(self, artist): ...
215
    def show(self): ...
216
```
217

218
[Visualization](./visualization.md)
219

220
### Plot Utilities
221

222
Matplotlib-based plotting utilities for 3D geometric shapes, coordinate frames, and visualization objects commonly used in robotics applications.
223

224
```python { .api }
225
def plot_box(ax=None, size=[1, 1, 1], A2B=None, **kwargs): ...
226
def plot_sphere(ax=None, radius=1.0, p=[0, 0, 0], **kwargs): ...
227
def plot_cylinder(ax=None, length=1.0, radius=1.0, A2B=None, **kwargs): ...
228
class LabeledFrame: ...
229
```
230

231
[Plot Utils](./plot-utils.md)
232

233
### Interactive Editing
234

235
GUI tools for visual transformation editing using PyQt with real-time 3D visualization and parameter adjustment.
236

237
```python { .api }
238
class TransformEditor(QMainWindow):
239
    def __init__(self, transform_manager, base_frame, **kwargs): ...
240
    def show(self): ...
241
```
242

243
[Editor](./editor.md)
244

245
## Types
246

247
```python { .api }
248
# Rotation representations
249
RotationMatrix = np.ndarray  # shape (3, 3)
250
Quaternion = np.ndarray  # shape (4,) - [w, x, y, z] or [x, y, z, w]
251
AxisAngle = np.ndarray  # shape (4,) - [x, y, z, angle] 
252
CompactAxisAngle = np.ndarray  # shape (3,) - [x*angle, y*angle, z*angle]
253
EulerAngles = np.ndarray  # shape (3,) - [angle1, angle2, angle3]
254

255
# Transformation representations  
256
Transform = np.ndarray  # shape (4, 4) - homogeneous transformation matrix
257
PositionQuaternion = np.ndarray  # shape (7,) - [x, y, z, qw, qx, qy, qz]
258
DualQuaternion = np.ndarray  # shape (8,) - dual quaternion representation
259
ScrewParameters = np.ndarray  # shape (6,) - screw motion parameters
260
ExponentialCoordinates = np.ndarray  # shape (6,) - exponential coordinates
261

262
# Batch representations
263
RotationMatrices = np.ndarray  # shape (..., 3, 3)
264
Quaternions = np.ndarray  # shape (..., 4)
265
Transforms = np.ndarray  # shape (..., 4, 4)
266
PositionQuaternions = np.ndarray  # shape (..., 7)
267

268
# Visualization types
269
Axes3D = matplotlib.axes._subplots.Axes3D
270
Figure3D = pytransform3d.visualizer.Figure
271
```