Map View

Map view components for the UI Generator framework.

This module provides geospatial visualization capabilities through the MapView class, enabling the display of location-based data on interactive maps. Map views support both individual location markers and connected route visualizations with rich customization options.

Map views transform geographic coordinate data into interactive visual representations, allowing users to explore spatial relationships, track movement patterns, and analyze location-based information intuitively.

Classes:

MapType: Enum defining LOCATION and ROUTE map types
MarkerInteraction: Configuration for marker hover and click behavior
MapConfig: Base configuration class for map views
LocationConfig: Configuration specific to LOCATION map type
RouteConfig: Configuration specific to ROUTE map type
PlaybackConfig: Configuration for route playback animation
MapView: Complete map view with geographic visualization

Example:

>>> # Define the data source for store locations
>>> stores_table = Table("store_locations")
>>> lat_field = Field("latitude", DataType.DECIMAL)
>>> lng_field = Field("longitude", DataType.DECIMAL)
>>> name_field = Field("store_name", DataType.STRING)
>>>
>>> # Create a location map view
>>> builder = UiBuilder()
>>> map_view = builder.add_location_view(
...     table=stores_table,
...     latitude=lat_field,
...     longitude=lng_field,
...     display_name="Store Locations"
... )
>>>
>>> # Customize the map
>>> map_view.set_name(name_field)
>>> map_view.set_colour(Field("region_color", DataType.STRING))
>>> map_view.set_editable(True)
>>>
>>> # Add marker interaction
>>> from daitum_ui.elements import Card
>>> info_card = Card(...)
>>> map_view.set_marker_behaviour(info_card)
>>>
>>> # Example: Create a route map for deliveries
>>> routes_table = Table("delivery_routes")
>>> route_lat = Field("waypoint_lat", DataType.DECIMAL_ARRAY)
>>> route_lng = Field("waypoint_lng", DataType.DECIMAL_ARRAY)
>>>
>>> route_view = builder.add_route_view(
...     table=routes_table,
...     latitude=route_lat,
...     longitude=route_lng,
...     display_name="Delivery Routes"
... )
>>>
>>> # Configure route-specific features
>>> route_view.set_date_time(Field("timestamps", DataType.DATETIME_ARRAY))
>>> route_view.set_collapse_markers(True)
>>> route_view.set_start_location_icon(Field("start_icon", DataType.STRING))
>>> route_view.set_end_location_icon(Field("end_icon", DataType.STRING))

class MapView(table, map_type, latitude, longitude)[source]

Bases: BaseView, FilterableView

Represents a map view for visualising either locations or routes.

source_table

ID of the source table containing the data.

Type:: str

map_type

Type of map (ROUTE or LOCATION).

Type:: MapType

config

Configuration object specific to the map type.

Type:: MapConfig

set_display_name(display_name)[source]

Sets the display name for this map view.

Return type:: MapView

set_hidden(hidden)[source]

Sets whether this map view is hidden.

Return type:: MapView

set_use_filter(use_filter)[source]

Attaches a filter component to this map view.

Return type:: MapView

set_marker_behaviour(card, on_click=None)[source]

Sets the marker interaction behaviour for the map view.

Parameters:

card (Card) – The card to display when interacting with a marker.
on_click (ModelEvent | None) – Event to trigger on marker click.

set_colour(colour)[source]

Sets the colour column for the map view.

Parameters:: colour (Field) – The field to use for colouring map elements.

set_name(name)[source]

Sets the name column for the map view.

Parameters:: name (Field) – The field to use for naming map elements.

set_editable(editable)[source]

Sets whether the map view is editable. Only applicable for LOCATION map type.

Parameters:: editable (bool) – True to make the map editable, False otherwise.

set_start_location_icon(start_location_icon)[source]

Sets the start location icon for the route.

Parameters:

start_location_icon (Field) – The field containing the icon to display as the start
location.

set_end_location_icon(end_location_icon)[source]

Sets the end location icon for the route.

Parameters:: end_location_icon (Field) – The field containing the icon to display as the end location.

set_marker_name(marker_name)[source]

