Fix user figure DPI being silently overridden by pl.show() (#310)

When a user created a figure with a custom DPI (e.g. plt.figure(dpi=300))
and passed its axes to .pl.show(ax=ax), the DPI was silently overwritten
with the rcParams default. This happened because _prepare_params_plot()
unconditionally resolved dpi=None to rcParams["figure.dpi"] and then
called fig.set_dpi() on the user's figure.

Now the figure's existing DPI is preserved when the user provides their
own axes without an explicit dpi= argument. Explicit dpi= still overrides.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: timtreis

src/spatialdata_plot/pl/utils.py

@@ -244,14 +244,17 @@ def _prepare_params_plot(
     # handle axes and size
     wspace = 0.75 / rcParams["figure.figsize"][0] + 0.02 if wspace is None else wspace
     figsize = rcParams["figure.figsize"] if figsize is None else figsize
-    dpi = rcParams["figure.dpi"] if dpi is None else dpi
+    # When creating a new figure, fall back to rcParams; when the user provides
+    # their own axes, preserve the figure's existing DPI (only override if
+    # the user explicitly passed dpi= to show()).
+    resolved_dpi = rcParams["figure.dpi"] if dpi is None else dpi
     if num_panels > 1 and ax is None:
         fig, grid = _panel_grid(
             num_panels=num_panels,
             hspace=hspace,
             wspace=wspace,
             ncols=ncols,
-            dpi=dpi,
+            dpi=resolved_dpi,
             figsize=figsize,
         )
         axs: None | Sequence[Axes] = [plt.subplot(grid[c]) for c in range(num_panels)]
@@ -266,14 +269,16 @@ def _prepare_params_plot(
             )
         assert ax is None or isinstance(ax, Sequence), f"Invalid type of `ax`: {type(ax)}, expected `Sequence`."
         axs = ax
+        if dpi is not None:
+            fig.set_dpi(dpi)
     else:
         axs = None
         if ax is None:
-            fig, ax = plt.subplots(figsize=figsize, dpi=dpi, constrained_layout=True)
+            fig, ax = plt.subplots(figsize=figsize, dpi=resolved_dpi, constrained_layout=True)
         elif isinstance(ax, Axes):
-            # needed for rasterization if user provides Axes object
             fig = ax.get_figure()
-            fig.set_dpi(dpi)
+            if dpi is not None:
+                fig.set_dpi(dpi)
 
     # set scalebar
     if scalebar_dx is not None:

tests/pl/test_show.py

@@ -42,6 +42,11 @@ def test_plot_no_decorations(self, sdata_blobs: SpatialData):
         """Visual test: frameon=False + title='' produces just the plot content (regression for #204)."""
         sdata_blobs.pl.render_images(element="blobs_image").pl.show(frameon=False, title="", colorbar=False)
 
+    def test_plot_user_ax_dpi_preserved(self, sdata_blobs: SpatialData):
+        """Visual test: rendering into a user-provided high-DPI ax produces correct layout (regression for #310)."""
+        fig, ax = plt.subplots(dpi=200)
+        sdata_blobs.pl.render_images(element="blobs_image").pl.show(ax=ax)
+
     def test_no_plt_show_when_ax_provided(self, sdata_blobs: SpatialData):
         """plt.show() must not be called when the user supplies ax= (regression for #362)."""
         _, ax = plt.subplots()
@@ -110,3 +115,27 @@ def test_frameon_false_multi_panel(sdata_blobs: SpatialData):
     for ax in axs:
         assert not ax.axison
     plt.close("all")
+
+
+def test_user_figure_dpi_preserved_when_ax_provided(sdata_blobs: SpatialData):
+    """User's figure DPI must not be overridden when ax is passed without explicit dpi (regression for #310)."""
+    fig, ax = plt.subplots(dpi=300)
+    sdata_blobs.pl.render_images(element="blobs_image").pl.show(ax=ax, show=False)
+    assert fig.get_dpi() == 300
+    plt.close(fig)
+
+
+def test_explicit_dpi_overrides_figure_dpi(sdata_blobs: SpatialData):
+    """Explicit dpi= in show() should override the figure's DPI."""
+    fig, ax = plt.subplots(dpi=300)
+    sdata_blobs.pl.render_images(element="blobs_image").pl.show(ax=ax, dpi=150, show=False)
+    assert fig.get_dpi() == 150
+    plt.close(fig)
+
+
+def test_dpi_default_used_when_no_ax(sdata_blobs: SpatialData):
+    """When no ax is provided and dpi is not set, rcParams default should be used."""
+    ax = sdata_blobs.pl.render_images(element="blobs_image").pl.show(return_ax=True, show=False)
+    fig = ax.get_figure()
+    assert fig.get_dpi() == matplotlib.rcParams["figure.dpi"]
+    plt.close(fig)