irsim.gui.keyboard_control
==========================

.. py:module:: irsim.gui.keyboard_control


Attributes
----------

.. autoapisummary::

   irsim.gui.keyboard_control.keyboard
   irsim.gui.keyboard_control.keyboard


Classes
-------

.. autoapisummary::

   irsim.gui.keyboard_control.KeyboardControl


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

.. py:data:: keyboard
   :type:  Optional[Any]
   :value: None


.. py:data:: keyboard

.. py:class:: KeyboardControl(env_ref: Optional[Any] = None, **keyboard_kwargs: Any)

   Keyboard input handler for IR-SIM with dual backends.

   Overview:
       - Provides manual control of robots and environment using keyboard keys.
       - Supports two backends:
           - "mpl" (default): Matplotlib figure key events (no extra dependency).
           - "pynput": Global keyboard hook (requires the ``pynput`` package).
       - If the requested backend is unavailable, it automatically falls back to "mpl".

   Control mode gating:
       - Robot control keys (w/s/a/d, q/e, z/c, alt+number) only take effect when
         ``world_param.control_mode == "keyboard"``.
       - Environment keys (space to pause/resume, r to reset, esc to quit) are always active.

   Key mappings (both backends):
       - w/s: Increase/decrease linear velocity (forward/backward)
       - a/d: Increase/decrease angular velocity (turn left/right)
       - q/e: Decrease/increase maximum linear velocity (key_lv_max)
       - z/c: Decrease/increase maximum angular velocity (key_ang_max)
       - alt + number: Change current controlled robot id
       - r: Reset the environment (if ``env_ref`` provided)
       - space: Toggle pause/resume
       - esc: Quit the environment immediately (closes figure and raises ``SystemExit(0)``)
       - x: Switch between keyboard and auto control modes
       - l: Reload the environment
       - F5: Debug the environment

   .. rubric:: Notes

   - The "mpl" backend requires the Matplotlib figure window to have focus to receive key events.
   - In keyboard control mode, behavior planners are ignored; robot motion follows key input.

   Initialize keyboard control for the environment.

   :param env_ref: Reference to the environment instance. Used for pause/resume and reset.
   :param keyboard_kwargs: Optional settings for keyboard control.

                           - key_lv_max (float): Maximum linear velocity. Default is 3.0.
                           - key_ang_max (float): Maximum angular velocity. Default is 1.0.
                           - key_lv (float): Initial linear velocity. Default is 0.0.
                           - key_ang (float): Initial angular velocity. Default is 0.0.
                           - key_id (int): Initial robot control ID. Default is 0.
                           - backend (str): Keyboard backend. ``"mpl"`` (default) uses
                             Matplotlib figure key events; ``"pynput"`` uses a global
                             keyboard hook if the ``pynput`` package is available.
   :type keyboard_kwargs: dict

   Keyboard mappings (both backends):
       - w: Move forward
       - s: Move backward
       - a: Turn left
       - d: Turn right
       - q/e: Decrease/Increase linear velocity
       - z/c: Decrease/Increase angular velocity
       - alt + number: Change current control robot id
       - r: Reset the environment (if ``env_ref`` provided)
       - space: Pause/Resume the environment
       - esc: Quit the environment
       - x: Switch between keyboard and auto control modes
       - l: Reload the environment
       - F5: Debug the environment


   .. py:attribute:: env_ref
      :value: None



   .. py:attribute:: key_lv_max


   .. py:attribute:: key_ang_max


   .. py:attribute:: key_lv


   .. py:attribute:: key_ang


   .. py:attribute:: key_id


   .. py:attribute:: alt_flag
      :value: 0



   .. py:attribute:: backend


   .. py:attribute:: key_vel


   .. py:property:: logger
      :type: Any


      Get the environment logger.

      :returns: The logger instance for the environment.
      :rtype: EnvLogger