perf(shapes): datashader renders large uniform circle sets as points

On the datashader backend, buffering every circle (Point+radius) to a polygon dominates
the render for large sets. A large (>50k), uniform-radius, outline-free circle element is
a dot-field where a filled disc and a spread point are visually equivalent, so rasterize
centroids as radius-faithful points (_circles_render_as_points gate + radius-aware spread
in _datashader_points) instead of buffering. This is datashader-backend behavior; use
method="matplotlib" for a pixel-exact rendering. Per-circle varying radii, outlines, and
custom shapes keep the polygon path.

`as_points` stays a simple bool (style: dots vs geometry) and is itself a speedup on both
backends; it is orthogonal to this datashader optimization.

Adds a 2x2 visual test (geometry/as_points x matplotlib/datashader) verifying the four
render paths look alike, incl. the datashader fast-path matching exact matplotlib discs.

End-to-end on Visium HD (single coordinate system): 91k circles 6.85s->0.56s vs v0.4.0,
352k 22.95s->1.14s, 5.5M 002um impractical->~12.7s; method="matplotlib" stays exact.

Author: timtreis

src/spatialdata_plot/pl/basic.py

@@ -444,10 +444,16 @@ def render_shapes(
             Reduction method for datashader when coloring by continuous values. When ``None``, defaults to ``"max"``.
         transfunc : Callable[[float], float] | None, optional
             Optional transformation applied to the continuous color vector before normalization and colormap mapping.
+        as_points : bool
+            If ``True``, draw one ``size``-d dot per shape centroid instead of its full geometry
+            (faster for large sets; available on both the matplotlib and datashader backends).
 
         Notes
         -----
         - Empty geometries will be removed at the time of plotting.
+        - On the datashader backend, a large (>50k) uniform-radius, outline-free circle element is
+          rendered as radius-faithful points for speed (visually equivalent at that scale); pass
+          ``method="matplotlib"`` for a pixel-exact rendering of every circle.
         - An `outline_width` of 0.0 leads to no border being plotted.
         - If ``color`` is a string that is both a matplotlib color name and a column name in the
           element or an annotating table, a ``ValueError`` is raised. Disambiguate by passing

src/spatialdata_plot/pl/render.py

@@ -573,6 +573,32 @@ def _check_instance_ids_overlap(
         )
 
 
+# Above this many circles, a uniform-radius outline-free element is a dot-field where buffering every
+# circle to a polygon dominates the render; rasterizing centroids as spread discs is far cheaper and
+# visually equivalent at that scale.
+_CIRCLE_FAST_PATH_MIN = 50_000
+
+
+def _circles_render_as_points(shapes: gpd.GeoDataFrame, is_point: Any, render_params: ShapesRenderParams) -> bool:
+    """Gate for the datashader circle fast-path: a large, uniform-radius, outline-free, default-shape element.
+
+    A datashader speed optimization (use ``method="matplotlib"`` for exact circles), restricted so the
+    point approximation never silently distorts: per-circle varying radii and outlines can't be
+    reproduced by a single uniform spread, and a custom ``shape`` is meaningless for points.
+    """
+    if (
+        render_params.shape is not None
+        or "radius" not in shapes.columns
+        or len(shapes) <= _CIRCLE_FAST_PATH_MIN
+        or render_params.outline_alpha[0] > 0
+        or render_params.outline_alpha[1] > 0
+        or not bool(is_point.all())
+    ):
+        return False
+    radius = pd.to_numeric(shapes["radius"], errors="coerce").to_numpy()
+    return bool(np.isfinite(radius).all() and np.ptp(radius) == 0)
+
+
 def _render_shapes(
     sdata: sd.SpatialData,
     render_params: ShapesRenderParams,
@@ -718,12 +744,8 @@ def _render_shapes(
 
     shapes = gpd.GeoDataFrame(shapes, geometry="geometry")
 
-    if render_params.as_points:
-        # Fast mode: draw one dot per shape at its centroid instead of its geometry.
-        logger.info("`as_points=True`: rendering shape centroids; `outline_*` and `shape` are ignored.")
-        centroids = shapes.geometry.centroid  # intrinsic coords, positionally aligned to color_vector
-        # transform to coordinate-system coords so dots land correctly under non-identity transforms
-        xy = trans.transform(np.column_stack([centroids.x.to_numpy(), centroids.y.to_numpy()]))
+    def _draw_centroids(xy: np.ndarray, radius: float | None = None) -> None:
+        """Render the element's centroids (coordinate-system coords) as dots; ``radius`` sizes the disc."""
         _render_centroids_as_points(
             ax,
             render_params,
@@ -739,7 +761,14 @@ def _render_shapes(
             legend_params=legend_params,
             colorbar_requests=colorbar_requests,
             axes_extent=_fast_extent(sdata_filt.shapes[element], coordinate_system),
+            radius=radius,
         )
+
+    if render_params.as_points:
+        # Fast mode: draw one dot per shape at its centroid instead of its geometry.
+        logger.info("`as_points=True`: rendering shape centroids; `outline_*` and `shape` are ignored.")
+        centroids = shapes.geometry.centroid  # intrinsic; transform so dots land under non-identity transforms
+        _draw_centroids(trans.transform(np.column_stack([centroids.x.to_numpy(), centroids.y.to_numpy()])))
         return
 
     # convert shapes if necessary
@@ -773,6 +802,16 @@ def _render_shapes(
         is_point = _geometry.type == "Point"
         tm = trans.get_matrix()  # coordinate-system affine; reused for circle sizing and the transform below
 
+        # Fast path: a large uniform-radius circle element with no outline rasterizes (to within a
+        # pixel) the same as spread points, skipping the per-circle buffer/polygon-aggregation cost.
+        if _circles_render_as_points(shapes, is_point, render_params):
+            logger.info(f"Rendering {len(shapes)} uniform circles as datashader points (fast path).")
+            stretch = float(np.linalg.svd(tm[:2, :2], compute_uv=False).max())  # circle radius in CS units
+            radius_cs = float(pd.to_numeric(shapes["radius"], errors="coerce").iloc[0]) * render_params.scale * stretch
+            xy = trans.transform(np.column_stack([_geometry.x.to_numpy(), _geometry.y.to_numpy()]))
+            _draw_centroids(xy, radius=radius_cs)
+            return
+
         # Handle circles encoded as points with radius
         if is_point.any():
             # Convert to numeric, replacing non-numeric values with NaN
@@ -1078,12 +1117,14 @@ def _render_centroids_as_points(
     colorbar_requests: list[ColorbarSpec] | None,
     axes_extent: dict[str, tuple[float, float]],
     allow_datashader: bool = True,
+    radius: float | None = None,
 ) -> None:
     """Render one dot per cell at ``(x, y)`` (coordinate-system coords), colored like the fill.
 
     Shared "fast mode" for shapes/labels; backend chosen by ``_resolve_as_points_method``. ``axes_extent``
     (the element's extent, i.e. the frame the axes will use) is what the datashader backend rasterizes over
-    so its dots match the matplotlib markers.
+    so its dots match the matplotlib markers. ``radius`` (coordinate-system units), when set, sizes the
+    datashader spread to a faithful disc of that radius instead of the marker ``size``.
     """
     method = _resolve_as_points_method(render_params, n=len(x), allow_datashader=allow_datashader)
     if method == "datashader":
@@ -1108,6 +1149,7 @@ def _render_centroids_as_points(
             fig_params=fig_params,
             as_markers=True,
             axes_extent=axes_extent,
+            radius=radius,
         )
         color_spec = color_spec.evolve(source_vector=csv, color_vector=cv)
     else:
@@ -1159,23 +1201,20 @@ def _datashader_points(
     default_reduction: _DsReduction = "sum",
     as_markers: bool = False,
     axes_extent: dict[str, tuple[float, float]] | None = None,
+    radius: float | None = None,
 ) -> tuple[Any, Any, Any]:
     """Datashade an x/y(+color) point frame onto ``ax``; return ``(cax, color_vector, color_source_vector)``.
 
     Shared by ``render_points`` and the centroid "fast mode" of shapes/labels; ``df`` holds ``x``/``y`` in
     coordinate-system coords. The (possibly recomputed) color vectors are returned so the caller's legend
     matches. ``as_markers`` mimics matplotlib markers: it rasterizes over ``axes_extent`` (the plot frame),
-    sizes the spread to the marker radius, and uses a uniform alpha.
+    sizes the spread to the marker radius, and uses a uniform alpha. ``radius`` (coordinate-system units)
+    overrides ``size`` to spread each dot to a faithful disc of that radius (circle fast-path).
     """
-    # Spread radius = matplotlib marker radius: an 'o' marker has diameter sqrt(s)*dpi/72 px, so radius
-    # sqrt(s)*dpi/144. render_points keeps the looser sqrt(s)*dpi/100 it was calibrated with.
-    px_div = 144 if as_markers else 100
-    px: int | None = None if density else int(np.round(np.sqrt(size) * (fig_params.fig.dpi / px_div)))
-
     if as_markers and axes_extent is not None:
         # Size the canvas to the AXES display box, not the figure: the datashader output is a
         # data-coordinate image that scales with the (smaller) axes, so a figure-sized canvas shrinks the
-        # dots. With 1 canvas px == 1 axes-display px, the spread radius above matches the marker.
+        # dots. With 1 canvas px == 1 axes-display px, the spread radius below matches the marker.
         x_ext = [float(axes_extent["x"][0]), float(axes_extent["x"][1])]
         y_ext = [float(axes_extent["y"][0]), float(axes_extent["y"][1])]
         bb = ax.get_window_extent()
@@ -1184,6 +1223,17 @@ def _datashader_points(
         plot_width, plot_height = int(round(rx / factor)), int(round(ry / factor))
     else:
         plot_width, plot_height, x_ext, y_ext, factor = _datashader_canvas_from_dataframe(df, fig_params)
+
+    if density:
+        px: int | None = None
+    elif radius is not None:
+        # Faithful disc: spread to the circle's on-screen pixel radius (factor = CS units per axes px).
+        # ds.tf.spread's footprint radius is ~px+0.5, so subtract 0.5 to match a filled disc of radius r.
+        px = max(int(round(radius / factor - 0.5)), 0)
+    else:
+        # Spread radius = matplotlib marker radius: an 'o' marker has diameter sqrt(s)*dpi/72 px, so
+        # radius sqrt(s)*dpi/144. render_points keeps the looser sqrt(s)*dpi/100 it was calibrated with.
+        px = int(np.round(np.sqrt(size) * (fig_params.fig.dpi / (144 if as_markers else 100))))
     cvs = ds.Canvas(plot_width=plot_width, plot_height=plot_height, x_range=x_ext, y_range=y_ext)
 
     # ensure color column exists on the frame with positional alignment

tests/pl/test_render_shapes.py

@@ -48,6 +48,29 @@ def _annotate_polygons_with_outline_columns(sdata: SpatialData) -> SpatialData:
 
 
 class TestShapes(PlotTester, metaclass=PlotTesterMeta):
+    def test_plot_circle_render_permutations(self, monkeypatch):
+        """2x2 of (geometry / as_points) x (matplotlib / datashader); each row should look similar across backends."""
+        import spatialdata_plot.pl.render as render_mod
+
+        # exercise the datashader circle fast-path (points) on this small uniform set
+        monkeypatch.setattr(render_mod, "_CIRCLE_FAST_PATH_MIN", 1)
+
+        grid = np.arange(8) * 10.0
+        cx, cy = (a.ravel() for a in np.meshgrid(grid, grid))
+        gdf = gpd.GeoDataFrame({"radius": np.full(cx.size, 3.0)}, geometry=gpd.points_from_xy(cx, cy))
+        sdata = SpatialData(shapes={"circ": ShapesModel.parse(gdf)})
+
+        _, axs = plt.subplots(2, 2, figsize=(6, 6))
+        panels = [
+            (axs[0, 0], "geometry · matplotlib", {"method": "matplotlib"}),
+            (axs[0, 1], "geometry · datashader", {"method": "datashader"}),
+            (axs[1, 0], "as_points · matplotlib", {"method": "matplotlib", "as_points": True, "size": 100}),
+            (axs[1, 1], "as_points · datashader", {"method": "datashader", "as_points": True, "size": 100}),
+        ]
+        for ax, title, kw in panels:
+            sdata.pl.render_shapes("circ", **kw).pl.show(ax=ax)
+            ax.set_title(title, fontsize=8)
+
     def test_plot_can_render_circles(self, sdata_blobs: SpatialData):
         sdata_blobs.pl.render_shapes(element="blobs_circles").pl.show()
 
@@ -1861,3 +1884,42 @@ def test_circle_buffer_fidelity_to_default():
     full = c.buffer(1.0, quad_segs=16)
     iou = reduced.intersection(full).area / reduced.union(full).area
     assert iou >= 0.97
+
+
+def _uniform_circle_gdf(n: int, radius) -> gpd.GeoDataFrame:
+    import shapely
+
+    radii = radius if hasattr(radius, "__len__") else [radius] * n
+    geom = gpd.GeoSeries(shapely.points(np.column_stack([np.arange(n), np.zeros(n)])))
+    return gpd.GeoDataFrame({"radius": radii}, geometry=geom)
+
+
+def test_circles_render_as_points_gate():
+    """Phase 2 gate fires only for a large, uniform-radius, outline-free, default-shape circle element."""
+    from types import SimpleNamespace
+
+    from spatialdata_plot.pl.render import _CIRCLE_FAST_PATH_MIN, _circles_render_as_points
+
+    big = _CIRCLE_FAST_PATH_MIN + 1
+
+    def gate(gdf, **kw):
+        rp = SimpleNamespace(**{"shape": None, "outline_alpha": (0.0, 0.0), **kw})
+        return _circles_render_as_points(gdf, gdf.geometry.type == "Point", rp)
+
+    assert gate(_uniform_circle_gdf(big, 2.0)) is True
+    assert gate(_uniform_circle_gdf(10, 2.0)) is False  # too few
+    assert gate(_uniform_circle_gdf(big, np.arange(big) + 1.0)) is False  # varying radius
+    assert gate(_uniform_circle_gdf(big, 2.0), outline_alpha=(1.0, 0.0)) is False  # outline requested
+    assert gate(_uniform_circle_gdf(big, 2.0), shape="square") is False  # custom shape
+
+
+def test_circle_fast_path_renders_without_error(monkeypatch):
+    """A uniform circle element above the (patched-low) threshold renders via the datashader point path."""
+    import spatialdata_plot.pl.render as render_mod
+
+    monkeypatch.setattr(render_mod, "_CIRCLE_FAST_PATH_MIN", 4)
+    sdata = SpatialData(shapes={"circ": ShapesModel.parse(_uniform_circle_gdf(20, 2.0))})
+    fig, ax = plt.subplots()
+    sdata.pl.render_shapes("circ", method="datashader").pl.show(ax=ax)
+    assert len(ax.images) >= 1  # datashader raster produced
+    plt.close(fig)