refactor(render_points): tighten codes+palette per review

- datashader strip: when no two categories collapse to the same stripped colour
  (the common case) reuse the int8 codes via rename_categories instead of building
  an n-length int64 array; only remap (at the original int width) on a real collision.
- _scatter_points: guard the categorical codes path against an empty Categorical
  (len check) so it can't hit BoundaryNorm with zero colours; correct the NaN comment.
- trim a narrating comment; dedup the scatter-kwargs in the new tests.

Output unchanged: strip is byte-equivalent to the old factorize path (verified incl.
alpha-collision and NaN); 63 non-visual render_points tests pass.

Author: timtreis

src/spatialdata_plot/pl/_datashader.py

@@ -110,8 +110,7 @@ def _build_datashader_color_key(
     # avoiding a Python loop over all points.  See #379.
     unique_codes, first_indices = np.unique(codes, return_index=True)
 
-    # Index color_vector only at those first occurrences (one per category) rather than expanding the
-    # whole per-point vector to an object array — color_vector is a compact pd.Categorical at scale.
+    # Index only the first occurrence per category — color_vector is a compact pd.Categorical at scale.
     first_color: dict[str, str] = {}
     for code, idx in zip(unique_codes, first_indices, strict=True):
         if code < 0 or idx >= len(color_vector):
@@ -404,14 +403,17 @@ def _shade_datashader_aggregate(
         and isinstance(color_vector[0], str)
         and color_vector[0].startswith("#")
     ):
-        # Strip alpha on the unique colours, never on the per-point vector. color_vector is already a
-        # pd.Categorical (codes + a small palette) at scale: strip its k categories and remap the codes,
-        # staying compact. (Plain-array fallback factorizes in O(n) — hash, no sort.)
+        # Strip alpha on the k categories, never on the per-point vector — color_vector is a compact
+        # pd.Categorical at scale. (Plain-array fallback factorizes in O(n): hash, no sort.)
         if isinstance(color_vector, pd.Categorical):
-            stripped = np.asarray([_hex_no_alpha(c) for c in color_vector.categories])
-            uniq_codes, uniques = pd.factorize(stripped)  # dedup over k categories, not n points
-            new_codes = np.where(color_vector.codes >= 0, uniq_codes[color_vector.codes], -1)
-            color_vector = pd.Categorical.from_codes(new_codes, categories=uniques)
+            stripped = [_hex_no_alpha(c) for c in color_vector.categories]
+            uniq_codes, uniques = pd.factorize(np.asarray(stripped))
+            if len(uniques) == len(stripped):
+                color_vector = color_vector.rename_categories(stripped)  # no collisions: reuse the codes as-is
+            else:  # two categories share a stripped colour: remap, keeping the compact int width
+                remapped = uniq_codes[color_vector.codes].astype(color_vector.codes.dtype)
+                remapped[color_vector.codes < 0] = -1
+                color_vector = pd.Categorical.from_codes(remapped, categories=uniques)
         else:
             codes, uniques = pd.factorize(np.asarray(color_vector))
             color_vector = np.asarray([_hex_no_alpha(c) for c in uniques])[codes]

src/spatialdata_plot/pl/render.py

@@ -1057,11 +1057,11 @@ def _scatter_points(
     # machinery — the dominant cost at scale (10M points: ~9s -> ~3.7s) — for a visually identical result.
     # Numeric vectors keep the ``c=``/``cmap``/``norm`` path (they need the colormap).
     color_kwargs: dict[str, Any]
-    if isinstance(color_vector, pd.Categorical) and (color_vector.codes >= 0).all():
+    if isinstance(color_vector, pd.Categorical) and len(color_vector) and (color_vector.codes >= 0).all():
         # Categorical hex colours: pass the int codes + a ListedColormap of the (few) category colours
         # instead of expanding to a per-point hex object array (~8x more memory at scale). BoundaryNorm
         # edges at the half-integers map code i -> colormap entry i exactly, so the RGBA is identical.
-        # (_color.py bakes NaN into the na_color category, so codes >= 0; a stray -1 falls back below.)
+        # _color.py bakes NaN into the na_color category, so codes >= 0 here; anything else takes the path below.
         categories = list(color_vector.categories)
         if len(categories) == 1:
             color_kwargs = {"color": str(categories[0])}  # uniform: scalar color=, skip per-point machinery

tests/pl/test_render_points.py

@@ -1349,22 +1349,17 @@ def _categorical_hex_vector(n: int, k: int, seed: int = 0) -> pd.Categorical:
     return pd.Categorical(pd.Series(src).map(palette))
 
 
+_SCATTER_KW = {"size": 10.0, "cmap": "viridis", "norm": Normalize(), "alpha": 1.0, "trans_data": None, "zorder": 1}
+
+
 def test_scatter_points_categorical_codes_match_per_point_hex():
     # The codes+ListedColormap path must produce byte-identical RGBA to passing the per-point hex array.
     cv = _categorical_hex_vector(400, k=6, seed=1)
     rng = np.random.default_rng(2)
     x, y = rng.random(400), rng.random(400)
-    common = {
-        "size": 10.0,
-        "cmap": plt.get_cmap("viridis"),
-        "norm": Normalize(),
-        "alpha": 1.0,
-        "trans_data": None,
-        "zorder": 1,
-    }
 
     fig, ax = plt.subplots()
-    sc_codes = _scatter_points(ax, x, y, cv, **common)  # exercises the new codes path
+    sc_codes = _scatter_points(ax, x, y, cv, **_SCATTER_KW)  # exercises the new codes path
     sc_codes.update_scalarmappable()
     fc_codes = sc_codes.get_facecolors()
     plt.close(fig)
@@ -1382,18 +1377,7 @@ def test_scatter_points_single_category_uses_scalar_color():
     cv = _categorical_hex_vector(300, k=1, seed=3)
     rng = np.random.default_rng(5)
     fig, ax = plt.subplots()
-    sc = _scatter_points(
-        ax,
-        rng.random(300),
-        rng.random(300),
-        cv,
-        size=10.0,
-        cmap=plt.get_cmap("viridis"),
-        norm=Normalize(),
-        alpha=1.0,
-        trans_data=None,
-        zorder=1,
-    )
+    sc = _scatter_points(ax, rng.random(300), rng.random(300), cv, **_SCATTER_KW)
     assert sc.get_facecolors().shape[0] == 1  # scalar color -> single facecolor
     plt.close(fig)