quantized-lab 0.8.0__py3-none-any.whl

quantized/calc/figure_field.py

@@ -0,0 +1,137 @@
+"""Publication rendering for vector field plots (quiver and streamline).
+
+ORIGIN_GAP_PLAN #23 / GAP_TIER3_PLAN item 4. Pure layer: gridded (x, y, u, v)
+field data -> quiver or streamline vector plot in image bytes. Shares
+``calc.figure_styles`` presets and ``calc.figure``'s resolved-dpi convention.
+
+Validates that x/y axes have matching grid shape to the (u, v) components.
+"""
+
+from __future__ import annotations
+
+from io import BytesIO
+from typing import Any
+
+import matplotlib
+
+matplotlib.use("Agg")  # headless
+
+import matplotlib.pyplot as plt  # noqa: E402
+import numpy as np  # noqa: E402
+from numpy.typing import ArrayLike  # noqa: E402
+
+from quantized.calc.figure_labels import safe_mathtext_label  # noqa: E402
+from quantized.calc.figure_styles import figure_style  # noqa: E402
+
+__all__ = ["render_field_figure"]
+
+_FORMATS = ("pdf", "svg", "png", "tiff")
+_FIGURE_SIZE_IN = (10, 8)  # inches
+
+
+def render_field_figure(
+    x_axis: ArrayLike,
+    y_axis: ArrayLike,
+    u_grid: ArrayLike,
+    v_grid: ArrayLike,
+    *,
+    kind: str = "quiver",
+    fmt: str = "pdf",
+    style: str = "default",
+    dpi: int | None = None,
+    title: str = "",
+    x_label: str = "",
+    y_label: str = "",
+) -> bytes:
+    """Render a vector field plot (quiver or streamline).
+
+    ``x_axis`` and ``y_axis`` are 1-D coordinate arrays defining a regular grid.
+    ``u_grid`` and ``v_grid`` are 2-D arrays (shape: len(y_axis) × len(x_axis))
+    of x and y components of the field at each grid point.
+
+    ``kind`` is either "quiver" (arrows at each grid point) or "streamline"
+    (streamlines following the field). ``fmt``, ``style``, and ``dpi`` follow
+    ``render_figure``'s conventions: ``dpi`` defaults to the preset's calibrated
+    resolution when not given.
+
+    ``title``, ``x_label``, and ``y_label`` are optional figure labels.
+
+    Returns image bytes in the requested ``fmt``. Raises ``ValueError`` on
+    malformed input (wrong shape, bad kind, bad format).
+    """
+    if fmt not in _FORMATS:
+        raise ValueError(f"fmt must be one of {_FORMATS}")
+    if kind not in ("quiver", "streamline"):
+        raise ValueError("kind must be 'quiver' or 'streamline'")
+    # Rich-text labels (GOTO #5): de-math INVALID $...$ so savefig never raises.
+    title = safe_mathtext_label(title)
+    x_label = safe_mathtext_label(x_label)
+    y_label = safe_mathtext_label(y_label)
+
+    x_arr = np.asarray(x_axis, dtype=float)
+    y_arr = np.asarray(y_axis, dtype=float)
+    u_arr = np.asarray(u_grid, dtype=float)
+    v_arr = np.asarray(v_grid, dtype=float)
+
+    if x_arr.ndim != 1 or y_arr.ndim != 1:
+        raise ValueError("x_axis and y_axis must be 1-D arrays")
+    if u_arr.ndim != 2 or v_arr.ndim != 2:
+        raise ValueError("u_grid and v_grid must be 2-D arrays")
+    if u_arr.shape != v_arr.shape:
+        raise ValueError("u_grid and v_grid must have the same shape")
+    if u_arr.shape != (len(y_arr), len(x_arr)):
+        raise ValueError(
+            f"u_grid/v_grid shape {u_arr.shape} doesn't match "
+            f"grid dimensions ({len(y_arr)}, {len(x_arr)})"
+        )
+
+    st = figure_style(style)
+    resolved_dpi = int(dpi) if dpi is not None else int(st.dpi)
+    fallback = "DejaVu Serif" if st.font_generic == "serif" else "DejaVu Sans"
+    rc: dict[str, Any] = {
+        "font.family": st.font_generic,
+        f"font.{st.font_generic}": [st.font_name, fallback],
+        "font.size": st.font_size,
+        "axes.labelsize": st.font_size,
+        "axes.titlesize": st.title_font_size,
+        "xtick.labelsize": st.font_size - 1,
+        "ytick.labelsize": st.font_size - 1,
+        "xtick.direction": st.tick_dir,
+        "ytick.direction": st.tick_dir,
+    }
+
+    # Build a meshgrid for proper vector field plotting
+    xx, yy = np.meshgrid(x_arr, y_arr, indexing="xy")
+
+    with matplotlib.rc_context(rc):  # type: ignore[arg-type]
+        fig, ax = plt.subplots(figsize=_FIGURE_SIZE_IN)
+        try:
+            if kind == "quiver":
+                # Quiver: arrows at grid points, colored by magnitude
+                magnitude = np.sqrt(u_arr**2 + v_arr**2)
+                q = ax.quiver(xx, yy, u_arr, v_arr, magnitude, cmap="viridis")
+                fig.colorbar(q, ax=ax, label="Magnitude")
+            else:  # streamline
+                # Streamline: field lines following the vector field
+                speed = np.sqrt(u_arr**2 + v_arr**2)
+                strm = ax.streamplot(
+                    x_arr, y_arr, u_arr, v_arr,
+                    color=speed, cmap="viridis", density=1.5, linewidth=1.0,
+                )
+                fig.colorbar(strm.lines, ax=ax, label="Speed")
+
+            ax.set_xlabel(x_label)
+            ax.set_ylabel(y_label)
+            if title:
+                ax.set_title(title, fontsize=st.title_font_size)
+
+            if not st.box_on:
+                ax.spines["top"].set_visible(False)
+                ax.spines["right"].set_visible(False)
+
+            fig.tight_layout()
+            buf = BytesIO()
+            fig.savefig(buf, format=fmt, dpi=resolved_dpi)
+            return buf.getvalue()
+        finally:
+            plt.close(fig)

