2.29. pycsamt.topo#

Terrain-aware section rendering: elevation extraction, terrain-following coordinate draping, section overlays, and a one-call topography-embedded section plot for resistivity models and inversion results.

Topography subpackage for pycsamt.

Provides a global configuration singleton (PYCSAMT_TOPO) and a set of utilities to extract elevation data from station collections, transform flat depth-grids into terrain-following coordinates, and render terrain polygons on 2-D section plots.

2.29.1. Quick start#

Enable topography for all 2-D plots in the current session:

from pycsamt.topo import configure_topo

configure_topo(enabled=True)

Disable / reset:

from pycsamt.topo import reset_topo

reset_topo()

Temporarily override with a context manager:

from pycsamt.topo import PYCSAMT_TOPO

with PYCSAMT_TOPO.context(enabled=True, exaggeration=2.0):
    fig = section.plot()

2.29.2. Public API#

PYCSAMT_TOPO: Global TopoConfig singleton.
configure_topo(): Set attributes on the global singleton.
reset_topo(): Restore all attributes to package defaults.
extract_elevation(): Pull per-station elevation arrays from Sites / EDI collections.
extract_chainage(): Compute along-profile cumulative distance (km).
has_elevation(): Quick boolean check for meaningful elevation data.
extract_station_names(): Return station name strings in collection order.
interp_elev(): Interpolate station elevations to arbitrary x positions.
drape_section(): Build terrain-following 2-D node arrays for pcolormesh.
mask_above_topo(): NaN-mask data cells above the terrain surface.
station_surface_z(): Draped z-coordinate for station marker pins.
draw_topo_section(): Overlay terrain fill + station pins on a depth-section axes.
draw_topo_strip(): Add a topo elevation strip above a pseudosection image axes.
add_station_labels(): Draw rotated station name labels at marker positions.
plot_topo_section(): One-call topography-embedded section plot for any pycsamt resistivity model or inversion result.
plot_topo_array(): The same terrain-following drape for an arbitrary non-resistivity 2-D array (misfit map, sensitivity map, …).
build_topo_section(): Resolve a model + topography source into a TopoSection without plotting.
TopoSection: Resolved terrain-draped section data returned by build_topo_section().
synthetic_elevation_profile(): Generate a plausible elevation profile for a synthetic survey with no real field topography.

class pycsamt.topo.TopoConfig(enabled=False, source='sites', elev_array=None, elev_file=None, interp_method='linear', exaggeration=1.0, fill_color='#a89070', fill_alpha=0.4, line_color='#6b4e2a', line_width=1.2, show_surface_line=True, clip_below_surface=True, station_pins_at_surface=True, show_topo_strip=True, strip_height_ratio=0.18, marker_pad_fraction=0.015)#

Bases: object

Package-wide topography rendering policy for 2-D section plots.

Once configured, the settings apply to every 2-D section plot (pseudosections, inversion sections, interpretation panels) until reset() is called.

Variables:

enabled (bool) – Master switch. False → stations appear at a flat z = 0 datum (default). True → terrain-following geometry active.
source ({"sites", "file", "array"}) – Where to read elevation data from. "sites" — read .elev from each Site’s EDI HEAD (default). "file" — load from elev_file (CSV / parquet). "array" — use the elev_array ndarray directly.
elev_array (array-like or None) – External elevation values (m a.s.l.) when source="array". Must have one value per station in profile order.
elev_file (str or None) – Path to a tabular file when source="file". Expected columns: station, elevation (or lat / lon / elevation).
interp_method ({"linear", "cubic", "nearest"}) – Method for interpolating station elevations to intermediate x positions on the section grid.
exaggeration (float) – Vertical exaggeration factor applied to the elevation profile during rendering. 1.0 = true scale.
fill_color (str) – Matplotlib color for the above-surface terrain fill polygon.
fill_alpha (float) – Opacity of the terrain fill (0–1).
line_color (str) – Color of the terrain surface polyline.
line_width (float) – Line width of the terrain surface polyline.
show_surface_line (bool) – Draw the surface polyline on top of the terrain fill.
clip_below_surface (bool) – Mask model cells that lie above the terrain surface (set to NaN).
station_pins_at_surface (bool) – Place station marker triangles at the real terrain elevation instead of at the flat z = 0 datum.
show_topo_strip (bool) – For period-vs-station pseudosections: add a thin elevation profile strip above the main colour image.
strip_height_ratio (float) – Height of the topo strip relative to the main axes (0–1).

