rsqsim_api.visualisation.utilities

Visualisation utilities for plotting New Zealand map backgrounds, coastlines, hillshading, and GIS vector layers.

Provides functions to clip and overlay the NZ coastline shapefile, render hillshade rasters, plot GIS line and polygon features (roads, rivers, lakes, regional boundaries, Hikurangi boundary), format WGS84 axis tick labels, and compose composite map backgrounds via plot_background.

Attributes

coast_shp_fine_name

coast_shp_coarse_name

coast_nat_earth_name

coast_shp_fine

coast_shp_coarse

coast_nat_earth

roads

lakes

rivers

regions

hk_boundary

niwa

min_x1

min_y1

max_x2

max_y2

min_x1_wgs

max_x2_wgs

min_y1_wgs

max_y2_wgs

Functions

clip_coast_with_trim(x1, y1, x2, y2[, wgs, coarse, fine])

Clip the NZ coastline to a bounding box and trim polygon boundaries.

clip_coast(x1, y1, x2, y2[, wgs, coarse, fine])

Clip the NZ coastline to a bounding box using coordinate indexing.

plot_gis_lines(gis_file, ax, color[, linewidth, ...])

Plot line features from a GIS vector file onto a matplotlib axis.

plot_gis_polygons(gis_file, ax, edgecolor[, ...])

Plot polygon features from a GIS vector file onto a matplotlib axis.

plot_highway_lines(ax[, color, linewidth, ...])

Overlay NZ state highway lines on a matplotlib axis.

plot_river_lines(ax[, color, linewidth, clip_bounds, ...])

Overlay NZ major river lines on a matplotlib axis.

plot_boundary_polygons(ax[, edgecolor, linewidth, ...])

Overlay NZ regional boundary polygons on a matplotlib axis.

plot_lake_polygons(ax[, edgecolor, linewidth, ...])

Overlay NZ lake polygons on a matplotlib axis.

plot_hk_boundary(ax[, edgecolor, linewidth, ...])

Overlay the Hikurangi subduction zone clipping-area polygon.

plot_coast(ax[, clip_boundary, edgecolor, facecolor, ...])

Overlay the NZ coastline on a matplotlib axis.

plot_hillshade(ax[, alpha, vertical_exaggeration, ...])

Overlay a hillshaded bathymetry/topography raster on a matplotlib axis.

plot_hillshade_niwa(ax[, alpha, ...])

Overlay a hillshaded NIWA NZTM raster on a matplotlib axis.

format_label_text_wgs(ax[, xspacing, yspacing, y_only])

Format axis tick labels as degree notation for WGS84 plots.

plot_background([figsize, hillshading_intensity, ...])

Compose a NZ map background figure with optional GIS overlays.

Module Contents

rsqsim_api.visualisation.utilities.coast_shp_fine_name = 'data/coastline/nz-coastlines-and-islands-polygons-topo-150k.shp'[source]
rsqsim_api.visualisation.utilities.coast_shp_coarse_name = 'data/coastline/nz-coastlines-and-islands-polygons-topo-1500k.shp'[source]
rsqsim_api.visualisation.utilities.coast_nat_earth_name = 'data/coastline/natural_earth_nztm.shp'[source]
rsqsim_api.visualisation.utilities.coast_shp_fine[source]
rsqsim_api.visualisation.utilities.coast_shp_coarse[source]
rsqsim_api.visualisation.utilities.coast_nat_earth[source]
rsqsim_api.visualisation.utilities.roads[source]
rsqsim_api.visualisation.utilities.lakes[source]
rsqsim_api.visualisation.utilities.rivers[source]
rsqsim_api.visualisation.utilities.regions[source]
rsqsim_api.visualisation.utilities.hk_boundary[source]
rsqsim_api.visualisation.utilities.niwa = ''[source]
rsqsim_api.visualisation.utilities.min_x1 = 800000[source]
rsqsim_api.visualisation.utilities.min_y1 = 4000000[source]
rsqsim_api.visualisation.utilities.max_x2 = 3200000[source]
rsqsim_api.visualisation.utilities.max_y2 = 7500000[source]
rsqsim_api.visualisation.utilities.min_x1_wgs = 160.0[source]
rsqsim_api.visualisation.utilities.max_x2_wgs = 185.0[source]
rsqsim_api.visualisation.utilities.min_y1_wgs = -51.0[source]
rsqsim_api.visualisation.utilities.max_y2_wgs = -33.0[source]
rsqsim_api.visualisation.utilities.clip_coast_with_trim(x1, y1, x2, y2, wgs=False, coarse=False, fine=False)[source]

