pytransform3d

pytransform3d is a Python library designed for 3D transformations with a focus on readability and debugging rather than raw computational efficiency. It provides a functional interface for working with rotations, translations, and complex transformation chains.

Key features include:

• Representations & Conversions: Operations for common rotation/orientation and translation/position representations and conversions between them.
• Validation: Functions to check for common pitfalls like singularities, ambiguities, and discontinuities.
• Visualization: Tight integration with matplotlib for plotting and animating transformations, and a matplotlib-like interface to Open3D's visualizer for displaying geometries.
• Management Tools:
  • TransformManager: Organizes complex chains of transformations.
  • TransformEditor: Allows for graphical modification of transformations.
  • UrdfTransformManager: Loads transformations from URDF files.
• Ecosystem Integration: Built on NumPy (linear algebra), SciPy (graph-based transformation computation), and Matplotlib (plotting).

The pytransform3d library provides multiple ways to represent 3D rotations (the SO(3) group). Different representations support different operations like inversion, vector rotation, concatenation, interpolation, and renormalization.

Key representations include:

• Rotation matrix: Supports most operations; requires renormalization to maintain orthonormality.
• Axis-angle: Represented by a unit axis and an angle; supports interpolation via SLERP.
• Rotation vector: A compact representation; supports interpolation.
• Quaternion: Highly efficient for rotation of vectors and concatenation; requires renormalization.
• Euler angles: Uses three angles; does not support direct interpolation or vector rotation without conversion.
• Rotor: Supports most operations including interpolation.
• Modified Rodrigues parameters: Supports concatenation.

Note: SLERP (Spherical Linear Interpolation) is the standard method for smooth interpolation between orientations.

The logarithm of a transformation can be represented as a $4 \times 4$ matrix, often called a screw matrix or transform_log. This matrix belongs to the Lie algebra $se(3)$.

Key Operations:

• Exponential Map: Converts a screw matrix to a transformation matrix using pytransform3d.transformations.transform_from_transform_log.
• Logarithmic Map: Converts a transformation matrix to its matrix logarithm (transform_log) using pytransform3d.transformations.transform_log_from_transform.
• ScLERP: Like exponential coordinates, the matrix logarithm allows for Screw Linear Interpolation by computing a fraction of the difference between two transformations.

In the API, a screw matrix is represented as a numpy array of shape (4, 4) and is typically named screw_matrix.

# Example conceptual usage
# transform_log = transform_log_from_transform(T)
# T_new = transform_from_transform_log(transform_log)

Quaternions are represented by a numpy array of shape (4,) (typically named q).

Convention:

• Hamilton's convention: pytransform3d uses this convention ($ijk = -1$).
• Scalar component: The scalar part $w$ is stored as the first element of the array (wxyz).

Key Operations:

• Conversion: Use quaternion_wxyz_from_xyzw and quaternion_xyzw_from_wxyz to switch between Hamilton and JPL/Shuster conventions.
• Concatenation: Use concatenate_quaternions to combine rotations.
• Inverse: Use q_conj to get the conjugate (inverse rotation).
• Vector Rotation: Use q_prod_vector to rotate a vector by a quaternion.
• Renormalization: Check if a quaternion needs renormalization using quaternion_requires_renormalization.

Important Notes:

• Double Cover: The antipodal quaternions $\boldsymbol{\hat{q}}$ and $-\boldsymbol{\hat{q}}$ represent the same rotation. Use quaternion_double to handle this. This must be considered during interpolation or equality checks.

Pros/Cons:

• Pros: Compact, no singularities, computationally efficient, and easy to renormalize.
• Cons: Not straightforward to interpret and subject to the double-cover ambiguity.

In pytransform3d.uncertainty, uncertain transformations are represented as Gaussian distributions. The mean is a transformation matrix $\boldsymbol{T} \in SE(3)$ and the covariance $\boldsymbol{\Sigma} \in \mathbb{R}^{6 \times 6}$ is defined in the tangent space using exponential coordinates.

