Python =========== Download and Installation ------------------------- The Python SDK is available as a **PyPI package** for easy installation. .. raw:: html

Supported platforms:

Installation using pip:

.. code-block:: bash pip install bota-tf-utils .. raw:: html
Usage Demo ---------- .. _tf_py_usage_demo: We provide a demo to **get yourself started** with the Python SDK. .. raw:: html

What you'll find in the demo:

→ Python Demo Repository ←
API Description --------------- All four transformation utilities follow the same interface pattern. Each class is imported from the ``bota_tf_utils`` module and is constructed with an optional path to a JSON configuration file (see :ref:`tf_utils_concept` for the config file structure). BotaTfWrench ^^^^^^^^^^^^ Transforms a 6-DOF wrench ``[fx, fy, fz, tx, ty, tz]`` between reference points and expression axes. .. py:class:: bota_tf_utils.BotaTfWrench **Constructor and Destructor** .. py:method:: __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. :param config_file: Path to the JSON configuration file (may be empty). :type config_file: str .. py:method:: __del__() -> None Default destructor. **Metadata** .. py:method:: name() -> str Returns the name specified in the JSON config, or an empty string if no config was loaded. :rtype: str **TF Setters** .. py:method:: set_input_reference_point(origin: str, translation: list[float]) -> bool Sets the translation from *origin* to the input reference point (expressed in *origin* axes). :param origin: ``"fixed_frame"`` or ``"moving_frame"``. :type origin: str :param translation: ``[x, y, z]`` in metres from origin frame to input reference point. :type translation: list[float] :returns: ``True`` on success; ``False`` if this entry was already loaded from JSON. :rtype: bool .. py:method:: set_input_expression_axes(origin: str, rotation: list[float]) -> bool Sets the rotation from *origin* to the input expression axes. :param origin: ``"fixed_frame"`` or ``"moving_frame"``. :type origin: str :param rotation: ``[qw, qx, qy, qz]`` unit quaternion rotation from origin frame to input expression axes. :type rotation: list[float] :returns: ``True`` on success; ``False`` if this entry was already loaded from JSON. :rtype: bool .. py:method:: set_output_reference_point(origin: str, translation: list[float]) -> bool Sets the translation from *origin* to the output reference point (expressed in *origin* axes). :param origin: ``"fixed_frame"`` or ``"moving_frame"``. :type origin: str :param translation: ``[x, y, z]`` in metres from origin frame to output reference point. :type translation: list[float] :returns: ``True`` on success; ``False`` if this entry was already loaded from JSON. :rtype: bool .. py:method:: set_output_expression_axes(origin: str, rotation: list[float]) -> bool Sets the rotation from *origin* to the output expression axes. :param origin: ``"fixed_frame"`` or ``"moving_frame"``. :type origin: str :param rotation: ``[qw, qx, qy, qz]`` unit quaternion rotation from origin frame to output expression axes. :type rotation: list[float] :returns: ``True`` on success; ``False`` if this entry was already loaded from JSON. :rtype: bool **Dynamic TF** .. py:method:: set_fixed_to_moving_frame_tf(tf: list[float]) -> 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 the JSON config. :param tf: ``[tx, ty, tz, qw, qx, qy, qz]`` — translation (metres) followed by unit quaternion from fixed frame to moving frame. :type tf: list[float] **Transform** .. py:method:: update(wrench_in: list[float], wrench_out: list[float]) -> BotaControlReturnCode Transforms the input wrench and writes the result to ``wrench_out``. :param wrench_in: Input wrench ``[fx, fy, fz, tx, ty, tz]`` at the input reference point, expressed in the input expression axes. :type wrench_in: list[float] :param wrench_out: Output wrench ``[fx, fy, fz, tx, ty, tz]`` at the output reference point, expressed in the output expression axes. :type wrench_out: list[float] :returns: ``BotaControlReturnCode.OK`` on success, or a warning/error code according to the configured policy. :rtype: 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. .. py:class:: bota_tf_utils.BotaTfPose **Constructor and Destructor** .. py:method:: __init__(config_file: str = "") -> None Constructs the transformer. Optionally loads static TF entries from ``"tf_pose_config"``. :param config_file: Path to the JSON configuration file (may be empty). :type config_file: str .. py:method:: __del__() -> None **Metadata** .. py:method:: name() -> str **TF Setters** .. py:method:: set_input_reference_point(origin: str, translation: list[float]) -> bool .. py:method:: set_input_expression_axes(origin: str, rotation: list[float]) -> bool .. py:method:: set_output_reference_point(origin: str, translation: list[float]) -> bool .. py:method:: set_output_expression_axes(origin: str, rotation: list[float]) -> bool **Transform** .. py:method:: update(pose_in: list[float], pose_out: list[float]) -> BotaControlReturnCode Transforms the input pose and writes the result to ``pose_out``. :param pose_in: Input pose ``[px, py, pz, qw, qx, qy, qz]``. :type pose_in: list[float] :param pose_out: Output pose ``[px, py, pz, qw, qx, qy, qz]``. :type pose_out: list[float] :rtype: 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. .. py:class:: bota_tf_utils.BotaTfTwist .. py:method:: __init__(config_file: str = "") -> None Constructs the transformer. Optionally loads static TF entries from ``"tf_twist_config"``. .. py:method:: __del__() -> None .. py:method:: name() -> str .. py:method:: set_input_reference_point(origin: str, translation: list[float]) -> bool .. py:method:: set_input_expression_axes(origin: str, rotation: list[float]) -> bool .. py:method:: set_output_reference_point(origin: str, translation: list[float]) -> bool .. py:method:: set_output_expression_axes(origin: str, rotation: list[float]) -> bool .. py:method:: set_fixed_to_moving_frame_tf(tf: list[float]) -> None .. py:method:: update(twist_in: list[float], twist_out: list[float]) -> BotaControlReturnCode Transforms the input twist and writes the result to ``twist_out``. :param twist_in: Input twist ``[vx, vy, vz, wx, wy, wz]``. :type twist_in: list[float] :param twist_out: Output twist ``[vx, vy, vz, wx, wy, wz]``. :type twist_out: list[float] :rtype: 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"``. .. py:class:: bota_tf_utils.BotaTfImu .. py:method:: __init__(config_file: str = "") -> None Constructs the transformer. Optionally loads static TF entries from ``"tf_imu_config"``. .. py:method:: __del__() -> None .. py:method:: name() -> str .. py:method:: set_input_reference_point(origin: str, translation: list[float]) -> bool .. py:method:: set_input_expression_axes(origin: str, rotation: list[float]) -> bool .. py:method:: set_output_reference_point(origin: str, translation: list[float]) -> bool .. py:method:: set_output_expression_axes(origin: str, rotation: list[float]) -> bool .. py:method:: set_fixed_to_moving_frame_tf(tf: list[float]) -> None .. py:method:: update(imu_in: list[float], imu_out: list[float]) -> BotaControlReturnCode Transforms the input IMU signal and writes the result to ``imu_out``. :param imu_in: Input IMU signal ``[ax, ay, az, wx, wy, wz]`` (m/s² and rad/s). :type imu_in: list[float] :param imu_out: Output IMU signal ``[ax, ay, az, wx, wy, wz]``. :type imu_out: list[float] :rtype: BotaControlReturnCode