Fix per-panel colorbars overflowing into neighbouring panels

src/spatialdata_plot/pl/basic.py

@@ -22,7 +22,10 @@
 from matplotlib.backend_bases import RendererBase
 from matplotlib.colors import Colormap, LogNorm, Normalize
 from matplotlib.figure import Figure
-from mpl_toolkits.axes_grid1.inset_locator import inset_axes
+from matplotlib.transforms import Bbox
+from mpl_toolkits.axes_grid1 import make_axes_locatable
+from mpl_toolkits.axes_grid1.axes_divider import AxesDivider
+from mpl_toolkits.axes_grid1.axes_size import Fixed
 from spatialdata import get_extent
 from spatialdata._utils import _deprecation_alias
 from spatialdata.transformations.operations import get_transformation
@@ -43,6 +46,7 @@
  CBAR_DEFAULT_FRACTION,
  CBAR_DEFAULT_LOCATION,
  CBAR_DEFAULT_PAD,
+ CBAR_STACK_GAP_INCHES,
  ChannelLegendEntry,
  CmapParams,
  ColorbarSpec,
@@ -84,6 +88,33 @@
 # once https://github.com/scverse/spatialdata/pull/689/ is in a release
 ColorLike = tuple[float, ...] | list[float] | str
 
+# Below this clearance (inches), a colorbar side is treated as having no axis decorations to clear,
+# so the colorbar keeps its relative pad (matching the historical placement) instead of an absolute one.
+_CBAR_DECORATION_EPS_INCHES = 0.05
+
+# Per colorbar location: the axis ("x"/"y") its ticks live on, and the opposite side.
+_CBAR_TICK_SIDE = {"left": ("y", "right"), "right": ("y", "left"), "top": ("x", "bottom"), "bottom": ("x", "top")}
+
+
+def _extent_beyond_box_inches(box: Bbox, tight: Bbox | None, dpi: float, side: str) -> float:
+ """Inches that ``tight`` (an artist's full extent incl. ticks/labels) sticks out past ``box`` on ``side``.
+
+ Returns ``0.0`` when there is no overhang, when ``tight`` is ``None`` (an axes with nothing
+ drawable), or when ``dpi`` is non-positive. Used both to clear a panel's own decorations and to
+ clear a stacked colorbar's labels before placing the next one.
+ """
+ if tight is None or dpi <= 0:
+ return 0.0
+ if side == "left":
+ delta = box.x0 - tight.x0
+ elif side == "right":
+ delta = tight.x1 - box.x1
+ elif side == "bottom":
+ delta = box.y0 - tight.y0
+ else: # top
+ delta = tight.y1 - box.y1
+ return max(0.0, float(delta) / dpi)
+
 
 @register_spatial_data_accessor("pl")
 class PlotAccessor:
