perf(legend): skip the categorical legend past scanpy's color-palette limit

Coloring by a high-cardinality categorical (e.g. Xenium points by gene, ~3000
genes) spent ~10s building the legend: scanpy's _add_categorical_legend adds one
autoscaling artist per category, so matplotlib re-autoscales O(categories^2)
(sticky_edges called ~categories^2 times). Past len(default_102)=102 categories
scanpy already colors every point uniform grey, so a per-entry legend carries no
information anyway. Skip it with a warning above that limit (tied to scanpy's
palette so the two stay in sync). 2M points x 3085 genes: 16.9s -> 6.5s.

Author: timtreis

src/spatialdata_plot/pl/utils.py

@@ -31,6 +31,7 @@
 from pandas.api.types import CategoricalDtype, is_numeric_dtype
 from pandas.core.arrays.categorical import Categorical
 from scanpy import settings
+from scanpy.plotting import palettes
 from scanpy.plotting._tools.scatterplots import _add_categorical_legend
 from spatialdata import (
     SpatialData,
@@ -447,6 +448,13 @@ def _stack_categorical_legend(
     new_leg._sdata_column = column  # type: ignore[attr-defined]
 
 
+# scanpy assigns distinguishable colors only up to len(default_102) categories; beyond that it warns
+# and colors every point uniform grey (_set_default_colors_for_categorical_obs). At that point a
+# per-entry legend is meaningless AND scanpy builds it in O(categories^2) (one autoscaling artist each,
+# dominating the render), so we skip it with a warning. Tied to scanpy's palette so the two stay in sync.
+_MAX_LEGEND_CATEGORIES = len(palettes.default_102)
+
+
 def _decorate_axs(
     ax: Axes,
     cax: PatchCollection,
@@ -498,6 +506,14 @@ def _decorate_axs(
             already = any(tagged)
             if legend_loc in (None, "none"):
                 pass  # legend suppressed
+            elif len(clusters) > _MAX_LEGEND_CATEGORIES:
+                # Past scanpy's palette limit the points are all uniform grey anyway, so a per-entry legend
+                # carries no information and (built in O(categories^2)) dominates the render. Skip it.
+                logger.warning(
+                    f"Skipping the categorical legend for '{value_to_plot}': {len(clusters)} categories "
+                    f"exceed scanpy's {_MAX_LEGEND_CATEGORIES}-color palette (points are uniform grey past "
+                    f"that). Pass a `groups` subset to get a legend."
+                )
             elif already:
                 na_hex = na_color.get_hex() if (na_in_legend and pd.isnull(color_source_vector).any()) else None
                 _stack_categorical_legend(