quantized/calc/figure_hitmap.py

@@ -0,0 +1,116 @@
+"""Figure-hitmap element collection (gap #13): draw a figure and harvest one
+pixel bounding box per interactive artist (title / axis labels / legend /
+series lines / annotations) + the axes rect with data limits, so the client
+can hit-test a preview render and map pixels back to data coordinates.
+
+Split out of ``calc.figure`` purely to stay under the 500-line god-module
+ceiling (mirrors ``figure_break``/``figure_scale``/``figure_overrides``);
+``figure.render_figure_map`` (``_render_impl(..., collect_map=True)``) is the
+only caller. Pure layer: a live ``Figure``/``Axes`` in -> a plain dict out.
+"""
+
+from __future__ import annotations
+
+import base64
+from collections.abc import Sequence
+from io import BytesIO
+from typing import Any
+
+__all__ = ["collect_map"]
+
+
+def _bbox_to_pixels(bbox: Any, height: float) -> dict[str, float]:
+    """Window extent (origin bottom-left) -> image pixels (origin top-left)."""
+    return {
+        "x0": float(bbox.x0),
+        "y0": float(height - bbox.y1),
+        "x1": float(bbox.x1),
+        "y1": float(height - bbox.y0),
+    }
+
+
+def _artist_window_extent(artist: Any, renderer: Any) -> Any:
+    """``artist.get_window_extent(renderer)``, with a workaround for
+    matplotlib's ``Collection`` (what ``ax.scatter`` -- MAIN #14's colour-
+    mapped scatter -- returns): ``Collection.get_window_extent`` calls
+    ``get_datalim(IdentityTransform())`` instead of transforming to display
+    space, which returns a degenerate all-``inf`` bbox for a plain scatter.
+    Detected via ``get_offsets``/``get_offset_transform`` (present on any
+    ``Collection`` with point offsets, scatter included) -- compute the real
+    screen-space bbox from the transformed offsets instead. Falls through to
+    the artist's own ``get_window_extent`` for everything else (``Line2D``,
+    ``Text``, ``Legend``, ...)."""
+    get_offsets = getattr(artist, "get_offsets", None)
+    get_offset_transform = getattr(artist, "get_offset_transform", None)
+    if get_offsets is not None and get_offset_transform is not None:
+        pts = get_offset_transform().transform(get_offsets())
+        if len(pts):
+            from matplotlib.transforms import Bbox
+
+            return Bbox([pts.min(axis=0), pts.max(axis=0)])
+    return artist.get_window_extent(renderer)
+
+
+def collect_map(
+    fig: Any, ax: Any, *, series_artists: Sequence[Any], dpi: int, x_scale: str, y_scale: str
+) -> dict[str, Any]:
+    """Draw at ``dpi`` and harvest artist extents in image-pixel coords.
+    ``series_artists`` is ``figure.draw_series_axes``'s return value (one
+    artist per series, in order -- a ``Line2D`` normally, a
+    ``PathCollection`` for a colour-mapped-scatter series) rather than
+    re-derived from ``ax.lines``: a colour-mapped series draws via
+    ``ax.scatter``, so it has NO entry in ``ax.lines`` at all -- indexing
+    ``ax.lines[:n_series]`` would silently misalign every series hit-box
+    after it. ``x_scale``/``y_scale`` are the ALREADY-RESOLVED scale names
+    (MAIN #12) -- not re-derived from ``ax.get_xscale()``, which reports a
+    reciprocal axis as ``"function"`` (matplotlib's generic custom-scale
+    name), not ``"reciprocal"`` -- the client's ``lib/previewmap.ts`` needs
+    the real name to invert a preview pixel drag back to data coordinates
+    (``pxToData``)."""
+    fig.set_dpi(dpi)
+    fig.canvas.draw()
+    renderer = fig.canvas.get_renderer()
+    width, height = fig.canvas.get_width_height()
+
+    elements: list[dict[str, Any]] = []
+
+    def add(el_id: str, artist: Any) -> None:
+        try:
+            bbox = _artist_window_extent(artist, renderer)
+        except (RuntimeError, AttributeError):
+            return
+        if bbox.width <= 0 or bbox.height <= 0:
+            return
+        elements.append({"id": el_id, **_bbox_to_pixels(bbox, height)})
+
+    if ax.get_title():
+        add("title", ax.title)
+    if ax.get_xlabel():
+        add("xlabel", ax.xaxis.label)
+    if ax.get_ylabel():
+        add("ylabel", ax.yaxis.label)
+    if ax.get_legend() is not None:
+        add("legend", ax.get_legend())
+    for i, artist in enumerate(series_artists):
+        add(f"series:{i}", artist)
+    for i, txt in enumerate(ax.texts):
+        add(f"ann:{i}", txt)
+
+    axes_px = _bbox_to_pixels(ax.get_window_extent(renderer), height)
+    buf = BytesIO()
+    fig.savefig(buf, format="png")
+    return {
+        "image": base64.b64encode(buf.getvalue()).decode("ascii"),
+        "width": int(width),
+        "height": int(height),
+        "elements": elements,
+        "axes": {
+            **axes_px,
+            "xlim": [float(v) for v in ax.get_xlim()],
+            "ylim": [float(v) for v in ax.get_ylim()],
+            "xlog": x_scale == "log",
+            "ylog": y_scale == "log",
+            "xscale": x_scale,
+            "yscale": y_scale,
+        },
+    }

