irsim.world.map.fog_map
=======================

.. py:module:: irsim.world.map.fog_map


Classes
-------

.. autoapisummary::

   irsim.world.map.fog_map.FogMap


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

.. py:class:: FogMap(width: float = 10, height: float = 10, resolution: float = 0.1, world_offset: tuple[float, float] | list[float] | None = None)

   Bases: :py:obj:`irsim.world.map.Map`


   Fog-of-map overlay grid, built on :class:`Map`.

   Every cell starts *unexplored* (covered by fog). A robot's lidar reveals
   cells along each beam's line of sight, so the explored region grows as the
   robot navigates. The overlay is rendered as a grey layer that is opaque
   where unexplored and transparent where explored, so the underlying obstacle
   map shows through only once an area has been seen (free space appears white,
   obstacles black, the unknown stays grey).

   The explored mask is updated regardless of whether a display is active, so it
   is also usable headless as an exploration observation or coverage metric.

   Initialize the fog grid.

   :param width: Width of the world (metres) — matches the world it covers.
   :param height: Height of the world (metres).
   :param resolution: Fog cell size (metres/cell). Finer is smoother but
                      heavier; coarser is faster.
   :param world_offset: World origin ``(x, y)`` for cell indexing.

   :raises ValueError: If ``resolution`` is not positive and finite (it is
       user-configurable via ``fog_map_resolution``).


   .. py:attribute:: explored


   .. py:property:: shape
      :type: tuple[int, int]


      Grid shape ``(nx, ny)`` (cells along x and y).


   .. py:property:: explored_ratio
      :type: float


      Fraction of the world revealed so far, in ``[0, 1]``.


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

      Re-cover the whole world with fog.



   .. py:method:: reveal_from_lidar(origin: numpy.ndarray | list[float], angles: numpy.ndarray | list[float], ranges: numpy.ndarray | list[float]) -> None

      Reveal cells along each lidar beam's line of sight.

      :param origin: Lidar world pose ``[x, y, theta]`` (theta optional).
      :param angles: Per-beam angles in the lidar's local frame (radians).
      :param ranges: Per-beam measured ranges (metres), aligned with ``angles``.



   .. py:method:: reveal_fov(origin: numpy.ndarray | list[float], fov: float, fov_radius: float) -> None

      Reveal every cell within a field-of-view sector (no occlusion).

      Used when a sensing object has no lidar: each cell within ``fov_radius``
      of the origin and within ``±fov/2`` of the object's heading is revealed.

      :param origin: Object world pose ``[x, y, theta]`` (theta optional).
      :param fov: Full field-of-view angle in radians (``2*pi`` is a full circle).
      :param fov_radius: View range in metres.



   .. py:method:: to_rgba(color: tuple[float, float, float] = (0.78, 0.78, 0.8), alpha: float = 1.0) -> numpy.ndarray

      RGBA image of the fog for rendering.

      Unexplored cells get ``color`` at ``alpha`` (a soft light grey, opaque
      by default so the fog still fully hides the map until seen); explored
      cells are fully transparent so the underlying map shows through. Shape
      is ``(nx, ny, 4)`` (transpose the first two axes for ``imshow``).

      The buffer is allocated once and reused: the constant RGB channels are
      filled on the first call, and only the alpha channel is recomputed (the
      only thing that changes as cells are revealed).



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

      Remove the fog overlay artist.