sidescanpy.viz.gridded

Plot a gridded raster (SideScanGriddedRaster).

plot_gridded_raster() draws one raster on one Axes and returns (fig, ax); plot_grid_coverage() draws the same raster with each cell’s opacity set by how many samples fell in it. Comparisons of several rasters are the caller’s layout (see the Grid to a map example).

2026 rshomberg@uri.edu

Contents

plot_gridded_raster	Plot a gridded raster as a 2D heatmap.
plot_grid_coverage	Plot a gridded raster with each cell's opacity set by its sample count.

sidescanpy.viz.gridded.plot_gridded_raster(raster, fig=None, ax=None, cmap='viridis', vmin=None, vmax=None, vmin_pct=1.0, vmax_pct=99.0, gamma=1.0, show_colorbar=True, show_grid=False, show_land=False, show_locator=False, show_scale_bar=True, title=None)

Plot a gridded raster as a 2D heatmap.

Parameters:

rasterSideScanGriddedRaster

Gridded backscatter raster.

figmatplotlib.figure.Figure, optional

Existing figure. If None, create new.

axmatplotlib.axes.Axes, optional

Existing axes. If None, create new.

cmapstr, default “viridis”

Colormap name.

vmin, vmaxfloat, optional

Colorbar min/max. If None, use percentile-based auto-scaling (vmin_pct/vmax_pct).

vmin_pct, vmax_pctfloat, default 1.0 and 99.0

Percentiles for auto color scaling when vmin/vmax aren’t given. Matches plot_waterfall’s defaults — use the same values for both when comparing a waterfall and a gridded export of the same data, otherwise the two can show very different apparent contrast/normalization purely from differing percentile cutoffs, independent of any real difference in the underlying values (backscatter distributions with a sharp low-end density cliff, e.g. from floor-clipped no-return samples, are especially sensitive to this — a 1-2 percentile difference can shift the effective vmin by tens of dB).

Matching these two values is necessary but not sufficient for a waterfall and a gridded export to look comparably normalized: percentiles are computed over different underlying populations (every raw sample vs. every gridded cell mean), so even identical vmin_pct/vmax_pct can yield different absolute bounds — see resample_channel_to_grid()’s “Notes” section.

gammafloat, default 1.0

Display-only power-law contrast curve, applied via matplotlib.colors.PowerNorm(gamma, vmin, vmax) instead of a plain linear scale. The plotted array is never renormalized — only the value-to-color mapping is warped — so raster stays in its real units (e.g. dB) and the colorbar (if shown) keeps honest, correctly-labeled tick values, just non-uniformly spaced. gamma=1.0 (default) is linear, identical to this function’s behavior before this parameter existed.

show_colorbarbool, default True

Include colorbar.

show_gridbool, default False

Show grid lines.

show_landbool, default False

Draw land/water context (vendored 1:50m Natural Earth data) behind the raster, in cells NaN masks out (see sidescanpy.viz.basemap) – water-colored fill plus land polygons, drawn first so the raster paints over it wherever there’s real data. Requires the optional maps extra (cartopy); raises ImportError with an install hint if it isn’t installed, rather than silently skipping the background.

show_locatorbool, default False

Add a small inset (bottom-left) showing this raster’s location zoomed way out, with a marker box — “where is this, relative to the coast.” Requires the optional maps extra.

show_scale_barbool, default True

Draw a scale bar (see sidescanpy.viz.scalebar). Only drawn for a projected raster (raster.is_geographic False, the common case — auto-UTM-selected grids) – a geographic raster is skipped, not drawn wrong, since meters-per-degree isn’t a single constant this function can infer.

titlestr, optional

Plot title. If None, auto-generate from raster metadata, including the CRS (see _crs_label).

Returns:

figmatplotlib.figure.Figure

axmatplotlib.axes.Axes

Axes with plotted raster.

sidescanpy.viz.gridded.plot_grid_coverage(raster, fig=None, ax=None, cmap='viridis', vmin=None, vmax=None, vmin_pct=1.0, vmax_pct=99.0, full_opacity_count=None, title=None)

Plot a gridded raster with each cell’s opacity set by its sample count.

The color is the backscatter, as in plot_gridded_raster(); the opacity is n_contributing_samples divided by full_opacity_count (capped at 1), so cells built from few samples fade into the background. A diagnostic view, not a data product: at resolutions finer than the ping spacing it shows thin streaks fanning out from the track, which are the normal variation of samples per cell, not misplaced data.

Parameters:

rasterSideScanGriddedRaster

Gridded raster. Without an n_contributing_samples variable (e.g. a raster read back from a GeoTIFF), every finite cell is opaque and every empty one transparent.

figmatplotlib.figure.Figure, optional

Existing figure. If None, create new.

axmatplotlib.axes.Axes, optional

Existing axes. If None, create new.

cmapstr, default “viridis”

Colormap name.

vmin, vmaxfloat, optional

Color range. If None, the vmin_pct/vmax_pct percentiles of the finite, non-floor-clipped cells.

vmin_pct, vmax_pctfloat, default 1.0 and 99.0

Percentiles for the automatic color range.

full_opacity_countfloat, optional

Sample count drawn fully opaque. If None, the 95th percentile of the counts of cells with data, so a few very busy cells do not make every other cell faint.

titlestr, optional

Plot title. If None, the channel name and the share of cells with data.

Returns:

figmatplotlib.figure.Figure

axmatplotlib.axes.Axes