Clip the NZ coastline to a bounding box and trim polygon boundaries.

Uses geopandas.clip to trim coastline polygons to the bounding box, then returns the individual polygon geometries.

Parameters:

  • x1 (int or float) – Bottom-left easting (NZTM metres, or longitude if wgs=True).

  • y1 (int or float) – Bottom-left northing (NZTM metres, or latitude if wgs=True).

  • x2 (int or float) – Top-right easting.

  • y2 (int or float) – Top-right northing.

  • wgs (bool, optional) – If True, interpret coordinates as WGS84 longitude/latitude. Defaults to False.

  • coarse (bool, optional) – If True, use the coarse Natural Earth coastline. Defaults to False.

  • fine (bool, optional) – If True, use the fine 150 k topo coastline. Defaults to False.

Returns:

Clipped coastline polygons in NZTM (EPSG:2193).

Return type:

geopandas.GeoSeries

rsqsim_api.visualisation.utilities.clip_coast(x1, y1, x2, y2, wgs=False, coarse=False, fine=False)[source]

Clip the NZ coastline to a bounding box using coordinate indexing.

Uses the cx indexer rather than geopandas.clip, so polygons that overlap the boundary are kept whole rather than trimmed.

Parameters:

  • x1 (int or float) – Bottom-left easting (NZTM metres, or longitude if wgs=True).

  • y1 (int or float) – Bottom-left northing (NZTM metres, or latitude if wgs=True).

  • x2 (int or float) – Top-right easting.

  • y2 (int or float) – Top-right northing.

  • wgs (bool, optional) – If True, interpret coordinates as WGS84 longitude/latitude. Defaults to False.

  • coarse (bool, optional) – If True, use the coarse Natural Earth coastline. Defaults to False.

  • fine (bool, optional) – If True, use the fine 150 k topo coastline. Defaults to False.

Returns:

Coastline polygons intersecting the bounding box, in NZTM.

Return type:

geopandas.GeoSeries

rsqsim_api.visualisation.utilities.plot_gis_lines(gis_file, ax, color, linewidth=0.3, clip_bounds=None, linestyle='-')[source]

Plot line features from a GIS vector file onto a matplotlib axis.

Parameters:

  • gis_file (str or pathlib.Path) – Path to the GIS file (shapefile, GeoPackage, etc.).

  • ax (matplotlib.axes.Axes) – Axis to draw onto.

  • color (str) – Line colour.

  • linewidth (int, optional) – Line width in points. Defaults to 0.3.

  • clip_bounds (list or None, optional) – [x_min, y_min, x_max, y_max] bounding box for clipping. If None, all features are plotted.

  • linestyle (str, optional) – Matplotlib line-style string. Defaults to "-".

rsqsim_api.visualisation.utilities.plot_gis_polygons(gis_file, ax, edgecolor, linewidth=0.3, clip_bounds=None, linestyle='-', facecolor='none')[source]

Plot polygon features from a GIS vector file onto a matplotlib axis.