@@ -1522,9 +1553,13 @@ def show(
  def _draw_colorbar(
  spec: ColorbarSpec,
  fig: Figure,
+ divider: AxesDivider,
+ side_counts: dict[str, int],
+ clearance: dict[str, float],
+ axes_size_in: tuple[float, float],
+ prev_outer: dict[str, float],
  renderer: RendererBase,
- base_offsets_axes: dict[str, float],
- trackers_axes: dict[str, float],
+ dpi: float,
  ) -> None:
  norm = spec.mappable.norm
  if isinstance(norm, LogNorm):
@@ -1551,63 +1586,73 @@ def _draw_colorbar(
  location = cast(str, layout.get("location", base_layout["location"]))
  if location not in {"left", "right", "top", "bottom"}:
  location = CBAR_DEFAULT_LOCATION
- default_orientation = "vertical" if location in {"right", "left"} else "horizontal"
- cbar_kwargs.setdefault("orientation", default_orientation)
+ orientation = "vertical" if location in {"right", "left"} else "horizontal"
+ # Orientation is fixed by the location (the divider places a left/right colorbar
+ # vertically and a top/bottom one horizontally); warn rather than silently ignore a
+ # conflicting user-supplied orientation.
+ user_orientation = cbar_kwargs.pop("orientation", None)
+ if user_orientation is not None and user_orientation != orientation:
+ warnings.warn(
+ f"`orientation` is determined by the colorbar location ('{location}' -> '{orientation}'); "
+ f"the requested '{user_orientation}' is ignored.",
+ UserWarning,
+ stacklevel=2,
+ )
 
  fraction = float(cast(float | int, layout.get("fraction", base_layout["fraction"])))
  pad = float(cast(float | int, layout.get("pad", base_layout["pad"])))
 
- if location in {"left", "right"}:
- pad_axes = pad + trackers_axes[location]
- x0 = -pad_axes - fraction if location == "left" else 1 + pad_axes
- bbox = (float(x0), 0.0, float(fraction), 1.0)
+ # Append the colorbar axes through the panel's shared divider. This steals space from the
+ # panel (so the colorbar matches the equal-aspect plot's extent) and keeps it inside the
+ # panel's grid cell, never overflowing into a neighbouring panel.
+ # Pad of the first colorbar on a side clears the panel's own decorations (ticks/labels/
+ # title); a side with negligible clearance (typically "right") keeps the relative pad to
+ # match the historical placement. Each subsequent (stacked) colorbar is padded past the
+ # *measured* outer extent of the previous one (its tick labels AND axis label) so it never
+ # overlaps it.
+ n_on_side = side_counts.get(location, 0)
+ ref_in = axes_size_in[0] if location in {"left", "right"} else axes_size_in[1]
+ side_clearance = clearance.get(location, 0.0)
+ pad_spec: str | Fixed
+ if n_on_side:
+ pad_spec = Fixed(prev_outer.get(location, 0.0) + CBAR_STACK_GAP_INCHES)
+ elif side_clearance > _CBAR_DECORATION_EPS_INCHES:
+ pad_spec = Fixed(side_clearance + max(pad, 0.0) * ref_in)
  else:
- pad_axes = pad + trackers_axes[location]
- y0 = -pad_axes - fraction if location == "bottom" else 1 + pad_axes
- bbox = (0.0, float(y0), 1.0, float(fraction))
- cax = inset_axes(
- spec.ax,
- width="100%",
- height="100%",
- loc="center",
- bbox_to_anchor=bbox,
- bbox_transform=spec.ax.transAxes,
- borderpad=0.0,
+ pad_spec = f"{max(pad, 0.0) * 100}%"
+ cax = divider.append_axes(
+ location,
+ size=f"{max(fraction, 0.0) * 100}%",
+ pad=pad_spec,
+ axes_class=Axes,
  )
-
- cb = fig.colorbar(spec.mappable, cax=cax, **cbar_kwargs)
- if location == "left":
- cb.ax.yaxis.set_ticks_position("left")
- cb.ax.yaxis.set_label_position("left")
- cb.ax.tick_params(labelleft=True, labelright=False)
- elif location == "top":
- cb.ax.xaxis.set_ticks_position("top")
- cb.ax.xaxis.set_label_position("top")
- cb.ax.tick_params(labeltop=True, labelbottom=False)
- elif location == "right":
- cb.ax.yaxis.set_ticks_position("right")
- cb.ax.yaxis.set_label_position("right")
- cb.ax.tick_params(labelright=True, labelleft=False)
- elif location == "bottom":
- cb.ax.xaxis.set_ticks_position("bottom")
- cb.ax.xaxis.set_label_position("bottom")
- cb.ax.tick_params(labelbottom=True, labeltop=False)
+ side_counts[location] = n_on_side + 1
+ cb = fig.colorbar(spec.mappable, cax=cax, orientation=orientation, **cbar_kwargs)
+ tick_axis, opposite = _CBAR_TICK_SIDE[location]
+ cb_axis = cb.ax.yaxis if tick_axis == "y" else cb.ax.xaxis
+ cb_axis.set_ticks_position(location)
+ cb_axis.set_label_position(location)
+ cb.ax.tick_params(**{f"label{location}": True, f"label{opposite}": False})
 
  final_label = global_label_override or layer_label_override or spec.label
  if final_label:
  cb.set_label(final_label)
- if spec.alpha is not None:
+ # `fig.colorbar(mappable)` already bakes the mappable's alpha into the colorbar's
+ # facecolors, so we only apply `spec.alpha` when the mappable carries no alpha of its own
+ # — otherwise we'd multiply alpha twice and the colorbar would render at alpha squared
+ # (much paler than the layer it represents).
+ if spec.alpha is not None and spec.mappable.get_alpha() is None:
  with contextlib.suppress(Exception):
  cb.solids.set_alpha(spec.alpha)
- bbox_axes = cb.ax.get_tightbbox(renderer).transformed(spec.ax.transAxes.inverted())
-if location == "left":
- trackers_axes["left"] = pad_axes + bbox_axes.width
-elif location == "right":
- trackers_axes["right"] = pad_axes + bbox_axes.width
-elif location == "bottom":
- trackers_axes["bottom"] = pad_axes + bbox_axes.height
-elif location == "top":
- trackers_axes["top"] = pad_axes + bbox_axes.height
+
+# Measure how far this colorbar's ticks/labels/axis-label extend beyond its box, so the
+# next stacked colorbar on this side clears them. The draw is kept unconditionally: it is
+# also load-bearing for the layout engine (skipping it shifts wide colorbars), so it is not
+# safe to skip even for the last colorbar on a side.
+fig.canvas.draw()
+prev_outer[location] = _extent_beyond_box_inches(
+ cb.ax.get_window_extent(renderer), cb.ax.get_tightbbox(renderer), dpi, location
+)
 
  # go through tree
 
@@ -1797,6 +1842,7 @@ def _draw_colorbar(
  fig = fig_params.fig
  fig.canvas.draw()
  renderer = fig.canvas.get_renderer()
+ dpi = fig.get_dpi()
  for axis, requests in pending_colorbars:
  unique_specs: list[ColorbarSpec] = []
  seen_mappables: set[int] = set()
@@ -1806,16 +1852,20 @@ def _draw_colorbar(
  continue
  seen_mappables.add(mappable_id)
  unique_specs.append(spec)
- tight_bbox = axis.get_tightbbox(renderer).transformed(axis.transAxes.inverted())
- base_offsets_axes = {
- "left": max(0.0, -tight_bbox.x0),
- "right": max(0.0, tight_bbox.x1 - 1),
- "bottom": max(0.0, -tight_bbox.y0),
- "top": max(0.0, tight_bbox.y1 - 1),
- }
- trackers_axes = {k: base_offsets_axes[k] for k in base_offsets_axes}
+ # Clearance (inches) that the panel's own ticks, tick labels and title extend beyond
+ # the axes box on each side. The first colorbar on a side is padded past this so it
+ # clears those decorations instead of overlapping them (the divider only knows about
+ # the axes box, not its decorations).
+ box = axis.get_window_extent(renderer)
+ tight = axis.get_tightbbox(renderer)
+ clearance = {side: _extent_beyond_box_inches(box, tight, dpi, side) for side in _CBAR_TICK_SIDE}
+ axes_size_in = (box.width / dpi, box.height / dpi)
+ # One divider per panel so multiple colorbars on the same panel stack via the divider.
+ divider = make_axes_locatable(axis)
+ side_counts: dict[str, int] = {}
+ prev_outer: dict[str, float] = {}
  for spec in unique_specs:
- _draw_colorbar(spec, fig, renderer, base_offsets_axes, trackers_axes)
+ _draw_colorbar(spec, fig, divider, side_counts, clearance, axes_size_in, prev_outer, renderer, dpi)
 
  if fig_params.fig is not None and save is not None:
  save_fig(fig_params.fig, path=save)

src/spatialdata_plot/pl/render_params.py

@@ -219,6 +219,9 @@ class ChannelLegendEntry:
 CBAR_DEFAULT_LOCATION = "right"
 CBAR_DEFAULT_FRACTION = 0.075
 CBAR_DEFAULT_PAD = 0.015
+# Small gap (inches) added beyond a stacked colorbar's measured outer extent (its tick labels and
+# axis label) before placing the next colorbar on the same side, so they never overlap.
+CBAR_STACK_GAP_INCHES = 0.08
 
 
 @dataclass

src/spatialdata_plot/pl/basic.py

@@ -22,7 +22,10 @@
 from matplotlib.backend_bases import RendererBase
 from matplotlib.colors import Colormap, LogNorm, Normalize
 from matplotlib.figure import Figure
-from mpl_toolkits.axes_grid1.inset_locator import inset_axes
+from matplotlib.transforms import Bbox
+from mpl_toolkits.axes_grid1 import make_axes_locatable
+from mpl_toolkits.axes_grid1.axes_divider import AxesDivider
+from mpl_toolkits.axes_grid1.axes_size import Fixed
 from spatialdata import get_extent
 from spatialdata._utils import _deprecation_alias
 from spatialdata.transformations.operations import get_transformation
@@ -43,6 +46,7 @@
  CBAR_DEFAULT_FRACTION,
  CBAR_DEFAULT_LOCATION,
  CBAR_DEFAULT_PAD,
+ CBAR_STACK_GAP_INCHES,
  ChannelLegendEntry,
  CmapParams,
  ColorbarSpec,
@@ -84,6 +88,33 @@
 # once https://github.com/scverse/spatialdata/pull/689/ is in a release
 ColorLike = tuple[float, ...] | list[float] | str
 
+# Below this clearance (inches), a colorbar side is treated as having no axis decorations to clear,
+# so the colorbar keeps its relative pad (matching the historical placement) instead of an absolute one.
+_CBAR_DECORATION_EPS_INCHES = 0.05
+
+# Per colorbar location: the axis ("x"/"y") its ticks live on, and the opposite side.
+_CBAR_TICK_SIDE = {"left": ("y", "right"), "right": ("y", "left"), "top": ("x", "bottom"), "bottom": ("x", "top")}
+
+
+def _extent_beyond_box_inches(box: Bbox, tight: Bbox | None, dpi: float, side: str) -> float:
+ """Inches that ``tight`` (an artist's full extent incl. ticks/labels) sticks out past ``box`` on ``side``.
+
+ Returns ``0.0`` when there is no overhang, when ``tight`` is ``None`` (an axes with nothing
+ drawable), or when ``dpi`` is non-positive. Used both to clear a panel's own decorations and to
+ clear a stacked colorbar's labels before placing the next one.
+ """
+ if tight is None or dpi <= 0:
+ return 0.0
+ if side == "left":
+ delta = box.x0 - tight.x0
+ elif side == "right":
+ delta = tight.x1 - box.x1
+ elif side == "bottom":
+ delta = box.y0 - tight.y0
+ else: # top
+ delta = tight.y1 - box.y1
+ return max(0.0, float(delta) / dpi)
+
 
 @register_spatial_data_accessor("pl")
 class PlotAccessor:
@@ -1522,9 +1553,13 @@ def show(
  def _draw_colorbar(
  spec: ColorbarSpec,
  fig: Figure,
+ divider: AxesDivider,
+ side_counts: dict[str, int],
+ clearance: dict[str, float],
+ axes_size_in: tuple[float, float],
+ prev_outer: dict[str, float],
  renderer: RendererBase,
- base_offsets_axes: dict[str, float],
- trackers_axes: dict[str, float],
+ dpi: float,
  ) -> None:
  norm = spec.mappable.norm
  if isinstance(norm, LogNorm):
@@ -1551,63 +1586,73 @@ def _draw_colorbar(
  location = cast(str, layout.get("location", base_layout["location"]))
  if location not in {"left", "right", "top", "bottom"}:
  location = CBAR_DEFAULT_LOCATION
- default_orientation = "vertical" if location in {"right", "left"} else "horizontal"
- cbar_kwargs.setdefault("orientation", default_orientation)
+ orientation = "vertical" if location in {"right", "left"} else "horizontal"
+ # Orientation is fixed by the location (the divider places a left/right colorbar
+ # vertically and a top/bottom one horizontally); warn rather than silently ignore a
+ # conflicting user-supplied orientation.
+ user_orientation = cbar_kwargs.pop("orientation", None)
+ if user_orientation is not None and user_orientation != orientation:
+ warnings.warn(
+ f"`orientation` is determined by the colorbar location ('{location}' -> '{orientation}'); "
+ f"the requested '{user_orientation}' is ignored.",
+ UserWarning,
+ stacklevel=2,
+ )
 
  fraction = float(cast(float | int, layout.get("fraction", base_layout["fraction"])))
  pad = float(cast(float | int, layout.get("pad", base_layout["pad"])))
 
- if location in {"left", "right"}:
- pad_axes = pad + trackers_axes[location]
- x0 = -pad_axes - fraction if location == "left" else 1 + pad_axes
- bbox = (float(x0), 0.0, float(fraction), 1.0)
+ # Append the colorbar axes through the panel's shared divider. This steals space from the
+ # panel (so the colorbar matches the equal-aspect plot's extent) and keeps it inside the
+ # panel's grid cell, never overflowing into a neighbouring panel.
+ # Pad of the first colorbar on a side clears the panel's own decorations (ticks/labels/
+ # title); a side with negligible clearance (typically "right") keeps the relative pad to
+ # match the historical placement. Each subsequent (stacked) colorbar is padded past the
+ # *measured* outer extent of the previous one (its tick labels AND axis label) so it never
+ # overlaps it.
+ n_on_side = side_counts.get(location, 0)
+ ref_in = axes_size_in[0] if location in {"left", "right"} else axes_size_in[1]
+ side_clearance = clearance.get(location, 0.0)
+ pad_spec: str | Fixed
+ if n_on_side:
+ pad_spec = Fixed(prev_outer.get(location, 0.0) + CBAR_STACK_GAP_INCHES)
+ elif side_clearance > _CBAR_DECORATION_EPS_INCHES:
+ pad_spec = Fixed(side_clearance + max(pad, 0.0) * ref_in)
  else:
- pad_axes = pad + trackers_axes[location]
- y0 = -pad_axes - fraction if location == "bottom" else 1 + pad_axes
- bbox = (0.0, float(y0), 1.0, float(fraction))
- cax = inset_axes(
- spec.ax,
- width="100%",
- height="100%",
- loc="center",
- bbox_to_anchor=bbox,
- bbox_transform=spec.ax.transAxes,
- borderpad=0.0,
+ pad_spec = f"{max(pad, 0.0) * 100}%"
+ cax = divider.append_axes(
+ location,
+ size=f"{max(fraction, 0.0) * 100}%",
+ pad=pad_spec,
+ axes_class=Axes,
  )
-
- cb = fig.colorbar(spec.mappable, cax=cax, **cbar_kwargs)
- if location == "left":
- cb.ax.yaxis.set_ticks_position("left")
- cb.ax.yaxis.set_label_position("left")
- cb.ax.tick_params(labelleft=True, labelright=False)
- elif location == "top":
- cb.ax.xaxis.set_ticks_position("top")
- cb.ax.xaxis.set_label_position("top")
- cb.ax.tick_params(labeltop=True, labelbottom=False)
- elif location == "right":
- cb.ax.yaxis.set_ticks_position("right")
- cb.ax.yaxis.set_label_position("right")
- cb.ax.tick_params(labelright=True, labelleft=False)
- elif location == "bottom":
- cb.ax.xaxis.set_ticks_position("bottom")
- cb.ax.xaxis.set_label_position("bottom")
- cb.ax.tick_params(labelbottom=True, labeltop=False)
+ side_counts[location] = n_on_side + 1
+ cb = fig.colorbar(spec.mappable, cax=cax, orientation=orientation, **cbar_kwargs)
+ tick_axis, opposite = _CBAR_TICK_SIDE[location]
+ cb_axis = cb.ax.yaxis if tick_axis == "y" else cb.ax.xaxis
+ cb_axis.set_ticks_position(location)
+ cb_axis.set_label_position(location)
+ cb.ax.tick_params(**{f"label{location}": True, f"label{opposite}": False})
 
  final_label = global_label_override or layer_label_override or spec.label
  if final_label:
  cb.set_label(final_label)
- if spec.alpha is not None:
+ # `fig.colorbar(mappable)` already bakes the mappable's alpha into the colorbar's
+ # facecolors, so we only apply `spec.alpha` when the mappable carries no alpha of its own
+ # — otherwise we'd multiply alpha twice and the colorbar would render at alpha squared
+ # (much paler than the layer it represents).
+ if spec.alpha is not None and spec.mappable.get_alpha() is None:
  with contextlib.suppress(Exception):
  cb.solids.set_alpha(spec.alpha)
- bbox_axes = cb.ax.get_tightbbox(renderer).transformed(spec.ax.transAxes.inverted())
-if location == "left":
- trackers_axes["left"] = pad_axes + bbox_axes.width
-elif location == "right":
- trackers_axes["right"] = pad_axes + bbox_axes.width
-elif location == "bottom":
- trackers_axes["bottom"] = pad_axes + bbox_axes.height
-elif location == "top":
- trackers_axes["top"] = pad_axes + bbox_axes.height
+
+# Measure how far this colorbar's ticks/labels/axis-label extend beyond its box, so the
+# next stacked colorbar on this side clears them. The draw is kept unconditionally: it is
+# also load-bearing for the layout engine (skipping it shifts wide colorbars), so it is not
+# safe to skip even for the last colorbar on a side.
+fig.canvas.draw()
+prev_outer[location] = _extent_beyond_box_inches(
+ cb.ax.get_window_extent(renderer), cb.ax.get_tightbbox(renderer), dpi, location
+)
 
  # go through tree
 
@@ -1797,6 +1842,7 @@ def _draw_colorbar(
  fig = fig_params.fig
  fig.canvas.draw()
  renderer = fig.canvas.get_renderer()
+ dpi = fig.get_dpi()
  for axis, requests in pending_colorbars:
  unique_specs: list[ColorbarSpec] = []
  seen_mappables: set[int] = set()
@@ -1806,16 +1852,20 @@ def _draw_colorbar(
  continue
  seen_mappables.add(mappable_id)
  unique_specs.append(spec)
- tight_bbox = axis.get_tightbbox(renderer).transformed(axis.transAxes.inverted())
- base_offsets_axes = {
- "left": max(0.0, -tight_bbox.x0),
- "right": max(0.0, tight_bbox.x1 - 1),
- "bottom": max(0.0, -tight_bbox.y0),
- "top": max(0.0, tight_bbox.y1 - 1),
- }
- trackers_axes = {k: base_offsets_axes[k] for k in base_offsets_axes}
+ # Clearance (inches) that the panel's own ticks, tick labels and title extend beyond
+ # the axes box on each side. The first colorbar on a side is padded past this so it
+ # clears those decorations instead of overlapping them (the divider only knows about
+ # the axes box, not its decorations).
+ box = axis.get_window_extent(renderer)
+ tight = axis.get_tightbbox(renderer)
+ clearance = {side: _extent_beyond_box_inches(box, tight, dpi, side) for side in _CBAR_TICK_SIDE}
+ axes_size_in = (box.width / dpi, box.height / dpi)
+ # One divider per panel so multiple colorbars on the same panel stack via the divider.
+ divider = make_axes_locatable(axis)
+ side_counts: dict[str, int] = {}
+ prev_outer: dict[str, float] = {}
  for spec in unique_specs:
- _draw_colorbar(spec, fig, renderer, base_offsets_axes, trackers_axes)
+ _draw_colorbar(spec, fig, divider, side_counts, clearance, axes_size_in, prev_outer, renderer, dpi)
 
  if fig_params.fig is not None and save is not None:
  save_fig(fig_params.fig, path=save)

src/spatialdata_plot/pl/render_params.py

@@ -219,6 +219,9 @@ class ChannelLegendEntry:
 CBAR_DEFAULT_LOCATION = "right"
 CBAR_DEFAULT_FRACTION = 0.075
 CBAR_DEFAULT_PAD = 0.015
+# Small gap (inches) added beyond a stacked colorbar's measured outer extent (its tick labels and
+# axis label) before placing the next colorbar on the same side, so they never overlap.
+CBAR_STACK_GAP_INCHES = 0.08
 
 
 @dataclass

src/spatialdata_plot/pl/basic.py

@@ -22,7 +22,10 @@
 from matplotlib.backend_bases import RendererBase
 from matplotlib.colors import Colormap, LogNorm, Normalize
 from matplotlib.figure import Figure
-from mpl_toolkits.axes_grid1.inset_locator import inset_axes
+from matplotlib.transforms import Bbox
+from mpl_toolkits.axes_grid1 import make_axes_locatable
+from mpl_toolkits.axes_grid1.axes_divider import AxesDivider
+from mpl_toolkits.axes_grid1.axes_size import Fixed
 from spatialdata import get_extent
 from spatialdata._utils import _deprecation_alias
 from spatialdata.transformations.operations import get_transformation
@@ -43,6 +46,7 @@
  CBAR_DEFAULT_FRACTION,
  CBAR_DEFAULT_LOCATION,
  CBAR_DEFAULT_PAD,
+ CBAR_STACK_GAP_INCHES,
  ChannelLegendEntry,
  CmapParams,
  ColorbarSpec,
@@ -84,6 +88,33 @@
 # once https://github.com/scverse/spatialdata/pull/689/ is in a release
 ColorLike = tuple[float, ...] | list[float] | str
 
+# Below this clearance (inches), a colorbar side is treated as having no axis decorations to clear,
+# so the colorbar keeps its relative pad (matching the historical placement) instead of an absolute one.
+_CBAR_DECORATION_EPS_INCHES = 0.05
+
+# Per colorbar location: the axis ("x"/"y") its ticks live on, and the opposite side.
+_CBAR_TICK_SIDE = {"left": ("y", "right"), "right": ("y", "left"), "top": ("x", "bottom"), "bottom": ("x", "top")}
+
+
+def _extent_beyond_box_inches(box: Bbox, tight: Bbox | None, dpi: float, side: str) -> float:
+ """Inches that ``tight`` (an artist's full extent incl. ticks/labels) sticks out past ``box`` on ``side``.
+
+ Returns ``0.0`` when there is no overhang, when ``tight`` is ``None`` (an axes with nothing
+ drawable), or when ``dpi`` is non-positive. Used both to clear a panel's own decorations and to
+ clear a stacked colorbar's labels before placing the next one.
+ """
+ if tight is None or dpi <= 0:
+ return 0.0
+ if side == "left":
+ delta = box.x0 - tight.x0
+ elif side == "right":
+ delta = tight.x1 - box.x1
+ elif side == "bottom":
+ delta = box.y0 - tight.y0
+ else: # top
+ delta = tight.y1 - box.y1
+ return max(0.0, float(delta) / dpi)
+
 
 @register_spatial_data_accessor("pl")
 class PlotAccessor:
@@ -1522,9 +1553,13 @@ def show(
  def _draw_colorbar(
  spec: ColorbarSpec,
  fig: Figure,
+ divider: AxesDivider,
+ side_counts: dict[str, int],
+ clearance: dict[str, float],
+ axes_size_in: tuple[float, float],
+ prev_outer: dict[str, float],
  renderer: RendererBase,
- base_offsets_axes: dict[str, float],
- trackers_axes: dict[str, float],
+ dpi: float,
  ) -> None:
  norm = spec.mappable.norm
  if isinstance(norm, LogNorm):
@@ -1551,63 +1586,73 @@ def _draw_colorbar(
  location = cast(str, layout.get("location", base_layout["location"]))
  if location not in {"left", "right", "top", "bottom"}:
  location = CBAR_DEFAULT_LOCATION
- default_orientation = "vertical" if location in {"right", "left"} else "horizontal"
- cbar_kwargs.setdefault("orientation", default_orientation)
+ orientation = "vertical" if location in {"right", "left"} else "horizontal"
+ # Orientation is fixed by the location (the divider places a left/right colorbar
+ # vertically and a top/bottom one horizontally); warn rather than silently ignore a
+ # conflicting user-supplied orientation.
+ user_orientation = cbar_kwargs.pop("orientation", None)
+ if user_orientation is not None and user_orientation != orientation:
+ warnings.warn(
+ f"`orientation` is determined by the colorbar location ('{location}' -> '{orientation}'); "
+ f"the requested '{user_orientation}' is ignored.",
+ UserWarning,
+ stacklevel=2,
+ )
 
  fraction = float(cast(float | int, layout.get("fraction", base_layout["fraction"])))
  pad = float(cast(float | int, layout.get("pad", base_layout["pad"])))
 
- if location in {"left", "right"}:
- pad_axes = pad + trackers_axes[location]
- x0 = -pad_axes - fraction if location == "left" else 1 + pad_axes
- bbox = (float(x0), 0.0, float(fraction), 1.0)
+ # Append the colorbar axes through the panel's shared divider. This steals space from the
+ # panel (so the colorbar matches the equal-aspect plot's extent) and keeps it inside the
+ # panel's grid cell, never overflowing into a neighbouring panel.
+ # Pad of the first colorbar on a side clears the panel's own decorations (ticks/labels/
+ # title); a side with negligible clearance (typically "right") keeps the relative pad to
+ # match the historical placement. Each subsequent (stacked) colorbar is padded past the
+ # *measured* outer extent of the previous one (its tick labels AND axis label) so it never
+ # overlaps it.
+ n_on_side = side_counts.get(location, 0)
+ ref_in = axes_size_in[0] if location in {"left", "right"} else axes_size_in[1]
+ side_clearance = clearance.get(location, 0.0)
+ pad_spec: str | Fixed
+ if n_on_side:
+ pad_spec = Fixed(prev_outer.get(location, 0.0) + CBAR_STACK_GAP_INCHES)
+ elif side_clearance > _CBAR_DECORATION_EPS_INCHES:
+ pad_spec = Fixed(side_clearance + max(pad, 0.0) * ref_in)
  else:
- pad_axes = pad + trackers_axes[location]
- y0 = -pad_axes - fraction if location == "bottom" else 1 + pad_axes
- bbox = (0.0, float(y0), 1.0, float(fraction))
- cax = inset_axes(
- spec.ax,
- width="100%",
- height="100%",
- loc="center",
- bbox_to_anchor=bbox,
- bbox_transform=spec.ax.transAxes,
- borderpad=0.0,
+ pad_spec = f"{max(pad, 0.0) * 100}%"
+ cax = divider.append_axes(
+ location,
+ size=f"{max(fraction, 0.0) * 100}%",
+ pad=pad_spec,
+ axes_class=Axes,
  )
-
- cb = fig.colorbar(spec.mappable, cax=cax, **cbar_kwargs)
- if location == "left":
- cb.ax.yaxis.set_ticks_position("left")
- cb.ax.yaxis.set_label_position("left")
- cb.ax.tick_params(labelleft=True, labelright=False)
- elif location == "top":
- cb.ax.xaxis.set_ticks_position("top")
- cb.ax.xaxis.set_label_position("top")
- cb.ax.tick_params(labeltop=True, labelbottom=False)
- elif location == "right":
- cb.ax.yaxis.set_ticks_position("right")
- cb.ax.yaxis.set_label_position("right")
- cb.ax.tick_params(labelright=True, labelleft=False)
- elif location == "bottom":
- cb.ax.xaxis.set_ticks_position("bottom")
- cb.ax.xaxis.set_label_position("bottom")
- cb.ax.tick_params(labelbottom=True, labeltop=False)
+ side_counts[location] = n_on_side + 1
+ cb = fig.colorbar(spec.mappable, cax=cax, orientation=orientation, **cbar_kwargs)
+ tick_axis, opposite = _CBAR_TICK_SIDE[location]
+ cb_axis = cb.ax.yaxis if tick_axis == "y" else cb.ax.xaxis
+ cb_axis.set_ticks_position(location)
+ cb_axis.set_label_position(location)
+ cb.ax.tick_params(**{f"label{location}": True, f"label{opposite}": False})
 
  final_label = global_label_override or layer_label_override or spec.label
  if final_label:
  cb.set_label(final_label)
- if spec.alpha is not None:
+ # `fig.colorbar(mappable)` already bakes the mappable's alpha into the colorbar's
+ # facecolors, so we only apply `spec.alpha` when the mappable carries no alpha of its own
+ # — otherwise we'd multiply alpha twice and the colorbar would render at alpha squared
+ # (much paler than the layer it represents).
+ if spec.alpha is not None and spec.mappable.get_alpha() is None:
  with contextlib.suppress(Exception):
  cb.solids.set_alpha(spec.alpha)
- bbox_axes = cb.ax.get_tightbbox(renderer).transformed(spec.ax.transAxes.inverted())
-if location == "left":
- trackers_axes["left"] = pad_axes + bbox_axes.width
-elif location == "right":
- trackers_axes["right"] = pad_axes + bbox_axes.width
-elif location == "bottom":
- trackers_axes["bottom"] = pad_axes + bbox_axes.height
-elif location == "top":
- trackers_axes["top"] = pad_axes + bbox_axes.height
+
+# Measure how far this colorbar's ticks/labels/axis-label extend beyond its box, so the
+# next stacked colorbar on this side clears them. The draw is kept unconditionally: it is
+# also load-bearing for the layout engine (skipping it shifts wide colorbars), so it is not
+# safe to skip even for the last colorbar on a side.
+fig.canvas.draw()
+prev_outer[location] = _extent_beyond_box_inches(
+ cb.ax.get_window_extent(renderer), cb.ax.get_tightbbox(renderer), dpi, location
+)
 
  # go through tree
 
@@ -1797,6 +1842,7 @@ def _draw_colorbar(
  fig = fig_params.fig
  fig.canvas.draw()
  renderer = fig.canvas.get_renderer()
+ dpi = fig.get_dpi()
  for axis, requests in pending_colorbars:
  unique_specs: list[ColorbarSpec] = []
  seen_mappables: set[int] = set()
@@ -1806,16 +1852,20 @@ def _draw_colorbar(
  continue
  seen_mappables.add(mappable_id)
  unique_specs.append(spec)
- tight_bbox = axis.get_tightbbox(renderer).transformed(axis.transAxes.inverted())
- base_offsets_axes = {
- "left": max(0.0, -tight_bbox.x0),
- "right": max(0.0, tight_bbox.x1 - 1),
- "bottom": max(0.0, -tight_bbox.y0),
- "top": max(0.0, tight_bbox.y1 - 1),
- }
- trackers_axes = {k: base_offsets_axes[k] for k in base_offsets_axes}
+ # Clearance (inches) that the panel's own ticks, tick labels and title extend beyond
+ # the axes box on each side. The first colorbar on a side is padded past this so it
+ # clears those decorations instead of overlapping them (the divider only knows about
+ # the axes box, not its decorations).
+ box = axis.get_window_extent(renderer)
+ tight = axis.get_tightbbox(renderer)
+ clearance = {side: _extent_beyond_box_inches(box, tight, dpi, side) for side in _CBAR_TICK_SIDE}
+ axes_size_in = (box.width / dpi, box.height / dpi)
+ # One divider per panel so multiple colorbars on the same panel stack via the divider.
+ divider = make_axes_locatable(axis)
+ side_counts: dict[str, int] = {}
+ prev_outer: dict[str, float] = {}
  for spec in unique_specs:
- _draw_colorbar(spec, fig, renderer, base_offsets_axes, trackers_axes)
+ _draw_colorbar(spec, fig, divider, side_counts, clearance, axes_size_in, prev_outer, renderer, dpi)
 
  if fig_params.fig is not None and save is not None:
  save_fig(fig_params.fig, path=save)

src/spatialdata_plot/pl/render_params.py

@@ -219,6 +219,9 @@ class ChannelLegendEntry:
 CBAR_DEFAULT_LOCATION = "right"
 CBAR_DEFAULT_FRACTION = 0.075
 CBAR_DEFAULT_PAD = 0.015
+# Small gap (inches) added beyond a stacked colorbar's measured outer extent (its tick labels and
+# axis label) before placing the next colorbar on the same side, so they never overlap.
+CBAR_STACK_GAP_INCHES = 0.08
 
 
 @dataclass

src/spatialdata_plot/pl/basic.py

@@ -22,7 +22,10 @@
 from matplotlib.backend_bases import RendererBase
 from matplotlib.colors import Colormap, LogNorm, Normalize
 from matplotlib.figure import Figure
-from mpl_toolkits.axes_grid1.inset_locator import inset_axes
+from matplotlib.transforms import Bbox
+from mpl_toolkits.axes_grid1 import make_axes_locatable
+from mpl_toolkits.axes_grid1.axes_divider import AxesDivider
+from mpl_toolkits.axes_grid1.axes_size import Fixed
 from spatialdata import get_extent
 from spatialdata._utils import _deprecation_alias
 from spatialdata.transformations.operations import get_transformation
@@ -43,6 +46,7 @@
  CBAR_DEFAULT_FRACTION,
  CBAR_DEFAULT_LOCATION,
  CBAR_DEFAULT_PAD,
+ CBAR_STACK_GAP_INCHES,
  ChannelLegendEntry,
  CmapParams,
  ColorbarSpec,
@@ -84,6 +88,33 @@
 # once https://github.com/scverse/spatialdata/pull/689/ is in a release
 ColorLike = tuple[float, ...] | list[float] | str
 
+# Below this clearance (inches), a colorbar side is treated as having no axis decorations to clear,
+# so the colorbar keeps its relative pad (matching the historical placement) instead of an absolute one.
+_CBAR_DECORATION_EPS_INCHES = 0.05
+
+# Per colorbar location: the axis ("x"/"y") its ticks live on, and the opposite side.
+_CBAR_TICK_SIDE = {"left": ("y", "right"), "right": ("y", "left"), "top": ("x", "bottom"), "bottom": ("x", "top")}
+
+
+def _extent_beyond_box_inches(box: Bbox, tight: Bbox | None, dpi: float, side: str) -> float:
+ """Inches that ``tight`` (an artist's full extent incl. ticks/labels) sticks out past ``box`` on ``side``.
+
+ Returns ``0.0`` when there is no overhang, when ``tight`` is ``None`` (an axes with nothing
+ drawable), or when ``dpi`` is non-positive. Used both to clear a panel's own decorations and to
+ clear a stacked colorbar's labels before placing the next one.
+ """
+ if tight is None or dpi <= 0:
+ return 0.0
+ if side == "left":
+ delta = box.x0 - tight.x0
+ elif side == "right":
+ delta = tight.x1 - box.x1
+ elif side == "bottom":
+ delta = box.y0 - tight.y0
+ else: # top
+ delta = tight.y1 - box.y1
+ return max(0.0, float(delta) / dpi)
+
 
 @register_spatial_data_accessor("pl")
 class PlotAccessor:
@@ -1522,9 +1553,13 @@ def show(
  def _draw_colorbar(
  spec: ColorbarSpec,
  fig: Figure,
+ divider: AxesDivider,
+ side_counts: dict[str, int],
+ clearance: dict[str, float],
+ axes_size_in: tuple[float, float],
+ prev_outer: dict[str, float],
  renderer: RendererBase,
- base_offsets_axes: dict[str, float],
- trackers_axes: dict[str, float],
+ dpi: float,
  ) -> None:
  norm = spec.mappable.norm
  if isinstance(norm, LogNorm):
@@ -1551,63 +1586,73 @@ def _draw_colorbar(
  location = cast(str, layout.get("location", base_layout["location"]))
  if location not in {"left", "right", "top", "bottom"}:
  location = CBAR_DEFAULT_LOCATION
- default_orientation = "vertical" if location in {"right", "left"} else "horizontal"
- cbar_kwargs.setdefault("orientation", default_orientation)
+ orientation = "vertical" if location in {"right", "left"} else "horizontal"
+ # Orientation is fixed by the location (the divider places a left/right colorbar
+ # vertically and a top/bottom one horizontally); warn rather than silently ignore a
+ # conflicting user-supplied orientation.
+ user_orientation = cbar_kwargs.pop("orientation", None)
+ if user_orientation is not None and user_orientation != orientation:
+ warnings.warn(
+ f"`orientation` is determined by the colorbar location ('{location}' -> '{orientation}'); "
+ f"the requested '{user_orientation}' is ignored.",
+ UserWarning,
+ stacklevel=2,
+ )
 
  fraction = float(cast(float | int, layout.get("fraction", base_layout["fraction"])))
  pad = float(cast(float | int, layout.get("pad", base_layout["pad"])))
 
- if location in {"left", "right"}:
- pad_axes = pad + trackers_axes[location]
- x0 = -pad_axes - fraction if location == "left" else 1 + pad_axes
- bbox = (float(x0), 0.0, float(fraction), 1.0)
+ # Append the colorbar axes through the panel's shared divider. This steals space from the
+ # panel (so the colorbar matches the equal-aspect plot's extent) and keeps it inside the
+ # panel's grid cell, never overflowing into a neighbouring panel.
+ # Pad of the first colorbar on a side clears the panel's own decorations (ticks/labels/
+ # title); a side with negligible clearance (typically "right") keeps the relative pad to
+ # match the historical placement. Each subsequent (stacked) colorbar is padded past the
+ # *measured* outer extent of the previous one (its tick labels AND axis label) so it never
+ # overlaps it.
+ n_on_side = side_counts.get(location, 0)
+ ref_in = axes_size_in[0] if location in {"left", "right"} else axes_size_in[1]
+ side_clearance = clearance.get(location, 0.0)
+ pad_spec: str | Fixed
+ if n_on_side:
+ pad_spec = Fixed(prev_outer.get(location, 0.0) + CBAR_STACK_GAP_INCHES)
+ elif side_clearance > _CBAR_DECORATION_EPS_INCHES:
+ pad_spec = Fixed(side_clearance + max(pad, 0.0) * ref_in)
  else:
- pad_axes = pad + trackers_axes[location]
- y0 = -pad_axes - fraction if location == "bottom" else 1 + pad_axes
- bbox = (0.0, float(y0), 1.0, float(fraction))
- cax = inset_axes(
- spec.ax,
- width="100%",
- height="100%",
- loc="center",
- bbox_to_anchor=bbox,
- bbox_transform=spec.ax.transAxes,
- borderpad=0.0,
+ pad_spec = f"{max(pad, 0.0) * 100}%"
+ cax = divider.append_axes(
+ location,
+ size=f"{max(fraction, 0.0) * 100}%",
+ pad=pad_spec,
+ axes_class=Axes,
  )
-
- cb = fig.colorbar(spec.mappable, cax=cax, **cbar_kwargs)
- if location == "left":
- cb.ax.yaxis.set_ticks_position("left")
- cb.ax.yaxis.set_label_position("left")
- cb.ax.tick_params(labelleft=True, labelright=False)
- elif location == "top":
- cb.ax.xaxis.set_ticks_position("top")
- cb.ax.xaxis.set_label_position("top")
- cb.ax.tick_params(labeltop=True, labelbottom=False)
- elif location == "right":
- cb.ax.yaxis.set_ticks_position("right")
- cb.ax.yaxis.set_label_position("right")
- cb.ax.tick_params(labelright=True, labelleft=False)
- elif location == "bottom":
- cb.ax.xaxis.set_ticks_position("bottom")
- cb.ax.xaxis.set_label_position("bottom")
- cb.ax.tick_params(labelbottom=True, labeltop=False)
+ side_counts[location] = n_on_side + 1
+ cb = fig.colorbar(spec.mappable, cax=cax, orientation=orientation, **cbar_kwargs)
+ tick_axis, opposite = _CBAR_TICK_SIDE[location]
+ cb_axis = cb.ax.yaxis if tick_axis == "y" else cb.ax.xaxis
+ cb_axis.set_ticks_position(location)
+ cb_axis.set_label_position(location)
+ cb.ax.tick_params(**{f"label{location}": True, f"label{opposite}": False})
 
  final_label = global_label_override or layer_label_override or spec.label
  if final_label:
  cb.set_label(final_label)
- if spec.alpha is not None:
+ # `fig.colorbar(mappable)` already bakes the mappable's alpha into the colorbar's
+ # facecolors, so we only apply `spec.alpha` when the mappable carries no alpha of its own
+ # — otherwise we'd multiply alpha twice and the colorbar would render at alpha squared
+ # (much paler than the layer it represents).
+ if spec.alpha is not None and spec.mappable.get_alpha() is None:
  with contextlib.suppress(Exception):
  cb.solids.set_alpha(spec.alpha)
- bbox_axes = cb.ax.get_tightbbox(renderer).transformed(spec.ax.transAxes.inverted())
-if location == "left":
- trackers_axes["left"] = pad_axes + bbox_axes.width
-elif location == "right":
- trackers_axes["right"] = pad_axes + bbox_axes.width
-elif location == "bottom":
- trackers_axes["bottom"] = pad_axes + bbox_axes.height
-elif location == "top":
- trackers_axes["top"] = pad_axes + bbox_axes.height
+
+# Measure how far this colorbar's ticks/labels/axis-label extend beyond its box, so the
+# next stacked colorbar on this side clears them. The draw is kept unconditionally: it is
+# also load-bearing for the layout engine (skipping it shifts wide colorbars), so it is not
+# safe to skip even for the last colorbar on a side.
+fig.canvas.draw()
+prev_outer[location] = _extent_beyond_box_inches(
+ cb.ax.get_window_extent(renderer), cb.ax.get_tightbbox(renderer), dpi, location
+)
 
  # go through tree
 
@@ -1797,6 +1842,7 @@ def _draw_colorbar(
  fig = fig_params.fig
  fig.canvas.draw()
  renderer = fig.canvas.get_renderer()
+ dpi = fig.get_dpi()
  for axis, requests in pending_colorbars:
  unique_specs: list[ColorbarSpec] = []
  seen_mappables: set[int] = set()
@@ -1806,16 +1852,20 @@ def _draw_colorbar(
  continue
  seen_mappables.add(mappable_id)
  unique_specs.append(spec)
- tight_bbox = axis.get_tightbbox(renderer).transformed(axis.transAxes.inverted())
- base_offsets_axes = {
- "left": max(0.0, -tight_bbox.x0),
- "right": max(0.0, tight_bbox.x1 - 1),
- "bottom": max(0.0, -tight_bbox.y0),
- "top": max(0.0, tight_bbox.y1 - 1),
- }
- trackers_axes = {k: base_offsets_axes[k] for k in base_offsets_axes}
+ # Clearance (inches) that the panel's own ticks, tick labels and title extend beyond
+ # the axes box on each side. The first colorbar on a side is padded past this so it
+ # clears those decorations instead of overlapping them (the divider only knows about
+ # the axes box, not its decorations).
+ box = axis.get_window_extent(renderer)
+ tight = axis.get_tightbbox(renderer)
+ clearance = {side: _extent_beyond_box_inches(box, tight, dpi, side) for side in _CBAR_TICK_SIDE}
+ axes_size_in = (box.width / dpi, box.height / dpi)
+ # One divider per panel so multiple colorbars on the same panel stack via the divider.
+ divider = make_axes_locatable(axis)
+ side_counts: dict[str, int] = {}
+ prev_outer: dict[str, float] = {}
  for spec in unique_specs:
- _draw_colorbar(spec, fig, renderer, base_offsets_axes, trackers_axes)
+ _draw_colorbar(spec, fig, divider, side_counts, clearance, axes_size_in, prev_outer, renderer, dpi)
 
  if fig_params.fig is not None and save is not None:
  save_fig(fig_params.fig, path=save)

src/spatialdata_plot/pl/render_params.py

@@ -219,6 +219,9 @@ class ChannelLegendEntry:
 CBAR_DEFAULT_LOCATION = "right"
 CBAR_DEFAULT_FRACTION = 0.075
 CBAR_DEFAULT_PAD = 0.015
+# Small gap (inches) added beyond a stacked colorbar's measured outer extent (its tick labels and
+# axis label) before placing the next colorbar on the same side, so they never overlap.
+CBAR_STACK_GAP_INCHES = 0.08
 
 
 @dataclass

src/spatialdata_plot/pl/basic.py

@@ -22,7 +22,10 @@
 from matplotlib.backend_bases import RendererBase
 from matplotlib.colors import Colormap, LogNorm, Normalize
 from matplotlib.figure import Figure
-from mpl_toolkits.axes_grid1.inset_locator import inset_axes
+from matplotlib.transforms import Bbox
+from mpl_toolkits.axes_grid1 import make_axes_locatable
+from mpl_toolkits.axes_grid1.axes_divider import AxesDivider
+from mpl_toolkits.axes_grid1.axes_size import Fixed
 from spatialdata import get_extent
 from spatialdata._utils import _deprecation_alias
 from spatialdata.transformations.operations import get_transformation
@@ -43,6 +46,7 @@
  CBAR_DEFAULT_FRACTION,
  CBAR_DEFAULT_LOCATION,
  CBAR_DEFAULT_PAD,
+ CBAR_STACK_GAP_INCHES,
  ChannelLegendEntry,
  CmapParams,
  ColorbarSpec,
@@ -84,6 +88,33 @@
 # once https://github.com/scverse/spatialdata/pull/689/ is in a release
 ColorLike = tuple[float, ...] | list[float] | str
 
+# Below this clearance (inches), a colorbar side is treated as having no axis decorations to clear,
+# so the colorbar keeps its relative pad (matching the historical placement) instead of an absolute one.
+_CBAR_DECORATION_EPS_INCHES = 0.05
+
+# Per colorbar location: the axis ("x"/"y") its ticks live on, and the opposite side.
+_CBAR_TICK_SIDE = {"left": ("y", "right"), "right": ("y", "left"), "top": ("x", "bottom"), "bottom": ("x", "top")}
+
+
+def _extent_beyond_box_inches(box: Bbox, tight: Bbox | None, dpi: float, side: str) -> float:
+ """Inches that ``tight`` (an artist's full extent incl. ticks/labels) sticks out past ``box`` on ``side``.
+
+ Returns ``0.0`` when there is no overhang, when ``tight`` is ``None`` (an axes with nothing
+ drawable), or when ``dpi`` is non-positive. Used both to clear a panel's own decorations and to
+ clear a stacked colorbar's labels before placing the next one.
+ """
+ if tight is None or dpi <= 0:
+ return 0.0
+ if side == "left":
+ delta = box.x0 - tight.x0
+ elif side == "right":
+ delta = tight.x1 - box.x1
+ elif side == "bottom":
+ delta = box.y0 - tight.y0
+ else: # top
+ delta = tight.y1 - box.y1
+ return max(0.0, float(delta) / dpi)
+
 
 @register_spatial_data_accessor("pl")
 class PlotAccessor:
@@ -1522,9 +1553,13 @@ def show(
  def _draw_colorbar(
  spec: ColorbarSpec,
  fig: Figure,
+ divider: AxesDivider,
+ side_counts: dict[str, int],
+ clearance: dict[str, float],
+ axes_size_in: tuple[float, float],
+ prev_outer: dict[str, float],
  renderer: RendererBase,
- base_offsets_axes: dict[str, float],
- trackers_axes: dict[str, float],
+ dpi: float,
  ) -> None:
  norm = spec.mappable.norm
  if isinstance(norm, LogNorm):
@@ -1551,63 +1586,73 @@ def _draw_colorbar(
  location = cast(str, layout.get("location", base_layout["location"]))
  if location not in {"left", "right", "top", "bottom"}:
  location = CBAR_DEFAULT_LOCATION
- default_orientation = "vertical" if location in {"right", "left"} else "horizontal"
- cbar_kwargs.setdefault("orientation", default_orientation)
+ orientation = "vertical" if location in {"right", "left"} else "horizontal"
+ # Orientation is fixed by the location (the divider places a left/right colorbar
+ # vertically and a top/bottom one horizontally); warn rather than silently ignore a
+ # conflicting user-supplied orientation.
+ user_orientation = cbar_kwargs.pop("orientation", None)
+ if user_orientation is not None and user_orientation != orientation:
+ warnings.warn(
+ f"`orientation` is determined by the colorbar location ('{location}' -> '{orientation}'); "
+ f"the requested '{user_orientation}' is ignored.",
+ UserWarning,
+ stacklevel=2,
+ )
 
  fraction = float(cast(float | int, layout.get("fraction", base_layout["fraction"])))
  pad = float(cast(float | int, layout.get("pad", base_layout["pad"])))
 
- if location in {"left", "right"}:
- pad_axes = pad + trackers_axes[location]
- x0 = -pad_axes - fraction if location == "left" else 1 + pad_axes
- bbox = (float(x0), 0.0, float(fraction), 1.0)
+ # Append the colorbar axes through the panel's shared divider. This steals space from the
+ # panel (so the colorbar matches the equal-aspect plot's extent) and keeps it inside the
+ # panel's grid cell, never overflowing into a neighbouring panel.
+ # Pad of the first colorbar on a side clears the panel's own decorations (ticks/labels/
+ # title); a side with negligible clearance (typically "right") keeps the relative pad to
+ # match the historical placement. Each subsequent (stacked) colorbar is padded past the
+ # *measured* outer extent of the previous one (its tick labels AND axis label) so it never
+ # overlaps it.
+ n_on_side = side_counts.get(location, 0)
+ ref_in = axes_size_in[0] if location in {"left", "right"} else axes_size_in[1]
+ side_clearance = clearance.get(location, 0.0)
+ pad_spec: str | Fixed
+ if n_on_side:
+ pad_spec = Fixed(prev_outer.get(location, 0.0) + CBAR_STACK_GAP_INCHES)
+ elif side_clearance > _CBAR_DECORATION_EPS_INCHES:
+ pad_spec = Fixed(side_clearance + max(pad, 0.0) * ref_in)
  else:
- pad_axes = pad + trackers_axes[location]
- y0 = -pad_axes - fraction if location == "bottom" else 1 + pad_axes
- bbox = (0.0, float(y0), 1.0, float(fraction))
- cax = inset_axes(
- spec.ax,
- width="100%",
- height="100%",
- loc="center",
- bbox_to_anchor=bbox,
- bbox_transform=spec.ax.transAxes,
- borderpad=0.0,
+ pad_spec = f"{max(pad, 0.0) * 100}%"
+ cax = divider.append_axes(
+ location,
+ size=f"{max(fraction, 0.0) * 100}%",
+ pad=pad_spec,
+ axes_class=Axes,
  )
-
- cb = fig.colorbar(spec.mappable, cax=cax, **cbar_kwargs)
- if location == "left":
- cb.ax.yaxis.set_ticks_position("left")
- cb.ax.yaxis.set_label_position("left")
- cb.ax.tick_params(labelleft=True, labelright=False)
- elif location == "top":
- cb.ax.xaxis.set_ticks_position("top")
- cb.ax.xaxis.set_label_position("top")
- cb.ax.tick_params(labeltop=True, labelbottom=False)
- elif location == "right":
- cb.ax.yaxis.set_ticks_position("right")
- cb.ax.yaxis.set_label_position("right")
- cb.ax.tick_params(labelright=True, labelleft=False)
- elif location == "bottom":
- cb.ax.xaxis.set_ticks_position("bottom")
- cb.ax.xaxis.set_label_position("bottom")
- cb.ax.tick_params(labelbottom=True, labeltop=False)
+ side_counts[location] = n_on_side + 1
+ cb = fig.colorbar(spec.mappable, cax=cax, orientation=orientation, **cbar_kwargs)
+ tick_axis, opposite = _CBAR_TICK_SIDE[location]
+ cb_axis = cb.ax.yaxis if tick_axis == "y" else cb.ax.xaxis
+ cb_axis.set_ticks_position(location)
+ cb_axis.set_label_position(location)
+ cb.ax.tick_params(**{f"label{location}": True, f"label{opposite}": False})
 
  final_label = global_label_override or layer_label_override or spec.label
  if final_label:
  cb.set_label(final_label)
- if spec.alpha is not None:
+ # `fig.colorbar(mappable)` already bakes the mappable's alpha into the colorbar's
+ # facecolors, so we only apply `spec.alpha` when the mappable carries no alpha of its own
+ # — otherwise we'd multiply alpha twice and the colorbar would render at alpha squared
+ # (much paler than the layer it represents).
+ if spec.alpha is not None and spec.mappable.get_alpha() is None:
  with contextlib.suppress(Exception):
  cb.solids.set_alpha(spec.alpha)
- bbox_axes = cb.ax.get_tightbbox(renderer).transformed(spec.ax.transAxes.inverted())
-if location == "left":
- trackers_axes["left"] = pad_axes + bbox_axes.width
-elif location == "right":
- trackers_axes["right"] = pad_axes + bbox_axes.width
-elif location == "bottom":
- trackers_axes["bottom"] = pad_axes + bbox_axes.height
-elif location == "top":
- trackers_axes["top"] = pad_axes + bbox_axes.height
+
+# Measure how far this colorbar's ticks/labels/axis-label extend beyond its box, so the
+# next stacked colorbar on this side clears them. The draw is kept unconditionally: it is
+# also load-bearing for the layout engine (skipping it shifts wide colorbars), so it is not
+# safe to skip even for the last colorbar on a side.
+fig.canvas.draw()
+prev_outer[location] = _extent_beyond_box_inches(
+ cb.ax.get_window_extent(renderer), cb.ax.get_tightbbox(renderer), dpi, location
+)
 
  # go through tree
 
@@ -1797,6 +1842,7 @@ def _draw_colorbar(
  fig = fig_params.fig
  fig.canvas.draw()
  renderer = fig.canvas.get_renderer()
+ dpi = fig.get_dpi()
  for axis, requests in pending_colorbars:
  unique_specs: list[ColorbarSpec] = []
  seen_mappables: set[int] = set()
@@ -1806,16 +1852,20 @@ def _draw_colorbar(
  continue
  seen_mappables.add(mappable_id)
  unique_specs.append(spec)
- tight_bbox = axis.get_tightbbox(renderer).transformed(axis.transAxes.inverted())
- base_offsets_axes = {
- "left": max(0.0, -tight_bbox.x0),
- "right": max(0.0, tight_bbox.x1 - 1),
- "bottom": max(0.0, -tight_bbox.y0),
- "top": max(0.0, tight_bbox.y1 - 1),
- }
- trackers_axes = {k: base_offsets_axes[k] for k in base_offsets_axes}
+ # Clearance (inches) that the panel's own ticks, tick labels and title extend beyond
+ # the axes box on each side. The first colorbar on a side is padded past this so it
+ # clears those decorations instead of overlapping them (the divider only knows about
+ # the axes box, not its decorations).
+ box = axis.get_window_extent(renderer)
+ tight = axis.get_tightbbox(renderer)
+ clearance = {side: _extent_beyond_box_inches(box, tight, dpi, side) for side in _CBAR_TICK_SIDE}
+ axes_size_in = (box.width / dpi, box.height / dpi)
+ # One divider per panel so multiple colorbars on the same panel stack via the divider.
+ divider = make_axes_locatable(axis)
+ side_counts: dict[str, int] = {}
+ prev_outer: dict[str, float] = {}
  for spec in unique_specs:
- _draw_colorbar(spec, fig, renderer, base_offsets_axes, trackers_axes)
+ _draw_colorbar(spec, fig, divider, side_counts, clearance, axes_size_in, prev_outer, renderer, dpi)
 
  if fig_params.fig is not None and save is not None:
  save_fig(fig_params.fig, path=save)

src/spatialdata_plot/pl/render_params.py

@@ -219,6 +219,9 @@ class ChannelLegendEntry:
 CBAR_DEFAULT_LOCATION = "right"
 CBAR_DEFAULT_FRACTION = 0.075
 CBAR_DEFAULT_PAD = 0.015
+# Small gap (inches) added beyond a stacked colorbar's measured outer extent (its tick labels and
+# axis label) before placing the next colorbar on the same side, so they never overlap.
+CBAR_STACK_GAP_INCHES = 0.08
 
 
 @dataclass

src/spatialdata_plot/pl/basic.py

@@ -22,7 +22,10 @@
 from matplotlib.backend_bases import RendererBase
 from matplotlib.colors import Colormap, LogNorm, Normalize
 from matplotlib.figure import Figure
-from mpl_toolkits.axes_grid1.inset_locator import inset_axes
+from matplotlib.transforms import Bbox
+from mpl_toolkits.axes_grid1 import make_axes_locatable
+from mpl_toolkits.axes_grid1.axes_divider import AxesDivider
+from mpl_toolkits.axes_grid1.axes_size import Fixed
 from spatialdata import get_extent
 from spatialdata._utils import _deprecation_alias
 from spatialdata.transformations.operations import get_transformation
@@ -43,6 +46,7 @@
  CBAR_DEFAULT_FRACTION,
  CBAR_DEFAULT_LOCATION,
  CBAR_DEFAULT_PAD,
+ CBAR_STACK_GAP_INCHES,
  ChannelLegendEntry,
  CmapParams,
  ColorbarSpec,
@@ -84,6 +88,33 @@
 # once https://github.com/scverse/spatialdata/pull/689/ is in a release
 ColorLike = tuple[float, ...] | list[float] | str
 
+# Below this clearance (inches), a colorbar side is treated as having no axis decorations to clear,
+# so the colorbar keeps its relative pad (matching the historical placement) instead of an absolute one.
+_CBAR_DECORATION_EPS_INCHES = 0.05
+
+# Per colorbar location: the axis ("x"/"y") its ticks live on, and the opposite side.
+_CBAR_TICK_SIDE = {"left": ("y", "right"), "right": ("y", "left"), "top": ("x", "bottom"), "bottom": ("x", "top")}
+
+
+def _extent_beyond_box_inches(box: Bbox, tight: Bbox | None, dpi: float, side: str) -> float:
+ """Inches that ``tight`` (an artist's full extent incl. ticks/labels) sticks out past ``box`` on ``side``.
+
+ Returns ``0.0`` when there is no overhang, when ``tight`` is ``None`` (an axes with nothing
+ drawable), or when ``dpi`` is non-positive. Used both to clear a panel's own decorations and to
+ clear a stacked colorbar's labels before placing the next one.
+ """
+ if tight is None or dpi <= 0:
+ return 0.0
+ if side == "left":
+ delta = box.x0 - tight.x0
+ elif side == "right":
+ delta = tight.x1 - box.x1
+ elif side == "bottom":
+ delta = box.y0 - tight.y0
+ else: # top
+ delta = tight.y1 - box.y1
+ return max(0.0, float(delta) / dpi)
+
 
 @register_spatial_data_accessor("pl")
 class PlotAccessor:
@@ -1522,9 +1553,13 @@ def show(
  def _draw_colorbar(
  spec: ColorbarSpec,
  fig: Figure,
+ divider: AxesDivider,
+ side_counts: dict[str, int],
+ clearance: dict[str, float],
+ axes_size_in: tuple[float, float],
+ prev_outer: dict[str, float],
  renderer: RendererBase,
- base_offsets_axes: dict[str, float],
- trackers_axes: dict[str, float],
+ dpi: float,
  ) -> None:
  norm = spec.mappable.norm
  if isinstance(norm, LogNorm):
@@ -1551,63 +1586,73 @@ def _draw_colorbar(
  location = cast(str, layout.get("location", base_layout["location"]))
  if location not in {"left", "right", "top", "bottom"}:
  location = CBAR_DEFAULT_LOCATION
- default_orientation = "vertical" if location in {"right", "left"} else "horizontal"
- cbar_kwargs.setdefault("orientation", default_orientation)
+ orientation = "vertical" if location in {"right", "left"} else "horizontal"
+ # Orientation is fixed by the location (the divider places a left/right colorbar
+ # vertically and a top/bottom one horizontally); warn rather than silently ignore a
+ # conflicting user-supplied orientation.
+ user_orientation = cbar_kwargs.pop("orientation", None)
+ if user_orientation is not None and user_orientation != orientation:
+ warnings.warn(
+ f"`orientation` is determined by the colorbar location ('{location}' -> '{orientation}'); "
+ f"the requested '{user_orientation}' is ignored.",
+ UserWarning,
+ stacklevel=2,
+ )
 
  fraction = float(cast(float | int, layout.get("fraction", base_layout["fraction"])))
  pad = float(cast(float | int, layout.get("pad", base_layout["pad"])))
 
- if location in {"left", "right"}:
- pad_axes = pad + trackers_axes[location]
- x0 = -pad_axes - fraction if location == "left" else 1 + pad_axes
- bbox = (float(x0), 0.0, float(fraction), 1.0)
+ # Append the colorbar axes through the panel's shared divider. This steals space from the
+ # panel (so the colorbar matches the equal-aspect plot's extent) and keeps it inside the
+ # panel's grid cell, never overflowing into a neighbouring panel.
+ # Pad of the first colorbar on a side clears the panel's own decorations (ticks/labels/
+ # title); a side with negligible clearance (typically "right") keeps the relative pad to
+ # match the historical placement. Each subsequent (stacked) colorbar is padded past the
+ # *measured* outer extent of the previous one (its tick labels AND axis label) so it never
+ # overlaps it.
+ n_on_side = side_counts.get(location, 0)
+ ref_in = axes_size_in[0] if location in {"left", "right"} else axes_size_in[1]
+ side_clearance = clearance.get(location, 0.0)
+ pad_spec: str | Fixed
+ if n_on_side:
+ pad_spec = Fixed(prev_outer.get(location, 0.0) + CBAR_STACK_GAP_INCHES)
+ elif side_clearance > _CBAR_DECORATION_EPS_INCHES:
+ pad_spec = Fixed(side_clearance + max(pad, 0.0) * ref_in)
  else:
- pad_axes = pad + trackers_axes[location]
- y0 = -pad_axes - fraction if location == "bottom" else 1 + pad_axes
- bbox = (0.0, float(y0), 1.0, float(fraction))
- cax = inset_axes(
- spec.ax,
- width="100%",
- height="100%",
- loc="center",
- bbox_to_anchor=bbox,
- bbox_transform=spec.ax.transAxes,
- borderpad=0.0,
+ pad_spec = f"{max(pad, 0.0) * 100}%"
+ cax = divider.append_axes(
+ location,
+ size=f"{max(fraction, 0.0) * 100}%",
+ pad=pad_spec,
+ axes_class=Axes,
  )
-
- cb = fig.colorbar(spec.mappable, cax=cax, **cbar_kwargs)
- if location == "left":
- cb.ax.yaxis.set_ticks_position("left")
- cb.ax.yaxis.set_label_position("left")
- cb.ax.tick_params(labelleft=True, labelright=False)
- elif location == "top":
- cb.ax.xaxis.set_ticks_position("top")
- cb.ax.xaxis.set_label_position("top")
- cb.ax.tick_params(labeltop=True, labelbottom=False)
- elif location == "right":
- cb.ax.yaxis.set_ticks_position("right")
- cb.ax.yaxis.set_label_position("right")
- cb.ax.tick_params(labelright=True, labelleft=False)
- elif location == "bottom":
- cb.ax.xaxis.set_ticks_position("bottom")
- cb.ax.xaxis.set_label_position("bottom")
- cb.ax.tick_params(labelbottom=True, labeltop=False)
+ side_counts[location] = n_on_side + 1
+ cb = fig.colorbar(spec.mappable, cax=cax, orientation=orientation, **cbar_kwargs)
+ tick_axis, opposite = _CBAR_TICK_SIDE[location]
+ cb_axis = cb.ax.yaxis if tick_axis == "y" else cb.ax.xaxis
+ cb_axis.set_ticks_position(location)
+ cb_axis.set_label_position(location)
+ cb.ax.tick_params(**{f"label{location}": True, f"label{opposite}": False})
 
  final_label = global_label_override or layer_label_override or spec.label
  if final_label:
  cb.set_label(final_label)
- if spec.alpha is not None:
+ # `fig.colorbar(mappable)` already bakes the mappable's alpha into the colorbar's
+ # facecolors, so we only apply `spec.alpha` when the mappable carries no alpha of its own
+ # — otherwise we'd multiply alpha twice and the colorbar would render at alpha squared
+ # (much paler than the layer it represents).
+ if spec.alpha is not None and spec.mappable.get_alpha() is None:
  with contextlib.suppress(Exception):
  cb.solids.set_alpha(spec.alpha)
- bbox_axes = cb.ax.get_tightbbox(renderer).transformed(spec.ax.transAxes.inverted())
-if location == "left":
- trackers_axes["left"] = pad_axes + bbox_axes.width
-elif location == "right":
- trackers_axes["right"] = pad_axes + bbox_axes.width
-elif location == "bottom":
- trackers_axes["bottom"] = pad_axes + bbox_axes.height
-elif location == "top":
- trackers_axes["top"] = pad_axes + bbox_axes.height
+
+# Measure how far this colorbar's ticks/labels/axis-label extend beyond its box, so the
+# next stacked colorbar on this side clears them. The draw is kept unconditionally: it is
+# also load-bearing for the layout engine (skipping it shifts wide colorbars), so it is not
+# safe to skip even for the last colorbar on a side.
+fig.canvas.draw()
+prev_outer[location] = _extent_beyond_box_inches(
+ cb.ax.get_window_extent(renderer), cb.ax.get_tightbbox(renderer), dpi, location
+)
 
  # go through tree
 
@@ -1797,6 +1842,7 @@ def _draw_colorbar(
  fig = fig_params.fig
  fig.canvas.draw()
  renderer = fig.canvas.get_renderer()
+ dpi = fig.get_dpi()
  for axis, requests in pending_colorbars:
  unique_specs: list[ColorbarSpec] = []
  seen_mappables: set[int] = set()
@@ -1806,16 +1852,20 @@ def _draw_colorbar(
  continue
  seen_mappables.add(mappable_id)
  unique_specs.append(spec)
- tight_bbox = axis.get_tightbbox(renderer).transformed(axis.transAxes.inverted())
- base_offsets_axes = {
- "left": max(0.0, -tight_bbox.x0),
- "right": max(0.0, tight_bbox.x1 - 1),
- "bottom": max(0.0, -tight_bbox.y0),
- "top": max(0.0, tight_bbox.y1 - 1),
- }
- trackers_axes = {k: base_offsets_axes[k] for k in base_offsets_axes}
+ # Clearance (inches) that the panel's own ticks, tick labels and title extend beyond
+ # the axes box on each side. The first colorbar on a side is padded past this so it
+ # clears those decorations instead of overlapping them (the divider only knows about
+ # the axes box, not its decorations).
+ box = axis.get_window_extent(renderer)
+ tight = axis.get_tightbbox(renderer)
+ clearance = {side: _extent_beyond_box_inches(box, tight, dpi, side) for side in _CBAR_TICK_SIDE}
+ axes_size_in = (box.width / dpi, box.height / dpi)
+ # One divider per panel so multiple colorbars on the same panel stack via the divider.
+ divider = make_axes_locatable(axis)
+ side_counts: dict[str, int] = {}
+ prev_outer: dict[str, float] = {}
  for spec in unique_specs:
- _draw_colorbar(spec, fig, renderer, base_offsets_axes, trackers_axes)
+ _draw_colorbar(spec, fig, divider, side_counts, clearance, axes_size_in, prev_outer, renderer, dpi)
 
  if fig_params.fig is not None and save is not None:
  save_fig(fig_params.fig, path=save)

src/spatialdata_plot/pl/render_params.py

@@ -219,6 +219,9 @@ class ChannelLegendEntry:
 CBAR_DEFAULT_LOCATION = "right"
 CBAR_DEFAULT_FRACTION = 0.075
 CBAR_DEFAULT_PAD = 0.015
+# Small gap (inches) added beyond a stacked colorbar's measured outer extent (its tick labels and
+# axis label) before placing the next colorbar on the same side, so they never overlap.
+CBAR_STACK_GAP_INCHES = 0.08
 
 
 @dataclass

src/spatialdata_plot/pl/basic.py

@@ -22,7 +22,10 @@
 from matplotlib.backend_bases import RendererBase
 from matplotlib.colors import Colormap, LogNorm, Normalize
 from matplotlib.figure import Figure
-from mpl_toolkits.axes_grid1.inset_locator import inset_axes
+from matplotlib.transforms import Bbox
+from mpl_toolkits.axes_grid1 import make_axes_locatable
+from mpl_toolkits.axes_grid1.axes_divider import AxesDivider
+from mpl_toolkits.axes_grid1.axes_size import Fixed
 from spatialdata import get_extent
 from spatialdata._utils import _deprecation_alias
 from spatialdata.transformations.operations import get_transformation
@@ -43,6 +46,7 @@
  CBAR_DEFAULT_FRACTION,
  CBAR_DEFAULT_LOCATION,
  CBAR_DEFAULT_PAD,
+ CBAR_STACK_GAP_INCHES,
  ChannelLegendEntry,
  CmapParams,
  ColorbarSpec,
@@ -84,6 +88,33 @@
 # once https://github.com/scverse/spatialdata/pull/689/ is in a release
 ColorLike = tuple[float, ...] | list[float] | str
 
+# Below this clearance (inches), a colorbar side is treated as having no axis decorations to clear,
+# so the colorbar keeps its relative pad (matching the historical placement) instead of an absolute one.
+_CBAR_DECORATION_EPS_INCHES = 0.05
+
+# Per colorbar location: the axis ("x"/"y") its ticks live on, and the opposite side.
+_CBAR_TICK_SIDE = {"left": ("y", "right"), "right": ("y", "left"), "top": ("x", "bottom"), "bottom": ("x", "top")}
+
+
+def _extent_beyond_box_inches(box: Bbox, tight: Bbox | None, dpi: float, side: str) -> float:
+ """Inches that ``tight`` (an artist's full extent incl. ticks/labels) sticks out past ``box`` on ``side``.
+
+ Returns ``0.0`` when there is no overhang, when ``tight`` is ``None`` (an axes with nothing
+ drawable), or when ``dpi`` is non-positive. Used both to clear a panel's own decorations and to
+ clear a stacked colorbar's labels before placing the next one.
+ """
+ if tight is None or dpi <= 0:
+ return 0.0
+ if side == "left":
+ delta = box.x0 - tight.x0
+ elif side == "right":
+ delta = tight.x1 - box.x1
+ elif side == "bottom":
+ delta = box.y0 - tight.y0
+ else: # top
+ delta = tight.y1 - box.y1
+ return max(0.0, float(delta) / dpi)
+
 
 @register_spatial_data_accessor("pl")
 class PlotAccessor:
@@ -1522,9 +1553,13 @@ def show(
  def _draw_colorbar(
  spec: ColorbarSpec,
  fig: Figure,
+ divider: AxesDivider,
+ side_counts: dict[str, int],
+ clearance: dict[str, float],
+ axes_size_in: tuple[float, float],
+ prev_outer: dict[str, float],
  renderer: RendererBase,
- base_offsets_axes: dict[str, float],
- trackers_axes: dict[str, float],
+ dpi: float,
  ) -> None:
  norm = spec.mappable.norm
  if isinstance(norm, LogNorm):
@@ -1551,63 +1586,73 @@ def _draw_colorbar(
  location = cast(str, layout.get("location", base_layout["location"]))
  if location not in {"left", "right", "top", "bottom"}:
  location = CBAR_DEFAULT_LOCATION
- default_orientation = "vertical" if location in {"right", "left"} else "horizontal"
- cbar_kwargs.setdefault("orientation", default_orientation)
+ orientation = "vertical" if location in {"right", "left"} else "horizontal"
+ # Orientation is fixed by the location (the divider places a left/right colorbar
+ # vertically and a top/bottom one horizontally); warn rather than silently ignore a
+ # conflicting user-supplied orientation.
+ user_orientation = cbar_kwargs.pop("orientation", None)
+ if user_orientation is not None and user_orientation != orientation:
+ warnings.warn(
+ f"`orientation` is determined by the colorbar location ('{location}' -> '{orientation}'); "
+ f"the requested '{user_orientation}' is ignored.",
+ UserWarning,
+ stacklevel=2,
+ )
 
  fraction = float(cast(float | int, layout.get("fraction", base_layout["fraction"])))
  pad = float(cast(float | int, layout.get("pad", base_layout["pad"])))
 
- if location in {"left", "right"}:
- pad_axes = pad + trackers_axes[location]
- x0 = -pad_axes - fraction if location == "left" else 1 + pad_axes
- bbox = (float(x0), 0.0, float(fraction), 1.0)
+ # Append the colorbar axes through the panel's shared divider. This steals space from the
+ # panel (so the colorbar matches the equal-aspect plot's extent) and keeps it inside the
+ # panel's grid cell, never overflowing into a neighbouring panel.
+ # Pad of the first colorbar on a side clears the panel's own decorations (ticks/labels/
+ # title); a side with negligible clearance (typically "right") keeps the relative pad to
+ # match the historical placement. Each subsequent (stacked) colorbar is padded past the
+ # *measured* outer extent of the previous one (its tick labels AND axis label) so it never
+ # overlaps it.
+ n_on_side = side_counts.get(location, 0)
+ ref_in = axes_size_in[0] if location in {"left", "right"} else axes_size_in[1]
+ side_clearance = clearance.get(location, 0.0)
+ pad_spec: str | Fixed
+ if n_on_side:
+ pad_spec = Fixed(prev_outer.get(location, 0.0) + CBAR_STACK_GAP_INCHES)
+ elif side_clearance > _CBAR_DECORATION_EPS_INCHES:
+ pad_spec = Fixed(side_clearance + max(pad, 0.0) * ref_in)
  else:
- pad_axes = pad + trackers_axes[location]
- y0 = -pad_axes - fraction if location == "bottom" else 1 + pad_axes
- bbox = (0.0, float(y0), 1.0, float(fraction))
- cax = inset_axes(
- spec.ax,
- width="100%",
- height="100%",
- loc="center",
- bbox_to_anchor=bbox,
- bbox_transform=spec.ax.transAxes,
- borderpad=0.0,
+ pad_spec = f"{max(pad, 0.0) * 100}%"
+ cax = divider.append_axes(
+ location,
+ size=f"{max(fraction, 0.0) * 100}%",
+ pad=pad_spec,
+ axes_class=Axes,
  )
-
- cb = fig.colorbar(spec.mappable, cax=cax, **cbar_kwargs)
- if location == "left":
- cb.ax.yaxis.set_ticks_position("left")
- cb.ax.yaxis.set_label_position("left")
- cb.ax.tick_params(labelleft=True, labelright=False)
- elif location == "top":
- cb.ax.xaxis.set_ticks_position("top")
- cb.ax.xaxis.set_label_position("top")
- cb.ax.tick_params(labeltop=True, labelbottom=False)
- elif location == "right":
- cb.ax.yaxis.set_ticks_position("right")
- cb.ax.yaxis.set_label_position("right")
- cb.ax.tick_params(labelright=True, labelleft=False)
- elif location == "bottom":
- cb.ax.xaxis.set_ticks_position("bottom")
- cb.ax.xaxis.set_label_position("bottom")
- cb.ax.tick_params(labelbottom=True, labeltop=False)
+ side_counts[location] = n_on_side + 1
+ cb = fig.colorbar(spec.mappable, cax=cax, orientation=orientation, **cbar_kwargs)
+ tick_axis, opposite = _CBAR_TICK_SIDE[location]
+ cb_axis = cb.ax.yaxis if tick_axis == "y" else cb.ax.xaxis
+ cb_axis.set_ticks_position(location)
+ cb_axis.set_label_position(location)
+ cb.ax.tick_params(**{f"label{location}": True, f"label{opposite}": False})
 
  final_label = global_label_override or layer_label_override or spec.label
  if final_label:
  cb.set_label(final_label)
- if spec.alpha is not None:
+ # `fig.colorbar(mappable)` already bakes the mappable's alpha into the colorbar's
+ # facecolors, so we only apply `spec.alpha` when the mappable carries no alpha of its own
+ # — otherwise we'd multiply alpha twice and the colorbar would render at alpha squared
+ # (much paler than the layer it represents).
+ if spec.alpha is not None and spec.mappable.get_alpha() is None:
  with contextlib.suppress(Exception):
  cb.solids.set_alpha(spec.alpha)
- bbox_axes = cb.ax.get_tightbbox(renderer).transformed(spec.ax.transAxes.inverted())
-if location == "left":
- trackers_axes["left"] = pad_axes + bbox_axes.width
-elif location == "right":
- trackers_axes["right"] = pad_axes + bbox_axes.width
-elif location == "bottom":
- trackers_axes["bottom"] = pad_axes + bbox_axes.height
-elif location == "top":
- trackers_axes["top"] = pad_axes + bbox_axes.height
+
+# Measure how far this colorbar's ticks/labels/axis-label extend beyond its box, so the
+# next stacked colorbar on this side clears them. The draw is kept unconditionally: it is
+# also load-bearing for the layout engine (skipping it shifts wide colorbars), so it is not
+# safe to skip even for the last colorbar on a side.
+fig.canvas.draw()
+prev_outer[location] = _extent_beyond_box_inches(
+ cb.ax.get_window_extent(renderer), cb.ax.get_tightbbox(renderer), dpi, location
+)
 
  # go through tree
 
@@ -1797,6 +1842,7 @@ def _draw_colorbar(
  fig = fig_params.fig
  fig.canvas.draw()
  renderer = fig.canvas.get_renderer()
+ dpi = fig.get_dpi()
  for axis, requests in pending_colorbars:
  unique_specs: list[ColorbarSpec] = []
  seen_mappables: set[int] = set()
@@ -1806,16 +1852,20 @@ def _draw_colorbar(
  continue
  seen_mappables.add(mappable_id)
  unique_specs.append(spec)
- tight_bbox = axis.get_tightbbox(renderer).transformed(axis.transAxes.inverted())
- base_offsets_axes = {
- "left": max(0.0, -tight_bbox.x0),
- "right": max(0.0, tight_bbox.x1 - 1),
- "bottom": max(0.0, -tight_bbox.y0),
- "top": max(0.0, tight_bbox.y1 - 1),
- }
- trackers_axes = {k: base_offsets_axes[k] for k in base_offsets_axes}
+ # Clearance (inches) that the panel's own ticks, tick labels and title extend beyond
+ # the axes box on each side. The first colorbar on a side is padded past this so it
+ # clears those decorations instead of overlapping them (the divider only knows about
+ # the axes box, not its decorations).
+ box = axis.get_window_extent(renderer)
+ tight = axis.get_tightbbox(renderer)
+ clearance = {side: _extent_beyond_box_inches(box, tight, dpi, side) for side in _CBAR_TICK_SIDE}
+ axes_size_in = (box.width / dpi, box.height / dpi)
+ # One divider per panel so multiple colorbars on the same panel stack via the divider.
+ divider = make_axes_locatable(axis)
+ side_counts: dict[str, int] = {}
+ prev_outer: dict[str, float] = {}
  for spec in unique_specs:
- _draw_colorbar(spec, fig, renderer, base_offsets_axes, trackers_axes)
+ _draw_colorbar(spec, fig, divider, side_counts, clearance, axes_size_in, prev_outer, renderer, dpi)
 
  if fig_params.fig is not None and save is not None:
  save_fig(fig_params.fig, path=save)

src/spatialdata_plot/pl/render_params.py

@@ -219,6 +219,9 @@ class ChannelLegendEntry:
 CBAR_DEFAULT_LOCATION = "right"
 CBAR_DEFAULT_FRACTION = 0.075
 CBAR_DEFAULT_PAD = 0.015
+# Small gap (inches) added beyond a stacked colorbar's measured outer extent (its tick labels and
+# axis label) before placing the next colorbar on the same side, so they never overlap.
+CBAR_STACK_GAP_INCHES = 0.08
 
 
 @dataclass

src/spatialdata_plot/pl/basic.py

@@ -22,7 +22,10 @@
 from matplotlib.backend_bases import RendererBase
 from matplotlib.colors import Colormap, LogNorm, Normalize
 from matplotlib.figure import Figure
-from mpl_toolkits.axes_grid1.inset_locator import inset_axes
+from matplotlib.transforms import Bbox
+from mpl_toolkits.axes_grid1 import make_axes_locatable
+from mpl_toolkits.axes_grid1.axes_divider import AxesDivider
+from mpl_toolkits.axes_grid1.axes_size import Fixed
 from spatialdata import get_extent
 from spatialdata._utils import _deprecation_alias
 from spatialdata.transformations.operations import get_transformation
@@ -43,6 +46,7 @@
  CBAR_DEFAULT_FRACTION,
  CBAR_DEFAULT_LOCATION,
  CBAR_DEFAULT_PAD,
+ CBAR_STACK_GAP_INCHES,
  ChannelLegendEntry,
  CmapParams,
  ColorbarSpec,
@@ -84,6 +88,33 @@
 # once https://github.com/scverse/spatialdata/pull/689/ is in a release
 ColorLike = tuple[float, ...] | list[float] | str
 
+# Below this clearance (inches), a colorbar side is treated as having no axis decorations to clear,
+# so the colorbar keeps its relative pad (matching the historical placement) instead of an absolute one.
+_CBAR_DECORATION_EPS_INCHES = 0.05
+
+# Per colorbar location: the axis ("x"/"y") its ticks live on, and the opposite side.
+_CBAR_TICK_SIDE = {"left": ("y", "right"), "right": ("y", "left"), "top": ("x", "bottom"), "bottom": ("x", "top")}
+
+
+def _extent_beyond_box_inches(box: Bbox, tight: Bbox | None, dpi: float, side: str) -> float:
+ """Inches that ``tight`` (an artist's full extent incl. ticks/labels) sticks out past ``box`` on ``side``.
+
+ Returns ``0.0`` when there is no overhang, when ``tight`` is ``None`` (an axes with nothing
+ drawable), or when ``dpi`` is non-positive. Used both to clear a panel's own decorations and to
+ clear a stacked colorbar's labels before placing the next one.
+ """
+ if tight is None or dpi <= 0:
+ return 0.0
+ if side == "left":
+ delta = box.x0 - tight.x0
+ elif side == "right":
+ delta = tight.x1 - box.x1
+ elif side == "bottom":
+ delta = box.y0 - tight.y0
+ else: # top
+ delta = tight.y1 - box.y1
+ return max(0.0, float(delta) / dpi)
+
 
 @register_spatial_data_accessor("pl")
 class PlotAccessor:
@@ -1522,9 +1553,13 @@ def show(
  def _draw_colorbar(
  spec: ColorbarSpec,
  fig: Figure,
+ divider: AxesDivider,
+ side_counts: dict[str, int],
+ clearance: dict[str, float],
+ axes_size_in: tuple[float, float],
+ prev_outer: dict[str, float],
  renderer: RendererBase,
- base_offsets_axes: dict[str, float],
- trackers_axes: dict[str, float],
+ dpi: float,
  ) -> None:
  norm = spec.mappable.norm
  if isinstance(norm, LogNorm):
@@ -1551,63 +1586,73 @@ def _draw_colorbar(
  location = cast(str, layout.get("location", base_layout["location"]))
  if location not in {"left", "right", "top", "bottom"}:
  location = CBAR_DEFAULT_LOCATION
- default_orientation = "vertical" if location in {"right", "left"} else "horizontal"
- cbar_kwargs.setdefault("orientation", default_orientation)
+ orientation = "vertical" if location in {"right", "left"} else "horizontal"
+ # Orientation is fixed by the location (the divider places a left/right colorbar
+ # vertically and a top/bottom one horizontally); warn rather than silently ignore a
+ # conflicting user-supplied orientation.
+ user_orientation = cbar_kwargs.pop("orientation", None)
+ if user_orientation is not None and user_orientation != orientation:
+ warnings.warn(
+ f"`orientation` is determined by the colorbar location ('{location}' -> '{orientation}'); "
+ f"the requested '{user_orientation}' is ignored.",
+ UserWarning,
+ stacklevel=2,
+ )
 
  fraction = float(cast(float | int, layout.get("fraction", base_layout["fraction"])))
  pad = float(cast(float | int, layout.get("pad", base_layout["pad"])))
 
- if location in {"left", "right"}:
- pad_axes = pad + trackers_axes[location]
- x0 = -pad_axes - fraction if location == "left" else 1 + pad_axes
- bbox = (float(x0), 0.0, float(fraction), 1.0)
+ # Append the colorbar axes through the panel's shared divider. This steals space from the
+ # panel (so the colorbar matches the equal-aspect plot's extent) and keeps it inside the
+ # panel's grid cell, never overflowing into a neighbouring panel.
+ # Pad of the first colorbar on a side clears the panel's own decorations (ticks/labels/
+ # title); a side with negligible clearance (typically "right") keeps the relative pad to
+ # match the historical placement. Each subsequent (stacked) colorbar is padded past the
+ # *measured* outer extent of the previous one (its tick labels AND axis label) so it never
+ # overlaps it.
+ n_on_side = side_counts.get(location, 0)
+ ref_in = axes_size_in[0] if location in {"left", "right"} else axes_size_in[1]
+ side_clearance = clearance.get(location, 0.0)
+ pad_spec: str | Fixed
+ if n_on_side:
+ pad_spec = Fixed(prev_outer.get(location, 0.0) + CBAR_STACK_GAP_INCHES)
+ elif side_clearance > _CBAR_DECORATION_EPS_INCHES:
+ pad_spec = Fixed(side_clearance + max(pad, 0.0) * ref_in)
  else:
- pad_axes = pad + trackers_axes[location]
- y0 = -pad_axes - fraction if location == "bottom" else 1 + pad_axes
- bbox = (0.0, float(y0), 1.0, float(fraction))
- cax = inset_axes(
- spec.ax,
- width="100%",
- height="100%",
- loc="center",
- bbox_to_anchor=bbox,
- bbox_transform=spec.ax.transAxes,
- borderpad=0.0,
+ pad_spec = f"{max(pad, 0.0) * 100}%"
+ cax = divider.append_axes(
+ location,
+ size=f"{max(fraction, 0.0) * 100}%",
+ pad=pad_spec,
+ axes_class=Axes,
  )
-
- cb = fig.colorbar(spec.mappable, cax=cax, **cbar_kwargs)
- if location == "left":
- cb.ax.yaxis.set_ticks_position("left")
- cb.ax.yaxis.set_label_position("left")
- cb.ax.tick_params(labelleft=True, labelright=False)
- elif location == "top":
- cb.ax.xaxis.set_ticks_position("top")
- cb.ax.xaxis.set_label_position("top")
- cb.ax.tick_params(labeltop=True, labelbottom=False)
- elif location == "right":
- cb.ax.yaxis.set_ticks_position("right")
- cb.ax.yaxis.set_label_position("right")
- cb.ax.tick_params(labelright=True, labelleft=False)
- elif location == "bottom":
- cb.ax.xaxis.set_ticks_position("bottom")
- cb.ax.xaxis.set_label_position("bottom")
- cb.ax.tick_params(labelbottom=True, labeltop=False)
+ side_counts[location] = n_on_side + 1
+ cb = fig.colorbar(spec.mappable, cax=cax, orientation=orientation, **cbar_kwargs)
+ tick_axis, opposite = _CBAR_TICK_SIDE[location]
+ cb_axis = cb.ax.yaxis if tick_axis == "y" else cb.ax.xaxis
+ cb_axis.set_ticks_position(location)
+ cb_axis.set_label_position(location)
+ cb.ax.tick_params(**{f"label{location}": True, f"label{opposite}": False})
 
  final_label = global_label_override or layer_label_override or spec.label
  if final_label:
  cb.set_label(final_label)
- if spec.alpha is not None:
+ # `fig.colorbar(mappable)` already bakes the mappable's alpha into the colorbar's
+ # facecolors, so we only apply `spec.alpha` when the mappable carries no alpha of its own
+ # — otherwise we'd multiply alpha twice and the colorbar would render at alpha squared
+ # (much paler than the layer it represents).
+ if spec.alpha is not None and spec.mappable.get_alpha() is None:
  with contextlib.suppress(Exception):
  cb.solids.set_alpha(spec.alpha)
- bbox_axes = cb.ax.get_tightbbox(renderer).transformed(spec.ax.transAxes.inverted())
-if location == "left":
- trackers_axes["left"] = pad_axes + bbox_axes.width
-elif location == "right":
- trackers_axes["right"] = pad_axes + bbox_axes.width
-elif location == "bottom":
- trackers_axes["bottom"] = pad_axes + bbox_axes.height
-elif location == "top":
- trackers_axes["top"] = pad_axes + bbox_axes.height
+
+# Measure how far this colorbar's ticks/labels/axis-label extend beyond its box, so the
+# next stacked colorbar on this side clears them. The draw is kept unconditionally: it is
+# also load-bearing for the layout engine (skipping it shifts wide colorbars), so it is not
+# safe to skip even for the last colorbar on a side.
+fig.canvas.draw()
+prev_outer[location] = _extent_beyond_box_inches(
+ cb.ax.get_window_extent(renderer), cb.ax.get_tightbbox(renderer), dpi, location
+)
 
  # go through tree
 
@@ -1797,6 +1842,7 @@ def _draw_colorbar(
  fig = fig_params.fig
  fig.canvas.draw()
  renderer = fig.canvas.get_renderer()
+ dpi = fig.get_dpi()
  for axis, requests in pending_colorbars:
  unique_specs: list[ColorbarSpec] = []
  seen_mappables: set[int] = set()
@@ -1806,16 +1852,20 @@ def _draw_colorbar(
  continue
  seen_mappables.add(mappable_id)
  unique_specs.append(spec)
- tight_bbox = axis.get_tightbbox(renderer).transformed(axis.transAxes.inverted())
- base_offsets_axes = {
- "left": max(0.0, -tight_bbox.x0),
- "right": max(0.0, tight_bbox.x1 - 1),
- "bottom": max(0.0, -tight_bbox.y0),
- "top": max(0.0, tight_bbox.y1 - 1),
- }
- trackers_axes = {k: base_offsets_axes[k] for k in base_offsets_axes}
+ # Clearance (inches) that the panel's own ticks, tick labels and title extend beyond
+ # the axes box on each side. The first colorbar on a side is padded past this so it
+ # clears those decorations instead of overlapping them (the divider only knows about
+ # the axes box, not its decorations).
+ box = axis.get_window_extent(renderer)
+ tight = axis.get_tightbbox(renderer)
+ clearance = {side: _extent_beyond_box_inches(box, tight, dpi, side) for side in _CBAR_TICK_SIDE}
+ axes_size_in = (box.width / dpi, box.height / dpi)
+ # One divider per panel so multiple colorbars on the same panel stack via the divider.
+ divider = make_axes_locatable(axis)
+ side_counts: dict[str, int] = {}
+ prev_outer: dict[str, float] = {}
  for spec in unique_specs:
- _draw_colorbar(spec, fig, renderer, base_offsets_axes, trackers_axes)
+ _draw_colorbar(spec, fig, divider, side_counts, clearance, axes_size_in, prev_outer, renderer, dpi)
 
  if fig_params.fig is not None and save is not None:
  save_fig(fig_params.fig, path=save)

src/spatialdata_plot/pl/render_params.py

@@ -219,6 +219,9 @@ class ChannelLegendEntry:
 CBAR_DEFAULT_LOCATION = "right"
 CBAR_DEFAULT_FRACTION = 0.075
 CBAR_DEFAULT_PAD = 0.015
+# Small gap (inches) added beyond a stacked colorbar's measured outer extent (its tick labels and
+# axis label) before placing the next colorbar on the same side, so they never overlap.
+CBAR_STACK_GAP_INCHES = 0.08
 
 
 @dataclass