irsim.lib.behavior.behavior
===========================

.. py:module:: irsim.lib.behavior.behavior


Classes
-------

.. autoapisummary::

   irsim.lib.behavior.behavior.Behavior


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

.. py:class:: Behavior(object_info=None, behavior_dict=None)

   Represents the behavior of an agent in the simulation.

   :param object_info: Object information from the object_base class ObjectInfo.
   :type object_info: object
   :param behavior_dict: Dictionary containing behavior parameters for different behaviors.
                         Name Options include: 'dash', 'rvo'.
                         target_roles:

                         - 'all': all objects in the environment will be considered within this behavior.
                         - 'obstacle': only obstacles will be considered within this behavior.
                         - 'robot': only robots will be considered within this behavior.
   :type behavior_dict: dict

   Initialize the behavior with object info and parameters.

   :param object_info: Information about the agent (from ObjectBase.ObjectInfo).
   :param behavior_dict: Behavior parameters; if ``None``,
                         defaults to an empty dict.
   :type behavior_dict: dict | None


   .. py:attribute:: object_info
      :value: None



   .. py:attribute:: behavior_dict


   .. py:method:: gen_vel(ego_object, external_objects=None)

      Generate a velocity for the agent based on configured behavior.

      :param ego_object: The agent itself (object with needed attributes).
      :param external_objects: Other objects in the environment.
      :type external_objects: list | None

      :returns: A 2x1 velocity vector appropriate for the agent
                kinematics.
      :rtype: numpy.ndarray



   .. py:method:: load_behavior(behaviors: str = '.behavior_methods')

      Load behavior parameters from the script.

      :param behaviors: name of the behavior script.
      :type behaviors: str



   .. py:method:: invoke_behavior(kinematics: str, action: str, **kwargs: Any) -> Any

      Invoke a specific behavior method based on kinematics model and action type.

      This method looks up and executes the appropriate behavior function from the
      behavior registry based on the combination of kinematics model and action name.

      :param kinematics: Kinematics model identifier. Supported values:

                         - 'diff': Differential drive kinematics
                         - 'omni': Omnidirectional kinematics
                         - 'acker': Ackermann steering kinematics
      :type kinematics: str
      :param action: Behavior action name. Examples:

                     - 'dash': Direct movement toward goal
                     - 'rvo': Reciprocal Velocity Obstacles for collision avoidance
      :type action: str
      :param \*\*kwargs: Additional keyword arguments passed to the behavior function.
                         Common parameters include ego_object, external_objects, goal, etc.

      :returns: Generated velocity vector (2x1) in the format appropriate
                for the specified kinematics model.
      :rtype: np.ndarray

      :raises ValueError: If no behavior method is found for the given kinematics
          and action combination.

      .. rubric:: Example

      >>> # Invoke differential drive dash behavior
      >>> vel = behavior.invoke_behavior('diff', 'dash',
      ...                               ego_object=robot,
      ...                               external_objects=obstacles)