Python

Download and Installation

The Python SDK is available as a PyPI package for easy installation.

Supported platforms:

  • Linux: x86_64 and aarch64 (Python ≥ 3.10)
  • Windows: Python ≥ 3.12
  • macOS: Python ≥ 3.12

Installation using pip:

pip install bota-tf-utils

Usage Demo

We provide a demo to get yourself started with the Python SDK.

What you'll find in the demo:

  • Wrench, Twist, IMU and Pose transformer setup and configuration
  • Static and dynamic TF entry patterns
  • Real-time loop integration examples in Python

API Description

All four transformation utilities follow the same interface pattern. Each class is imported from the bota_tf_utils module and can be constructed with either a JSON configuration file or a BotaTfConfig object (see Concept for the config structure).

BotaTfConfig

Configuration object used to construct any of the four transformer classes directly from code, without a JSON file.

class bota_tf_utils.BotaTfConfig
name: str

Name of the block (optional; informational only when configuring from code).

policy

Policy for handling non-OK conditions (optional; defaults to BestEffort).

input_ref_point: Translation

Input reference point: origin frame and translation.

input_expr_axes: Rotation

Input expression axes: origin frame and rotation.

output_ref_point: Translation

Output reference point: origin frame and translation.

output_expr_axes: Rotation

Output expression axes: origin frame and rotation.

class bota_tf_utils.Translation
origin: str

Frame origin: "fixed_frame" or "moving_frame".

translation: numpy.ndarray

Translation vector [x, y, z] in metres. Shape (3,), dtype float64.

class bota_tf_utils.Rotation
origin: str

Frame origin: "fixed_frame" or "moving_frame".

rotation: numpy.ndarray

Unit quaternion [qw, qx, qy, qz]. Shape (4,), dtype float64.

BotaTfWrench

Transforms a 6-DOF wrench [fx, fy, fz, tx, ty, tz] between reference points and expression axes.

class bota_tf_utils.BotaTfWrench

Constructor and Destructor

__init__(config_file: str = '') → None

Constructs the transformer. Optionally loads static TF entries from a JSON config file (section key "tf_wrench_config"). If config_file is empty, all entries must be set via the setters below.

Parameters:

config_file (str) – Path to the JSON configuration file (may be empty).

__init__(config: BotaTfConfig) → None

Constructs the transformer from a BotaTfConfig object populated in user code. All TF entries present in the config object are applied immediately; any entry not set in the config can still be supplied via the setters below.

Parameters:

config (BotaTfConfig) – Fully or partially populated configuration object.

__del__() → None

Default destructor.

Metadata

name() → str

Returns the name specified in the config, or an empty string if no name was set.

Return type:

str

TF Setters

set_input_reference_point(origin: str, translation: numpy.ndarray) → bool

Sets the translation from origin to the input reference point (expressed in origin axes).

Parameters:

  • origin (str) – "fixed_frame" or "moving_frame".

  • translation (numpy.ndarray) – [x, y, z] in metres from origin frame to input reference point. Shape (3,), dtype float64.

Returns:

True on success; False if this entry was already loaded from JSON or config.

Return type:

bool

set_input_expression_axes(origin: str, rotation: numpy.ndarray) → bool

Sets the rotation from origin to the input expression axes.

Parameters:

  • origin (str) – "fixed_frame" or "moving_frame".

  • rotation (numpy.ndarray) – [qw, qx, qy, qz] unit quaternion from origin frame to input expression axes. Shape (4,), dtype float64.

Returns:

True on success; False if this entry was already loaded from JSON or config.

Return type:

bool

set_output_reference_point(origin: str, translation: numpy.ndarray) → bool

Sets the translation from origin to the output reference point (expressed in origin axes).

Parameters:

  • origin (str) – "fixed_frame" or "moving_frame".

  • translation (numpy.ndarray) – [x, y, z] in metres from origin frame to output reference point. Shape (3,), dtype float64.

Returns:

True on success; False if this entry was already loaded from JSON or config.

Return type:

bool

set_output_expression_axes(origin: str, rotation: numpy.ndarray) → bool

Sets the rotation from origin to the output expression axes.

Parameters:

  • origin (str) – "fixed_frame" or "moving_frame".

  • rotation (numpy.ndarray) – [qw, qx, qy, qz] unit quaternion from origin frame to output expression axes. Shape (4,), dtype float64.

Returns:

True on success; False if this entry was already loaded from JSON or config.

Return type:

bool

Dynamic TF

set_fixed_to_moving_frame_tf(tf: numpy.ndarray) → None

Pushes the current fixed-to-moving-frame transform. Must be called every loop iteration when any TF entry uses "moving_frame". Cannot be set via JSON or config object.

Parameters:

tf (numpy.ndarray) – [tx, ty, tz, qw, qx, qy, qz] — translation (metres) followed by unit quaternion from fixed frame to moving frame. Shape (7,), dtype float64.

Transform

update(wrench_in: numpy.ndarray, wrench_out: numpy.ndarray) → BotaControlReturnCode

Transforms the input wrench and writes the result into wrench_out in-place.

Parameters:

  • wrench_in (numpy.ndarray) – Input wrench [fx, fy, fz, tx, ty, tz] at the input reference point, expressed in the input expression axes. Shape (6,), dtype float64.

  • wrench_out (numpy.ndarray) – Pre-allocated output array of shape (6,), dtype float64. Overwritten in-place with the transformed wrench [fx, fy, fz, tx, ty, tz] at the output reference point, expressed in the output expression axes.

