pipeworks_mud_mapper.callbacks.map_callbacks

Map visualization and interaction callbacks.

This module handles:

  • Rendering the flattened map when zone data or visibility filter changes

  • Selecting rooms when clicked on the map

The map displays all Z-levels on a single 2D plane with visual differentiation:

  • z=-1 (Down): Black filled circles (smallest)

  • z=0 (Ground): Blue filled circles (largest)

  • z=+1 (Up): White circles with black border (medium)

Component Dependencies

Inputs:

  • current-zone-data: Zone data for rendering

  • z-level-filter: List of visible Z-levels (checklist)

  • selected-room: Currently selected room

  • map-graph: Click events on the map

Outputs:

  • map-graph: Updated Plotly figure

  • selected-room: Room ID from click

Click Selection with Stacked Rooms

When rooms overlap (same X,Y, different Z), ground level (z=0) receives clicks first due to render order. To select a lower-level room:

  1. Uncheck higher levels in the z-level-filter

  2. Click the now-visible lower-level room

  3. Re-check levels when done

See also

-, -

Functions

update_map_with_rooms(zone_data, visible_z_levels, ...)

Update the map figure when zone data, visibility, or selection changes.

handle_map_click(click_data, zone_data, current_selection)

Select a room when clicked, or unselect if clicking the same room again.

adjust_z_level_offset_x(decrease_clicks, ...)

Adjust the X-axis visual offset via +/- buttons.

adjust_z_level_offset_y(decrease_clicks, ...)

Adjust the Y-axis visual offset via +/- buttons.

Module Contents

pipeworks_mud_mapper.callbacks.map_callbacks.update_map_with_rooms(zone_data, visible_z_levels, selected_room, visual_offset_x, visual_offset_y)[source]

Update the map figure when zone data, visibility, or selection changes.

Re-renders the Plotly figure with rooms from all visible Z-levels, displayed on a single 2D plane with visual differentiation by level.

Parameters:

  • zone_data (dict | None) – Current zone data containing rooms, or None if no zone loaded.

  • visible_z_levels (list[int]) – List of Z-levels to display, from the filter checklist. Default is all levels: [-1, 0, 1]. Empty list shows base map only.

  • selected_room (str | None) – Currently selected room ID, or None. Selected room is highlighted in red regardless of its Z-level.

  • visual_offset_x (float | None) – X-axis scale factor for Z-level visual offset. Controls horizontal separation of stacked rooms.

  • visual_offset_y (float | None) – Y-axis scale factor for Z-level visual offset. Controls vertical separation of stacked rooms.

Returns:

  • dict – Plotly figure dictionary for the map graph.

  • Rendering Behavior

  • ------------------

  • - Rooms are rendered in Z-order (z=-1 first, z=+1 second, z=0 last)

  • - Ground level (z=0) appears on top and receives clicks first

  • - Exit lines only connect rooms on the same Z-level

    • Vertical exits (up/down) are shown as "U/D" labels near stacked rooms

  • - Cross-zone exits are shown as triangle markers near the source room

  • - Hover text includes Z-level information for each room

Return type:

Any

Examples

Show all levels (default):

>>> figure = update_map_with_rooms(zone_data, [-1, 0, 1], None, 1.0)

Show only ground level:

>>> figure = update_map_with_rooms(zone_data, [0], None, 1.0)

Hide ground to select a basement room:

>>> figure = update_map_with_rooms(zone_data, [-1, 1], "cellar", 1.0)
pipeworks_mud_mapper.callbacks.map_callbacks.handle_map_click(click_data, zone_data, current_selection)[source]

Select a room when clicked, or unselect if clicking the same room again.

Extracts the room ID from the clicked point’s text field and validates that it exists in the current zone. Clicking on an already-selected room toggles the selection off.

Parameters:

  • click_data (dict | None) – Plotly click event data containing information about the clicked point, or None if no click occurred.

  • zone_data (dict | None) – Current zone data containing rooms dictionary.

  • current_selection (str | None) – Currently selected room ID, used for toggle behavior.

Returns:

  • str | None | no_update – Room ID if a new room was clicked, None if the same room was clicked again (toggle off), or no_update if the click was on a non-room element like an exit line.

  • Click Handling Details

  • ----------------------

  • - Room ID is stored in the ``text` field` of Scatter points

  • - Clicking an already-selected room clears the selection (toggle)

  • - Clicks on exit lines return no_update (hoverinfo=``”skip”``)

  • - Invalid room IDs (not in zone_data) return no_update

  • Stacked Room Selection

  • ----------------------

  • When rooms are stacked (same X,Y, different Z), the topmost visible

  • room receives the click. Due to render order

  • - If z=0 is visible, ground-level room gets the click

  • - If z=0 is hidden but z=+1 visible, upper-level room gets the click

  • - If only z=-1 is visible, lower-level room gets the click

  • To select a specific stacked room, use the z-level-filter to hide

  • the levels above it.

Return type:

Any

Examples

Click data structure from Plotly:

>>> click_data = {
...     "points": [{
...         "x": 0,
...         "y": 0,
...         "text": "spawn",  # Room ID
...         "curveNumber": 2,
...     }]
... }
>>> handle_map_click(click_data, zone_data, None)
'spawn'

Click same room again to unselect:

>>> handle_map_click(click_data, zone_data, "spawn")
None
pipeworks_mud_mapper.callbacks.map_callbacks.adjust_z_level_offset_x(decrease_clicks, increase_clicks, current_value)[source]

Adjust the X-axis visual offset via +/- buttons.

pipeworks_mud_mapper.callbacks.map_callbacks.adjust_z_level_offset_y(decrease_clicks, increase_clicks, current_value)[source]

Adjust the Y-axis visual offset via +/- buttons.