Visualization API

viz

Visualization for EuroFlood: static (matplotlib) + interactive (folium).

Public entry points (also re-exported lazily from the top-level euroflood):

• plot / explore — dispatch on a FloodFrame, a depth GeoTIFF path, a list of paths, or a DepthRaster.
• plot_depth / explore_depth — render an already-downloaded depth raster (no download).
• open_depth — wrap a depth GeoTIFF as a DepthRaster.

The default view for a historic FloodFrame is the cheap flood-recurrence heatmap (no download). The depth raster — which requires downloading tiles — is opt-in via depth=True and guarded by a row-count cap.

All heavy imports (matplotlib/folium) are lazy; without the viz extra any entry point raises a friendly pip install "euroflood[viz]" error.

Classes:

Name	Description
DepthRaster	A downloaded flood-depth GeoTIFF with plot/explore/read/save helpers.

Functions:

Name	Description
plot	Static plot dispatching on a frame, a depth path/list, or a DepthRaster.
explore	Interactive map dispatching on a frame, a depth path/list, or a DepthRaster.
footprints	Per-event flood extents from the index (one dissolved polygon per event).
plot_depth	Plot a downloaded flood-depth GeoTIFF (metres) with a colorbar.
explore_depth	Interactive flood-depth map: an ImageOverlay + legend on a toggleable basemap.
open_depth	Wrap an already-downloaded depth GeoTIFF as a DepthRaster.

Classes

DepthRaster dataclass

DepthRaster(path: Path)

A downloaded flood-depth GeoTIFF with plot/explore/read/save helpers.

Methods:

Name	Description
read	Read the raster into (array, transform, crs, nodata).
plot	Static depth plot (matplotlib Axes).
explore	Interactive depth map (folium.Map).
save	Render and save to .png (static) or .html (interactive).

Methods:

read

read() -> tuple[Any, Any, Any, float | None]

Read the raster into (array, transform, crs, nodata).

plot

plot(**kwargs: Any) -> Any

Static depth plot (matplotlib Axes).

explore

explore(**kwargs: Any) -> Any

Interactive depth map (folium.Map).

save

save(out: str | Path) -> Path

Render and save to .png (static) or .html (interactive).

Functions:

plot

plot(obj: Any, **kwargs: Any) -> Any

Static plot dispatching on a frame, a depth path/list, or a DepthRaster.

explore

explore(obj: Any, **kwargs: Any) -> Any

Interactive map dispatching on a frame, a depth path/list, or a DepthRaster.

footprints

footprints(frame: Any) -> Any

Per-event flood extents from the index (one dissolved polygon per event).

Replaces the catalogue's shared ROI geometry with each event's actual footprint — the union of ROI pixels whose combo_id includes that event — and adds an extent_km2 column. No rasters are downloaded; the extent is the ~90 m index presence mask, i.e. an approximate footprint.

Parameters:

Name	Type	Description	Default
frame	Any	A historic FloodFrame.	required

Returns:

Type	Description
Any	A plain geopandas.GeoDataFrame (EPSG:4326), date-sorted, with the
Any	catalogue's metadata, a per-event geometry, extent_km2 (the area
Any	within the queried view — the footprint is clipped to the ROI), and
Any	duration_days (event length, when end_date is available).

Raises:

Type	Description
VisualizationError	For an empty or hazard catalogue (no combo index).

plot_depth

plot_depth(
    path: str | Path,
    *,
    ax: Any = None,
    cmap: str | None = None,
    vmax: float | None = None,
    scale: float = 0.01,
    basemap: bool = False,
    tiles: str = "OpenStreetMap",
    title: str | None = None,
    **kwargs: Any
) -> Any

Plot a downloaded flood-depth GeoTIFF (metres) with a colorbar.

Parameters:

Name	Type	Description	Default
path	str | Path	A downloaded depth GeoTIFF.	required
ax	Any	An existing Axes to draw on (a new figure/axes is made if None).	None
cmap	str | None	Colormap name (default "Blues").	None
vmax	float | None	Upper depth bound; defaults to the image's max depth (full range).	None
scale	float	Multiplier applied to the raster values. EFAS depth is stored in centimetres, so the default 0.01 converts to metres; pass 1.0 for a raster already in metres.	0.01
basemap	bool	Add a contextily basemap (needs network); default off.	False
tiles	str	Basemap style when basemap=True (e.g. "grayscale").	'OpenStreetMap'
title	str | None	Plot title.	None
**kwargs	Any	Forwarded to ax.imshow.	{}

Returns:

Type	Description
Any	The matplotlib Axes.

explore_depth

explore_depth(
    path: str | Path,
    *,
    cmap: str | None = None,
    vmax: float | None = None,
    scale: float = 0.01,
    opacity: float = 0.8,
    tiles: str = "OpenStreetMap",
    boundary_geom: Any = None,
    **kwargs: Any
) -> Any

Interactive flood-depth map: an ImageOverlay + legend on a toggleable basemap.

Depth is shown in metres (EFAS values are centimetres, so scale defaults to 0.01; pass 1.0 for a metres raster). boundary_geom (a shapely geometry) adds a toggleable query-area outline. Returns a folium.Map.

open_depth

open_depth(path: str | Path) -> DepthRaster

Wrap an already-downloaded depth GeoTIFF as a DepthRaster.