C++
===========

Download and Installation
-------------------------

The C++ SDK is distributed as **pre-compiled binaries** for easy integration.

.. raw:: html

   <div style="background-color: #f8f9fa; border: 2px solid #6c757d; border-radius: 0.375rem; padding: 1rem; margin: 1rem 0;">
   <p><strong>Supported platforms:</strong></p>
   <ul>
   <li><strong>Linux:</strong> x86_64 and aarch64</li>
   <li><strong>Windows:</strong> x86_64</li>
   <li><strong>macOS:</strong> arm64</li>
   </ul>
   <p><strong>Download:</strong> <a href="https://botasys.gitlab.io/control_toolkit/priv_bota_tf_utils/index.html" target="_blank">Get the binaries here</a></p>
   <p><strong>Installation:</strong> Copy the downloaded files to your C++ project and configure your build system to link against the library.</p>
   </div>

Usage Demo
----------
.. _tf_cpp_usage_demo:

We provide a demo to **get yourself started** with the C++ SDK.

.. raw:: html

   <div style="background-color: #f8f9fa; border: 2px solid #6c757d; border-radius: 0.5rem; padding: 1.5rem; margin: 1.5rem 0; box-shadow: 0 2px 4px rgba(0,0,0,0.1);">
   <p style="margin-bottom: 1rem;"><strong>What you'll find in the demo:</strong></p>
   <ul style="margin-bottom: 1.5rem;">
   <li>Wrench, Twist, IMU and Pose transformer setup and configuration</li>
   <li>Static and dynamic TF entry patterns</li>
   <li>Real-time loop integration examples in C++</li>
   </ul>
   <div style="background-color: #ffffff; border: 1px solid #dee2e6; border-radius: 0.25rem; padding: 1rem; text-align: center;">
   <a href="https://gitlab.com/botasys/control_toolkit/bota_demo_cpp" target="_blank"
      style="font-weight: bold; font-size: 1.1em; color: #495057; text-decoration: none;">
      → C++ Demo Repository ←
   </a>
   </div>
   </div>

API Description
---------------

All four transformation utilities follow the same interface pattern.
Each class lives in the ``bota`` namespace and is constructed with a 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.

.. cpp:class:: bota::BotaTfWrench

   **Constructor and Destructor**

   .. cpp:function:: explicit BotaTfWrench(const std::string& config_file = "")

      Constructs the object. 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 descruved below.

      :param config_file: Path to the JSON configuration file (may be empty).
      :type config_file: const std::string&

   .. cpp:function:: ~BotaTfWrench()

      Default destructor.

   **Metadata**

   .. cpp:function:: const std::string& name() const

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

      :rtype: const std::string&

   **TF Setters**

   .. cpp:function:: bool setInputReferencePoint(const std::string& origin, const std::array<double,3>& translation)

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

      :param origin: ``"fixed_frame"`` or ``"moving_frame"``.
      :param translation: ``[x, y, z]`` in metres from origin frame to input reference point.
      :returns: ``true`` on success; ``false`` if this entry was already loaded from JSON.
      :rtype: bool

   .. cpp:function:: bool setInputExpressionAxes(const std::string& origin, const std::array<double,4>& rotation)

      Sets the rotation from *origin* to the input expression axes.

      :param origin: ``"fixed_frame"`` or ``"moving_frame"``.
      :param rotation: ``[qw, qx, qy, qz]`` unit quaternion rotation from origin frame to input expression axes.
      :returns: ``true`` on success; ``false`` if this entry was already loaded from JSON.
      :rtype: bool

   .. cpp:function:: bool setOutputReferencePoint(const std::string& origin, const std::array<double,3>& translation)

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

      :param origin: ``"fixed_frame"`` or ``"moving_frame"``.
      :param translation: ``[x, y, z]`` in metres from origin frame to output reference point.
      :returns: ``true`` on success; ``false`` if this entry was already loaded from JSON.
      :rtype: bool

   .. cpp:function:: bool setOutputExpressionAxes(const std::string& origin, const std::array<double,4>& rotation)

      Sets the rotation from *origin* to the output expression axes.

      :param origin: ``"fixed_frame"`` or ``"moving_frame"``.
      :param rotation: ``[qw, qx, qy, qz]`` unit quaternion rotation from origin frame to output expression axes.
      :returns: ``true`` on success; ``false`` if this entry was already loaded from JSON.
      :rtype: bool

   **Dynamic TF**

   .. cpp:function:: void setFixedToMovingFrameTf(const std::array<double,7>& tf)

      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.

   **Transform**

   .. cpp:function:: BotaControlReturnCode update(const std::array<double,6>& wrench_in, std::array<double,6>& wrench_out)

      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.
      :param wrench_out: Output 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.
      :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 ``setFixedToMovingFrameTf()`` 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.

