sidescanpy.viz.basemap

Land/water context for georeferenced plots.

Two things live here: a background layer (land/water fill) to draw behind an already-projected plot (a gridded raster, a survey track), and a small standalone locator thumbnail (zoomed way out, with a marker showing where the main plot sits) — “where is this, relative to the coast.” Neither one interprets or corrects backscatter; this is orientation context only.

Land geometry comes from a vendored 1:50m Natural Earth shapefile (assets/natural_earth/, public domain) — coarse by design (a coastline resolves as a smooth simplified outline, not a survey-scale shoreline). Good enough to tell “near land” from “open water” and to place a survey on a regional map; not a substitute for real chart data at sidescan survey scales (tens to thousands of meters). See that directory’s own README for provenance/regeneration.

Requires the optional maps extra (cartopy) — every function here raises ImportError with a clear message if it isn’t installed, rather than silently skipping the background (which could be mistaken for “there’s no land nearby”).

2026 rshomberg@uri.edu

Contents

add_land_background	Fill ax with a water color, draw land polygons on top of it, and set the axes' data limits to bbox (plus a margin) -- meant to be called before the caller's own real data is plotted at a higher zorder, so land/water sits behind it.
plot_locator_thumbnail	Land/water context zoomed out to roughly region_km across, centered on (center_lon, center_lat), with a red marker showing where the "real" plot (a gridded segment, a survey track) sits within that region -- "where is this, relative to the coast."

sidescanpy.viz.basemap.add_land_background(ax, bbox, crs, *, land_color='#ddd2ba', water_color='#cfe3ec', zorder=0, margin_frac=0.08)

Fill ax with a water color, draw land polygons on top of it, and set the axes’ data limits to bbox (plus a margin) – meant to be called before the caller’s own real data is plotted at a higher zorder, so land/water sits behind it.

Parameters:

axmatplotlib.axes.Axes

bbox(south, west, north, east)

In crs’s own units – matches sidescanpy.grids.raster.SideScanGriddedRaster.bbox’s own convention directly. Degrees for a geographic CRS, meters for a projected one (e.g. UTM).

crspyproj.CRS

The CRS ax’s existing data (if any) is already plotted in.

margin_fracfloat, default 0.08

Extra margin around bbox, as a fraction of its own height/width, so land right at the requested edge doesn’t look abruptly clipped.

sidescanpy.viz.basemap.plot_locator_thumbnail(center_lon, center_lat, *, region_km=50.0, mark_bbox_wgs84=None, fig=None, ax=None, figsize=(2.4, 2.4))

Land/water context zoomed out to roughly region_km across, centered on (center_lon, center_lat), with a red marker showing where the “real” plot (a gridded segment, a survey track) sits within that region – “where is this, relative to the coast.”

Draws into ax if given (e.g. an inset axes embedded in a larger figure via fig.add_axes([...])/ax.inset_axes([...]) – matches this module’s usual fig=None, ax=None convention), or creates its own small standalone figure otherwise.

Parameters:

center_lon, center_latfloat

WGS84 degrees – typically the survey/segment’s own centroid.

region_kmfloat, default 50.0

Approximate width/height of the thumbnail’s own view, in kilometers (converted to degrees locally via a flat-earth approximation – fine at this zoomed-out, orientation-only scale, not meant for precise measurement).

mark_bbox_wgs84(west, south, east, north), optional

The real plot’s own extent, drawn as a red box. If it would be too small to see at this thumbnail’s scale, a red dot is drawn at its center instead (a box a fraction of a pixel wide is indistinguishable from nothing, not from “precisely located”).

fig, axoptional

Existing figure/axes to draw into.

figsize(float, float), default (2.4, 2.4)

Figure size in inches, only used when creating a new figure.

Returns:

fig, ax