Parameters:

  • gis_file (str or pathlib.Path) – Path to the GIS file (shapefile, GeoPackage, etc.).

  • ax (matplotlib.axes.Axes) – Axis to draw onto.

  • edgecolor (str) – Polygon edge colour.

  • linewidth (int, optional) – Edge line width in points. Defaults to 0.3.

  • clip_bounds (list or None, optional) – [x_min, y_min, x_max, y_max] bounding box for clipping. If None, all features are plotted.

  • linestyle (str, optional) – Matplotlib line-style string. Defaults to "-".

  • facecolor (str, optional) – Polygon fill colour. Defaults to "none" (transparent).

rsqsim_api.visualisation.utilities.plot_highway_lines(ax, color='r', linewidth=1.0, clip_bounds=None, linestyle='-')[source]

Overlay NZ state highway lines on a matplotlib axis.

Parameters:

  • ax (matplotlib.axes.Axes) – Axis to draw onto.

  • color (str, optional) – Line colour. Defaults to "r".

  • linewidth (int, optional) – Line width in points. Defaults to 1.

  • clip_bounds (list or None, optional) – [x_min, y_min, x_max, y_max] clipping bounds.

  • linestyle (str, optional) – Matplotlib line-style string. Defaults to "-".

rsqsim_api.visualisation.utilities.plot_river_lines(ax, color='b', linewidth=0.3, clip_bounds=None, linestyle='-')[source]

Overlay NZ major river lines on a matplotlib axis.

Parameters:

  • ax (matplotlib.axes.Axes) – Axis to draw onto.

  • color (str, optional) – Line colour. Defaults to "b".

  • linewidth (int, optional) – Line width in points. Defaults to 0.3.

  • clip_bounds (list or None, optional) – [x_min, y_min, x_max, y_max] clipping bounds.

  • linestyle (str, optional) – Matplotlib line-style string. Defaults to "-".

rsqsim_api.visualisation.utilities.plot_boundary_polygons(ax, edgecolor='k', linewidth=0.3, clip_bounds=None, linestyle='--', facecolor='none')[source]

Overlay NZ regional boundary polygons on a matplotlib axis.

Parameters:

  • ax (matplotlib.axes.Axes) – Axis to draw onto.

  • edgecolor (str, optional) – Edge colour. Defaults to "k".

  • linewidth (int, optional) – Edge line width in points. Defaults to 0.3.

  • clip_bounds (list or None, optional) – [x_min, y_min, x_max, y_max] clipping bounds.

  • linestyle (str, optional) – Matplotlib line-style string. Defaults to "--".

  • facecolor (str, optional) – Fill colour. Defaults to "none" (transparent).

rsqsim_api.visualisation.utilities.plot_lake_polygons(ax, edgecolor='b', linewidth=0.3, clip_bounds=None, linestyle='-', facecolor='b')[source]

Overlay NZ lake polygons on a matplotlib axis.

Parameters:

  • ax (matplotlib.axes.Axes) – Axis to draw onto.

  • edgecolor (str, optional) – Edge colour. Defaults to "b".

  • linewidth (int, optional) – Edge line width in points. Defaults to 0.3.

  • clip_bounds (list or None, optional) – [x_min, y_min, x_max, y_max] clipping bounds.

  • linestyle (str, optional) – Matplotlib line-style string. Defaults to "-".

  • facecolor (str, optional) – Fill colour. Defaults to "b" (blue).

rsqsim_api.visualisation.utilities.plot_hk_boundary(ax, edgecolor='r', linewidth=0.1, clip_bounds=None, linestyle='-', facecolor='0.8')[source]

Overlay the Hikurangi subduction zone clipping-area polygon.

Parameters:

  • ax (matplotlib.axes.Axes) – Axis to draw onto.

  • edgecolor (str, optional) – Edge colour. Defaults to "r".

  • linewidth (int, optional) – Edge line width in points. Defaults to 0.1.

  • clip_bounds (list or None, optional) – [x_min, y_min, x_max, y_max] clipping bounds.

  • linestyle (str, optional) – Matplotlib line-style string. Defaults to "-".

  • facecolor (str, optional) – Fill colour. Defaults to "0.8" (light grey).