.. cpp:class:: bota::BotaTfPose

   **Constructor and Destructor**

   .. cpp:function:: explicit BotaTfPose(const std::string& config_file = "")

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

      :param config_file: Path to the JSON configuration file (may be empty).

   .. cpp:function:: ~BotaTfPose()

   **Metadata**

   .. cpp:function:: const std::string& name() const

   **TF Setters**

   .. cpp:function:: bool setInputReferencePoint(const std::string& origin, const std::array<double,3>& translation)

   .. cpp:function:: bool setInputExpressionAxes(const std::string& origin, const std::array<double,4>& rotation)

   .. cpp:function:: bool setOutputReferencePoint(const std::string& origin, const std::array<double,3>& translation)

   .. cpp:function:: bool setOutputExpressionAxes(const std::string& origin, const std::array<double,4>& rotation)

   **Transform**

   .. cpp:function:: BotaControlReturnCode update(const std::array<double,7>& pose_in, std::array<double,7>& pose_out)

      Transforms the input pose and writes the result to ``pose_out``.

      :param pose_in:  Input pose ``[px, py, pz, qw, qx, qy, qz]``.
      :param pose_out: Output pose ``[px, py, pz, qw, qx, qy, qz]``.
      :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.

.. cpp:class:: bota::BotaTfTwist

   .. cpp:function:: explicit BotaTfTwist(const std::string& config_file = "")

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

   .. cpp:function:: ~BotaTfTwist()

   .. cpp:function:: const std::string& name() const

   .. cpp:function:: bool setInputReferencePoint(const std::string& origin, const std::array<double,3>& translation)

   .. cpp:function:: bool setInputExpressionAxes(const std::string& origin, const std::array<double,4>& rotation)

   .. cpp:function:: bool setOutputReferencePoint(const std::string& origin, const std::array<double,3>& translation)

   .. cpp:function:: bool setOutputExpressionAxes(const std::string& origin, const std::array<double,4>& rotation)

   .. cpp:function:: void setFixedToMovingFrameTf(const std::array<double,7>& tf)

   .. cpp:function:: BotaControlReturnCode update(const std::array<double,6>& twist_in, std::array<double,6>& twist_out)

      Transforms the input twist and writes the result to ``twist_out``.

      :param twist_in:  Input twist ``[vx, vy, vz, wx, wy, wz]``.
      :param twist_out: Output twist ``[vx, vy, vz, wx, wy, wz]``.
      :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. The interface is identical to ``BotaTfWrench`` — only the config key
(``"tf_imu_config"``) and the signal semantics differ.

.. cpp:class:: bota::BotaTfImu

   .. cpp:function:: explicit BotaTfImu(const std::string& config_file = "")

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

   .. cpp:function:: ~BotaTfImu()

   .. cpp:function:: const std::string& name() const

   .. cpp:function:: bool setInputReferencePoint(const std::string& origin, const std::array<double,3>& translation)

   .. cpp:function:: bool setInputExpressionAxes(const std::string& origin, const std::array<double,4>& rotation)

   .. cpp:function:: bool setOutputReferencePoint(const std::string& origin, const std::array<double,3>& translation)

   .. cpp:function:: bool setOutputExpressionAxes(const std::string& origin, const std::array<double,4>& rotation)

   .. cpp:function:: void setFixedToMovingFrameTf(const std::array<double,7>& tf)

   .. cpp:function:: BotaControlReturnCode update(const std::array<double,6>& imu_in, std::array<double,6>& imu_out)

      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).
      :param imu_out: Output IMU signal ``[ax, ay, az, wx, wy, wz]``.
      :rtype: BotaControlReturnCode