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:

Wrench

Forces and torques.

Pose

Position and orientation.

Twist

Linear and angular velocities.

IMU

Linear acceleration + angular velocity.

Reference Point and Expression Axes

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

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.

Transformation Mathematics

Index Glossary

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).

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 \(A\) to \(B\):

\[\begin{split}\begin{align} \mathbf{f}_B &= \mathbf{f}_A \\ \boldsymbol{\tau}_B &= \boldsymbol{\tau}_A + \mathbf{r}_{BA} \times \mathbf{f}_A \end{align}\end{split}\]

where \(\mathbf{r}_{BA} = \mathbf{p}_B - \mathbf{p}_A\) is the vector from \(A\) to \(B\).

Changing the expression axes from frame \(X\) to frame \(Y\):

\[\mathbf{f}^{\{Y\}} = R^{\{Y\}}_{\{X\}}\,\mathbf{f}^{\{X\}}, \qquad \boldsymbol{\tau}^{\{Y\}} = R^{\{Y\}}_{\{X\}}\,\boldsymbol{\tau}^{\{X\}}\]

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 \(A\) to \(B\) (position only):

\[\begin{split}\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}\end{split}\]

Changing the expression axes from frame \(X\) to frame \(Y\):

\[\mathbf{p}^{\{Y\}} = R^{\{Y\}}_{\{X\}}\,\mathbf{p}^{\{X\}}, \qquad \mathbf{q}^{\{Y\}} = q^{\{Y\}}_{\{X\}} \otimes \mathbf{q}^{\{X\}}\]

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 \(\boldsymbol{\omega}\), but their linear velocities differ because of the rigid-body rotation.

Changing the reference point from \(A\) to \(B\):

\[\begin{split}\begin{align} \mathbf{v}_B &= \mathbf{v}_A + \boldsymbol{\omega}_A \times \mathbf{r}_{AB} \\ \boldsymbol{\omega}_B &= \boldsymbol{\omega}_A \end{align}\end{split}\]

where \(\mathbf{r}_{AB} = \mathbf{p}_B - \mathbf{p}_A\).

Changing the expression axes from frame \(X\) to frame \(Y\):

\[\mathbf{v}^{\{Y\}} = R^{\{Y\}}_{\{X\}}\,\mathbf{v}^{\{X\}}, \qquad \boldsymbol{\omega}^{\{Y\}} = R^{\{Y\}}_{\{X\}}\,\boldsymbol{\omega}^{\{X\}}\]

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 \(\boldsymbol{\omega}\) is identical at every point on the body — only expression axes change for that component.

Changing the reference point from \(A\) to \(B\):

\[\begin{split}\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}\end{split}\]

Note

The angular acceleration term \(\boldsymbol{\alpha} \times \mathbf{r}_{AB}\) is not included because an IMU does not directly measure angular acceleration.

Changing the expression axes from frame \(X\) to frame \(Y\):

\[\mathbf{a}^{\{Y\}} = R^{\{Y\}}_{\{X\}}\,\mathbf{a}^{\{X\}}, \qquad \boldsymbol{\omega}^{\{Y\}} = R^{\{Y\}}_{\{X\}}\,\boldsymbol{\omega}^{\{X\}}\]

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.

2

Choose Your SDK

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

Tip: New here? Start with the Concept page. Already familiar? Jump straight to the SDK documentation.