irsim.world.sensors.contact2d
=============================

.. py:module:: irsim.world.sensors.contact2d


Classes
-------

.. autoapisummary::

   irsim.world.sensors.contact2d.Contact2D


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

.. py:class:: Contact2D(state: numpy.ndarray | None = None, obj_id: int = 0, force_scale: float = 0.05, marker_size: float = 6.0, linewidth: float = 1.5, alpha: float = 0.9, **kwargs)

   Contact sensor of one object: what the contact step recorded about it
   (``collision_mode: contact`` only), as a contact sensor mounted on the
   object reports.

   Every object carries one as ``obj.contact``, written by the environment
   and the contact solver, so its readings are always available:
   ``obj.contact.in_contact``, ``partners``, ``reports``, ``force``,
   ``contact_time``, ``air_time``, ``started`` and ``ended``.
   Listing it under the object's ``sensors`` as ``type: 'contact2d'`` makes
   that one the object's sensor and draws it: a marker at each contact
   point and a line along the contact normal whose length is the contact
   force times ``force_scale``.

   :param state: Initial state of the object ``[x, y, theta]``,
                 kept for the common sensor interface; the readings do not
                 depend on it.
   :type state: np.ndarray
   :param obj_id: ID of the associated object.
   :type obj_id: int
   :param force_scale: Length of the drawn force line per newton, in
                       meters. Default 0.05.
   :type force_scale: float
   :param marker_size: Size of the contact point markers. Default 6.
   :type marker_size: float
   :param linewidth: Width of the force lines. Default 1.5.
   :type linewidth: float
   :param alpha: Transparency of the drawing. Default 0.9.
   :type alpha: float
   :param \*\*kwargs: ``plot`` sub-dict (preferred) with the visualization options
                      above and ``color`` (default: the palette ``marker`` color), plus
                      the ``name`` / ``type`` key of the YAML entry.

   :ivar sensor_type: ``"contact2d"``.
   :vartype sensor_type: str
   :ivar parent: The object the sensor is mounted on.
   :vartype parent: ObjectBase
   :ivar in_contact: Whether a contact was resolved against ``parent``
                     in the last step.
   :vartype in_contact: bool
   :ivar partners: The objects ``parent`` touched in the last step,
                   each once.
   :vartype partners: list
   :ivar records: The contact records of the last step, in
                  the solver's order.
   :vartype records: list[Contact]
   :ivar force: Net world-frame contact force ``(2, 1)`` on
                ``parent`` in the last step, in newtons.
   :vartype force: np.ndarray
   :ivar contact_time: Seconds ``parent`` has been touching something.
   :vartype contact_time: float
   :ivar air_time: Seconds ``parent`` has been free; one of the two
                   timers runs while the other is held at zero.
   :vartype air_time: float
   :ivar started: Whether the last step began a contact.
   :vartype started: bool
   :ivar ended: Whether the last step ended one.

   :vartype ended: bool


   .. py:attribute:: sensor_type
      :value: 'contact2d'



   .. py:attribute:: obj_id
      :value: 0



   .. py:attribute:: parent
      :type:  irsim.world.object_base.ObjectBase | None
      :value: None



   .. py:attribute:: force_scale


   .. py:attribute:: marker_size


   .. py:attribute:: linewidth


   .. py:attribute:: alpha


   .. py:attribute:: color


   .. py:attribute:: in_contact
      :value: False



   .. py:attribute:: partners
      :type:  list[Any]
      :value: []



   .. py:attribute:: records
      :type:  list[irsim.lib.algorithm.contact.Contact]
      :value: []



   .. py:attribute:: force


   .. py:attribute:: contact_time
      :value: 0.0



   .. py:attribute:: air_time
      :value: 0.0



   .. py:attribute:: started
      :value: False



   .. py:attribute:: ended
      :value: False



   .. py:property:: reports
      :type: list[irsim.lib.algorithm.contact.ContactReport]


      Last step's contacts seen from ``parent``'s side.


   .. py:method:: clear() -> None

      Forget last step's contacts: flag, partners, records and force.



   .. py:method:: reset() -> None

      Forget everything, the timers included, as at the start of a run.



   .. py:method:: add(contact: irsim.lib.algorithm.contact.Contact) -> None

      Record a contact the solver resolved against ``parent``.



   .. py:method:: add_force(force_xy: numpy.ndarray) -> None

      Accumulate a world-frame force ``(2,)`` or ``(2, 1)`` on ``parent``.



   .. py:method:: tick(step_time: float) -> None

      Advance ``contact_time`` or ``air_time`` by one step and raise
      ``started`` or ``ended`` for a step that switched between them.



   .. py:method:: step(state: numpy.ndarray) -> None

      Keep the sensor state; the readings are written by the contact step.



   .. py:method:: plot(ax, state: numpy.ndarray | None = None, **kwargs) -> None

      Draw the contact points and force lines on a given axis.

      Nothing is drawn on a 3D axis, since contacts are planar.



   .. py:method:: step_plot() -> None

      Move the markers and force lines to the last step's contacts.



   .. py:method:: plot_clear() -> None

      Remove the drawing from the axis.