Python
===========

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

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

.. 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 (Python ≥ 3.10)</li>
   <li><strong>Windows:</strong> Python ≥ 3.12</li>
   <li><strong>macOS:</strong> Python ≥ 3.12</li>
   </ul>

   <p><strong>Installation using pip:</strong></p>

.. code-block:: bash

   pip install bota-payload-utils

.. raw:: html

   </div>

Usage Examples
---------------
.. _py_usage_examples:

We provide a demo to **get yourself started** with the Python Payload Utilities.

.. 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 examples:</strong></p>
   <ul style="margin-bottom: 1.5rem;">
   <li>Estimator and Compensator setup and configuration</li>
   <li>Real-time pipeline setup in Python</li>
   <li>Integration patterns and best practices</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_py" target="_blank"
      style="font-weight: bold; font-size: 1.1em; color: #495057; text-decoration: none;">
      → Python Demo Repository ←
   </a>
   </div>
   </div>



API description
------------------

BotaPayloadCompensator
^^^^^^^^^^^^^^^^^^^^^^

Compensates force/torque measurements for the effects of payload mass and gravity.

.. py:class:: BotaPayloadCompensator(config_path: str)

   Initializes the compensator from a JSON configuration file.

   .. py:method:: update(timestamp: float, wrench_imu_raw: np.ndarray, wrench_imu_compensated: np.ndarray) -> BotaControlReturnCode

      Computes compensated output from raw input. Result is written into ``wrench_imu_compensated`` in-place.

   .. py:method:: tare_compensated_wrench() -> bool

      Zeros the compensated wrench output by computing and applying current offsets.

BotaPayloadEstimator
^^^^^^^^^^^^^^^^^^^^

Estimates payload properties (mass, center of mass) from force/torque measurements.

.. py:class:: BotaPayloadEstimator(config_path: str)

   Initializes the estimator from a JSON configuration file.

   .. py:method:: update(timestamp: float, wrench_imu_raw: np.ndarray) -> BotaControlReturnCode

      Feeds new raw data into the estimation algorithm.

   .. py:method:: start_payload_estimation() -> bool

      Starts the payload estimation process.

   .. py:method:: is_estimator_running() -> bool

      Returns ``True`` if estimation is currently in progress.

   .. py:method:: is_estimation_successful() -> bool

      Returns ``True`` if the last estimation completed successfully.