perf(shapes): adaptive circle-buffer resolution for the datashader path

Circles (Point+radius) were buffered to polygons at shapely's default resolution=16
(65 vertices/circle) before datashader rasterization. For large circle sets this
coordinate explosion dominates the render (buffer + per-vertex transform + polygon
aggregation), e.g. ~5.9M coords for 91k circles.

Choose the buffer resolution from the largest disc's on-screen pixel radius
(_circle_buffer_quad_segs / _circle_quad_segs): 4 segments/quadrant for small discs
(<=8px, where extra vertices are sub-pixel), 8 (<=32px), and shapely's full 16 once
discs are large enough to show facets. Faithful (IoU >=0.98 vs the 65-vertex circle)
and handles per-circle varying radii.

End-to-end on Visium HD (single coordinate system): 91k circles 2.0s->1.5s,
352k circles 8.3s->4.9s.

Note: shifts the datashader-circle visual baselines (17- vs 65-vertex circles);
regenerate those from CI artifacts.

Author: timtreis

src/spatialdata_plot/pl/_datashader.py

@@ -721,6 +721,48 @@ def _pad_degenerate_extent(ext: list[Any]) -> list[Any]:
     return [ext[0] - 0.5, ext[1] + 0.5] if ext[1] == ext[0] else ext
 
 
+def _circle_quad_segs(max_radius_px: float) -> int:
+    """Segments-per-quadrant for buffering circles, chosen by the largest disc's on-screen radius.
+
+    Circles are stored as ``Point + radius`` and buffered to polygons before datashader rasterizes
+    them; shapely's default (``resolution=16`` = 65 vertices) is far more than a small disc needs and
+    dominates the render cost for large circle sets. Use fewer vertices when discs are small (their
+    extra vertices are sub-pixel and invisible) and only step up to the full default once discs are
+    large enough to show facets. ``NaN`` (e.g. all-NaN radius) falls through to the faithful default.
+    """
+    if max_radius_px <= 8:
+        return 4
+    if max_radius_px <= 32:
+        return 8
+    return 16
+
+
+def _circle_buffer_quad_segs(
+    centroids_xy: np.ndarray,
+    max_radius: float,
+    tm: np.ndarray,
+    fig_params: FigParams,
+) -> int:
+    """Pick the circle-buffer ``resolution`` from the largest circle's on-screen pixel radius.
+
+    Estimates the same world-units-per-pixel ``factor`` the datashader canvas will use (mirrors
+    ``_compute_datashader_canvas_params``), computed *before* buffering from the transformed centroids
+    expanded by the (major-axis) radius. ``tm`` is the coordinate-system affine; an anisotropic/shear
+    transform turns the circle into an ellipse, so size to its largest stretch (major axis).
+    """
+    linear = tm[:2, :2]
+    stretch = float(np.linalg.svd(linear, compute_uv=False).max())  # circle -> ellipse major-axis scale
+    r_t = float(max_radius) * stretch
+    xy_t = centroids_xy @ linear.T + tm[:2, 2]
+    ext_w = (xy_t[:, 0].max() + r_t) - (xy_t[:, 0].min() - r_t)
+    ext_h = (xy_t[:, 1].max() + r_t) - (xy_t[:, 1].min() - r_t)
+    fig = fig_params.fig
+    fig_px_w = fig.get_size_inches()[0] * fig.dpi
+    fig_px_h = fig.get_size_inches()[1] * fig.dpi
+    factor = max(ext_w / fig_px_w, ext_h / fig_px_h)
+    return _circle_quad_segs(r_t / factor if factor > 0 else 0.0)
+
+
 def _compute_datashader_canvas_params(
     x_ext: list[Any],
     y_ext: list[Any],

src/spatialdata_plot/pl/render.py

@@ -46,6 +46,7 @@
 from spatialdata_plot.pl._datashader import (
     _ax_show_and_transform,
     _build_ds_colorbar,
+    _circle_buffer_quad_segs,
     _datashader_canvas_from_dataframe,
     _get_extent_and_range_for_datashader_canvas,
     _hex_no_alpha,
@@ -770,14 +771,19 @@ def _render_shapes(
     if method == "datashader":
         _geometry = shapes["geometry"]
         is_point = _geometry.type == "Point"
+        tm = trans.get_matrix()  # coordinate-system affine; reused for circle sizing and the transform below
 
         # Handle circles encoded as points with radius
         if is_point.any():
-            radius_values = shapes[is_point]["radius"]
             # Convert to numeric, replacing non-numeric values with NaN
-            radius_numeric = pd.to_numeric(radius_values, errors="coerce")
-            scale = radius_numeric * render_params.scale
-            shapes.loc[is_point, "geometry"] = _geometry[is_point].buffer(scale.to_numpy())
+            radius = (pd.to_numeric(shapes[is_point]["radius"], errors="coerce") * render_params.scale).to_numpy()
+            points = _geometry[is_point]
+            # Buffer at a vertex count matched to the largest disc's on-screen size: tiny discs don't
+            # need shapely's 65-vertex default, which otherwise dominates the render for large sets.
+            quad_segs = _circle_buffer_quad_segs(
+                np.column_stack([points.x.to_numpy(), points.y.to_numpy()]), float(np.nanmax(radius)), tm, fig_params
+            )
+            shapes.loc[is_point, "geometry"] = points.buffer(radius, resolution=quad_segs)
 
         # Handle polygon/multipolygon scaling
         is_polygon = _geometry.type.isin(["Polygon", "MultiPolygon"])
@@ -789,7 +795,6 @@ def _render_shapes(
             )
 
         # apply transformations to the individual points
-        tm = trans.get_matrix()
         transformed_geometry = shapes["geometry"].transform(
             lambda x: (np.hstack([x, np.ones((x.shape[0], 1))]) @ tm.T)[:, :2]
         )

tests/pl/test_render_shapes.py

@@ -1839,3 +1839,25 @@ def test_continuous_fill_colorbar_matches_pixel_range(sdata_blobs_shapes_annotat
     clims = [c.get_clim() for c in ax.collections if isinstance(c, PatchCollection)]
     plt.close(fig)
     assert clims == [(1.0, 5.0)]  # fixture's value column is [1, 2, 3, 4, 5]
+
+
+# ---------------------------------------------------------------------------
+# Adaptive circle buffer resolution (datashader perf)
+# ---------------------------------------------------------------------------
+
+
+def test_circle_quad_segs_step_rule():
+    """quad_segs steps up with on-screen disc radius: ≤8px→4, ≤32px→8, else 16 (NaN→faithful 16)."""
+    from spatialdata_plot.pl._datashader import _circle_quad_segs
+
+    assert [_circle_quad_segs(r) for r in (0.5, 8.0, 8.1, 32.0, 33.0, 500.0)] == [4, 4, 8, 8, 16, 16]
+    assert _circle_quad_segs(float("nan")) == 16  # all-NaN radius falls back to the faithful default
+
+
+def test_circle_buffer_fidelity_to_default():
+    """A reduced-vertex circle (quad_segs=4) still matches shapely's default (resolution=16) within 3%."""
+    c = Point(5.0, 5.0)
+    reduced = c.buffer(1.0, quad_segs=4)
+    full = c.buffer(1.0, quad_segs=16)
+    iou = reduced.intersection(full).area / reduced.union(full).area
+    assert iou >= 0.97