2.29.3.1. pycsamt.topo.config#

Package-wide topography configuration for 2-D section displays.

Follows the same singleton + configure/reset/context pattern as the rest of pycsamt.api. Import the singleton directly:

from pycsamt.topo import PYCSAMT_TOPO, configure_topo

Or via the public API interface:

from pycsamt.api.topo import configure_topo, reset_topo

Examples

Enable topography globally (applies to every 2-D plot until reset):

from pycsamt.topo import configure_topo

configure_topo(enabled=True)

Temporarily override inside a with block:

from pycsamt.topo import PYCSAMT_TOPO

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

Functions

configure_topo(**kw)

Configure the global PYCSAMT_TOPO singleton.

reset_topo()

Reset PYCSAMT_TOPO to package defaults.

Classes

TopoConfig([enabled, source, elev_array, ...])

Package-wide topography rendering policy for 2-D section plots.
class pycsamt.topo.config.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)[source]

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)[source]

Set one or more configuration attributes by keyword.

Parameters:

kw (Any)

Return type:

TopoConfig

context(**kw)[source]

Temporarily override config values, then restore them.

Parameters:

kw (Any)

Return type:

Generator[TopoConfig, None, None]

reset()[source]

Restore all attributes to package defaults.

Return type:

None

clone()[source]

Return a deep copy of this config.

Return type:

TopoConfig

is_active_for(y_type)[source]

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()[source]

One-line status string.

Return type:

str

pycsamt.topo.config.configure_topo(**kw)[source]

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.config.reset_topo()[source]

Reset PYCSAMT_TOPO to package defaults.

Return type:

None