Sets the marker name.

Parameters:: marker_name (Field) – The field containing the marker name.

set_resource(resource)[source]

Sets the resource.

Parameters:: resource (Field) – The field containing the resource.

set_resource_icon(resource_icon)[source]

Sets the resource icon.

Parameters:: resource_icon (Field) – The field containing the icon to display for resources. For ROUTE map type, accepts STRING or STRING_ARRAY.

set_date_time(date_time)[source]

Sets the date-time for markers on a route view.

set_collapse_markers(collapse_markers)[source]

Sets whether to collapse markers on the map view. Only applicable for ROUTE map type.

set_detailed_route_overview(detailed_route_overview)[source]

Sets whether to show detailed road-following routes.

Parameters:: detailed_route_overview (bool) – True for detailed routes, False for simplified.

set_work_duration(work_duration)[source]

Sets the work/service duration column per waypoint.

Parameters:: work_duration (Field) – The field containing work duration values (DECIMAL_ARRAY, hours).

set_job_id(job_id)[source]

Sets the job/visit identifier column per waypoint.

Parameters:: job_id (Field) – The field containing job identifiers (STRING_ARRAY).

set_playback_icon(playback_icon)[source]

Sets the icon for the playback position marker.

Parameters:: playback_icon (Field) – The field containing the icon identifier (STRING).

set_wait_time(wait_time)[source]

Sets the model-provided wait time column per waypoint.

Parameters:: wait_time (Field) – The field containing wait time values (DECIMAL_ARRAY, hours).

set_travel_time(travel_time)[source]

Sets the model-provided travel time column per waypoint.

Parameters:: travel_time (Field) – The field containing travel time values (DECIMAL_ARRAY, hours).

set_travel_distance(travel_distance)[source]

Sets the model-provided travel distance column per waypoint.

Parameters:: travel_distance (Field) – The field containing travel distance values (DECIMAL_ARRAY, km).

set_travel_time_is_to_waypoint(travel_time_is_to_waypoint)[source]

Sets how travel time and distance arrays are indexed.

Parameters:: travel_time_is_to_waypoint (bool) – When False (default), array[i] is the value for the leg departing FROM waypoint i. When True, array[i] is the value for the leg arriving AT waypoint i.

enable_playback(playback_duration=None, playback_start_time=None, playback_end_time=None, metric_labels=None, show_all_routes=True)[source]

Enables playback animation for this route view.

Parameters:

playback_duration (Calculation | Parameter | None) – Named value providing the total playback duration in seconds.
playback_start_time (Calculation | Parameter | None) – Named value providing the playback start time.
playback_end_time (Calculation | Parameter | None) – Named value providing the playback end time.
metric_labels (dict[str, str] | None) – Configurable labels for the metrics summary box.
show_all_routes (bool) – Whether to show all route polylines fully from the start of playback. Default is True.

class LocationConfig(latitude_column, longitude_column, colour_column=None, name_column=None, marker_interaction=None, start_location_icon_column=None, end_location_icon_column=None, resource_icon_column=None, editable=False)[source]

Bases: MapConfig

Configuration for LOCATION map type.

editable

Whether the map points are editable by the user.

Type:: bool

editable: bool = False

class MapConfig(latitude_column, longitude_column, colour_column=None, name_column=None, marker_interaction=None, start_location_icon_column=None, end_location_icon_column=None, resource_icon_column=None)[source]

Bases: ABC, Buildable

Base configuration for map views.

latitude_column

Field representing latitude values.

Type:: str

longitude_column

Field representing longitude values.

Type:: str

colour_column

Field used to colour map elements.

Type:: Optional[str]

name_column

Field used to name map elements.

Type:: Optional[str]

latitude_column: str

longitude_column: str

colour_column: str | None = None

name_column: str | None = None

marker_interaction: MarkerInteraction | None = None

start_location_icon_column: str | None = None

end_location_icon_column: str | None = None

resource_icon_column: str | None = None

class MapType(*values)[source]

Bases: Enum

Defines the type of map view to be displayed.

