Anchor parameter for image insets

`inset_element(..., anchor=...)` chooses where an aspect-fitted
image sits inside the user's bbox. Default `"center"` reproduces the
previous behaviour; named anchors cover the eight corners and edges,
and a `(h, v)` tuple in [0, 1]² sets the anchor point directly.

`_fit_aspect` now splits the letterbox padding by the anchor's
fraction instead of always 50/50. The anchor is resolved once at
`_InsetImage` construction so the per-render path stays cheap and
typed as a plain tuple.

The parameter is ignored for ggplot / Compose insets, which fill
the bbox via gridspec sizing and have no letterbox to anchor.

Author: has2k1

plotnine/composition/_inset_element.py

@@ -13,6 +13,7 @@
 
     from ..ggplot import ggplot
     from ._compose import Compose
+    from ._inset_image import Anchor
 
 
 @dataclass
@@ -37,23 +38,33 @@ class inset_element:
           ratio is preserved.
     left, bottom, right, top :
         Bounding box of the inset as fractional coordinates in the
-        range ``[0, 1]``, relative to the host region selected by
+        range `[0, 1]`, relative to the host region selected by
         `align_to`. The bottom-left corner of that region is
-        ``(0, 0)`` and the top-right is ``(1, 1)``.
+        `(0, 0)` and the top-right is `(1, 1)`.
     align_to :
         Which region of the host plot the bounding box is relative to:
 
-        - ``"panel"`` — the data area only (default).
-        - ``"plot"``  — the panel plus axes, labels, titles, captions
+        - `"panel"` — the data area only (default).
+        - `"plot"`  — the panel plus axes, labels, titles, captions
            and legends
-        - ``"full"``  — everything the host plot occupies plus plot margin
+        - `"full"`  — everything the host plot occupies plus plot margin
     on_top :
         When `True` (default) the inset paints above the host plot.
         When `False`, the inset paints between the host's
         `plot_background` and the rest of the host (panel, titles,
         legends, ...), so the host's panel area covers the inset.
         Useful for backdrops, decorations, or branding that should
         look like part of the page rather than an overlay.
+    anchor :
+        Where to anchor the image inside the user's bbox when its
+        aspect ratio doesn't match. One of `"center"` (default),
+        `"top"`, `"top-right"`, `"right"`, `"bottom-right"`,
+        `"bottom"`, `"bottom-left"`, `"left"`, `"top-left"`,
+        or a `(h, v)` tuple in [0, 1]² with `h = 0` left / `h = 1`
+        right and `v = 0` bottom / `v = 1` top. Only meaningful for
+        image insets; plot / composition insets fill the entire area by
+        resizing without constraining the aspect ratio, so the anchor
+        has no effect.
 
     Notes
     -----
@@ -62,7 +73,7 @@ class inset_element:
     theme. The canvas size of the inset is determined by the bounding
     box and the area it is `align_to`.
 
-    For image insets, ``inset_element(...) + theme(...)`` draws a
+    For image insets, `inset_element(...) + theme(...)` draws a
     sibling rectangle around the image; only `plot_background` is
     honored today.
 
@@ -89,6 +100,7 @@ class inset_element:
     top: float
     align_to: Literal["panel", "plot", "full"] = "panel"
     on_top: bool = True
+    anchor: Anchor = "center"
 
     def __post_init__(self):
         import numpy as np
@@ -100,7 +112,7 @@ def __post_init__(self):
         if isinstance(self.obj, (ggplot, Compose)):
             pass
         elif isinstance(self.obj, (PILImage, np.ndarray)):
