.. raw:: html
i
The Payload Utilities are part of the Bota Control Toolkit. It is highly advisable to first read about the Bota Control Toolkit to understand the broader context and architecture.
------------ Transformation Utilities ============= The **Bota Transformation Utilities** are a collection of utilities that **ease the transformation of motion and force signals** between different reference points and coordinate frames on a rigid body. These utilities cleanly encapsulate the transformation mathematics, handling the following four commonly used signals: .. raw:: html

Wrench

Forces and torques.

Pose

Position and orientation.

Twist

Linear and angular velocities.

IMU

Linear acceleration + angular velocity.

.. raw:: html
.. raw:: html

Reference Point and Expression Axes

Wrench, Pose, Twist, and IMU signals have two independent properties that are easy to confuse: .. raw:: html

Reference Point

The point in space with respect to which quantities are expressed.

The same physical signal yields different moment components depending on where this point is chosen. This is relevant for torques, linear velocities and linear accelerations, but not for forces or angular velocities.

Expression Axes

The coordinate axes used to express the components of a signal.

The same vector can be decomposed along different axes. Expression axes do not have to be attached to the rigid body where the signal is measured or applied.

.. raw:: html

Transformation Mathematics

.. raw:: html

Index Glossary

.. raw:: html
Notation Meaning
sP  —  subscript Reference point P: the physical point on the rigid body at which the signal is measured or applied.
s{F}  —  superscript in braces Expression frame F: the coordinate axes in which the signal components are expressed.
rAB Position vector from reference point A to reference point B.
R{Y}{X} Rotation matrix that re-expresses vector components from frame {X} into frame {Y}.
q{Y}{X} Unit quaternion representing the same rotation as R{Y}{X}, used for quaternion composition (pose orientation only).
.. raw:: html

Wrench [fx, fy, fz, tx, ty, tz]

A wrench gathers the net force and torque acting on (or measured at) a rigid body. **Physical meaning of reference point** The point at which the torque components are evaluated. A force applied at a distance from the reference point creates a torque; shifting the reference point therefore changes the torque, even though the force itself is unchanged. **Changing the reference point** from :math:`A` to :math:`B`: .. math:: \begin{align} \mathbf{f}_B &= \mathbf{f}_A \\ \boldsymbol{\tau}_B &= \boldsymbol{\tau}_A + \mathbf{r}_{BA} \times \mathbf{f}_A \end{align} where :math:`\mathbf{r}_{BA} = \mathbf{p}_B - \mathbf{p}_A` is the vector from :math:`A` to :math:`B`. **Changing the expression axes** from frame :math:`X` to frame :math:`Y`: .. math:: \mathbf{f}^{\{Y\}} = R^{\{Y\}}_{\{X\}}\,\mathbf{f}^{\{X\}}, \qquad \boldsymbol{\tau}^{\{Y\}} = R^{\{Y\}}_{\{X\}}\,\boldsymbol{\tau}^{\{X\}} ---- .. raw:: html

Pose [px, py, pz, qw, qx, qy, qz]

A pose describes where a rigid-body point is and how it is oriented, always measured relative to the base (fixed) frame. **Physical meaning of reference point** The specific point on the rigid body for which the pose is computed. Shifting the reference point changes the position components, but **not** the orientation — all points on a rigid body share the same orientation. .. note:: For pose, the term *reference point* does not carry the same physical meaning as for wrench, twist, or IMU (where it denotes the point *from which* moments or velocities are computed). Here it simply identifies *which point's pose* is being described. The name is kept for API consistency across all four signal types. **Changing the reference point** from :math:`A` to :math:`B` (position only): .. math:: \begin{align} \mathbf{p}_B &= \mathbf{p}_A + R^{\{\text{base}\}}_{\{\text{body}\}}\,\mathbf{r}_{AB}^{\{\text{body}\}} \\ \mathbf{q}_B &= \mathbf{q}_A \quad \text{(orientation unchanged)} \end{align} **Changing the expression axes** from frame :math:`X` to frame :math:`Y`: .. math:: \mathbf{p}^{\{Y\}} = R^{\{Y\}}_{\{X\}}\,\mathbf{p}^{\{X\}}, \qquad \mathbf{q}^{\{Y\}} = q^{\{Y\}}_{\{X\}} \otimes \mathbf{q}^{\{X\}} .. raw:: html

Twist [vx, vy, vz, wx, wy, wz]

A twist captures the instantaneous linear and angular velocity of a rigid body. **Physical meaning of reference point** The point whose linear velocity is being described. Every point on a rigid body shares the same angular velocity :math:`\boldsymbol{\omega}`, but their linear velocities differ because of the rigid-body rotation. **Changing the reference point** from :math:`A` to :math:`B`: .. math:: \begin{align} \mathbf{v}_B &= \mathbf{v}_A + \boldsymbol{\omega}_A \times \mathbf{r}_{AB} \\ \boldsymbol{\omega}_B &= \boldsymbol{\omega}_A \end{align} where :math:`\mathbf{r}_{AB} = \mathbf{p}_B - \mathbf{p}_A`. **Changing the expression axes** from frame :math:`X` to frame :math:`Y`: .. math:: \mathbf{v}^{\{Y\}} = R^{\{Y\}}_{\{X\}}\,\mathbf{v}^{\{X\}}, \qquad \boldsymbol{\omega}^{\{Y\}} = R^{\{Y\}}_{\{X\}}\,\boldsymbol{\omega}^{\{X\}} ---- .. raw:: html

IMU [ax, ay, az, wx, wy, wz]

An IMU measures linear acceleration and angular velocity. The angular velocity component obeys the same rigid-body rule as for a twist; the linear acceleration does not, because of the centripetal term. **Physical meaning of reference point** The point whose linear acceleration is being described. Angular velocity :math:`\boldsymbol{\omega}` is identical at every point on the body — only expression axes change for that component. **Changing the reference point** from :math:`A` to :math:`B`: .. math:: \begin{align} \mathbf{a}_B &= \mathbf{a}_A + \boldsymbol{\omega} \times \bigl(\boldsymbol{\omega} \times \mathbf{r}_{AB}\bigr) \\ \boldsymbol{\omega}_B &= \boldsymbol{\omega}_A \end{align} .. note:: The angular acceleration term :math:`\boldsymbol{\alpha} \times \mathbf{r}_{AB}` is **not** included because an IMU does not directly measure angular acceleration. **Changing the expression axes** from frame :math:`X` to frame :math:`Y`: .. math:: \mathbf{a}^{\{Y\}} = R^{\{Y\}}_{\{X\}}\,\mathbf{a}^{\{X\}}, \qquad \boldsymbol{\omega}^{\{Y\}} = R^{\{Y\}}_{\{X\}}\,\boldsymbol{\omega}^{\{X\}} ---- .. raw:: html

Ready to Get Started?

1

Learn the Concept

Understand the usage pattern, how to define the transformation tree and how to integrate into a real-time loop.

Read Concept
2

Choose Your SDK

Select your preferred development platform and get started with code examples.

C++ Python
Tip: New here? Start with the Concept page. Already familiar? Jump straight to the SDK documentation.
.. toctree:: :maxdepth: 3 :caption: Contents :hidden: tf_utils_concept tf_utils_sdks