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
```