maps#

Core mapping interface for quick visualization.

This module provides the main entry points for creating maps with sensible defaults and automatic performance optimization.

Functions#

show_geometry_context(, max_attrs, title, ...)

Plot any geometry type (Point, LineString, Polygon, and their Multi-

show_building(location, geodatasets[, styles, radius, ...])

Show building in its context with basemap

show_ingested_geometries(...)

Plot the last ingested layer for visual inspection.

show_random_entity(→ tuple[matplotlib.pyplot.Figure, ...)

Plot a random entity from the last ingested admin unit with its attributes.

Module Contents#

openplaces.viz.maps.show_geometry_context(gdf: geopandas.GeoDataFrame, idx: int | str, buffer_factor: float = 3.0, basemap_source: str = 'Esri.WorldImagery', figsize: tuple = (12, 8), max_attrs: int = 20, title: str = None, min_buffer_m: float = 25.0) → tuple[matplotlib.pyplot.Figure, tuple[matplotlib.pyplot.Axes, matplotlib.pyplot.Axes]]#

Plot any geometry type (Point, LineString, Polygon, and their Multi- variants) in geographic context with its attributes.

Parameters:

  • gdf (gpd.GeoDataFrame) – Source geodataframe.

  • idx (int or str) – Integer position or index label of the target feature.

  • buffer_factor (float) – Buffer size as a multiple of the feature’s maximum dimension. For point geometries (zero extent) the buffer is derived from min_buffer_m instead.

  • basemap_source (str) – Contextily basemap provider string.

  • figsize (tuple) – Figure size (width, height).

  • max_attrs (int) – Maximum number of attributes to display in the table.

  • title (str) – Overrides the default title (‘Feature {idx}’).

  • min_buffer_m (float) – Minimum plot half-width in metres, applied when the feature’s projected extent is smaller than this value (most relevant for point geometries). Default is 1 000 m.

Returns:

  • fig (matplotlib.figure.Figure)

  • ax_map, ax_table (matplotlib.axes.Axes)

openplaces.viz.maps.show_building(location, geodatasets, styles=None, radius=100, size=10, show_basemap=True, show_crosshair=True, show_location=True, return_fig_ax=False, verbose=False)#

Show building in its context with basemap

Parameters:

  • location (tuple or gpd.GeoDataFrame) – A single-row GeoDataFrame

  • geodatasets (dict of GeoDataFrames) – Loaded geodatasets to be plotted alongside location. The 'parcels' key is special: drawn with inner border and attribute text box at top-left. Any other key is treated as a building footprint or point GeoDataFrame — polygons are drawn as boundaries, points as markers, labels from available columns.

  • styles (dict of dict, optional) – Per-dataset style overrides, keyed by geodatasets keys. Supported sub-keys: ‘color’ (str), ‘n_max’ (int, default 4), ‘columns’ (list[str]), ‘marker’ (str, default ‘o’), ‘markersize’ (int, default 10).

  • radius (float) – Radius of plot in EPSG:3857 “meters” (~1.3m in NY)

  • size (float) – Size of plot in inches (both height and width of figsize)

  • show_basemap (bool) – If True, a basemap is added, and colors of parcels are adjusted.

  • show_crosshair (bool) – Display crosshair of the centerpoint

  • show_location (bool) – Display latitude/longitude of location

  • return_fig_ax (bool) – If True, return the plot’s Figure and Axes objects

  • verbose (bool) – If True, prints counts of matched entities per dataset.

openplaces.viz.maps.show_ingested_geometries(ingester, admin_recipe_id: str | None = None, fill: bool = True, color: str = 'skyblue', edgecolor: str = 'blue', point_markersize: float = 2, max_plot: int = 250000, basemap_source: str = 'Esri.WorldImagery', figsize: tuple = (10, 10)) → tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes] | None#

Plot the last ingested layer for visual inspection.

Reads entities and admin boundary from the ingester, applies a sample cap for large datasets, and renders a basemap.

Parameters:

  • ingester (openplaces.io.ingester.Ingester) – Completed ingester whose last saved admin unit is shown.

  • admin_recipe_id (str, optional) – Recipe ID for the admin boundary dataset. Auto-detected from the recipe’s admin_id when omitted.

  • fill (bool) – If True (default), fill polygon geometries. If False, draw boundary only.

  • color (str) – Fill color for polygons or face color for points.

  • edgecolor (str) – Edge/boundary color for polygons.

  • point_markersize (float) – Marker size when entities are points.

  • max_plot (int) – Maximum number of polygon features to render; a random sample is taken when exceeded.

  • basemap_source (str) – Contextily basemap provider string (e.g. ‘Esri.WorldImagery’).

  • figsize (tuple) – Figure size (width, height) in inches.

Returns:

fig, ax

Return type:

matplotlib Figure and Axes, or None if nothing to plot.

openplaces.viz.maps.show_random_entity(ingester) → tuple[matplotlib.pyplot.Figure, tuple[matplotlib.pyplot.Axes, matplotlib.pyplot.Axes]]#

Plot a random entity from the last ingested admin unit with its attributes.

Delegates to show_geometry_context().

Parameters:

ingester (openplaces.io.ingester.Ingester) – Completed ingester whose last saved admin unit is sampled.

Returns:

fig, (ax_map, ax_table)

Return type:

matplotlib Figure and Axes pair.