Important: Frame of Reference By default, uncertainty is defined in the global frame (left-multiplied). To sample a transformation $\boldsymbol{T}{xA}$ from a distribution centered at $\boldsymbol{T}{BA}$ with covariance $\boldsymbol{\Sigma}{6 \times 6}$, the library computes $\Delta \boldsymbol{T}{xB} \boldsymbol{T}{BA}$, where $\Delta \boldsymbol{T}{xB} = Exp(\boldsymbol{\xi})$ and $\boldsymbol{\xi} \sim \mathcal{N}(\boldsymbol{0}6, \boldsymbol{\Sigma}{6 \times 6})$. This means the uncertainty is relative to the global frame $B$, not the local body frame $A$.

Key functions:

• pytransform3d.uncertainty.estimate_gaussian_transform_from_samples: Estimates a Gaussian distribution from a set of transformation samples.
• pytransform3d.transformations.random_transform: Samples from a known Gaussian distribution of transformations.

A transformation matrix is a $4 imes 4$ homogeneous representation consisting of a $3 imes 3$ rotation matrix $\boldsymbol{R}$ and a translation vector $\boldsymbol{t}$.

In pytransform3d, these are represented as a numpy array of shape (4, 4). A common convention is to use the variable name A2B to denote a transformation from frame $A$ to frame $B$.

Transforming Vectors and Points:

• Points (Position Vectors): To include translation, use a homogeneous vector $(x, y, z, 1)^T$. Use pytransform3d.transformations.vector_to_point.
• Directions (Direction Vectors): To ignore translation, use a homogeneous vector $(x, y, z, 0)^T$. Use pytransform3d.transformations.vector_to_direction.
• General Application: Use pytransform3d.transformations.transform to apply a matrix to a homogeneous vector.

Pros/Cons:

• Pros: Supports all operations except interpolation; no singularities.
• Cons: Uses 16 values for 6 degrees of freedom; requires renormalization.

import numpy as np
# Example of a 4x4 transformation matrix (A2B)
A2B = np.eye(4)

# To transform a point (position)
point_A = np.array([1, 2, 3, 1])
point_B = pytransform3d.transformations.transform(A2B, point_A)

# To transform a direction (ignores translation)
direction_A = np.array([1, 0, 0, 0])
direction_B = pytransform3d.transformations.transform(A2B, direction_A)

A rotation matrix $\boldsymbol{R}$ is a $3\times3$ numpy array representing an orientation.

Key Properties and Conventions

• Active Rotation: pytransform3d uses the active rotation convention.
• Pre-multiplication: To rotate a point $\boldsymbol{p}$ from frame $A$ to frame $B$, use the formula: $B\boldsymbol{p} = \boldsymbol{R}{BA} \boldsymbol{p}$. This is a linear map where the matrix is pre-multiplied to a column vector.
• Basis Vectors: Each column of the rotation matrix $\boldsymbol{R}_{BA}$ represents a basis vector of frame $A$ expressed in frame $B$.
• Concatenation: To chain rotations, ensure indices align. For example, applying $\boldsymbol{R}{CB}$ after $\boldsymbol{R}{BA}$ results in $\boldsymbol{R}{CA} = \boldsymbol{R}{CB} \boldsymbol{R}_{BA}$.

Maintenance

Because rotation matrices must be orthonormal, they may require renormalization. You can use:

• pytransform3d.rotations.norm_matrix to enforce orthonormality.
• pytransform3d.rotations.matrix_requires_renormalization to check if a matrix is valid.
• pytransform3d.rotations.check_matrix to validate the matrix.

Visualization

You can visualize the basis vectors of an orientation using plot_basis.

from pytransform3d.rotations import plot_basis
plot_basis()

Euler angles represent 3D rotations as three consecutive rotations about basis vectors. When working with Euler angles in pytransform3d, keep the following in mind:

1. Units: pytransform3d uses radians exclusively. Do not provide degrees.
2. Conventions: There are 24 possible conventions based on the combination of:
   • Proper Euler angles (6 conventions): The first and last rotation are about the same axis (e.g., xzx, xyx, yxy, yzy, zyz, zxz).
   • Cardan (Tait-Bryan) angles (6 conventions): The three rotations are about different axes (e.g., xzy, xyz, yxz, yzx, zyx, zxy).
   • Rotation Type: Rotations can be extrinsic (about the fixed basis vectors of a frame) or intrinsic (about the new, rotated basis vectors of the moving frame).
3. Common Mapping: The extrinsic xyz Cardan angles are often referred to as roll (x), pitch (y), and yaw (z).