2.29.3.4. pycsamt.topo.overlay#

Topography rendering helpers for 2-D section and pseudosection plots.

Two rendering modes are provided:

Depth-section mode (draw_topo_section)

For inversion / interpretation pcolormesh plots whose x-axis is along-profile distance (km) and y-axis is absolute elevation (km) in a terrain-following coordinate system. The function fills the above-surface polygon, draws the terrain polyline, and places station marker pins at the real terrain elevation.

Pseudosection strip mode (draw_topo_strip)

For period-vs-station imshow pseudosections. A compact elevation profile strip is inserted above the main image axes so that the station positions are linked to real terrain.

Both functions accept an optional TopoConfig argument; when omitted they fall back to the global singleton PYCSAMT_TOPO.

Typical usage:

from pycsamt.topo.overlay import draw_topo_section, draw_topo_strip

# After pcolormesh in a depth-section axes:
draw_topo_section(ax, chainage_km, elev_m, station_names)

# Above a pseudosection image:
ax_strip = draw_topo_strip(fig, ax_ps, chainage_km, elev_m, names)

Functions

add_station_labels(ax, x_km, y_km, names, *)

Draw rotated station name labels above marker positions.

draw_topo_section(ax, chainage_km, elev_m[, ...])

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

draw_topo_strip(fig, main_ax, chainage_km, ...)

Add an elevation-profile strip above a pseudosection image axes.
pycsamt.topo.overlay.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)[source]

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.overlay.draw_topo_strip(fig, main_ax, chainage_km, elev_m, station_names=None, *, cfg=None, dark=True, marker_style=None, facecolor=None)[source]

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.overlay.add_station_labels(ax, x_km, y_km, names, *, color='#cdd6f4', fontsize=7, offset_km=0.05, rotation=90)[source]

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