rsqsim_api.visualisation.utilities.plot_coast(ax, clip_boundary=None, edgecolor='0.5', facecolor='none', linewidth=0.3, trim_polygons=True, wgs=False, coarse=False, fine=False)[source]

Overlay the NZ coastline on a matplotlib axis.

Parameters:

  • ax (matplotlib.axes.Axes) – Axis to draw onto.

  • clip_boundary (list or None, optional) – [x_min, y_min, x_max, y_max] clipping bounds. Defaults to the full NZ extent.

  • edgecolor (str, optional) – Coastline edge colour. Defaults to "0.5" (mid-grey).

  • facecolor (str, optional) – Land fill colour. Defaults to "none" (transparent).

  • linewidth (int, optional) – Edge line width. Defaults to 0.3.

  • trim_polygons (bool, optional) – If True (default), use clip_coast_with_trim() to trim polygons to the bounding box; otherwise use clip_coast().

  • wgs (bool, optional) – If True, use WGS84 (lon/lat) coordinates. Defaults to False.

  • coarse (bool, optional) – If True, use the coarse Natural Earth coastline. Defaults to False.

  • fine (bool, optional) – If True, use the fine 150 k topo coastline. Defaults to False.

Returns:

x1, y1, x2, y2 – The clipping bounds actually used.

Return type:

float

rsqsim_api.visualisation.utilities.plot_hillshade(ax, alpha=0.3, vertical_exaggeration=0.01, cmap=None, vmin=-10000.0, vmax=10000, clip_bounds=None)[source]

Overlay a hillshaded bathymetry/topography raster on a matplotlib axis.

Uses a combined 10 000-m resolution NIWA raster.

Parameters:

  • ax (matplotlib.axes.Axes) – Axis to draw onto.

  • alpha (float, optional) – Transparency of the hillshade overlay (0–1). Defaults to 0.3.

  • vertical_exaggeration (float, optional) – Vertical exaggeration for the light-source shading. Defaults to 0.01.

  • cmap (LinearSegmentedColormap or None, optional) – Colourmap for the hillshade. Defaults to plt.cm.gist_earth.

  • vmin (float, optional) – Minimum value for the colour scale. Defaults to -10 000.

  • vmax (float, optional) – Maximum value for the colour scale. Defaults to 10 000.

  • clip_bounds (list or None, optional) – [x_min, y_min, x_max, y_max] bounds for clipping the raster.

rsqsim_api.visualisation.utilities.plot_hillshade_niwa(ax, alpha=0.3, vertical_exaggeration=0.01, clip_bounds=None, cmap=None, vmin=-10000.0, vmax=10000)[source]

Overlay a hillshaded NIWA NZTM raster on a matplotlib axis.

Uses the high-resolution niwa_nztm.tif raster.

Parameters:

  • ax (matplotlib.axes.Axes) – Axis to draw onto.

  • alpha (float, optional) – Transparency of the hillshade overlay (0–1). Defaults to 0.3.

  • vertical_exaggeration (float, optional) – Vertical exaggeration for the light-source shading. Defaults to 0.01.

  • clip_bounds (list or None, optional) – [x_min, y_min, x_max, y_max] bounds for clipping the raster.

  • cmap (LinearSegmentedColormap or None, optional) – Colourmap for the hillshade. Defaults to plt.cm.terrain.

  • vmin (float, optional) – Minimum value for the colour scale. Defaults to -10 000.

  • vmax (float, optional) – Maximum value for the colour scale. Defaults to 10 000.

rsqsim_api.visualisation.utilities.format_label_text_wgs(ax, xspacing=5, yspacing=5, y_only=False)[source]

Format axis tick labels as degree notation for WGS84 plots.

Converts raw longitude/latitude tick values to degree strings, handling longitudes > 180° by converting to negative (west) values.