quantized/calc/figure_labels.py

@@ -0,0 +1,62 @@
+"""Mathtext label guard for figure export (GOTO #5 rich-text labels).
+
+Labels flow from the UI as plain text with optional ``$...$`` mathtext
+regions (the frontend's ``lib/richtext`` micro-syntax is a strict subset of
+matplotlib mathtext, so passthrough is the rendering mechanism). matplotlib
+parses math regions at DRAW time, which means an invalid label would raise
+inside ``fig.savefig`` and turn an export into a 500. This module is the
+shared chokepoint every ``calc.figure*`` renderer routes its user-supplied
+strings through: it pre-validates with matplotlib's own mathtext parser and,
+on failure, escapes the dollar signs so the label renders as literal text
+(matplotlib renders ``\\$`` as a plain ``$``) -- an invalid label must NEVER
+error an export.
+
+Pure layer: string in -> string out. matplotlib is imported lazily (same
+convention as the figure modules -- the heavy import is paid only on export).
+"""
+
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+from typing import Any
+
+__all__ = ["safe_mathtext_label"]
+
+# A "$" not preceded by a backslash -- matplotlib's own math-region rule
+# (matplotlib.cbook.is_math_text counts these; an odd count means the string
+# is rendered as literal text, dollars visible, no mathtext at all).
+_UNESCAPED_DOLLAR = re.compile(r"(?<!\\)\$")
+
+
+@lru_cache(maxsize=1)
+def _parser() -> Any:
+    """The mathtext trial parser (cached -- construction is not free)."""
+    from matplotlib.mathtext import MathTextParser
+
+    return MathTextParser("agg")
+
+
+def safe_mathtext_label(label: str) -> str:
+    """Return ``label`` unchanged when it renders safely; else de-math it.
+
+    - No ``$`` at all: fast path, returned as-is (byte-identical to today).
+    - Odd count of unescaped ``$``: matplotlib already treats the whole
+      string as literal text -- returned as-is.
+    - Balanced ``$...$`` regions: trial-parsed with matplotlib's mathtext
+      parser. Valid -> unchanged (mathtext renders it at export). Invalid ->
+      every unescaped ``$`` is escaped to ``\\$`` so matplotlib renders the
+      literal string (dollars visible) instead of raising at savefig time.
+    """
+    if not label or "$" not in label:
+        return label
+    n_math = len(_UNESCAPED_DOLLAR.findall(label))
+    if n_math == 0 or n_math % 2 == 1:
+        # Zero unescaped $ (all \$-escaped) or an odd count: matplotlib
+        # already renders the whole string as literal text -- leave it be.
+        return label
+    try:
+        _parser().parse(label)
+    except Exception:  # ANY parse failure means "render literal", never raise
+        return _UNESCAPED_DOLLAR.sub(r"\\$", label)
+    return label