Parameters:

enabled (bool)
source (str)
elev_array (Any)
elev_file (str | None)
interp_method (str)
exaggeration (float)
fill_color (str)
fill_alpha (float)
line_color (str)
line_width (float)
show_surface_line (bool)
clip_below_surface (bool)
station_pins_at_surface (bool)
show_topo_strip (bool)
strip_height_ratio (float)
marker_pad_fraction (float)

enabled: bool = False#

source: str = 'sites'#

elev_array: Any = None#

elev_file: str | None = None#

interp_method: str = 'linear'#

exaggeration: float = 1.0#

fill_color: str = '#a89070'#

fill_alpha: float = 0.4#

line_color: str = '#6b4e2a'#

line_width: float = 1.2#

show_surface_line: bool = True#

clip_below_surface: bool = True#

station_pins_at_surface: bool = True#

show_topo_strip: bool = True#

strip_height_ratio: float = 0.18#

marker_pad_fraction: float = 0.015#

configure(**kw)#

Set one or more configuration attributes by keyword.

Parameters:: kw (Any)
Return type:: TopoConfig

context(**kw)#

Temporarily override config values, then restore them.

Parameters:: kw (Any)
Return type:: Generator[TopoConfig, None, None]

reset()#

Restore all attributes to package defaults.

Return type:: None

clone()#

Return a deep copy of this config.

Return type:: TopoConfig

is_active_for(y_type)#

Return True when topo rendering should fire for a given y-axis type.

Topo only makes physical sense when the y-axis represents a real spatial quantity (depth, elevation, skin depth). Period and frequency pseudosections carry no elevation information — topo rendering is silently skipped for those.

Parameters:: y_type (str) – String tag describing what the y-axis represents. Recognised depth-like values: "depth", "elevation", "elev", "skin_depth", "z". Recognised freq-like values: "period", "frequency", "freq", "per", "t", "f".
Return type:: bool

summary()#

One-line status string.

Return type:: str

pycsamt.topo.configure_topo(**kw)#

Configure the global PYCSAMT_TOPO singleton.

Parameters:: **kw (Any) – Keyword arguments forwarded to TopoConfig.configure().
Return type:: None

Examples

>>> from pycsamt.topo import configure_topo
>>> configure_topo(enabled=True, exaggeration=2.0)

pycsamt.topo.reset_topo()#

Reset PYCSAMT_TOPO to package defaults.

Return type:: None

pycsamt.topo.extract_elevation(sites)#

Extract per-station elevation (m a.s.l.) from a Sites or EDI collection.

Reads the .elev (or .elevation / .alt) field from each station’s HEAD coordinate block. Returns a zero array and emits a UserWarning when no valid non-zero elevation is found.

Parameters:: sites (Sites, EDICollection, list[EDIFile], or single EDIFile) – Any object that contains station data with HEAD lat/lon/elev.
Returns:: Elevation in metres above sea level, one value per station in the order they appear in the collection.
Return type:: numpy.ndarray, shape (n_stations,)

pycsamt.topo.extract_chainage(sites)#

Compute along-profile cumulative distance (km) for each station.

Uses a flat-Earth approximation: cumulative Euclidean distance in lat/lon space scaled to metres, converted to km. Stations are assumed to be in profile order.

Parameters:: sites (Sites, EDICollection, list[EDIFile])
Returns:: Cumulative chainage in km from the first station (starts at 0).
Return type:: numpy.ndarray, shape (n_stations,)

pycsamt.topo.has_elevation(sites)#

Return True if any station carries a meaningful non-zero elevation.

Parameters:: sites (any station container)
Return type:: bool

pycsamt.topo.extract_station_names(sites)#

Return station name / ID strings in collection order.

Parameters:: sites (any station container)
Return type:: list[str]