Returns:

BotaControlReturnCode.OK on success, or a warning/error code according to the configured policy.

Return type:

BotaControlReturnCode

BotaTfPose

Transforms a 7-DOF pose [px, py, pz, qw, qx, qy, qz] between reference points and expression axes. Uses config key "tf_pose_config".

Note

BotaTfPose does not have a set_fixed_to_moving_frame_tf() method. The orientation of the moving frame is encoded directly in the input pose quaternion, so no separate dynamic TF call is needed each loop iteration.

class bota_tf_utils.BotaTfPose

Constructor and Destructor

__init__(config_file: str = '') → None

Constructs the transformer. Optionally loads static TF entries from "tf_pose_config".

Parameters:

config_file (str) – Path to the JSON configuration file (may be empty).

__init__(config: BotaTfConfig) → None

Constructs the transformer from a BotaTfConfig object populated in user code.

Parameters:

config (BotaTfConfig) – Fully or partially populated configuration object.

__del__() → None

Metadata

name() → str

TF Setters

set_input_reference_point(origin: str, translation: numpy.ndarray) → bool
set_input_expression_axes(origin: str, rotation: numpy.ndarray) → bool
set_output_reference_point(origin: str, translation: numpy.ndarray) → bool
set_output_expression_axes(origin: str, rotation: numpy.ndarray) → bool

Transform

update(pose_in: numpy.ndarray, pose_out: numpy.ndarray) → BotaControlReturnCode

Transforms the input pose and writes the result into pose_out in-place.

Parameters:

  • pose_in (numpy.ndarray) – Input pose [px, py, pz, qw, qx, qy, qz]. Shape (7,), dtype float64.

  • pose_out (numpy.ndarray) – Pre-allocated output array of shape (7,), dtype float64. Overwritten in-place with the transformed pose [px, py, pz, qw, qx, qy, qz].

Return type:

BotaControlReturnCode

BotaTfTwist

Transforms a 6-DOF twist [vx, vy, vz, wx, wy, wz] between reference points and expression axes. The interface is identical to BotaTfWrench — only the config key ("tf_twist_config") and the signal semantics differ.

class bota_tf_utils.BotaTfTwist
__init__(config_file: str = '') → None

Constructs the transformer. Optionally loads static TF entries from "tf_twist_config".

Parameters:

config_file (str) – Path to the JSON configuration file (may be empty).

__init__(config: BotaTfConfig) → None

Constructs the transformer from a BotaTfConfig object populated in user code.

Parameters:

config (BotaTfConfig) – Fully or partially populated configuration object.

__del__() → None
name() → str
set_input_reference_point(origin: str, translation: numpy.ndarray) → bool
set_input_expression_axes(origin: str, rotation: numpy.ndarray) → bool
set_output_reference_point(origin: str, translation: numpy.ndarray) → bool
set_output_expression_axes(origin: str, rotation: numpy.ndarray) → bool
set_fixed_to_moving_frame_tf(tf: numpy.ndarray) → None
update(twist_in: numpy.ndarray, twist_out: numpy.ndarray) → BotaControlReturnCode

Transforms the input twist and writes the result into twist_out in-place.

Parameters:

  • twist_in (numpy.ndarray) – Input twist [vx, vy, vz, wx, wy, wz] (m/s and rad/s). Shape (6,), dtype float64.

  • twist_out (numpy.ndarray) – Pre-allocated output array of shape (6,), dtype float64. Overwritten in-place with the transformed twist [vx, vy, vz, wx, wy, wz].

Return type:

BotaControlReturnCode

BotaTfImu

Transforms a 6-DOF IMU signal [ax, ay, az, wx, wy, wz] between reference points and expression axes, accounting for the centripetal acceleration term when the reference point changes. Uses config key "tf_imu_config".

class bota_tf_utils.BotaTfImu
__init__(config_file: str = '') → None

Constructs the transformer. Optionally loads static TF entries from "tf_imu_config".

Parameters:

config_file (str) – Path to the JSON configuration file (may be empty).

__init__(config: BotaTfConfig) → None

Constructs the transformer from a BotaTfConfig object populated in user code.

Parameters:

config (BotaTfConfig) – Fully or partially populated configuration object.

__del__() → None
name() → str
set_input_reference_point(origin: str, translation: numpy.ndarray) → bool
set_input_expression_axes(origin: str, rotation: numpy.ndarray) → bool
set_output_reference_point(origin: str, translation: numpy.ndarray) → bool
set_output_expression_axes(origin: str, rotation: numpy.ndarray) → bool
set_fixed_to_moving_frame_tf(tf: numpy.ndarray) → None
update(imu_in: numpy.ndarray, imu_out: numpy.ndarray) → BotaControlReturnCode

Transforms the input IMU signal and writes the result into imu_out in-place.

Parameters:

  • imu_in (numpy.ndarray) – Input IMU signal [ax, ay, az, wx, wy, wz] (m/s² and rad/s). Shape (6,), dtype float64.

  • imu_out (numpy.ndarray) – Pre-allocated output array of shape (6,), dtype float64. Overwritten in-place with the transformed IMU signal [ax, ay, az, wx, wy, wz].

Return type:

BotaControlReturnCode