fix(render): align rasterized artists with get_extent (pixel-edge extent)

Images, labels, and datashader output were drawn with matplotlib's default
pixel-center imshow extent (-0.5, W-0.5, ...), placing them half a pixel off
the world coordinates used for the axis limits (get_extent), the affine box,
and matplotlib point/shape overlays. The affine's linear part amplifies the
constant 0.5 offset, so a Scale(1000) image shifted by 500 world units (#216).

Switch to the pixel-edge convention (0, W, H, 0) so each artist's data box is
the same [0, shape] box get_extent transforms — they now coincide under any
affine. Labels are drawn outside the shared _ax_show_and_transform helper via a
direct imshow(origin="lower"), so they get an explicit extent=(0, W, 0, H)
(origin-lower order) to match. This also removes the residual half-canvas-pixel
offset of datashader points relative to the matplotlib backend.

Adds non-visual regression tests asserting the rendered world box equals
get_extent for images and labels (Identity + Scale), and that the datashader
points image occupies the points' extent.

Author: timtreis

src/spatialdata_plot/pl/_datashader.py

@@ -730,9 +730,12 @@ def _ax_show_and_transform(
     norm: Normalize | None = None,
     interpolation: str | None = None,
 ) -> matplotlib.image.AxesImage:
-    # ``extent`` uses mpl's pixel-grid convention; world placement happens via
-    # ``set_transform(trans_data)`` afterwards.
-    image_extent = (-0.5, array.shape[1] - 0.5, array.shape[0] - 0.5, -0.5)
+    # Pixel-edge extent: the array spans [0, width] x [0, height], matching
+    # spatialdata's ``get_extent`` (which sets the axis limits) and the affine's
+    # data box. World placement happens via ``set_transform(trans_data)``. Using
+    # mpl's default pixel-center extent (-0.5, W-0.5, ...) would offset the image
+    # half a pixel from the axes/overlays, amplified by the affine.
+    image_extent = (0.0, array.shape[1], array.shape[0], 0.0)
     # ``alpha`` is applied only when no cmap is set, so RGBA arrays already
     # carrying per-pixel alpha (e.g. datashader output) are not double-attenuated.
     imshow_kwargs: dict[str, Any] = {"zorder": zorder, "extent": image_extent, "norm": norm}

src/spatialdata_plot/pl/render.py

@@ -2400,7 +2400,17 @@ def _draw_labels(
         # non-linear norm (LogNorm/PowerNorm). Display the RGB without a norm and build the
         # continuous colorbar mappable separately from the resolved norm (mirrors the outline path),
         # so the colorbar reflects the real norm subclass.
-        img = ax.imshow(labels, rasterized=True, alpha=alpha, origin="lower", zorder=render_params.zorder)
+        # Pixel-edge extent matching get_extent/the affine box; without it, imshow's
+        # default (pixel-center) would offset labels half a pixel from images and
+        # overlays. Note origin="lower" → extent order is (0, W, 0, H).
+        img = ax.imshow(
+            labels,
+            rasterized=True,
+            alpha=alpha,
+            origin="lower",
+            extent=(0.0, labels.shape[1], 0.0, labels.shape[0]),
+            zorder=render_params.zorder,
+        )
         img.set_transform(trans_data)
         if color_spec.is_categorical:
             return img

tests/pl/test_utils.py

@@ -1286,3 +1286,64 @@ def test_first_color_per_category_skips_nan_and_handles_numeric_categories():
     source = pd.Categorical([1, None, 2, 1], categories=[1, 2])
     cv = ["#aaaaaa", "#ffffff", "#bbbbbb", "#aaaaaa"]
     assert _first_color_per_category(source, cv) == {1: "#aaaaaa", 2: "#bbbbbb"}
+
+
+def _rendered_image_world_box(im, ax) -> tuple[float, float, float, float]:
+    """World-space (x0, x1, y0, y1) the AxesImage's pixel grid actually occupies."""
+    left, right, bottom, top = im.get_extent()
+    element_affine = im.get_transform() - ax.transData
+    (x0, y0), (x1, y1) = element_affine.transform([(left, bottom), (right, top)])
+    return float(x0), float(x1), float(y0), float(y1)
+
+
+@pytest.mark.parametrize("transform_name", ["identity", "scale"])
+@pytest.mark.parametrize("element", ["image", "labels"])
+def test_rasterized_artist_aligns_with_get_extent(transform_name, element):
+    # Regression test for #216: a rasterized image/labels artist must occupy the
+    # same world box as get_extent (which sets the axis limits). The old pixel-center
+    # extent left it half a pixel off, amplified by the affine (Scale -> hundreds of px).
+    from spatialdata import get_extent
+    from spatialdata.models import Image2DModel
+    from spatialdata.transformations import Identity, Scale
+
+    transform = Identity() if transform_name == "identity" else Scale([1000.0, 1000.0], axes=("x", "y"))
+    if element == "image":
+        el = Image2DModel.parse(np.zeros((1, 4, 8)), dims=("c", "y", "x"), transformations={"global": transform})
+        sdata = SpatialData(images={"el": el})
+        ax = sdata.pl.render_images().pl.show(return_ax=True)
+    else:
+        el = Labels2DModel.parse(
+            np.zeros((4, 8), dtype=np.int32), dims=("y", "x"), transformations={"global": transform}
+        )
+        sdata = SpatialData(labels={"el": el})
+        ax = sdata.pl.render_labels().pl.show(return_ax=True)
+
+    ext = get_extent(sdata["el"], coordinate_system="global")
+    x0, x1, y0, y1 = _rendered_image_world_box(ax.get_images()[0], ax)
+    assert (min(x0, x1), max(x0, x1)) == pytest.approx(tuple(map(float, ext["x"])))
+    assert (min(y0, y1), max(y0, y1)) == pytest.approx(tuple(map(float, ext["y"])))
+    plt.close("all")
+
+
+def test_datashader_points_image_aligns_with_points_extent():
+    # Regression test for #216 (Sonja's case): the rasterized datashader-points image
+    # must occupy the points' world extent, matching where matplotlib scatters them.
+    from spatialdata.models import Image2DModel
+    from spatialdata.transformations import Identity
+
+    sdata = SpatialData(
+        images={"img": Image2DModel.parse(np.full((10, 10, 3), 128, dtype=np.uint8), dims=("y", "x", "c"))},
+        points={
+            "pts": PointsModel.parse(
+                pd.DataFrame({"x": [0.1, 0.9, 0.9, 0.1], "y": [0.1, 0.1, 0.9, 0.9]}),
+                transformations={"global": Identity()},
+            )
+        },
+    )
+    ax = sdata.pl.render_images().pl.render_points("pts", method="datashader", size=40).pl.show(return_ax=True)
+
+    # second image on the axis is the rasterized points (first is the background image)
+    x0, x1, y0, y1 = _rendered_image_world_box(ax.get_images()[1], ax)
+    assert (min(x0, x1), max(x0, x1)) == pytest.approx((0.1, 0.9))
+    assert (min(y0, y1), max(y0, y1)) == pytest.approx((0.1, 0.9))
+    plt.close("all")