Parameters:

  • ax (matplotlib.axes.Axes) – Axis whose tick labels to format.

  • xspacing (int, optional) – Longitude tick spacing in degrees. Defaults to 5.

  • yspacing (int, optional) – Latitude tick spacing in degrees. Defaults to 5.

  • y_only (bool, optional) – If True, only format the y (latitude) axis. Defaults to False.

rsqsim_api.visualisation.utilities.plot_background(figsize=(6.4, 4.8), hillshading_intensity=0.0, bounds=None, plot_rivers=True, plot_lakes=True, hillshade_fine=False, plot_highways=True, plot_boundaries=False, subplots=None, pickle_name=None, hillshade_cmap=cm.terrain, plot_edge_label=True, plot_hk=False, plot_fault_outlines=True, wgs=False, land_color='antiquewhite', plot_sub_cbar=False, sub_slip_max=20.0, plot_crust_cbar=False, crust_slip_max=10.0, subduction_cmap=cm.plasma, crust_cmap=cm.viridis, slider_axis=False, aotearoa=True)[source]

Compose a NZ map background figure with optional GIS overlays.

Creates a subplot_mosaic figure with a main map panel and optional colourbar and slider axes. Overlays the coastline, optional hillshade, lakes, rivers, highways, regional boundaries, and/or the Hikurangi clipping area.

Parameters:

  • figsize (tuple, optional) – Figure size (width, height) in inches. Defaults to (6.4, 4.8).

  • hillshading_intensity (float, optional) – Hillshade alpha (0–1). If 0 (default), no hillshade is drawn.

  • bounds (tuple, optional) – (x_min, y_min, x_max, y_max) map bounds.

  • plot_rivers (bool, optional) – If True (default), overlay river lines.

  • plot_lakes (bool, optional) – If True (default), overlay lake polygons.

  • hillshade_fine (bool, optional) – If True, use the high-resolution NIWA hillshade raster. Defaults to False.

  • plot_highways (bool, optional) – If True (default), overlay state highway lines.

  • plot_boundaries (bool, optional) – If True, overlay regional boundary polygons. Defaults to False.

  • subplots (tuple or None, optional) – (fig, ax) to draw onto. A new figure is created if None.

  • pickle_name (str or None, optional) – If provided, pickle the (fig, ax) tuple to this path.

  • hillshade_cmap (LinearSegmentedColormap, optional) – Colourmap for the hillshade. Defaults to cm.terrain.

  • plot_edge_label (bool, optional) – If True (default), show axis tick labels.

  • plot_hk (bool, optional) – If True, overlay the Hikurangi clipping-area polygon. Defaults to False.

  • plot_fault_outlines (bool, optional) – Reserved for future use. Defaults to True.

  • wgs (bool, optional) – If True, use WGS84 coordinates. Defaults to False.

  • land_color (str, optional) – Land fill colour. Defaults to "antiquewhite".

  • plot_sub_cbar (bool, optional) – If True, add a subduction slip colourbar panel. Defaults to False.

  • sub_slip_max (float, optional) – Maximum subduction slip (m) for the colourbar. Defaults to 20.

  • plot_crust_cbar (bool, optional) – If True, add a crustal slip colourbar panel. Defaults to False.

  • crust_slip_max (float, optional) – Maximum crustal slip (m) for the colourbar. Defaults to 10.

  • subduction_cmap (LinearSegmentedColormap, optional) – Colourmap for the subduction colourbar. Defaults to cm.plasma.

  • crust_cmap (LinearSegmentedColormap, optional) – Colourmap for the crustal colourbar. Defaults to cm.viridis.

  • slider_axis (bool, optional) – If True, add a slider and year-label axes row. Defaults to False.

  • aotearoa (bool, optional) – If True (default), draw the NZ coastline and GIS overlays.

Returns:

  • fig (matplotlib.figure.Figure) – The composed figure.

  • ax (dict or matplotlib.axes.Axes) – Axis dict (from subplot_mosaic) or the provided ax.