pycsamt.topo.interp_elev(chainage_km, elev_km, x_query_km, method='linear')#

Interpolate station elevations to arbitrary profile positions.

Clamps extrapolated values to the boundary station elevations so the terrain surface never shoots up unexpectedly at the section edges.

Parameters:

chainage_km (array_like, shape (n_stations,)) – Along-profile distances of the stations (km).
elev_km (array_like, shape (n_stations,)) – Terrain elevation at each station (km a.s.l.).
x_query_km (array_like, shape (m,)) – Positions at which to evaluate the interpolated elevation (km).
method ({"linear", "cubic", "nearest"}) – Interpolation method. "cubic" requires scipy.

Returns:

Interpolated elevation in km a.s.l.

Return type:

numpy.ndarray, shape (m,)

pycsamt.topo.drape_section(x_nodes, z_nodes, data, elev_at_centres, exaggeration=1.0, clip_above_surface=False)#

Transform a flat depth section into terrain-following coordinates.

Builds a 2-D z_draped array (shape (nz+1, nx+1)) where each column is shifted so that z_nodes[0] (the surface) aligns with the local terrain elevation. The result can be passed directly to pcolormesh() as the Y argument.

Parameters:

x_nodes (array_like, shape (nx+1,)) – Horizontal pcolormesh node positions (km).
z_nodes (array_like, shape (nz+1,)) – Depth node positions (km, positive downward from flat datum). z_nodes[0] should be 0 (surface) or the shallowest depth.
data (array_like, shape (nz, nx)) – 2-D data values (e.g. log10(rho)).
elev_at_centres (array_like, shape (nx,)) – Terrain elevation at each cell-centre x position (km a.s.l.).
exaggeration (float) – Vertical exaggeration applied to both the elevation offset and the depth axis. Values > 1 amplify relief for display purposes.
clip_above_surface (bool) – If True, set cells that are above the terrain surface (unreachable subsurface) to NaN.

Returns:

x_nodes (numpy.ndarray, shape (nx+1,)) – Unchanged horizontal node positions.
z_draped (numpy.ndarray, shape (nz+1, nx+1)) – 2-D elevation node array. Column j equals elev_at_nodes[j] - z_nodes * exaggeration.
data_out (numpy.ndarray, shape (nz, nx)) – Input data, optionally NaN-masked above terrain.

Return type:

tuple[ndarray, ndarray, ndarray]

Notes

The terrain-following coordinate for node (k, j) is:

z_draped[k, j] = elev_nodes[j] - z_nodes[k] * exaggeration

where elev_nodes is the terrain interpolated to the x node positions (nx+1 values) from the cell-centre values.

pycsamt.topo.mask_above_topo(x_nodes, z_nodes, data, elev_at_centres, exaggeration=1.0)#

Set data cells that lie above the terrain surface to NaN.

A cell at column j and depth-row k has absolute elevation:

cell_elev = elev_at_centres[j] - z_centre[k] * exaggeration

where z_centre[k] = (z_nodes[k] + z_nodes[k+1]) / 2.

A cell is above the surface when cell_elev > elev_at_centres[j], which simplifies to z_centre[k] < 0. For standard meshes (all z ≥ 0) this never occurs; the masking is only relevant for meshes whose z-origin is below the deepest station (uncommon).

The more practically useful masking is for varying terrain: station A sits at 800 m, station B sits at 200 m. A cell at depth 500 m below A has absolute elevation 300 m — it is above the surface at B. This function masks such cells so they do not appear in the plot.

Parameters:

x_nodes ((nx+1,) node positions)
z_nodes ((nz+1,) depth nodes (km, positive down))
data ((nz, nx) data array)
elev_at_centres ((nx,) elevation at cell centres (km))
exaggeration (float)

Returns:

Data with cells above the terrain set to NaN.

Return type:

numpy.ndarray, shape (nz, nx)

pycsamt.topo.station_surface_z(chainage_km, elev_km, station_x_km, exaggeration=1.0)#

Return the terrain-draped z-coordinate for station marker positions.

In the draped coordinate frame the station sits at the surface elevation, not at z = 0.

Parameters:

chainage_km ((n,) station chainage values)
elev_km ((n,) elevation at each station (km))
station_x_km ((m,) x positions where markers should be drawn)
exaggeration (float)

Returns:

z-coordinates (km) at which to place station markers.

Return type:

numpy.ndarray, shape (m,)

pycsamt.topo.draw_topo_section(ax, chainage_km, elev_m, station_names=None, *, station_x_km=None, cfg=None, dark=True, marker_style=None, label_fontsize=7.0)#

Overlay terrain on a depth-section axes (terrain-following frame).

Call this after pcolormesh() has already drawn the 2-D section. The axes y-axis must represent absolute elevation (km a.s.l.) in a terrain-following coordinate frame (positive upward or positive downward — the function reads the current y-limits to decide direction).

Draws: 1. A filled polygon masking the above-surface space. 2. A terrain surface polyline. 3. Station marker pins at the real terrain elevation. 4. Station name labels above the pins.

Parameters:

ax (matplotlib.axes.Axes) – Target axes that already has the pcolormesh drawn.
chainage_km (array_like (n_stations,)) – Along-profile distances of stations (km).
elev_m (array_like (n_stations,)) – Terrain elevation at each station (m a.s.l.).
station_names (sequence of str, optional) – Station labels. Omit for no labels.
station_x_km (array_like (n_stations,), optional) – X positions of station markers. Defaults to chainage_km.
cfg (TopoConfig, optional) – Configuration override. Defaults to PYCSAMT_TOPO.
dark (bool) – Use dark-palette label colours when True.
marker_style (pycsamt.api.station.StationMarkerStyle, optional) – Station-pin style override. Defaults to pycsamt.api.station.PYCSAMT_STATION_RENDERING’s inversion marker when omitted, so existing callers keep their current appearance; pass this to use a different marker for this call only, without touching the global rendering config.
label_fontsize (float, default 7.0) – Font size of the station name labels only (the terrain, fill, and marker pins are unaffected). The default matches this function’s long-standing appearance; increase it for a wider figure where names would otherwise read as too small.

Return type:

None

pycsamt.topo.draw_topo_strip(fig, main_ax, chainage_km, elev_m, station_names=None, *, cfg=None, dark=True, marker_style=None, facecolor=None)#

Add an elevation-profile strip above a pseudosection image axes.

For period-vs-station pseudosections the x-axis is station index, not a real distance. This function maps station index ↔ chainage so the strip correctly displays the terrain shape.

The strip is inserted by shrinking the main axes and placing a new Axes in the freed space above it.

Parameters:

fig (matplotlib.figure.Figure)
main_ax (matplotlib.axes.Axes) – The existing pseudosection image axes.
chainage_km (array_like (n_stations,)) – Along-profile distances (km) — used as x in the strip.
elev_m (array_like (n_stations,)) – Terrain elevation at each station (m).
station_names (sequence of str, optional) – Labels for the strip tick marks.
cfg (TopoConfig, optional)
dark (bool)
marker_style (pycsamt.api.station.StationMarkerStyle, optional) – Station-pin style override for the strip, analogous to draw_topo_section()’s marker_style. Defaults to pycsamt.api.station.PYCSAMT_STATION_RENDERING’s pseudosection marker when omitted.
facecolor (str, optional) – Strip axes background colour. Defaults to a dark slate in dark=True mode and "none" (transparent, so the strip blends into the figure background rather than sitting inside a visibly distinct box) in dark=False mode.

Returns:

ax_strip – The newly created elevation-strip axes.

Return type:

matplotlib.axes.Axes

pycsamt.topo.add_station_labels(ax, x_km, y_km, names, *, color='#cdd6f4', fontsize=7, offset_km=0.05, rotation=90)#

Draw rotated station name labels above marker positions.

Parameters:

ax (Axes)
x_km (positions of each station marker)
y_km (positions of each station marker)
names (station name strings)
color (text color)
fontsize (int)
offset_km (vertical offset in axes units)
rotation (label rotation in degrees)

Return type:

None