quantized/calc/figure_map.py

@@ -0,0 +1,287 @@
+"""Publication rendering for 2-D maps: contour, filled contour, 3-D surface.
+
+ORIGIN_GAP_PLAN #17 (filled/labeled contour, incl. the scattered tri-contour
+remainder) + #19 (3-D static export). Pure layer: either a gridded map
+(``x_axis``/``y_axis``/``z_grid``, the ``calc.map.MapData`` shape,
+``contour_source="grid"``) or a raw scattered cloud (``x_axis``/``y_axis``/
+``z_values`` all the same length -- the RSM point-cloud shape produced by
+``io/_xrdml_scan.py``'s snapshot/coupled layouts, ``contour_source="points"``)
+in -> image bytes out, via matplotlib (vector by default), matching
+``calc.figure.render_figure``'s style/format/dpi/tick conventions so 1-D and
+2-D exports share presets. 3-D (surface / scatter / waterfall) is the static
+publication path; interactive 3-D is deferred (#22).
+"""
+
+from __future__ import annotations
+
+from io import BytesIO
+from typing import Any
+
+import matplotlib
+
+matplotlib.use("Agg")  # headless
+
+import matplotlib.pyplot as plt  # noqa: E402
+import matplotlib.tri as mtri  # noqa: E402
+import numpy as np  # noqa: E402
+from mpl_toolkits.mplot3d import Axes3D  # noqa: E402,F401  (registers the 3d projection)
+from numpy.typing import ArrayLike, NDArray  # noqa: E402
+
+from quantized.calc.figure_labels import safe_mathtext_label  # noqa: E402
+from quantized.calc.figure_styles import figure_style  # noqa: E402
+
+__all__ = ["MAP_KINDS", "render_map_figure"]
+
+_FORMATS = ("pdf", "svg", "png", "tiff")
+MAP_KINDS = ("contourf", "contour", "heatmap", "surface", "scatter3d", "waterfall")
+_3D_KINDS = ("surface", "scatter3d", "waterfall")
+_CONTOUR_SOURCES = ("grid", "points")
+_POINTS_KINDS = ("contour", "contourf")  # tricontour has no heatmap/3-D analogue here
+
+
+def _contour_levels(
+    z_min: float, z_max: float, levels: int | list[float], scale: str
+) -> NDArray[np.float64]:
+    """Explicit contour levels: ``levels`` count (or a list), lin or log spaced."""
+    if isinstance(levels, (list, tuple)):
+        arr = np.asarray(sorted(float(x) for x in levels), dtype=float)
+        if arr.size < 2:  # matplotlib's contourf needs >= 2 levels
+            raise ValueError("levels list needs at least 2 entries")
+        return arr
+    n = int(levels)
+    if n < 2:
+        raise ValueError("levels count must be >= 2")
+    if not (np.isfinite(z_min) and np.isfinite(z_max) and z_max > z_min):
+        raise ValueError("map has no finite z-range to contour")
+    if scale == "log":
+        if z_max <= 0:
+            raise ValueError("log level_scale needs a positive z-range")
+        lo = z_min if z_min > 0 else z_max * 1e-3
+        return np.asarray(np.logspace(np.log10(lo), np.log10(z_max), n), dtype=float)
+    if scale != "linear":
+        raise ValueError("level_scale must be 'linear' or 'log'")
+    return np.asarray(np.linspace(z_min, z_max, n), dtype=float)
+
+
+def render_map_figure(
+    x_axis: ArrayLike,
+    y_axis: ArrayLike,
+    z_grid: ArrayLike | None = None,
+    *,
+    contour_source: str = "grid",
+    z_values: ArrayLike | None = None,
+    kind: str = "contourf",
+    title: str = "",
+    x_label: str = "",
+    y_label: str = "",
+    z_label: str = "",
+    fmt: str = "pdf",
+    style: str = "default",
+    cmap: str = "viridis",
+    levels: int | list[float] = 12,
+    level_scale: str = "linear",
+    label_contours: bool = True,
+    colorbar: bool = True,
+    width_in: float | None = None,
+    height_in: float | None = None,
+    dpi: int | None = None,
+    view_elev: float = 30.0,
+    view_azim: float = -60.0,
+) -> bytes:
+    """Render a 2-D map to image bytes in the chosen ``kind``.
+
+    Two input shapes, selected by ``contour_source``:
+
+    - ``"grid"`` (default) — ``z_grid`` is ``(ny, nx)`` over ``x_axis``
+      ``(nx,)`` / ``y_axis`` ``(ny,)`` (NaN outside the data hull is left
+      blank), the regridded ``calc.map.MapData`` shape. All of ``MAP_KINDS``
+      are available.
+    - ``"points"`` — ``x_axis`` / ``y_axis`` / ``z_values`` are raw scattered
+      arrays of equal length (e.g. an RSM point cloud straight off
+      ``io/_xrdml_scan.py``'s snapshot/coupled layouts, never regridded).
+      Only ``kind`` ``"contour"`` / ``"contourf"`` apply; the cloud is
+      Delaunay-triangulated (``matplotlib.tri.Triangulation``) and drawn with
+      ``tricontour`` / ``tricontourf``. Degenerate input (e.g. collinear
+      points, or fewer than 3 finite points) raises ``ValueError``.
+
+    ``kind``:
+
+    - ``contourf`` / ``contour`` — filled / line contours; ``levels`` is a
+      count or explicit list, ``level_scale`` lin or log, ``label_contours``
+      draws inline labels on the line variant. Same level semantics
+      (:func:`_contour_levels`) for both ``contour_source`` values.
+    - ``heatmap`` — ``pcolormesh`` of the grid (``"grid"`` source only).
+    - ``surface`` / ``scatter3d`` / ``waterfall`` — static 3-D (mplot3d),
+      viewed from (``view_elev``, ``view_azim``) (``"grid"`` source only).
+
+    ``fmt`` / ``style`` / size overrides match ``render_figure``. ``dpi``
+    defaults to the style preset's calibrated resolution when not given
+    (``None``), same as ``calc.figure``'s ``resolved_dpi`` convention; the
+    preset's box-tick convention (``xtick.top``/``ytick.right`` mirrored
+    when the preset draws a closed box) is honored too.
+    """
+    if fmt not in _FORMATS:
+        raise ValueError(f"fmt must be one of {_FORMATS}")
+    if kind not in MAP_KINDS:
+        raise ValueError(f"kind must be one of {MAP_KINDS}")
+    if contour_source not in _CONTOUR_SOURCES:
+        raise ValueError(f"contour_source must be one of {_CONTOUR_SOURCES}")
+    # Rich-text labels (GOTO #5): de-math INVALID $...$ so savefig never raises.
+    title = safe_mathtext_label(title)
+    x_label = safe_mathtext_label(x_label)
+    y_label = safe_mathtext_label(y_label)
+    z_label = safe_mathtext_label(z_label)
+    st = figure_style(style)
+    resolved_dpi = int(dpi) if dpi is not None else int(st.dpi)
+
+    if contour_source == "points":
+        if kind not in _POINTS_KINDS:
+            raise ValueError(
+                f"contour_source='points' only supports kind {_POINTS_KINDS}, got {kind!r}"
+            )
+        if z_values is None:
+            raise ValueError("z_values is required when contour_source='points'")
+        xr = np.asarray(x_axis, dtype=float).ravel()
+        yr = np.asarray(y_axis, dtype=float).ravel()
+        zr = np.asarray(z_values, dtype=float).ravel()
+        if not (xr.size == yr.size == zr.size):
+            raise ValueError(
+                "x_axis/y_axis/z_values must have the same length for "
+                f"contour_source='points', got {xr.size}/{yr.size}/{zr.size}"
+            )
+        finite = np.isfinite(xr) & np.isfinite(yr) & np.isfinite(zr)
+        x, y, z = xr[finite], yr[finite], zr[finite]
+        if x.size < 3:
+            raise ValueError("need at least 3 finite points to triangulate a scattered contour")
+        z_min, z_max = float(np.min(z)), float(np.max(z))
+    else:
+        if z_grid is None:
+            raise ValueError("z_grid is required when contour_source='grid'")
+        x = np.asarray(x_axis, dtype=float).ravel()
+        y = np.asarray(y_axis, dtype=float).ravel()
+        z = np.asarray(z_grid, dtype=float)
+        if z.ndim != 2 or z.shape != (y.size, x.size):
+            raise ValueError(f"z_grid must be (ny, nx) = ({y.size}, {x.size}), got {z.shape}")
+        if x.size < 2 or y.size < 2:
+            raise ValueError(f"a map needs at least a 2x2 grid, got ({y.size}, {x.size})")
+
+        if np.any(np.isfinite(z)):
+            z_min, z_max = float(np.nanmin(z)), float(np.nanmax(z))
+        else:
+            z_min = z_max = float("nan")  # all-gaps map; contour kinds raise below
+
+    figsize = (width_in or st.fig_width_in, height_in or st.fig_height_in)
+    fallback = "DejaVu Serif" if st.font_generic == "serif" else "DejaVu Sans"
+    rc: dict[str, Any] = {
+        "font.family": st.font_generic,
+        f"font.{st.font_generic}": [st.font_name, fallback],
+        "font.size": st.font_size,
+        "axes.labelsize": st.font_size,
+        "axes.titlesize": st.title_font_size,
+        # Mirror ticks onto the top/right spines whenever the preset draws a
+        # closed box (matches calc.figure's convention; matplotlib's default
+        # leaves top/right bare even with the full rectangular border).
+        "xtick.top": st.box_on,
+        "ytick.right": st.box_on,
+    }
+
+    with matplotlib.rc_context(rc):  # type: ignore[arg-type]
+        if kind in _3D_KINDS:
+            fig = plt.figure(figsize=figsize)
+            ax = fig.add_subplot(projection="3d")
+        else:
+            fig, ax = plt.subplots(figsize=figsize)
+        try:
+            mappable = _draw(
+                ax, kind, x, y, z, z_min, z_max, cmap, levels, level_scale,
+                label_contours, view_elev, view_azim, contour_source=contour_source,
+            )
+            if title:
+                ax.set_title(title)
+            if x_label:
+                ax.set_xlabel(x_label)
+            if y_label:
+                ax.set_ylabel(y_label)
+            if kind in _3D_KINDS and z_label:
+                ax.set_zlabel(z_label)
+            if colorbar and mappable is not None:
+                fig.colorbar(mappable, ax=ax, label=z_label or None, shrink=0.8)
+            fig.tight_layout()
+            buf = BytesIO()
+            fig.savefig(buf, format=fmt, dpi=resolved_dpi)
+            return buf.getvalue()
+        finally:
+            plt.close(fig)
+
+
+def _draw(
+    ax: Any,
+    kind: str,
+    x: NDArray[np.float64],
+    y: NDArray[np.float64],
+    z: NDArray[np.float64],
+    z_min: float,
+    z_max: float,
+    cmap: str,
+    levels: int | list[float],
+    level_scale: str,
+    label_contours: bool,
+    view_elev: float,
+    view_azim: float,
+    *,
+    contour_source: str = "grid",
+) -> Any:
+    """Draw the requested mark; return the colorbar mappable (or None)."""
+    if contour_source == "points":
+        # x/y/z are flat, equal-length scattered arrays here (not a grid) --
+        # Delaunay-triangulate the cloud and contour straight off the
+        # triangulation, no regridding. Same level semantics as the grid path.
+        lv = _contour_levels(z_min, z_max, levels, level_scale)
+        try:
+            tri = mtri.Triangulation(x, y)
+        except RuntimeError as exc:
+            # qhull raises RuntimeError on degenerate input (e.g. all points
+            # collinear) -- surface it as a clean ValueError (-> 422), not a
+            # matplotlib internals leak.
+            raise ValueError(
+                "points are degenerate (e.g. collinear) and cannot be triangulated"
+            ) from exc
+        if kind == "contourf":
+            return ax.tricontourf(tri, z, levels=lv, cmap=cmap)
+        cs = ax.tricontour(tri, z, levels=lv, cmap=cmap)
+        if label_contours:
+            ax.clabel(cs, inline=True, fontsize=7, fmt="%.3g")
+        return cs
+
+    if kind == "heatmap":
+        return ax.pcolormesh(x, y, z, cmap=cmap, shading="auto")
+    if kind in ("contourf", "contour"):
+        lv = _contour_levels(z_min, z_max, levels, level_scale)
+        if kind == "contourf":
+            return ax.contourf(x, y, z, levels=lv, cmap=cmap)
+        cs = ax.contour(x, y, z, levels=lv, cmap=cmap)
+        if label_contours:
+            ax.clabel(cs, inline=True, fontsize=7, fmt="%.3g")
+        return cs
+
+    # 3-D kinds
+    ax.view_init(elev=view_elev, azim=view_azim)
+    xg, yg = np.meshgrid(x, y)  # (ny, nx)
+    if kind == "surface":
+        return ax.plot_surface(xg, yg, z, cmap=cmap, linewidth=0, antialiased=True)
+    if kind == "scatter3d":
+        finite = np.isfinite(z)
+        sc = ax.scatter(
+            xg[finite], yg[finite], z[finite], c=z[finite], cmap=cmap, s=6, depthshade=True
+        )
+        return sc
+    # waterfall: one profile line per y-row, stacked in depth
+    line_cmap = matplotlib.colormaps[cmap]
+    for j in range(y.size):
+        row = z[j]
+        finite = np.isfinite(row)
+        if not finite.any():
+            continue
+        frac = j / max(1, y.size - 1)
+        ax.plot(x[finite], np.full(int(finite.sum()), y[j]), row[finite], color=line_cmap(frac))
+    return None