-            self.obj = _InsetImage(self.obj)
+            self.obj = _InsetImage(self.obj, anchor=self.anchor)
         else:
             raise TypeError(
                 "inset_element requires a ggplot, Compose, PIL image, "

plotnine/composition/_inset_image.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from copy import deepcopy
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Literal
 
 import numpy as np
 from PIL.Image import Image as PILImage
@@ -18,14 +18,28 @@
     from ..ggplot import ggplot
     from ..themes.theme import theme as theme_type
 
+    AnchorName = Literal[
+        "center",
+        "top",
+        "right",
+        "bottom",
+        "left",
+        "top-left",
+        "top-right",
+        "bottom-left",
+        "bottom-right",
+    ]
+    Anchor = AnchorName | tuple[float, float]
+
 
 class _InsetImage:
     """
     A raster image rendered inside an `inset_element`'s bounding box
 
     The image keeps its intrinsic aspect ratio — when the bbox does
     not match, the image is letterboxed with transparent padding on
-    the two opposing edges so it stays centred.
+    the two opposing edges. The `anchor` parameter chooses where the
+    image sits inside the bbox (centered by default).
 
     Theming the inset (`inset_element(...) + theme(...)`) draws a
     background rectangle around the image; only `plot_background`
@@ -44,12 +58,22 @@ class _InsetImage:
     # this bbox sets where on the figure it lands and how big it is.
     _frac_bbox: Bbox
 
-    def __init__(self, image: PILImage | np.ndarray):
+    # Where the image sits inside the user's bbox when its aspect
+    # ratio doesn't match.
+    _anchor: tuple[float, float]
+
+    def __init__(
+        self,
+        image: PILImage | np.ndarray,
+        *,
+        anchor: Anchor = "center",
+    ):
         from matplotlib.transforms import Bbox
 
         self._image = image
         self._image_size = _image_size(image)  # (W, H) px
         self._frac_bbox = Bbox.unit()
+        self._anchor = _resolve_anchor(anchor)
         self.theme = theme()
 
     def __add__(self, other: object) -> _InsetImage:
@@ -69,10 +93,10 @@ def _arrange_in_box(
         """
         Place the image inside the given box, preserving aspect ratio
 
-        The image is letterboxed — centered inside the box with
-        transparent padding on the two opposing edges — so its
-        intrinsic aspect ratio survives. The background rectangle
-        tracks the same fitted box.
+        The image is letterboxed inside the box with transparent
+        padding on the two opposing edges, positioned by the
+        configured `anchor`. The background rectangle tracks the
+        same fitted box.
 
         Parameters
         ----------
@@ -81,7 +105,13 @@ def _arrange_in_box(
             inset by `inset_element.align_to`.
         """
         l, b, r, t = _fit_aspect(
-            left, bottom, right, top, self._image_size, self.figure
+            left,
+            bottom,
+            right,
+            top,
+            self._image_size,
+            self.figure,
+            anchor=self._anchor,
         )
         w, h = r - l, t - b
         self._frac_bbox.bounds = (l, b, w, h)  # pyright: ignore[reportAttributeAccessIssue]
@@ -128,17 +158,71 @@ def _image_size(obj: PILImage | np.ndarray) -> tuple[int, int]:
     return w, h
 
 
+# Named anchors → (h, v) fractions in [0, 1]², where `h = 0`
+# aligns the image to the bbox's left edge / `h = 1` to the right,
+# and `v = 0` aligns to the bottom / `v = 1` to the top.
+_ANCHOR_FRACTIONS: dict[str, tuple[float, float]] = {
+    "center": (0.5, 0.5),
+    "top": (0.5, 1.0),
+    "top-right": (1.0, 1.0),
+    "right": (1.0, 0.5),
+    "bottom-right": (1.0, 0.0),
+    "bottom": (0.5, 0.0),
+    "bottom-left": (0.0, 0.0),
+    "left": (0.0, 0.5),
+    "top-left": (0.0, 1.0),
+}
+
+
+def _resolve_anchor(anchor: Anchor) -> tuple[float, float]:
+    """
+    Normalise an anchor spec to a (h, v) tuple in [0, 1]²
+
+    Accepts a named anchor (e.g. `"top-right"`) or a numeric
+    `(h, v)` tuple. Raises `ValueError` on unknown names or
+    out-of-range tuple values.
+    """
+    if isinstance(anchor, str):
+        try:
+            return _ANCHOR_FRACTIONS[anchor]
+        except KeyError:
+            names = ", ".join(repr(k) for k in _ANCHOR_FRACTIONS)
+            raise ValueError(
+                f"Unknown anchor {anchor!r}. Expected one of: "
+                f"{names}, or a (h, v) tuple in [0, 1]²."
+            ) from None
+    try:
+        h, v = anchor
+    except (TypeError, ValueError):
+        raise ValueError(
+            f"Anchor must be a name or (h, v) tuple, got {anchor!r}."
+        ) from None
+    if not (0.0 <= h <= 1.0 and 0.0 <= v <= 1.0):
+        raise ValueError(
+            f"Anchor tuple values must lie in [0, 1], got ({h}, {v})."
+        )
+    return float(h), float(v)
+
+
 def _fit_aspect(
     left: float,
     bottom: float,
     right: float,
     top: float,
     image_size: tuple[int, int],
     fig: Figure,
+    anchor: tuple[float, float] = (0.5, 0.5),
 ) -> tuple[float, float, float, float]:
     """
-    Shrink the user's bbox to the largest centered sub-bbox with the
-    image's intrinsic aspect ratio
+    Shrink the user's bbox to the largest sub-bbox with the image's
+    intrinsic aspect ratio, positioned by `anchor`
+
+    `anchor` defaults to `"center"` (image centered, padding split
+    50/50 on the short axis). Named anchors map to corners and edges
+    of the bbox; a `(h, v)` tuple in [0, 1]² sets the anchor
+    point directly, where `h = 0` aligns the image to the bbox's
+    left edge / `h = 1` to the right, and `v = 0` to the bottom /
+    `v = 1` to the top.
     """
     # figure size in px
     W, H = fig.bbox.size
@@ -151,13 +235,15 @@ def _fit_aspect(
     img_aspect = img_w / img_h
     box_aspect = box_w / box_h
 
+    h, v = anchor
+
     if img_aspect > box_aspect:
         # Wider than the box: fit width, letterbox vertically
         new_box_h = box_w / img_aspect
-        pad_frac = (box_h - new_box_h) / 2 / H
-        return left, bottom + pad_frac, right, top - pad_frac
+        pad = (box_h - new_box_h) / H
+        return left, bottom + v * pad, right, top - (1 - v) * pad
 
     # Taller (or equal): fit height, letterbox horizontally
     new_box_w = box_h * img_aspect
-    pad_frac = (box_w - new_box_w) / 2 / W
-    return left + pad_frac, bottom, right - pad_frac, top
+    pad = (box_w - new_box_w) / W
+    return left + h * pad, bottom, right - (1 - h) * pad, top