class pycsamt.topo.TopoSection(x_nodes_km, z_draped_km, values, x_centers_km, z_centers_km, z_nodes_km, chainage_km, elev_km, surface_km, station_x_km, station_names, depth_min_km, depth_max_km, exaggeration, log_rho, method, rms, topo_source)#

Bases: object

Resolved, terrain-embedded 2-D resistivity section.

Returned by build_topo_section(). Carries both the terrain-draped grid (for pcolormesh) and the flat cell-centre grid plus raw topography arrays (for imshow / custom plots).

Variables:

x_nodes_km (ndarray, shape (n_x+1,)) – Profile-distance pcolormesh node positions (km).
z_draped_km (ndarray, shape (n_z+1, n_x+1)) – Terrain-following elevation node grid (km a.s.l.), ready for ax.pcolormesh(x_nodes_km, z_draped_km, values).
values (ndarray, shape (n_z, n_x)) – Cell values — log10(rho) when log_rho=True, linear resistivity otherwise. NaN-masked above terrain when clip_above_surface=True.
z_centers_km (x_centers_km,) – Flat (undraped) cell-centre coordinates (km), post depth-crop.
z_nodes_km (ndarray, shape (n_z+1,)) – Flat (undraped) depth node positions (km), post depth-crop.
elev_km (chainage_km,) – Resolved topography source arrays (one value per topography sample point — station count, which may differ from n_x).
surface_km (ndarray, shape (n_x+1,)) – Terrain elevation interpolated to x_nodes_km (km a.s.l.).
station_x_km (ndarray) – Marker x-positions (km) for station pins.
station_names (list of str) – Station labels, aligned with station_x_km.
depth_max_km (depth_min_km,) – Effective (post-crop) depth range, km below the flat datum.
exaggeration (float) – Vertical exaggeration applied while draping.
log_rho (bool) – Whether values is log10(rho) (True) or linear rho.
method (str) – Source model tag ("occam2d", "modem", "ai", …).
rms (float) – Inversion RMS misfit, if available; nan otherwise.
topo_source (str) – Which topography source was actually used: "sites", "array", "model", or "flat".

Parameters:

x_nodes_km (ndarray)
z_draped_km (ndarray)
values (ndarray)
x_centers_km (ndarray)
z_centers_km (ndarray)
z_nodes_km (ndarray)
chainage_km (ndarray)
elev_km (ndarray)
surface_km (ndarray)
station_x_km (ndarray)
station_names (list[str])
depth_min_km (float)
depth_max_km (float)
exaggeration (float)
log_rho (bool)
method (str)
rms (float)
topo_source (str)

x_nodes_km: ndarray#

z_draped_km: ndarray#

values: ndarray#

x_centers_km: ndarray#

z_centers_km: ndarray#

z_nodes_km: ndarray#

chainage_km: ndarray#

elev_km: ndarray#

surface_km: ndarray#

station_x_km: ndarray#

station_names: list[str]#

depth_min_km: float#

depth_max_km: float#

exaggeration: float#

log_rho: bool#

method: str#

rms: float#

topo_source: str#

pycsamt.topo.build_topo_section(model, *, sites=None, elevation=None, chainage=None, station_names=None, station_x=None, topo_source='auto', model_unit='m', depth_min=0.0, depth_max=None, exaggeration=1.0, log_rho=True, interp_method='linear', clip_above_surface=True, smooth_sigma=None, air_log10_threshold=5.0)#

Resolve a model + topography source into a terrain-draped section.

This is the data-building half of plot_topo_section() — use it directly when you want the resolved arrays without a figure.

Parameters:

model (object) – Any of the input forms documented in the module docstring: a (x_centers, z_centers, rho_2d) tuple, a pycsamt.interp.ResistivityModel, a backend-neutral or native Occam2D/ModEM InversionResult, or an AI agent result exposing pred_rho.
sites (object, optional) – Station/EDI collection to extract chainage + elevation from (see pycsamt.topo.extract). Takes priority over elevation when topo_source="auto".
elevation (array_like, optional) – Explicit per-station elevation (m a.s.l.). Paired with chainage (km); if chainage is omitted, the model’s own station positions are used.
chainage (array_like, optional) – Explicit per-station along-profile distance (km). Only used together with elevation.
station_names (sequence of str, optional) – Overrides the station labels carried by model / sites.
station_x (array_like, optional) – Overrides the marker x-positions carried by model.
topo_source ({"auto", "sites", "array", "model"}) – Which topography source to use. "auto" prefers sites, then elevation, then model-derived (air-cell) inference, then falls back to a flat datum with a warning.
model_unit ({"m", "km"}) – Unit of model’s coordinate arrays (and of depth_min / depth_max). Ignored for AI-style results, whose depths_km/coordinates are always treated as km.
depth_min (float, optional) – Depth window to display, in model_unit units. None keeps the full depth range.
depth_max (float, optional) – Depth window to display, in model_unit units. None keeps the full depth range.
exaggeration (float, default 1.0) – Vertical exaggeration applied to the terrain relief.
log_rho (bool, default True) – Keep values as log10(rho). False converts to linear Ω·m (10 ** log10_rho).
interp_method ({"linear", "cubic", "nearest"}) – Elevation interpolation method, forwarded to interp_elev().
clip_above_surface (bool, default True) – NaN-mask cells that lie above the local terrain surface.
smooth_sigma (float or (float, float), optional) – Gaussian-smoothing sigma (depth, distance), applied to values before draping. Requires scipy; silently skipped with a warning when scipy is unavailable.
air_log10_threshold (float, default 5.0) – log10(rho) threshold used for model-derived terrain inference (topo_source in {"auto", "model"}).

Return type:

TopoSection

Raises:

TypeError – If model is not a recognised input form.
ValueError – If topo_source is invalid, or is forced to a source that cannot be resolved (e.g. "sites" without sites).

pycsamt.topo.plot_topo_section(model, *, ax=None, kind='pcolormesh', sites=None, elevation=None, chainage=None, station_names=None, station_x=None, topo_source='auto', model_unit='m', depth_min=0.0, depth_max=None, exaggeration=1.0, log_rho=True, interp_method='linear', clip_above_surface=True, smooth_sigma=None, air_log10_threshold=5.0, cmap='jet_r', vmin=None, vmax=None, vmin_percentile=2.0, vmax_percentile=98.0, colorbar=True, section='inversion', show_stations=True, show_station_names=True, topo_cfg=None, station_marker=None, dark=False, title=None, figsize=None, savepath=None, savefig_kw=None, return_data=False)#

Plot a resistivity model or inversion result draped over topography.

A single entry point that accepts any of the model forms described in the pycsamt.topo.section module docstring (raw arrays, pycsamt.interp.ResistivityModel, backend-neutral or native Occam2D/ModEM InversionResult, AI agent results) together with any topography source (sites, explicit arrays, or model-derived inference), and renders a publication-style section using the shared pycsamt.api styling (pycsamt.api.section.PYCSAMT_SECTION, pycsamt.api.station.PYCSAMT_STATION_RENDERING).

Parameters:

model (object) – See the module docstring for accepted forms.
ax (matplotlib Axes, optional) – Existing axes to draw into. A new figure/axes is created when omitted, sized via the selected section style.
kind ({"pcolormesh", "imshow"}) – "pcolormesh" drapes the grid over real terrain (profile distance vs. elevation). "imshow" keeps a flat station-index vs. depth pseudosection with a compact elevation strip inserted above it.
sites (Any) – Topography source, forwarded to build_topo_section().
elevation (Any) – Topography source, forwarded to build_topo_section().
chainage (Any) – Topography source, forwarded to build_topo_section().
station_names (Sequence[str] | None) – Topography source, forwarded to build_topo_section().
station_x (Any) – Topography source, forwarded to build_topo_section().
topo_source (str) – Topography-resolution and unit controls, forwarded to build_topo_section().
model_unit (str) – Topography-resolution and unit controls, forwarded to build_topo_section().
depth_min (float) – Depth window and vertical exaggeration, forwarded to build_topo_section().
depth_max (float | None) – Depth window and vertical exaggeration, forwarded to build_topo_section().
exaggeration (float) – Depth window and vertical exaggeration, forwarded to build_topo_section().
log_rho (bool) – Value scaling and grid-building controls, forwarded to build_topo_section() — see its docstring for details.
interp_method (str) – Value scaling and grid-building controls, forwarded to build_topo_section() — see its docstring for details.
clip_above_surface (bool) – Value scaling and grid-building controls, forwarded to build_topo_section() — see its docstring for details.
smooth_sigma (float | tuple[float, float] | None) – Value scaling and grid-building controls, forwarded to build_topo_section() — see its docstring for details.
air_log10_threshold (float) – Value scaling and grid-building controls, forwarded to build_topo_section() — see its docstring for details.
cmap (str, default "jet_r") – Matplotlib colormap.
vmin (float, optional) – Explicit colour-scale limits. When omitted, computed from vmin_percentile / vmax_percentile of the visible values.
vmax (float, optional) – Explicit colour-scale limits. When omitted, computed from vmin_percentile / vmax_percentile of the visible values.
vmin_percentile (float, default 2.0, 98.0) – Percentile bounds used to auto-scale the colour map.
vmax_percentile (float, default 2.0, 98.0) – Percentile bounds used to auto-scale the colour map.
colorbar (bool, default True) – Draw a colorbar using the shared section colorbar style.
section (str or pycsamt.api.section.SectionStyle, default "inversion") – Section style preset name or explicit style object.
show_stations (bool, default True) – Draw station markers (pins for pcolormesh, the elevation strip’s markers for imshow).
show_station_names (bool, default True) – Draw station name labels alongside the markers.
topo_cfg (pycsamt.topo.config.TopoConfig, optional) – Full terrain-rendering style override (fill colour/alpha, line style, marker pad, …). Defaults to a config that only toggles station_pins_at_surface from show_stations and turns off the above-surface fill (see Notes).
station_marker (pycsamt.api.station.StationMarkerStyle, optional) – Station-pin style override, forwarded to draw_topo_section() / draw_topo_strip(). Defaults to a white-filled, black-edged marker sized for legibility against a busy cmap background; pass a StationMarkerStyle to override.
dark (bool, default False) – Use light-on-dark label colours for the terrain overlay.
title (str, optional) – Axes title. Defaults to a method/rms/topo-source summary.
figsize ((float, float), optional) – Explicit figure size, overriding the section style’s sizing.
savepath (str, optional) – Save the figure via pycsamt.api.plot.save_fig().
savefig_kw (dict, optional) – Extra keyword arguments forwarded to save_fig.
return_data (bool, default False) – When True, return (ax, TopoSection) instead of ax.

Returns:

Or (ax, TopoSection) when return_data=True.

Return type:

matplotlib.axes.Axes

Examples

>>> from pycsamt.topo import plot_topo_section
>>> ax = plot_topo_section(result, sites=sites)

Cropped to the shallow 1.5 km and rendered as a pseudosection:

>>> ax = plot_topo_section(
...     result,
...     sites=sites,
...     kind="imshow",
...     depth_max=1500.0,
... )

pycsamt.topo.plot_topo_array(x_centers, z_centers, values, *, ax=None, elevation, station_x=None, chainage=None, station_names=None, model_unit='m', depth_min=0.0, depth_max=None, exaggeration=1.0, clip_above_surface=True, cmap='viridis', vmin=None, vmax=None, colorbar=True, cbar_label='', show_stations=True, show_station_names=True, station_marker=None, dark=False, title=None, figsize=None)#

Drape an arbitrary 2-D scalar field over real topography.

The terrain-following counterpart of plot_topo_section() for grids that are not log10(resistivity) — a calibration misfit map, a sensitivity map, a depth-of-investigation mask, anything defined on the same (x_centers, z_centers) grid as a resistivity model but carrying its own physical units and colour scale. Uses the same drape_section() warp and draw_topo_section() terrain overlay (and the same default inversion station marker) as plot_topo_section(), without ever assuming the values are resistivity or applying a log10 transform.

Parameters:

x_centers (array_like) – Cell-centre coordinates of values, in model_unit.
z_centers (array_like) – Cell-centre coordinates of values, in model_unit.
values (ndarray, shape (n_z, n_x)) – The scalar field, plotted and colour-mapped exactly as given.
ax (matplotlib.axes.Axes, optional) – Existing axes to draw into. A new figure/axes is created when omitted.
elevation (array_like) – Terrain elevation (m a.s.l.) matching chainage (or station_x when chainage is omitted).
station_x (array_like, optional) – Station positions for the marker pins, in model_unit. Defaults to chainage.
chainage (array_like, optional) – Along-profile positions matching elevation, in model_unit. Defaults to station_x. One of the two is required.
station_names (sequence of str, optional)
model_unit ({"m", "km"})
depth_min (float) – Depth window to display, in model_unit. Defaults to the full range of z_centers.
depth_max (float) – Depth window to display, in model_unit. Defaults to the full range of z_centers.
exaggeration (float) – Vertical exaggeration applied to both the terrain and the depth axis.
clip_above_surface (bool) – Mask cells above the local terrain surface to NaN.
cmap (colour-scale controls forwarded to pcolormesh.)
vmin (colour-scale controls forwarded to pcolormesh.)
vmax (colour-scale controls forwarded to pcolormesh.)
colorbar (bool)
cbar_label (str) – Colorbar label. Unlike plot_topo_section(), this is never inferred — there is no single physical quantity to assume — so pass the correct label explicitly.
show_stations (bool)
show_station_names (bool)
station_marker (pycsamt.api.station.StationMarkerStyle, optional) – Defaults to the shared inversion marker (white-filled, black-edged downward triangle), matching plot_topo_section().
dark (bool)
title (str, optional)
figsize ((float, float), optional) – Used only when ax is omitted.

Return type:

matplotlib.axes.Axes

Examples

>>> import numpy as np
>>> from pycsamt.topo.section import plot_topo_array
>>> x = np.linspace(0.0, 900.0, 10)
>>> z = np.linspace(10.0, 500.0, 8)
>>> values = np.full((8, 10), 5.0)
>>> elev = 100.0 + 10.0 * np.sin(x / 300.0)
>>> ax = plot_topo_array(
...     x, z, values, elevation=elev, station_x=x,
...     cmap="RdYlBu_r", vmin=0.0, vmax=20.0, cbar_label="G (%)",
... )
>>> ax.get_ylabel()
'Elevation (km)'

pycsamt.topo.synthetic_elevation_profile(chainage_m, *, base_m=100.0, amplitude_m=30.0, period_m=900.0, secondary_period_m=260.0, phase_m=0.0)#

Return a smooth, deterministic elevation profile, metres.

The shape is two summed sinusoids – a dominant one at period_m and a secondary one (0.4x the amplitude) at secondary_period_m – giving a single broad rise or fall with smaller-scale undulation rather than a perfectly regular wave.

Parameters:

chainage_m (array_like) – Along-profile position(s), metres.
base_m (float, default 100.0) – Mean elevation, metres.
amplitude_m (float, default 30.0) – Amplitude of the dominant sinusoid, metres.
period_m (float, default 900.0) – Period of the dominant sinusoid, metres.
secondary_period_m (float, default 260.0) – Period of the secondary (0.4x amplitude) sinusoid, metres.
phase_m (float, default 0.0) – Along-profile shift applied before evaluating the profile – two calls with different phase_m (everything else equal) give related but genuinely different curves, e.g. for two nearby survey lines without duplicating this function.

Returns:

Elevation, metres, same shape as chainage_m.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from pycsamt.topo.synthetic import synthetic_elevation_profile
>>> chainage = np.linspace(0, 2400, 5)
>>> np.round(synthetic_elevation_profile(chainage), 1)
array([112. , 110.5, 128. , 136.9, 101.9])

2.29.3. Topo Modules#

`pycsamt.topo.config`	Package-wide topography configuration for 2-D section displays.
`pycsamt.topo.drape`	Terrain-following coordinate transform for 2-D section plots.
`pycsamt.topo.extract`	Extract elevation and chainage arrays from Sites / EDI collections.
`pycsamt.topo.overlay`	Topography rendering helpers for 2-D section and pseudosection plots.
`pycsamt.topo.section`	One-call topography-embedded 2-D resistivity section plots.