plot3 0.4.0__py3-none-any.whl

plot3/function.py

@@ -0,0 +1,1301 @@
+"""Sample a :class:`plot3.expr.Formula` into a drawable line or surface.
+
+``geom_function`` stays a thin parameter holder. At build time this module
+evaluates it and returns a ``geom_line``, ``geom_path``, or ``geom_surface``
+with ``data_override`` already filled — the same path bar and density stats use.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from functools import partial
+from typing import Any, Callable
+
+import numpy as np
+import pandas as pd
+
+from plot3.contour import _contour_lines, _refine_active_cells
+from plot3.expr import ExprError, Formula, _missing_param_build_message, evaluate
+from plot3.mathtext import _number, split_math
+from plot3.geoms import _Geom, aes, geom_line, geom_path
+from plot3.special import support_hint
+from plot3.stats3d import regular_grid_mesh
+from plot3.table import has_column, numeric_array
+
+_DEFAULT_DOMAIN = (-10.0, 10.0)
+_N_CURVE = 501
+_N_GRID = 80
+
+
+def data_domains(figure: Any, data: Any) -> dict[str, tuple[float, float]]:
+    """Numeric ranges of x/y/z columns already mapped on non-function layers."""
+    if data is None:
+        return {}
+    found: dict[str, tuple[float, float]] = {}
+    mappings = [getattr(figure, "mapping", None) or {}]
+    for layer in getattr(figure, "layers", []):
+        if getattr(layer, "kind", None) == "function":
+            continue
+        mapping = getattr(layer, "mapping", None)
+        if mapping:
+            mappings.append(mapping)
+    for mapping in mappings:
+        getter = getattr(mapping, "get", None)
+        if getter is None:
+            continue
+        for axis in ("x", "y", "z"):
+            if axis in found:
+                continue
+            column = getter(axis)
+            if not column or not has_column(data, column):
+                continue
+            try:
+                values = numeric_array(data, column, dropna=True)
+            except Exception:
+                continue
+            if values.size == 0:
+                continue
+            lo = float(np.min(values))
+            hi = float(np.max(values))
+            if not np.isfinite(lo) or not np.isfinite(hi):
+                continue
+            if hi <= lo:
+                lo, hi = lo - 1.0, hi + 1.0
+            found[axis] = (lo, hi)
+    return found
+
+
+def expand_function(
+    geom: _Geom,
+    base_mapping: Any,
+    data: Any,
+    domains: dict[str, tuple[float, float]] | None = None,
+    transition: Any = None,
+    slider: Any = None,
+    coord: Any = None,
+    addons: list | None = None,
+) -> list:
+    """Turn ``geom_function`` into one or more line, area, or point layers."""
+    del base_mapping, data  # the formula carries its own samples
+    formula: Formula = geom.formula
+    domains = domains or {}
+    # A slider replaces a transition. build_spec rejects having both.
+    sweep = slider if slider is not None else transition
+    ranges = getattr(sweep, "ranges", None) or {}
+    formula = _bind_swept_symbols(geom, formula, ranges)
+    pending = tuple(getattr(formula, "pending", ()) or ())
+    if pending:
+        missing = [name for name in pending if name not in ranges]
+        if missing:
+            raise ExprError(_missing_param_build_message(missing[0]))
+    namespace = getattr(formula, "namespace", None) or {}
+    # A coefficient passed as a keyword (a=2) already sits in the namespace.
+    # Naming it on a slider or transition sweeps that value instead.
+    covered = any(name in pending or name in namespace for name in ranges)
+    # Imported here: calculus imports this module at load time.
+    from plot3.calculus import animation_blocked, attach_calculus, expand_special
+
+    extras = list(addons or ())
+    blocked = animation_blocked(formula, geom, coord, extras)
+    if ranges and blocked:
+        raise ValueError(blocked)
+    special = expand_special(geom, formula, domains, coord)
+    if special is not None:
+        if extras or tuple(getattr(geom, "marks", ()) or ()):
+            _reject_curve_extras(geom, extras)
+        _link_colors(special)
+        return special
+    axes = _assign_axes(formula)
+    if ranges and (pending or covered):
+        return [_expand_animated(geom, formula, axes, domains, sweep)]
+    if axes.kind == "surface":
+        primary = _expand_surface(geom, formula, axes, domains)
+    elif axes.kind == "implicit":
+        primary = _expand_implicit(geom, formula, axes, domains)
+    else:
+        primary = _expand_curve(geom, formula, axes, domains)
+    layers = attach_calculus(primary, geom, formula, domains, extras)
+    _link_colors(layers)
+    return layers
+
+
+def _bind_swept_symbols(geom, formula: Formula, ranges: dict) -> Formula:
+    """Re-read symbols a slider or transition sweeps as coefficients.
+
+    ``sin(x - t)`` parses ``t`` as a second plot variable and
+    ``dnorm(x, mu, 1)`` does the same with ``mu``, which would turn a
+    travelling wave into a static surface. Naming the symbol on
+    ``transition_time(t=...)`` says it is a coefficient. Each frame sets
+    its value; the low end of the range only stands in while parsing.
+    """
+    swept = [name for name in ranges if name in (formula.variables or ())]
+    source = getattr(geom, "_source", None)
+    if not swept or source is None or formula.mode == "callable":
+        return formula
+    params = dict(getattr(geom, "params", None) or {})
+    for name in swept:
+        params[name] = float(ranges[name][0])
+    from plot3.expr import parse_formula
+
+    return parse_formula(source, params, defer_missing=True)
+
+
+def _reject_curve_extras(geom, addons) -> None:
+    """Parametric, polar, and inequality layers stay a single curve."""
+    if tuple(getattr(geom, "marks", ()) or ()):
+        raise ExprError(
+            "mark='roots' and mark='extrema' are for a curve y = f(x)"
+        )
+    name = type(addons[0]).__name__
+    raise ExprError(
+        f"{name}() is for a curve y = f(x). "
+        f'For example geom_function("y = x^2") + {name}(...)'
+    )
+
+
+def _link_colors(layers: list) -> None:
+    """Point a fill at the curve it belongs to, so each curve keeps its colour."""
+    primary = next(
+        (layer for layer in layers if getattr(layer, "_formula_primary", False)),
+        None,
+    )
+    if primary is None:
+        return
+    token = f"formula-{id(primary)}"
+    primary._color_key = token
+    for layer in layers:
+        if layer is primary:
+            continue
+        if getattr(layer, "_inherit_color", False) and not getattr(layer, "_inherit_from", None):
+            layer._inherit_from = token
+
+
+class _Axes:
+    def __init__(
+        self,
+        kind: str,
+        x: str,
+        y: str,
+        z: str | None,
+        computed: str | None,
+    ):
+        self.kind = kind
+        self.x = x
+        self.y = y
+        self.z = z
+        self.computed = computed
+
+
+def _assign_axes(formula: Formula) -> _Axes:
+    variables = list(formula.variables)
+    if formula.mode == "callable":
+        if len(formula.fn_args) >= 2:
+            return _Axes("surface", formula.fn_args[0], formula.fn_args[1], "z", "z")
+        name = formula.fn_args[0] if formula.fn_args else "x"
+        y_name = "f" if name == "y" else "y"
+        return _Axes("curve", name, y_name, None, "y")
+    if formula.mode == "implicit":
+        ordered = _prefer_xy(variables)
+        return _Axes("implicit", ordered[0], ordered[1], None, None)
+    dependent = formula.dependent or "y"
+    if len(variables) >= 2:
+        ordered = _prefer_xy(variables)
+        z_name = dependent if dependent not in ordered else "z"
+        return _Axes("surface", ordered[0], ordered[1], z_name, "z")
+    if len(variables) == 1 and dependent == "x":
+        return _Axes("curve", "x", variables[0], None, "x")
+    if len(variables) == 0:
+        return _Axes("curve", "x", dependent, None, "y")
+    return _Axes("curve", variables[0], dependent, None, "y")
+
+
+def _prefer_xy(names: list[str]) -> list[str]:
+    """Put ``x`` then ``y`` first when those names are present."""
+    rest = [name for name in names if name not in {"x", "y"}]
+    ordered: list[str] = []
+    for prefer in ("x", "y"):
+        if prefer in names:
+            ordered.append(prefer)
+    ordered.extend(rest)
+    return ordered
+
+
+def _limit_pair(value: Any, name: str) -> tuple[float, float] | None:
+    if value is None:
+        return None
+    if (
+        isinstance(value, (tuple, list))
+        and len(value) == 2
+        and _both_real(value[0], value[1])
+    ):
+        lo, hi = float(value[0]), float(value[1])
+        if hi < lo:
+            lo, hi = hi, lo
+        if hi == lo:
+            hi = lo + 1.0
+        return lo, hi
+    raise ExprError(f"{name} must be a pair of numbers, for example (-2, 2)")
+
+
+def _both_real(a: Any, b: Any) -> bool:
+    try:
+        return np.isfinite(float(a)) and np.isfinite(float(b))
+    except (TypeError, ValueError):
+        return False
+
+
+def _sample_count(geom: _Geom, grid: bool) -> int:
+    chosen = getattr(geom, "n", None)
+    if chosen is None:
+        return _N_GRID if grid else _N_CURVE
+    count = int(chosen)
+    if count < 2:
+        raise ExprError("n must be at least 2")
+    return count
+
+
+def _domain_for(
+    geom: _Geom,
+    axis: str,
+    domains: dict[str, tuple[float, float]],
+) -> tuple[tuple[float, float], str]:
+    """Return ``((lo, hi), source)`` where source is user, data, or default."""
+    explicit = _limit_pair(getattr(geom, axis + "lim", None), axis + "lim")
+    if explicit is not None:
+        return explicit, "user"
+    if axis in domains:
+        return domains[axis], "data"
+    return _DEFAULT_DOMAIN, "default"
+
+
+def _density_domain(formula: Formula) -> tuple[float, float] | None:
+    """Support of a density such as dbeta(x, 2, 5): [0, 1], not (-10, 10)."""
+    if formula.mode != "explicit" or len(formula.variables) != 1:
+        return None
+    return support_hint(
+        getattr(formula, "body", None), formula.variables[0], formula.namespace
+    )
+
+
+def _linspace(lo: float, hi: float, count: int) -> np.ndarray:
+    return np.linspace(float(lo), float(hi), int(count))
+
+
+def _call_formula(formula: Formula, variables: dict[str, np.ndarray]) -> np.ndarray:
+    values = evaluate(formula, variables)
+    shapes = [np.shape(array) for array in variables.values()]
+    target = shapes[0] if shapes else ()
+    if values.shape != target:
+        try:
+            values = np.broadcast_to(values, target).astype(np.float64, copy=True)
+        except ValueError as exc:
+            raise ExprError(
+                "formula result does not match the sampled grid"
+            ) from exc
+    return np.asarray(values, dtype=np.float64)
+
+
+def _expand_curve(geom: _Geom, formula: Formula, axes: _Axes, domains: dict) -> _Geom:
+    # Sideways ``x = f(y)`` samples the vertical axis. Everything else samples x.
+    sample_axis = "y" if axes.computed == "x" else "x"
+    (lo, hi), source = _domain_for(geom, sample_axis, domains)
+    if source == "default":
+        hint = _density_domain(formula)
+        if hint is not None:
+            (lo, hi), source = hint, "density"
+    count = _sample_count(geom, grid=False)
+    samples = _linspace(lo, hi, count)
+    lo, hi, samples = _narrow_curve(
+        formula, axes, samples, lo, hi, source, count
+    )
+    values = _curve_values(formula, axes, samples)
+    if getattr(geom, "n", None) is None:
+        samples, values = _refine_curve(formula, axes, samples, values)
+    view_axis = "x" if axes.computed == "x" else "y"
+    view_lim = _limit_pair(getattr(geom, view_axis + "lim", None), view_axis + "lim")
+    view_name = axes.x if view_axis == "x" else axes.y
+    kept_s, kept_v, lock, index, note = _clip_series(
+        samples, values, view_lim, view_axis, view_name,
+        probe=_curve_probe(formula, axes, samples),
+    )
+    if axes.computed == "x":
+        xs, ys = kept_v, kept_s
+    else:
+        xs, ys = kept_s, kept_v
+    frame = pd.DataFrame({"x": np.asarray(xs, dtype=np.float64), "y": np.asarray(ys, dtype=np.float64)})
+    groups = _groups_from_index(index)
+    if not any(count >= 2 for _start, count in groups):
+        raise ExprError("geom_function() needs at least two points on this domain")
+    # Sideways ``x = f(y)`` must keep sample order. ``_groups`` tells the
+    # encoder not to sort the line and where to break it.
+    maker = geom_path if axes.computed == "x" else geom_line
+    linewidth = getattr(geom, "linewidth", None)
+    out = maker(
+        aes(x="x", y="y"),
+        linewidth=2.0 if linewidth is None else linewidth,
+        color=geom.const_color,
+        alpha=geom.alpha,
+    )
+    out.data_override = frame
+    out._groups = groups
+    out._replace_mapping = True
+    _stamp_formula(out, geom, formula)
+    out._axis_labels = {"x": axes.x, "y": axes.y}
+    if lock is not None:
+        out._axis_lock = {view_axis: lock}
+    if note:
+        out._notes = [note]
+    return out
+
+
+_REFINE_ROUNDS = 8
+_REFINE_MAX_EXTRA = 4000
+
+
+def _refine_curve(formula, axes, samples, values):
+    """More samples where the curve bends sharply between them.
+
+    A narrow peak can fall between evenly spaced samples and be drawn short
+    (exp(-2000 x^2) topping out at 0.71). Wherever three neighbours bend by
+    more than a small share of the curve's height, the two gaps around the
+    middle one get a midpoint, and again, up to a few thousand points.
+    Poles (non-finite values) are left to the clipping that follows.
+    """
+    samples = np.asarray(samples, dtype=np.float64)
+    values = np.asarray(values, dtype=np.float64)
+    finite = np.isfinite(values)
+    if finite.sum() < 3:
+        return samples, values
+    span = float(np.nanmax(values[finite]) - np.nanmin(values[finite]))
+    if not np.isfinite(span) or span <= 0:
+        return samples, values
+    tol = 0.002 * span
+    added = 0
+    for _ in range(_REFINE_ROUNDS):
+        v = values
+        left, mid, right = v[:-2], v[1:-1], v[2:]
+        bend = np.abs(left - 2.0 * mid + right)
+        # Only peaks and valleys: a curve climbing toward a pole bends hard
+        # too, and the clipping that follows must see it as it is.
+        turning = ((mid >= left) & (mid >= right)) | ((mid <= left) & (mid <= right))
+        flagged = np.flatnonzero(np.isfinite(bend) & (bend > tol) & turning) + 1
+        if flagged.size == 0:
+            break
+        gaps = np.unique(np.concatenate([flagged - 1, flagged]))
+        gaps = gaps[(gaps >= 0) & (gaps < samples.size - 1)]
+        gaps = gaps[np.isfinite(values[gaps]) & np.isfinite(values[gaps + 1])]
+        # A big jump across zero is a pole between the samples (tan x).
+        jump = (np.sign(values[gaps]) != np.sign(values[gaps + 1])) & (
+            np.abs(values[gaps] - values[gaps + 1]) > 0.5 * span
+        )
+        gaps = gaps[~jump]
+        # Gaps already finer than float noise cannot be split usefully.
+        width = samples[gaps + 1] - samples[gaps]
+        gaps = gaps[width > 1e-12 * max(1.0, float(np.abs(samples).max()))]
+        if gaps.size == 0 or added + gaps.size > _REFINE_MAX_EXTRA:
+            break
+        mids = 0.5 * (samples[gaps] + samples[gaps + 1])
+        mid_values = _curve_values(formula, axes, mids)
+        samples = np.insert(samples, gaps + 1, mids)
+        values = np.insert(values, gaps + 1, mid_values)
+        added += gaps.size
+    return samples, values
+
+
+def _curve_values(formula: Formula, axes: _Axes, samples: np.ndarray) -> np.ndarray:
+    del axes
+    if formula.mode == "callable":
+        name = formula.fn_args[0]
+        return _call_formula(formula, {name: samples})
+    if not formula.variables:
+        raw = evaluate(formula, {})
+        number = float(np.asarray(raw, dtype=np.float64).reshape(-1)[0])
+        return np.full(samples.shape, number, dtype=np.float64)
+    return _call_formula(formula, {formula.variables[0]: samples})
+
+
+def _narrow_curve(
+    formula: Formula,
+    axes: _Axes,
+    samples: np.ndarray,
+    lo: float,
+    hi: float,
+    source: str,
+    count: int,
+) -> tuple[float, float, np.ndarray]:
+    """Shrink the default domain when the formula is undefined on most of it."""
+    if source != "default":
+        return lo, hi, samples
+    values = _curve_values(formula, axes, samples)
+    finite = np.isfinite(values)
+    fraction = float(np.mean(finite)) if finite.size else 0.0
+    if fraction >= 0.55 or fraction == 0.0:
+        return lo, hi, samples
+    good = samples[finite]
+    nlo, nhi = float(np.min(good)), float(np.max(good))
+    if nhi <= nlo:
+        return lo, hi, samples
+    narrowed = _linspace(nlo, nhi, count)
+    return nlo, nhi, narrowed
+
+
+def _clip_series(
+    samples: np.ndarray,
+    values: np.ndarray,
+    view_lim: tuple[float, float] | None,
+    view_axis: str,
+    note_name: str | None = None,
+    probe: Callable[..., bool] | None = None,
+) -> tuple[np.ndarray, np.ndarray, tuple[float, float] | None, np.ndarray, str | None]:
+    finite = np.isfinite(samples) & np.isfinite(values)
+    if not np.any(finite):
+        raise ExprError("geom_function() is undefined everywhere on this domain")
+    note: str | None = None
+    if view_lim is not None:
+        lo, hi = view_lim
+        keep = finite & (values >= lo) & (values <= hi)
+        lock: tuple[float, float] | None = (lo, hi)
+    else:
+        lo, hi, blew_up = _robust_window(np.where(finite, values, np.nan), probe)
+        # A pole is a thin spike. A piecewise curve (flat, then a parabola)
+        # puts a large share of its samples outside that window; keep them.
+        outside = finite & ((values < lo) | (values > hi))
+        thin = float(np.count_nonzero(outside)) < 0.2 * float(np.count_nonzero(finite))
+        if blew_up and thin:
+            keep = finite & (values >= lo) & (values <= hi)
+            note = _clip_note(note_name or view_axis, lo, hi, param=view_axis)
+        else:
+            keep = finite
+        lock = None
+    if not np.any(keep):
+        raise ExprError(
+            f"geom_function() has no points inside {view_axis}lim="
+            f"({view_lim[0]:.6g}, {view_lim[1]:.6g})"
+            if view_lim is not None
+            else "geom_function() is undefined everywhere on this domain"
+        )
+    index = np.flatnonzero(keep)
+    return samples[index], values[index], lock, index, note
+
+
+def _groups_from_index(index: np.ndarray) -> list[list[int]]:
+    """Break the line wherever clipped samples left a gap."""
+    if index.size == 0:
+        return []
+    groups: list[list[int]] = []
+    start = 0
+    for position in range(1, int(index.size)):
+        if int(index[position]) != int(index[position - 1]) + 1:
+            groups.append([start, position - start])
+            start = position
+    groups.append([start, int(index.size) - start])
+    return groups
+
+
+def _bound(value: float) -> str:
+    """About four significant figures, with a Unicode minus."""
+    return _number(float(value)).pretty
+
+
+def _clip_note(name: str, lo: float, hi: float, *, param: str | None = None) -> str:
+    """Caption for a pole that was clipped to the bulk of the samples.
+
+    ``name`` is the variable the reader sees (``t`` on a surface of ``t``).
+    ``param`` is the keyword that changes the window (``zlim``).
+    """
+    flag = param or name
+    return (
+        f"{name} clipped to [{_bound(lo)}, {_bound(hi)}]; "
+        f"pass {flag}lim= to change"
+    )
+
+
+def _stamp_formula(out, geom, formula: Formula) -> None:
+    """Legend text, and the symbolic form the tooltip shows above the values."""
+    custom = getattr(geom, "label", None)
+    if custom:
+        plain, segments = split_math(str(custom))
+        out._legend_label = plain
+        out._legend_math = segments
+        out._legend_latex = None
+        if formula.mode == "callable":
+            if segments and len(segments) == 1 and segments[0].get("latex"):
+                out._tip_latex = segments[0]["latex"]
+                out._tip_pretty = segments[0]["text"]
+            else:
+                out._tip_latex = ""
+                out._tip_pretty = plain
+        else:
+            out._tip_latex = formula.caption_latex or formula.latex
+            out._tip_pretty = formula.caption_pretty or formula.pretty
+    else:
+        pretty = formula.pretty or formula.label
+        caption = formula.caption_pretty or pretty
+        # The title stays the short symbolic formula. The legend keeps the
+        # symbols and lists the values, so a Beta density does not expand
+        # into ``x^(2 − 1)(1 − x)^(5 − 1)/0.0333333333333``.
+        out._title_label = pretty
+        out._title_latex = formula.latex or None
+        if caption != pretty:
+            out._legend_label = caption
+            out._legend_latex = formula.caption_latex or formula.latex
+        else:
+            out._legend_label = formula.legend_pretty or pretty
+            out._legend_latex = formula.legend_latex or formula.latex or None
+        out._legend_math = None
+        out._tip_latex = formula.caption_latex or formula.latex or ""
+        out._tip_pretty = caption
+    out._is_formula = True
+    out._formula_primary = True
+
+
+def _robust_window(
+    values: np.ndarray, probe: Callable[..., bool] | None = None
+) -> tuple[float, float, bool]:
+    """Return ``(lo, hi, blew_up)`` around the bulk of ``values``.
+
+    Only a side that actually leaves the bulk is pulled in. A density that
+    stays non-negative keeps its own minimum instead of a negative fence.
+
+    ``probe(index, value, sign, centre)`` confirms that the extreme at
+    ``values[index]`` really grows without bound (see ``_keeps_growing``).
+    Without it, anything past the fence counts as a blow-up.
+    """
+    values = np.asarray(values, dtype=np.float64)
+    where = np.flatnonzero(np.isfinite(values))
+    finite = values[where]
+    med = float(np.median(finite))
+    mad = float(np.median(np.abs(finite - med)))
+    scale = max(mad * 1.4826, 1e-9)
+    fence_lo = med - 8.0 * scale
+    fence_hi = med + 8.0 * scale
+    full_lo = float(np.min(finite))
+    full_hi = float(np.max(finite))
+    blew_lo = full_lo < fence_lo - 1e-8
+    blew_hi = full_hi > fence_hi + 1e-8
+    # A steep but finite curve (Beta(5, 1) = 5x^4 near x = 1) also leaves
+    # the fence. Keep its true extreme unless zooming in shows a pole.
+    if probe is not None:
+        if blew_hi:
+            index = int(where[int(np.argmax(finite))])
+            blew_hi = probe(index, full_hi, 1.0, med)
+        if blew_lo:
+            index = int(where[int(np.argmin(finite))])
+            blew_lo = probe(index, full_lo, -1.0, med)
+    lo = fence_lo if blew_lo else full_lo
+    hi = fence_hi if blew_hi else full_hi
+    if hi <= lo:
+        hi = lo + 1.0
+    return lo, hi, blew_lo or blew_hi
+
+
+_ZOOM_POINTS = 41
+_ZOOM_LEVELS = 2
+_ZOOM_GROWTH = 1.5
+_ZOOM_HUGE = 1e6
+
+
+def _keeps_growing(
+    evaluate: Callable[..., np.ndarray],
+    box: list[tuple[float, float]],
+    start: float,
+    sign: float,
+    centre: float,
+) -> bool:
+    """True when the extreme inside ``box`` grows on every zoom.
+
+    ``box`` holds one ``(lo, hi)`` interval per axis, the neighbours of the
+    extreme sample. ``evaluate(*axes)`` returns an array whose axis ``k``
+    follows ``box[k]``. A pole (``1/x``, ``tan x``) moves further from the
+    bulk each time the samples close in on it. A finite maximum, at an edge
+    or in a narrow peak between samples, settles after the first zoom.
+    """
+    distance = sign * (start - centre)
+    if distance <= 0.0:
+        return True
+    first = distance
+    for _level in range(_ZOOM_LEVELS):
+        axes = [np.linspace(lo, hi, _ZOOM_POINTS) for lo, hi in box]
+        try:
+            with np.errstate(all="ignore"):
+                toward = sign * np.asarray(evaluate(*axes), dtype=np.float64)
+        except Exception:
+            return True  # cannot tell; keep the old behaviour
+        if np.any(np.isposinf(toward)):
+            return True  # landed on the pole itself
+        ok = np.isfinite(toward)
+        if not np.any(ok):
+            return True
+        flat = np.where(ok, toward, -np.inf)
+        best = int(np.argmax(flat))
+        reached = float(flat.reshape(-1)[best]) - sign * centre
+        ratio = reached / distance
+        if ratio < 0.5:
+            # The sampled extreme vanished when resampled: a rounding spike
+            # beside a singularity (x*y/(x^2 - y^2) on the diagonal).
+            return True
+        if reached > first * _ZOOM_HUGE:
+            # Float precision stops the next zoom from closing in further.
+            return True
+        position = np.unravel_index(best, flat.shape)
+        if ratio < _ZOOM_GROWTH:
+            # Settled. A true maximum is continuous: the zoom points right
+            # beside it are nearly as high. An isolated point is rounding
+            # noise at a singularity, which should still be clipped.
+            near = tuple(
+                slice(max(int(i) - 1, 0), int(i) + 2) for i in position
+            )
+            around = flat[near].copy()
+            around[tuple(int(i) - s.start for i, s in zip(position, near))] = -np.inf
+            beside = float(np.max(around)) - sign * centre
+            return bool(beside < 0.5 * reached)
+        distance = reached
+        box = [
+            (
+                float(axis[max(int(i) - 1, 0)]),
+                float(axis[min(int(i) + 1, _ZOOM_POINTS - 1)]),
+            )
+            for axis, i in zip(axes, position)
+        ]
+    return True
+
+
+def _neighbours(axis: np.ndarray, i: int) -> tuple[float, float]:
+    return float(axis[max(i - 1, 0)]), float(axis[min(i + 1, axis.size - 1)])
+
+
+def _curve_probe(formula: Formula, axes: _Axes, samples: np.ndarray):
+    def evaluate(xs: np.ndarray) -> np.ndarray:
+        return _curve_values(formula, axes, xs)
+
+    def probe(index: int, value: float, sign: float, centre: float) -> bool:
+        box = [_neighbours(samples, index)]
+        return _keeps_growing(evaluate, box, value, sign, centre)
+
+    return probe
+
+
+def _surface_probe(formula: Formula, axes: _Axes, xs: np.ndarray, ys: np.ndarray):
+    """Probe for a flat index into a ``(len(ys), len(xs))`` grid."""
+
+    def evaluate(x_axis: np.ndarray, y_axis: np.ndarray) -> np.ndarray:
+        return _surface_values(formula, axes, x_axis, y_axis).T
+
+    def probe(index: int, value: float, sign: float, centre: float) -> bool:
+        row, col = divmod(index, xs.size)
+        box = [_neighbours(xs, col), _neighbours(ys, row)]
+        return _keeps_growing(evaluate, box, value, sign, centre)
+
+    return probe
+
+
+def _expand_surface(
+    geom: _Geom, formula: Formula, axes: _Axes, domains: dict
+) -> _Geom:
+    count = _sample_count(geom, grid=True)
+    (xlo, xhi), x_source = _domain_for(geom, "x", domains)
+    (ylo, yhi), y_source = _domain_for(geom, "y", domains)
+    xs = _linspace(xlo, xhi, count)
+    ys = _linspace(ylo, yhi, count)
+    zz = _surface_values(formula, axes, xs, ys)
+    xs, ys, zz = _narrow_surface(
+        formula,
+        axes,
+        xs,
+        ys,
+        zz,
+        x_source == "default" and _limit_pair(geom.xlim, "xlim") is None,
+        y_source == "default" and _limit_pair(geom.ylim, "ylim") is None,
+        count,
+    )
+    zz, lock, note = _clip_grid(
+        zz, _limit_pair(geom.zlim, "zlim"), axes.z or "z",
+        probe=_surface_probe(formula, axes, xs, ys),
+    )
+    xx, yy = np.meshgrid(xs, ys)
+    frame = pd.DataFrame(
+        {
+            "x": xx.ravel(),
+            "y": yy.ravel(),
+            "z": zz.ravel(),
+        }
+    )
+    # No colour of your own: colour by height, so the shape reads in print.
+    by_height = geom.const_color is None
+    if by_height:
+        frame["height"] = frame["z"]
+    vertices, indices, nx, ny = regular_grid_mesh(
+        frame, "x", "y", "z", ccol="height" if by_height else None
+    )
+    colour_col = "colour" if by_height and "colour" in vertices.columns else None
+    out = _Geom(
+        aes(x="x", y="y", z="z", colour=colour_col),
+        color=geom.const_color,
+        alpha=geom.alpha if geom.alpha is not None else 0.95,
+    )
+    out.kind = "surface"
+    if colour_col:
+        out._default_ramp = "viridis"
+        out._colour_title = axes.z or "z"
+    out.data_override = vertices
+    out.const_color = geom.const_color
+    out.alpha = geom.alpha if geom.alpha is not None else 0.95
+    out.wireframe = bool(getattr(geom, "wireframe", False))
+    out._indices = indices
+    out._nx = nx
+    out._ny = ny
+    out._replace_mapping = True
+    _stamp_formula(out, geom, formula)
+    out._axis_labels = {"x": axes.x, "y": axes.y, "z": axes.z or "z"}
+    out._function_surface = True
+    if lock is not None:
+        out._axis_lock = {"z": lock}
+    if note:
+        out._notes = [note]
+    return out
+
+
+def _surface_values(
+    formula: Formula, axes: _Axes, xs: np.ndarray, ys: np.ndarray
+) -> np.ndarray:
+    xx, yy = np.meshgrid(xs, ys)
+    if formula.mode == "callable":
+        return _call_formula(
+            formula,
+            {formula.fn_args[0]: xx, formula.fn_args[1]: yy},
+        )
+    return _call_formula(formula, {axes.x: xx, axes.y: yy})
+
+
+def _narrow_surface(
+    formula: Formula,
+    axes: _Axes,
+    xs: np.ndarray,
+    ys: np.ndarray,
+    zz: np.ndarray,
+    narrow_x: bool,
+    narrow_y: bool,
+    count: int,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    finite = np.isfinite(zz)
+    fraction = float(np.mean(finite)) if finite.size else 0.0
+    if fraction >= 0.55 or fraction == 0.0 or not (narrow_x or narrow_y):
+        return xs, ys, zz
+    rows = np.any(finite, axis=1)
+    cols = np.any(finite, axis=0)
+    if narrow_y and np.any(rows):
+        ys = _linspace(float(ys[rows][0]), float(ys[rows][-1]), count)
+    if narrow_x and np.any(cols):
+        xs = _linspace(float(xs[cols][0]), float(xs[cols][-1]), count)
+    return xs, ys, _surface_values(formula, axes, xs, ys)
+
+
+def _clip_grid(
+    zz: np.ndarray,
+    zlim: tuple[float, float] | None,
+    note_name: str = "z",
+    probe: Callable[..., bool] | None = None,
+) -> tuple[np.ndarray, tuple[float, float] | None, str | None]:
+    finite = zz[np.isfinite(zz)]
+    if finite.size == 0:
+        raise ExprError("geom_function() is undefined everywhere on this domain")
+    if zlim is not None:
+        lo, hi = zlim
+        clipped = np.clip(np.where(np.isfinite(zz), zz, lo), lo, hi)
+        return clipped, (lo, hi), None
+    lo, hi, blew_up = _robust_window(zz.ravel(), probe)
+    if not blew_up:
+        filled = np.where(np.isfinite(zz), zz, float(np.median(finite)))
+        return filled, None, None
+    filled = np.where(np.isfinite(zz), zz, lo)
+    filled = np.clip(filled, lo, hi)
+    return filled, (lo, hi), _clip_note(note_name, lo, hi, param="z")
+
+
+def _expand_implicit(
+    geom: _Geom, formula: Formula, axes: _Axes, domains: dict
+) -> _Geom:
+    count = _sample_count(geom, grid=True)
+    (xlo, xhi), _x_source = _domain_for(geom, "x", domains)
+    (ylo, yhi), _y_source = _domain_for(geom, "y", domains)
+    xs = _linspace(xlo, xhi, count)
+    ys = _linspace(ylo, yhi, count)
+    xx, yy = np.meshgrid(xs, ys)
+    field = _call_formula(formula, {axes.x: xx, axes.y: yy})
+
+    def sample(xx_fine: np.ndarray, yy_fine: np.ndarray) -> np.ndarray:
+        return _call_formula(formula, {axes.x: xx_fine, axes.y: yy_fine})
+
+    # The base grid stays at ``n`` (default 80). Only cells the contour
+    # crosses are subdivided, so a small loop stays smooth beside a long
+    # curve. A full-window refit cannot separate those two pieces. If the
+    # finer grid would be too large, keep the coarse contour.
+    polylines = _refine_active_cells(xs, ys, field, 0.0, sample)
+    if polylines is None:
+        polylines = _contour_lines(xs, ys, field, 0.0)
+    if not polylines:
+        raise ExprError(
+            "geom_function() found no curve where the equation is zero "
+            "on this domain. Try a wider xlim= and ylim="
+        )
+    rows_x: list[float] = []
+    rows_y: list[float] = []
+    groups: list[list[int]] = []
+    for poly in polylines:
+        if len(poly) < 2:
+            continue
+        start = len(rows_x)
+        for x_val, y_val in poly:
+            rows_x.append(x_val)
+            rows_y.append(y_val)
+        groups.append([start, len(rows_x) - start])
+    if not groups:
+        raise ExprError(
+            "geom_function() found no curve where the equation is zero "
+            "on this domain. Try a wider xlim= and ylim="
+        )
+    frame = pd.DataFrame({"x": rows_x, "y": rows_y})
+    linewidth = getattr(geom, "linewidth", None)
+    out = geom_path(
+        aes(x="x", y="y"),
+        linewidth=2.0 if linewidth is None else linewidth,
+        color=geom.const_color,
+        alpha=geom.alpha,
+    )
+    out.data_override = frame
+    out.sort_x = False
+    out._groups = groups
+    out._replace_mapping = True
+    out._implicit = True
+    _stamp_formula(out, geom, formula)
+    out._axis_labels = {"x": axes.x, "y": axes.y}
+    return out
+
+
+_MISSING = object()
+
+
+@contextmanager
+def _bound_params(formula: Formula, params: dict[str, float]):
+    """Inject sweep values for one frame, then restore the namespace."""
+    saved: list[tuple[str, Any]] = []
+    try:
+        for name, value in params.items():
+            saved.append((name, formula.namespace.get(name, _MISSING)))
+            formula.namespace[name] = float(value)
+        yield
+    finally:
+        for name, old in saved:
+            if old is _MISSING:
+                formula.namespace.pop(name, None)
+            else:
+                formula.namespace[name] = old
+
+
+def _sweep(transition: Any) -> list[dict[str, float]]:
+    """One shared step for every parameter, from lo to hi across ``frames``."""
+    count = int(transition.frames)
+    weights = np.linspace(0.0, 1.0, count)
+    steps: list[dict[str, float]] = []
+    for weight in weights:
+        t = float(weight)
+        steps.append(
+            {
+                name: float(lo + t * (hi - lo))
+                for name, (lo, hi) in transition.ranges.items()
+            }
+        )
+    return steps
+
+
+# nSamples * nFrames. A 501-point curve at 25x25 fits; a default surface
+# (80x80) times two 25-step sliders does not. Raise instead of thinning.
+_SLIDER_CELL_CAP = 500_000
+
+
+def _slider_frame_count(source: Any) -> int:
+    if getattr(source, "kind", None) != "slider":
+        return 0
+    n = 1
+    for _name in source.ranges:
+        n *= int(source.steps)
+    return n
+
+
+def _guard_slider(source: Any, n_samples: int, what: str) -> None:
+    n_frames = _slider_frame_count(source)
+    if not n_frames:
+        return
+    cells = int(n_samples) * n_frames
+    if cells <= _SLIDER_CELL_CAP:
+        return
+    raise ValueError(
+        f"slider() would sample {n_frames} frames of {n_samples} {what} "
+        f"({cells} values). Pass a smaller steps= or n=."
+    )
+
+
+def _parameter_steps(source: Any) -> list[dict[str, float]]:
+    """Frame parameters. A transition locksteps; a slider is the full grid.
+
+    Grid order is C-order, last keyword fastest, matching
+    ``np.meshgrid(..., indexing='ij')`` then ravel.
+    """
+    if getattr(source, "kind", None) != "slider":
+        return _sweep(source)
+    names = list(source.ranges)
+    axes = [
+        np.linspace(float(lo), float(hi), int(source.steps))
+        for lo, hi in source.ranges.values()
+    ]
+    grids = np.meshgrid(*axes, indexing="ij")
+    flat = [np.asarray(g, dtype=np.float64).ravel() for g in grids]
+    n = int(flat[0].size)
+    return [
+        {name: float(flat[k][i]) for k, name in enumerate(names)}
+        for i in range(n)
+    ]
+
+
+def _static_col(source: Any) -> int:
+    """Column shown with JavaScript off.
+
+    Sliders open with every thumb at the low end. A transition keeps the
+    last frame, which is the frame a paused chart already showed.
+    """
+    if getattr(source, "kind", None) == "slider":
+        return 0
+    return -1
+
+
+def _shared_frame_window(
+    mat: np.ndarray,
+    probe: Callable[..., bool] | None = None,
+) -> tuple[float, float, bool]:
+    """One clip window from every frame, without letting quiet frames shrink it.
+
+    A frame that stays inside its own robust window contributes its true
+    min and max. A frame with a pole contributes only that robust window.
+    Quiet frames (``a = 0``) would otherwise pull a pooled median toward
+    zero and clip a wave that is perfectly finite on its own.
+    """
+    healthy_lo = float("inf")
+    healthy_hi = -float("inf")
+    robust_lo = float("inf")
+    robust_hi = -float("inf")
+    any_blow = False
+    any_healthy = False
+    for col in range(mat.shape[1]):
+        column = mat[:, col]
+        values = column[np.isfinite(column)]
+        if values.size == 0:
+            continue
+        frame_probe = None if probe is None else partial(probe, col)
+        lo, hi, blew_up = _robust_window(column, frame_probe)
+        if blew_up:
+            any_blow = True
+            robust_lo = min(robust_lo, lo)
+            robust_hi = max(robust_hi, hi)
+        else:
+            any_healthy = True
+            healthy_lo = min(healthy_lo, float(np.min(values)))
+            healthy_hi = max(healthy_hi, float(np.max(values)))
+    if not any_blow:
+        return 0.0, 0.0, False
+    if any_healthy:
+        lo = min(robust_lo, healthy_lo)
+        hi = max(robust_hi, healthy_hi)
+    else:
+        lo, hi = robust_lo, robust_hi
+    if hi <= lo:
+        hi = lo + 1.0
+    return lo, hi, True
+
+
+def _clip_matrix(
+    mat: np.ndarray,
+    view_lim: tuple[float, float] | None,
+    view_axis: str,
+    note_name: str | None,
+    probe: Callable[..., bool] | None = None,
+) -> tuple[np.ndarray, tuple[float, float] | None, str | None]:
+    """One window for every frame. Vertices stay; poles are clipped, not dropped."""
+    finite = mat[np.isfinite(mat)]
+    if finite.size == 0:
+        raise ExprError("geom_function() is undefined everywhere on this domain")
+    if view_lim is not None:
+        lo, hi = view_lim
+        filled = np.where(np.isfinite(mat), mat, lo)
+        return np.clip(filled, lo, hi), (lo, hi), None
+    lo, hi, blew_up = _shared_frame_window(mat, probe)
+    if blew_up:
+        filled = np.where(np.isfinite(mat), mat, lo)
+        return (
+            np.clip(filled, lo, hi),
+            (lo, hi),
+            _clip_note(note_name or view_axis, lo, hi, param=view_axis),
+        )
+    fill = float(np.median(finite))
+    return np.where(np.isfinite(mat), mat, fill), None, None
+
+
+def _curve_matrix(
+    formula: Formula, samples: np.ndarray, steps: list[dict[str, float]]
+) -> np.ndarray:
+    columns = []
+    for params in steps:
+        with _bound_params(formula, params):
+            columns.append(_curve_values(formula, None, samples))
+    return np.column_stack(columns)
+
+
+def _expand_animated(geom, formula, axes, domains, transition) -> _Geom:
+    if axes.kind == "surface":
+        return _expand_surface_anim(geom, formula, axes, domains, transition)
+    if axes.kind == "implicit":
+        return _expand_implicit_anim(geom, formula, axes, domains, transition)
+    return _expand_curve_anim(geom, formula, axes, domains, transition)
+
+
+def _expand_curve_anim(geom, formula, axes, domains, transition) -> _Geom:
+    # Same samples on every frame, so the line can tween vertex for vertex.
+    sample_axis = "y" if axes.computed == "x" else "x"
+    (lo, hi), source = _domain_for(geom, sample_axis, domains)
+    count = _sample_count(geom, grid=False)
+    _guard_slider(transition, count, "curve samples")
+    steps = _parameter_steps(transition)
+    if source == "default":
+        # dbeta(x, a, b) under a slider: every frame's support, once.
+        spans = []
+        for params in steps:
+            with _bound_params(formula, params):
+                spans.append(_density_domain(formula))
+        if spans and all(span is not None for span in spans):
+            lo = min(span[0] for span in spans)
+            hi = max(span[1] for span in spans)
+            source = "density"
+    samples = _linspace(lo, hi, count)
+    mat = _curve_matrix(formula, samples, steps)
+    if source == "default":
+        finite = np.isfinite(mat)
+        fraction = float(np.mean(finite)) if finite.size else 0.0
+        if 0.0 < fraction < 0.55:
+            good = np.any(finite, axis=1)
+            if np.any(good):
+                nlo = float(np.min(samples[good]))
+                nhi = float(np.max(samples[good]))
+                if nhi > nlo:
+                    samples = _linspace(nlo, nhi, count)
+                    mat = _curve_matrix(formula, samples, steps)
+    view_axis = "x" if axes.computed == "x" else "y"
+    view_lim = _limit_pair(getattr(geom, view_axis + "lim", None), view_axis + "lim")
+    view_name = axes.x if view_axis == "x" else axes.y
+    def frame_probe(col: int, index: int, value: float, sign: float, centre: float) -> bool:
+        with _bound_params(formula, steps[col]):
+            return _curve_probe(formula, axes, samples)(index, value, sign, centre)
+
+    mat, lock, note = _clip_matrix(mat, view_lim, view_axis, view_name, frame_probe)
+    n_frames = mat.shape[1]
+    repeated = np.repeat(samples[:, None], n_frames, axis=1)
+    if axes.computed == "x":
+        x_mat, y_mat = mat, repeated
+    else:
+        x_mat, y_mat = repeated, mat
+    shown = _static_col(transition)
+    frame = pd.DataFrame(
+        {
+            "x": np.asarray(x_mat[:, shown], dtype=np.float64),
+            "y": np.asarray(y_mat[:, shown], dtype=np.float64),
+        }
+    )
+    maker = geom_path if axes.computed == "x" else geom_line
+    linewidth = getattr(geom, "linewidth", None)
+    out = maker(
+        aes(x="x", y="y"),
+        linewidth=2.0 if linewidth is None else linewidth,
+        color=geom.const_color,
+        alpha=geom.alpha,
+    )
+    out.data_override = frame
+    out._groups = [[0, int(samples.size)]]
+    out._replace_mapping = True
+    _stamp_formula(out, geom, formula)
+    out._axis_labels = {"x": axes.x, "y": axes.y}
+    if lock is not None:
+        out._axis_lock = {view_axis: lock}
+    if note:
+        out._notes = [note]
+    anim = {
+        "mode": "tween",
+        "channels": {"x": x_mat, "y": y_mat},
+    }
+    if shown == 0:
+        anim["static_col"] = 0
+    out._anim = anim
+    return out
+
+
+def _expand_surface_anim(geom, formula, axes, domains, transition) -> _Geom:
+    count = _sample_count(geom, grid=True)
+    _guard_slider(transition, count * count, "surface vertices")
+    (xlo, xhi), x_source = _domain_for(geom, "x", domains)
+    (ylo, yhi), y_source = _domain_for(geom, "y", domains)
+    xs = _linspace(xlo, xhi, count)
+    ys = _linspace(ylo, yhi, count)
+    steps = _parameter_steps(transition)
+
+    def grids(x_axis: np.ndarray, y_axis: np.ndarray) -> np.ndarray:
+        layers = []
+        for params in steps:
+            with _bound_params(formula, params):
+                layers.append(_surface_values(formula, axes, x_axis, y_axis))
+        return np.stack(layers, axis=-1)
+
+    stack = grids(xs, ys)
+    finite = np.isfinite(stack)
+    fraction = float(np.mean(finite)) if finite.size else 0.0
+    narrow_x = x_source == "default"
+    narrow_y = y_source == "default"
+    if 0.0 < fraction < 0.55 and (narrow_x or narrow_y):
+        any_finite = np.any(finite, axis=-1)
+        rows = np.any(any_finite, axis=1)
+        cols = np.any(any_finite, axis=0)
+        if narrow_y and np.any(rows):
+            ys = _linspace(float(ys[rows][0]), float(ys[rows][-1]), count)
+        if narrow_x and np.any(cols):
+            xs = _linspace(float(xs[cols][0]), float(xs[cols][-1]), count)
+        stack = grids(xs, ys)
+    zlim = _limit_pair(geom.zlim, "zlim")
+    flat = stack.reshape(-1, stack.shape[-1])
+    def frame_probe(col: int, index: int, value: float, sign: float, centre: float) -> bool:
+        with _bound_params(formula, steps[col]):
+            return _surface_probe(formula, axes, xs, ys)(index, value, sign, centre)
+
+    z_mat, lock, note = _clip_matrix(flat, zlim, "z", axes.z or "z", frame_probe)
+    xx, yy = np.meshgrid(xs, ys)
+    n_frames = z_mat.shape[1]
+    shown = _static_col(transition)
+    last = pd.DataFrame(
+        {
+            "x": xx.ravel(),
+            "y": yy.ravel(),
+            "z": np.asarray(z_mat[:, shown], dtype=np.float64),
+        }
+    )
+    vertices, indices, nx, ny = regular_grid_mesh(last, "x", "y", "z")
+    vx = vertices["x"].to_numpy(dtype=np.float64)
+    vy = vertices["y"].to_numpy(dtype=np.float64)
+    if np.allclose(vx, xx.ravel()) and np.allclose(vy, yy.ravel()):
+        src = np.arange(xx.size)
+    else:
+        ix = np.clip(np.searchsorted(xs, vx), 0, len(xs) - 1)
+        iy = np.clip(np.searchsorted(ys, vy), 0, len(ys) - 1)
+        src = iy * len(xs) + ix
+    x_mat = np.repeat(xx.ravel()[:, None], n_frames, axis=1)[src]
+    y_mat = np.repeat(yy.ravel()[:, None], n_frames, axis=1)[src]
+    z_ordered = z_mat[src]
+    out = _Geom(
+        aes(x="x", y="y", z="z"),
+        color=geom.const_color,
+        alpha=geom.alpha if geom.alpha is not None else 0.95,
+    )
+    out.kind = "surface"
+    out.data_override = vertices
+    out.const_color = geom.const_color
+    out.alpha = geom.alpha if geom.alpha is not None else 0.95
+    out.wireframe = bool(getattr(geom, "wireframe", False))
+    out._indices = indices
+    out._nx = nx
+    out._ny = ny
+    out._replace_mapping = True
+    _stamp_formula(out, geom, formula)
+    out._axis_labels = {"x": axes.x, "y": axes.y, "z": axes.z or "z"}
+    out._function_surface = True
+    if lock is not None:
+        out._axis_lock = {"z": lock}
+    if note:
+        out._notes = [note]
+    anim = {
+        "mode": "tween",
+        "channels": {"x": x_mat, "y": y_mat, "z": z_ordered},
+    }
+    if shown == 0:
+        anim["static_col"] = 0
+    out._anim = anim
+    return out
+
+
+def _rows_from_polylines(polylines) -> tuple[np.ndarray, np.ndarray, list]:
+    rows_x: list[float] = []
+    rows_y: list[float] = []
+    groups: list[list[int]] = []
+    for poly in polylines or []:
+        if len(poly) < 2:
+            continue
+        start = len(rows_x)
+        for x_val, y_val in poly:
+            rows_x.append(float(x_val))
+            rows_y.append(float(y_val))
+        groups.append([start, len(rows_x) - start])
+    return (
+        np.asarray(rows_x, dtype=np.float64),
+        np.asarray(rows_y, dtype=np.float64),
+        groups,
+    )
+
+
+def _expand_implicit_anim(geom, formula, axes, domains, transition) -> _Geom:
+    # Vertex counts change with the parameter, so frames are shown as-is.
+    count = _sample_count(geom, grid=True)
+    _guard_slider(transition, count * count, "grid samples")
+    (xlo, xhi), _x_source = _domain_for(geom, "x", domains)
+    (ylo, yhi), _y_source = _domain_for(geom, "y", domains)
+    xs = _linspace(xlo, xhi, count)
+    ys = _linspace(ylo, yhi, count)
+    steps = _parameter_steps(transition)
+    frames: list[dict] = []
+    static = None
+    static_i = 0
+    # A slider opens at the low end, so the fallback curve is the first
+    # non-empty frame. A transition keeps the last one.
+    keep_first = getattr(transition, "kind", None) == "slider"
+    for index, params in enumerate(steps):
+
+        def sample(xx_fine, yy_fine, params=params):
+            with _bound_params(formula, params):
+                return _call_formula(formula, {axes.x: xx_fine, axes.y: yy_fine})
+
+        with _bound_params(formula, params):
+            xx, yy = np.meshgrid(xs, ys)
+            field = _call_formula(formula, {axes.x: xx, axes.y: yy})
+        polylines = _refine_active_cells(xs, ys, field, 0.0, sample)
+        if polylines is None:
+            polylines = _contour_lines(xs, ys, field, 0.0)
+        rows_x, rows_y, groups = _rows_from_polylines(polylines)
+        frame = {"x": rows_x, "y": rows_y, "groups": groups}
+        frames.append(frame)
+        if rows_x.size >= 2 and (static is None or not keep_first):
+            static = frame
+            static_i = index
+    if static is None:
+        raise ExprError(
+            "geom_function() found no curve where the equation is zero "
+            "on this domain. Try a wider xlim= and ylim="
+        )
+    drawn = pd.DataFrame({"x": static["x"], "y": static["y"]})
+    linewidth = getattr(geom, "linewidth", None)
+    out = geom_path(
+        aes(x="x", y="y"),
+        linewidth=2.0 if linewidth is None else linewidth,
+        color=geom.const_color,
+        alpha=geom.alpha,
+    )
+    out.data_override = drawn
+    out.sort_x = False
+    out._groups = static["groups"]
+    out._replace_mapping = True
+    out._implicit = True
+    _stamp_formula(out, geom, formula)
+    out._axis_labels = {"x": axes.x, "y": axes.y}
+    out._anim = {"mode": "step", "frames": frames, "static": int(static_i)}
+    return out