timor.utilities.module_classification
=====================================

.. py:module:: timor.utilities.module_classification


Exceptions
----------

.. autoapisummary::

   timor.utilities.module_classification.ModuleClassificationError


Classes
-------

.. autoapisummary::

   timor.utilities.module_classification.ModuleType


Functions
---------

.. autoapisummary::

   timor.utilities.module_classification.divide_db_in_types
   timor.utilities.module_classification.get_module_type


Module Contents
---------------

.. py:exception:: ModuleClassificationError


   .. autoapi-inheritance-diagram:: timor.utilities.module_classification.ModuleClassificationError
      :parts: 1
      :private-bases:


   This can be raised when a module should be assigned a unique type but the classification is not possible

   Initialize self.  See help(type(self)) for accurate signature.


.. py:class:: ModuleType


   .. autoapi-inheritance-diagram:: timor.utilities.module_classification.ModuleType
      :parts: 1
      :private-bases:


   This class implements a simplified but useful distinction of modules in four types: Base, Joint, Link and Eef.

   Be aware that this classification might be an oversimplification, regarding the current module at hand and use
   with care. There is no such distinction in general - however, in the last decades multiple works have published
   modules that can clearly be assigned to one of these types, and if it is possible, this utility class can be
   used to annotate them.

   Initialize self.  See help(type(self)) for accurate signature.


   .. py:attribute:: BASE
      :value: 0



   .. py:attribute:: END_EFFECTOR
      :value: 3



   .. py:attribute:: JOINT
      :value: 2



   .. py:attribute:: LINK
      :value: 1



.. py:function:: divide_db_in_types(db, strict = True)

   Takes one module db and splits it into subsets of bases, links, joints and end-effectors if possible.

   In general, this distinction is an oversimplification, so in cases a module is not clearly one of the possible
   types, this will raise an Exception.

   :param db: Any input modules db with modules that can be uniquely assigned to a ModuleType
   :param strict: If true, this method will raise an Error if there are any doubts about the uniqueness of the
     classification.
   :return: Four DBs in the following order: (Bases, Links, Joints, End-Effectors)
   :raises: ModuleClassificationError


.. py:function:: get_module_type(module, strict = True)

   Tries to get the module type from Module data.

   Be aware the distinction is not always unique, so only use this method if you know your module set.

   :param module: The module to be classified.
   :param strict: If true, this method will raise an Error if there are any doubts about the uniqueness of the
       classification. There are no doubts if there is:

       * Exactly one base connector, one body, zero joints and one other connector OR
       * Exactly one eef connector, one body, zero joints and one other connector OR
       * One or more joints with a "serial" setup and no special connectors OR
       * Exactly one body, no special connectors and no joints
   :return: A Module Type