pycsamt.map.overlays#

Overlay helpers for station, profile, and 3-D maps.

Functions

auto_map_zoom(lon, lat)

Estimate a reasonable Plotly map zoom.

basemap_style_and_layers(style, *[, dark])

Resolve a style name into a (base style, raster layers) pair.

build_basemap_layout(lon, lat, *[, dark, ...])

Return layout settings for geographic station maps.

build_contour_overlay(x, y, values, *[, ...])

Build an interpolated map contour overlay.

build_geo_contour_image(lons, lats, values, *)

Render a Surfer-style filled-contour PNG for a basemap image layer.

build_profile_line_overlay(x, y, *[, geo, ...])

Build a reusable profile-line overlay trace.

build_station_label_overlay(x, y, labels, *)

Build a reusable station-label overlay trace.

build_topography_overlay(x, y, elevation, *)

Build a Plotly 3-D terrain mesh or surface.

default_basemap([dark])

Return a default public tile style.

interpolate_overlay_grid(x, y, values, *[, ...])

Interpolate scattered values to a regular grid.

normalize_epsg(epsg)

Return an EPSG authority string.

reproject_xy_to_lonlat(x, y, *, epsg)

Reproject x, y from epsg to WGS84 lon/lat.

resolve_crs_info([mode, zone, hemisphere, epsg])

Return a human-readable CRS description.

transform_xy(x, y, *, crs)

Transform coordinates between two CRS definitions.

Classes

BasemapConfig(style, center, zoom[, ...])

Plotly geographic map layout settings.

CRSConfig(source[, target, always_xy])

Coordinate transform settings.

ContourOverlay(values, x, y[, levels, cmap, ...])

Description of an interpolated contour overlay.

TopographyOverlay(elevation[, source, opacity])

Topography aligned to map coordinates.
class pycsamt.map.overlays.ContourOverlay(values, x, y, levels=12, cmap='viridis', opacity=0.65)[source]#

Bases: object

Description of an interpolated contour overlay.

Parameters:
values: ndarray#
x: ndarray#
y: ndarray#
levels: int = 12#
cmap: str = 'viridis'#
opacity: float = 0.65#
class pycsamt.map.overlays.TopographyOverlay(elevation, source='stations', opacity=0.7)[source]#

Bases: object

Topography aligned to map coordinates.

Parameters:
elevation: ndarray#
source: str = 'stations'#
opacity: float = 0.7#
class pycsamt.map.overlays.CRSConfig(source, target=4326, always_xy=True)[source]#

Bases: object

Coordinate transform settings.

Parameters:
source: int | str#
target: int | str = 4326#
always_xy: bool = True#
class pycsamt.map.overlays.BasemapConfig(style, center, zoom, bearing=0.0, layers=())[source]#

Bases: object

Plotly geographic map layout settings.

Parameters:
style: str#
center: dict[str, float]#
zoom: int#
bearing: float = 0.0#
layers: tuple = ()#
pycsamt.map.overlays.basemap_style_and_layers(style, *, dark=False)[source]#

Resolve a style name into a (base style, raster layers) pair.

ESRI styles are rendered as white-bg + a raster tile layer; native Plotly styles are returned as-is with no layers.

Parameters:
Return type:

tuple[str, list]

pycsamt.map.overlays.resolve_crs_info(mode='geo', *, zone=50, hemisphere='N', epsg=4326)[source]#

Return a human-readable CRS description.

Parameters:
Return type:

str

pycsamt.map.overlays.normalize_epsg(epsg)[source]#

Return an EPSG authority string.

Parameters:

epsg (int | str)

Return type:

str

pycsamt.map.overlays.transform_xy(x, y, *, crs)[source]#

Transform coordinates between two CRS definitions.

Parameters:
Return type:

tuple[ndarray, ndarray]

pycsamt.map.overlays.reproject_xy_to_lonlat(x, y, *, epsg)[source]#

Reproject x, y from epsg to WGS84 lon/lat.

Parameters:
Return type:

tuple[ndarray, ndarray]

pycsamt.map.overlays.build_contour_overlay(x, y, values, *, levels=12, cmap='Viridis', opacity=0.65, grid_size=80, mode='lines')[source]#

Build an interpolated map contour overlay.

Returns a Plotly Contour trace on a regular grid.

Parameters:
Return type:

Any

pycsamt.map.overlays.build_geo_contour_image(lons, lats, values, *, cmap='jet', n_levels=12, opacity=0.6, mode='filled+lines', log_scale=False, grid_res=160, expand=0.06, interp='cubic', smooth_sigma=0.0)[source]#

Render a Surfer-style filled-contour PNG for a basemap image layer.

Interpolates sparse station values onto a regular lon/lat grid and rasterises filled (and/or line) contours to a transparent PNG. The result is meant to be added to a Plotly map as an image layer.

Returns:

{"image": "data:image/png;base64,...", "coordinates": [...], "vmin": float, "vmax": float} (coordinates are the TL, TR, BR, BL [lon, lat] corners), or None when it cannot be built.

Return type:

dict | None

Parameters:
pycsamt.map.overlays.interpolate_overlay_grid(x, y, values, *, grid_size=80, method='linear')[source]#

Interpolate scattered values to a regular grid.

Parameters:
Return type:

tuple[ndarray, ndarray, ndarray]

pycsamt.map.overlays.build_topography_overlay(x, y, elevation, *, opacity=0.7, colorscale='Earth')[source]#

Build a Plotly 3-D terrain mesh or surface.

Parameters:
Return type:

Any

pycsamt.map.overlays.build_station_label_overlay(x, y, labels, *, geo=False, name='Station labels', color='#111827')[source]#

Build a reusable station-label overlay trace.

Parameters:
Return type:

Any

pycsamt.map.overlays.build_profile_line_overlay(x, y, *, geo=False, name='Profile', color='#2563eb', width=2.0)[source]#

Build a reusable profile-line overlay trace.

Parameters:
Return type:

Any

pycsamt.map.overlays.build_basemap_layout(lon, lat, *, dark=False, style=None, bearing=0.0)[source]#

Return layout settings for geographic station maps.

Parameters:
Return type:

BasemapConfig

pycsamt.map.overlays.default_basemap(dark=False)[source]#

Return a default public tile style.

Parameters:

dark (bool)

Return type:

str

pycsamt.map.overlays.auto_map_zoom(lon, lat)[source]#

Estimate a reasonable Plotly map zoom.

Parameters:
Return type:

int