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_building_imagery(location, geodatasets, ...[, ...])

Show a building's context map alongside its downloaded imagery.

show_ingested_geometries(...)

Plot the last ingested layer for visual inspection.

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

Plot a random entity from an admin unit's output 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, ax=None, 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

  • ax (matplotlib.axes.Axes, optional) – Axis to draw into. If None, a new figure and axis are created. When provided, the building is drawn into this axis (and its parent figure), which lets callers compose the context map alongside other panels.

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

openplaces.viz.maps.show_building_imagery(location, geodatasets, image_recipes, admin_id, styles=None, radius=100, size=6, return_fig_axes=False, verbose=False, **show_building_kwargs)#

Show a building’s context map alongside its downloaded imagery.

A diagnostics variant of show_building(): the first panel draws the building in context (delegating to show_building), and one panel per image recipe displays the downloaded image for that building (e.g. Google Satellite and Street View), or a placeholder when no image was downloaded.

Parameters:

  • location (gpd.GeoDataFrame) – Single-row GeoDataFrame for the building. Its index label is used to look up the building’s images in each image recipe’s metadata.

  • geodatasets (dict of GeoDataFrames) – Reference datasets for the context panel, passed to show_building.

  • image_recipes (dict) – Mapping of panel label to image recipe ID, e.g. {'Google Satellite': 'image-googlesatellite-z20', 'Street View': 'image-googlestreetview-2026'}.

  • admin_id (str or AdminId) – Admin unit whose image metadata is loaded.

  • styles (dict of dict, optional) – Per-dataset style overrides forwarded to show_building.

  • radius (float) – Radius of the context panel in EPSG:3857 “meters”.

  • size (float) – Height of the figure in inches (each panel is roughly square).

  • return_fig_axes (bool) – If True, return the figure and the array of axes.

  • verbose (bool) – If True, prints counts of matched entities in the context panel.

  • **show_building_kwargs – Additional keyword arguments forwarded to show_building.

Returns:

(fig, axes) when return_fig_axes is True.

Return type:

tuple, optional

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(recipe: dict, admin_id, partition_id: str | None = None) → tuple[matplotlib.pyplot.Figure, tuple[matplotlib.pyplot.Axes, matplotlib.pyplot.Axes]] | None#

Plot a random entity from an admin unit’s output with its attributes.

Delegates to show_geometry_context().

Parameters:

  • recipe (dict) – Recipe whose saved output should be sampled.

  • admin_id (AdminId or str) – Admin unit whose output file to sample from.

  • partition_id (str, optional) – Partition to read, if the recipe’s output is partitioned.

Returns:

fig, (ax_map, ax_table) – recipe’s output has no geometry to plot.

Return type:

matplotlib Figure and Axes pair, or None if the