.. _tf_utils_concept: Concept ============= All four transformation utilities (**BotaTfWrench**, **BotaTfTwist**, **BotaTfImu**, **BotaTfPose**) follow an identical usage pattern. Each is implemented as a self-contained C++ class (with a matching Python binding) that you configure once and then call in your real-time loop. .. raw:: html

FT Stack Compatibility

Designed to be easily used in combination with other components.

JSON-Based Configuration

Configuration is handled through a JSON file passed to the class constructor.

---- Defining the Transformation Tree ---------------------------------- For a transformation to be computed, the geometry of the problem must be fully described, i.e. defining the reference point and expression axes for both input and output. .. note:: All four entries must be set before calling ``update()``. They can be provided via code setters, loaded from a JSON configuration file, or supplied through a combination of both. In general, the four entries (input/output reference points and expressing frames) can be defined freely with respect to any fixed common frame. In practice however, since signals typically appear at the robot's end-effector, it is convenient to introduce a moving frame attached to it. By expressing all four entries relative to this moving frame, only a single transformation needs to be maintained at runtime — the one from the fixed frame to the moving frame — which updates as the robot moves. .. image:: /_static/images/tf_utils_diagrams.svg :alt: Transformation Tree Diagram :align: center Leveraging the idea of the "moving frame" and assigning this to the flange of the robot (point for which a TF from the base frame is usually available) the most common use cases can be easily described. For example: .. list-table:: Common use cases :header-rows: 1 :widths: 30 15 20 20 20 * - Signal type - Ref. point origin - Ref. point translation - Exp. axes origin - Exp. axes rotation * - Sensor frame as reference, expressed in sensor frame - moving_frame - [0, 0, λ] - moving_frame - [0.71, 0, 0, -0.71] * - TCP frame as reference, expressed in base frame - moving_frame - [0, 0, φ] - fixed_frame - [1, 0, 0, 0] * - Flange frame as reference, expressed in base frame - moving_frame - [0, 0, 0] - fixed_frame - [1, 0, 0, 0] .. image:: /_static/images/example_tf.svg :alt: Transformation Tree Diagram :align: center :width: 500px Configuration Files -------------------- Static TF entries can be loaded from a JSON file instead of (or in addition to) code. This separates hardware-specific geometry from application logic and makes it easy to reconfigure without recompiling. .. important:: A setter called in code will return ``false`` and print a warning if the same entry was already loaded from the JSON file. This prevents silent conflicts between file-based and code-based configuration. Each class reads a dedicated top-level key: ``"tf_wrench_config"``, ``"tf_twist_config"``, ``"tf_imu_config"``, or ``"tf_pose_config"``. As sub-level objects the following keys must be defined: .. raw:: html

TF Configuration JSON File Structure

Basic configuration

name string

Human-readable label for the block, accessible via name().

policy string

Runtime error policy. Accepted values: "best_effort" (default), "soft_rt", "hard_rt", "strict_rt".

Input Reference Point

set_input_reference_point object (optional)

It must have the following fields:

origin string

"fixed_frame" or "moving_frame".

translation double[3]

[x, y, z] in metres from origin frame to input reference point.

Input Expression Axes

set_input_expression_axes object (optional)

It must have the following fields:

origin string

"fixed_frame" or "moving_frame".

rotation double[4]

[qw, qx, qy, qz] unit quaternion rotation from origin frame to input expression axes

Output Reference Point

set_output_reference_point object (optional)

It must have the following fields:

origin string

"fixed_frame" or "moving_frame".

translation double[3]

[x, y, z] in metres from origin frame to output reference point

Output Expression Axes

set_output_expression_axes object (optional)

It must have the following fields:

origin string

"fixed_frame" or "moving_frame".

rotation double[4]

[qw, qx, qy, qz] unit quaternion rotation from origin frame to output expression axes

JSON File Templates ______________________ Templates for JSON configuration files are included in the examples provided with our SDKs. ------------ .. raw:: html

Ready to Get Started?

Choose your development platform

→ SDKs homepage