pipeworks_mud_mapper.layout.map_panel
=====================================

.. py:module:: pipeworks_mud_mapper.layout.map_panel

.. autoapi-nested-parse::

   Map panel component for the center column.

   The map panel displays the interactive Plotly visualization of rooms
   and exits, along with filter controls for showing/hiding Z-levels.

   The flattened view displays all rooms on a single 2D plane regardless
   of their Z coordinate, with visual differentiation by level:

   - **z=-1 (Down)**: Black filled circles (smallest)
   - **z=0 (Ground)**: Blue filled circles (largest)
   - **z=+1 (Up)**: White circles with black border (medium)

   Component Structure
   -------------------
   ::

       ┌─────────────────────────────────────────┐
       │                                         │
       │        ●───────●     ◐                  │
       │        │       │     │                  │
       │        ●───────●─────●   Plotly map     │
       │                ⬤                        │
       │                                         │
       ├─────────────────────────────────────────┤
       │ Show Layers: ☑ Down  ☑ Ground  ☑ Up   │
       └─────────────────────────────────────────┘

   Component IDs
   -------------
   - ``map-graph``: Plotly Graph component for room visualization
   - ``z-level-filter``: Checklist for filtering which Z-levels to display

   Filter Behavior
   ---------------
   All levels are shown by default (all checkboxes checked). Unchecking a
   level hides rooms at that Z coordinate. This is useful for:

   - Reducing visual clutter when working on a single floor
   - Selecting stacked rooms (hide upper levels to click lower ones)
   - Focusing on specific areas of the map

   .. seealso:: :py:obj:`-`, :py:obj:`-`



Functions
---------

.. autoapisummary::

   pipeworks_mud_mapper.layout.map_panel.create_map_panel


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

.. py:function:: create_map_panel()

   Create the center column map panel component.

   The map panel contains:

   - Plotly Graph component for room visualization (flattened multi-level view)
   - Z-level filter checkboxes for showing/hiding each level

   :returns: * :py:class:`dbc.Card` -- Bootstrap Card containing the map and layer filter controls.
             * :py:class:`Component IDs`
             * :py:class:`-------------`
             * **- ``map-graph``** (:py:class:`Plotly Graph for map visualization`)
             * **- ``z-level-filter``** (:py:class:`Checklist for filtering visible Z-levels`)
             * :py:class:`Visual Indicators`
             * :py:class:`-----------------`
             * :py:class:`The filter checkboxes include colored circles matching the room styling`
             * **- **Down (z=-1)**** (:py:class:`Small black circle`)
             * **- **Ground (z=0)**** (:py:class:`Medium blue circle`)
             * **- **Up (z=+1)**** (:py:class:`Medium white circle with black border`)

   .. admonition:: Notes

      - Map displays all Z-levels by default (flattened view)
      - Uncheck a level to hide rooms at that Z coordinate
      - Rooms are rendered in Z-order: down first, then up, then ground on top
      - Ground level rooms receive clicks first when stacked
      - To select a lower-level room, temporarily uncheck higher levels
      - Scroll zoom and pan are enabled via Graph config
      - Lasso and select tools are removed from mode bar

   .. admonition:: Examples

      The map panel is typically used within the main layout::
      
          >>> from pipeworks_mud_mapper.layout.map_panel import create_map_panel
          >>> panel = create_map_panel()
          >>> # Panel contains 'map-graph' and 'z-level-filter' components