feat: add as_points tutorial

Show the how and why of `as_points` on both render_shapes and
render_labels, using a real Xenium breast-cancer section (~168k cells).
Covers what it draws (one centroid dot per element), what it ignores
(outline_*, shape, contour_px), the matplotlib->datashader backend
switch at ~50k centroids, and the measured speed trade-off: a large
win for shapes (up to ~16x), roughly neutral for labels (a mask
already renders as a fast raster).

Segmentation masks are derived from the real cell_boundaries via
rasterize(return_regions_as_labels=True), since Xenium rep1 ships
outlines as shapes with no native labels element.

The 3.4 GB download makes the notebook too heavy for CI, so it is
excluded from execute.yaml and its committed outputs are trusted.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: timtreis

.github/workflows/execute.yaml

@@ -64,6 +64,9 @@ jobs:
           else
             nbs=$(find tutorials examples -name "*.ipynb" -not -path "*/.ipynb_checkpoints/*" 2>/dev/null || true)
           fi
+          # Notebooks whose datasets are too large for CI (multi-GB downloads):
+          # their committed outputs are trusted and never re-executed here.
+          nbs=$(printf '%s\n' "$nbs" | grep -vxF 'tutorials/as_points.ipynb' || true)
           if [ -z "$nbs" ]; then
             echo "No notebooks to execute."
           else

_static/img/as_points.png

@@ -45,6 +45,16 @@ selection for images, and the `datashader` backend for large collections
 of shapes and points.
 :::
 
+:::{grid-item-card} Rendering elements as points
+:link: /notebooks/tutorials/as_points
+:link-type: doc
+:img-top: /notebooks/_static/img/as_points.png
+
+Draw shapes and label masks as one dot per centroid with `as_points=True`
+— a fast overview that trades geometry for speed, including the matplotlib
+→ datashader switch above ~50k elements.
+:::
+
 :::{grid-item-card} Scalebars
 :link: /notebooks/tutorials/scalebars
 :link-type: doc
@@ -65,5 +75,6 @@ getting_started
 color_and_palette
 multi_panel_color
 performance
+as_points
 scalebars
 ```