ROUTE: Displays routes between locations, showing connections and paths.

LOCATION: Displays individual locations or waypoints without showing routes between them.

ROUTE = 'ROUTE'

LOCATION = 'LOCATION'

class MarkerInteraction(hover_card, on_click=None)[source]

Bases: ABC, Buildable

Defines the interaction behaviour for map markers.

hover_card

Card to display on marker hover or click.

Type:: Card

on_click

Event to trigger on marker click.

Type:: Optional[ModelEvent]

hover_card: Card

on_click: ModelEvent | None = None

class PlaybackConfig(enabled=False, playback_duration_ref=None, playback_start_time_ref=None, playback_end_time_ref=None, metric_labels=None, show_all_routes=True)[source]

Bases: Buildable

Configuration for route playback animation.

enabled

Whether playback is enabled for this route view.

Type:: bool

playback_duration_ref

Reference to a named value providing the total playback duration in seconds.

Type:: Optional[str]

playback_start_time_ref

Reference to a named value providing the playback start time.

Type:: Optional[str]

playback_end_time_ref

Reference to a named value providing the playback end time.

Type:: Optional[str]

metric_labels

Configurable labels for the metrics summary box.

Type:: Optional[dict[str, str]]

show_all_routes

Whether to show travel markers for all routes from the start of playback.

Type:: bool

enabled: bool = False

playback_duration_ref: str | None = None

playback_start_time_ref: str | None = None

playback_end_time_ref: str | None = None

metric_labels: dict[str, str] | None = None

show_all_routes: bool = True

class RouteConfig(latitude_column, longitude_column, colour_column=None, name_column=None, marker_interaction=None, start_location_icon_column=None, end_location_icon_column=None, resource_icon_column=None, date_time_column=None, marker_name_column=None, resource_column=None, collapse_markers=True, detailed_route_overview=None, work_duration_column=None, job_id_column=None, playback_icon_column=None, wait_time_column=None, travel_time_column=None, travel_distance_column=None, travel_time_is_to_waypoint=False, playback_config=None)[source]

Bases: MapConfig

Configuration for ROUTE map type.

date_time_column

Field containing datetime values for routes.

Type:: Optional[str]

marker_name_column

Field containing marker names for tooltips.

Type:: Optional[str]

resource_column

Field containing route resource identifiers.

Type:: Optional[str]

collapse_markers

Whether markers should be collapsed on the map.

Type:: bool

detailed_route_overview

Whether to show detailed road-following routes (True) or simplified straight lines (False). None defers to frontend default.

Type:: Optional[bool]

work_duration_column

Field containing work/service duration per waypoint (DECIMAL_ARRAY, hours).

Type:: Optional[str]

job_id_column

Field containing job/visit identifiers per waypoint (STRING_ARRAY).

Type:: Optional[str]

playback_icon_column

Field containing an icon identifier for the playback position marker (STRING).

Type:: Optional[str]

wait_time_column

Field containing model-provided wait time per waypoint (DECIMAL_ARRAY, hours).

Type:: Optional[str]

travel_time_column

Field containing model-provided travel time per waypoint (DECIMAL_ARRAY, hours).

Type:: Optional[str]

travel_distance_column

Field containing model-provided travel distance per waypoint (DECIMAL_ARRAY, km).

Type:: Optional[str]

travel_time_is_to_waypoint

Controls how travel time/distance arrays are indexed. When False (default), array[i] is the value for the leg departing FROM waypoint i. When True, array[i] is the value for the leg arriving AT waypoint i.

Type:: bool

playback_config

Playback animation configuration. If None, playback UI is hidden.

Type:: Optional[PlaybackConfig]

date_time_column: str | None = None

marker_name_column: str | None = None

resource_column: str | None = None

collapse_markers: bool = True

detailed_route_overview: bool | None = None

work_duration_column: str | None = None

job_id_column: str | None = None

playback_icon_column: str | None = None

wait_time_column: str | None = None

travel_time_column: str | None = None

travel_distance_column: str | None = None

travel_time_is_to_waypoint: bool = False

playback_config: PlaybackConfig | None = None