Preserve hatches in geometry legend proxies (#612)

cvanelteren · Copilot · web-flow · commit 69e0001014c1 · 2026-03-11T11:48:12.000+10:00
* Preserve geometry hatch styles in legend proxies Cartopy geometry artists created with add_geometries() were keeping hatch on the plotted FeatureArtist but dropping it when UltraPlot built the PathPatch legend proxy. This updates the geometry legend handler to copy common patch-style properties more generically, including hatch, while keeping the existing joinstyle fallback. A regression test now covers add_geometries(..., hatch='/', label=...) so semantic geometry legends preserve the plotted hatch pattern. Closes #611 * Generalize geometry legend patch style copying * Document geometry legend style-copy rationale * Black * Document geometry legend proxy limitations * Update ultraplot/legend.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
diff --git a/ultraplot/legend.py b/ultraplot/legend.py
@@ -395,6 +395,7 @@ def _fit_path_to_handlebox(
     width: float,
     height: float,
     pad: float = 0.08,
+    preserve_aspect: bool = True,
 ) -> mpath.Path:
     """
     Normalize an arbitrary path into the legend-handle box.
@@ -411,11 +412,15 @@ def _fit_path_to_handlebox(
     py = max(height * pad, 0.0)
     span_x = max(width - 2 * px, 1e-12)
     span_y = max(height - 2 * py, 1e-12)
-    scale = min(span_x / dx, span_y / dy)
     cx = -xdescent + width * 0.5
     cy = -ydescent + height * 0.5
-    verts[finite, 0] = (verts[finite, 0] - (xmin + xmax) * 0.5) * scale + cx
-    verts[finite, 1] = (verts[finite, 1] - (ymin + ymax) * 0.5) * scale + cy
+    if preserve_aspect:
+        scale_x = scale_y = min(span_x / dx, span_y / dy)
+    else:
+        scale_x = span_x / dx
+        scale_y = span_y / dy
+    verts[finite, 0] = (verts[finite, 0] - (xmin + xmax) * 0.5) * scale_x + cx
+    verts[finite, 1] = (verts[finite, 1] - (ymin + ymax) * 0.5) * scale_y + cy
     return mpath.Path(
         verts, None if path.codes is None else np.array(path.codes, copy=True)
     )
@@ -494,6 +499,89 @@ def _patch_joinstyle(value: Any, default: str = _DEFAULT_GEO_JOINSTYLE) -> str:
     return default
 
 
+def _patch_color(
+    orig_handle: Any,
+    prop: str,
+    default: Any = None,
+) -> Any:
+    """
+    Resolve a patch color, preferring the artist's original color spec.
+
+    Collection-like artists often report post-alpha RGBA arrays from
+    `get_facecolor()` / `get_edgecolor()`. If we then also copy `alpha`, the
+    legend proxy ends up visually double-dimmed. Prefer the original color
+    attributes when available so patch proxies can apply alpha once.
+    """
+    original = getattr(orig_handle, f"_original_{prop}", None)
+    if original is not None:
+        value = _first_scalar(original, default=None)
+        if value is not None:
+            return value
+    getter = getattr(orig_handle, f"get_{prop}", None)
+    if not callable(getter):
+        return default
+    try:
+        value = getter()
+    except Exception:
+        return default
+    return _first_scalar(value, default=default)
+
+
+_PATCH_STYLE_PROP_SPECS = {
+    "facecolor": {"default": "none", "transform": None},
+    "edgecolor": {"default": "none", "transform": None},
+    "linewidth": {"default": 0.0, "transform": _first_scalar},
+    "linestyle": {"default": None, "transform": _first_scalar},
+    "hatch": {"default": None, "transform": None},
+    "hatch_linewidth": {"default": None, "transform": None},
+    "fill": {"default": None, "transform": None},
+    "alpha": {"default": None, "transform": None},
+    "capstyle": {"default": None, "transform": None},
+}
+
+
+def _copy_patch_style(
+    legend_handle: mpatches.Patch,
+    orig_handle: Any,
+    *,
+    joinstyle_default: str = _DEFAULT_GEO_JOINSTYLE,
+) -> None:
+    """
+    Copy common patch-style properties from source artist to legend proxy.
+
+    Matplotlib does not provide a reliable generic style-transfer API for
+    cross-family artists here. In particular, `Artist.update_from()` is not
+    safe for `Collection -> Patch` copies like `FeatureArtist -> PathPatch`,
+    and `properties()` still leaves us to normalize collection-valued fields.
+    So this helper intentionally copies the shared patch-style surface only.
+    """
+    for prop, spec in _PATCH_STYLE_PROP_SPECS.items():
+        setter = getattr(legend_handle, f"set_{prop}", None)
+        if not callable(setter):
+            continue
+        default = spec["default"]
+        if prop in ("facecolor", "edgecolor"):
+            value = _patch_color(orig_handle, prop, default=default)
+        else:
+            getter = getattr(orig_handle, f"get_{prop}", None)
+            if not callable(getter):
+                continue
+            try:
+                value = getter()
+            except Exception:
+                continue
+            transform = spec["transform"]
+            if transform is not None:
+                value = transform(value, default=default)
+            elif value is None:
+                value = default
+        if value is not None:
+            setter(value)
+    legend_handle.set_joinstyle(
+        _patch_joinstyle(orig_handle, default=joinstyle_default)
+    )
+
+
 def _feature_legend_patch(
     legend,
     orig_handle,
@@ -515,6 +603,7 @@ def _feature_legend_patch(
         ydescent=ydescent,
         width=width,
         height=height,
+        preserve_aspect=False,
     )
     return mpatches.PathPatch(path, joinstyle=_DEFAULT_GEO_JOINSTYLE)
 
@@ -544,6 +633,7 @@ def _shapely_geometry_patch(
         ydescent=ydescent,
         width=width,
         height=height,
+        preserve_aspect=False,
     )
     return mpatches.PathPatch(path, joinstyle=_DEFAULT_GEO_JOINSTYLE)
 
@@ -566,6 +656,7 @@ def _geometry_entry_patch(
         ydescent=ydescent,
         width=width,
         height=height,
+        preserve_aspect=True,
     )
     return mpatches.PathPatch(path, joinstyle=_DEFAULT_GEO_JOINSTYLE)
 
@@ -579,36 +670,7 @@ def __init__(self):
         super().__init__(patch_func=_feature_legend_patch)
 
     def update_prop(self, legend_handle, orig_handle, legend):
-        facecolor = _first_scalar(
-            (
-                orig_handle.get_facecolor()
-                if hasattr(orig_handle, "get_facecolor")
-                else None
-            ),
-            default="none",
-        )
-        edgecolor = _first_scalar(
-            (
-                orig_handle.get_edgecolor()
-                if hasattr(orig_handle, "get_edgecolor")
-                else None
-            ),
-            default="none",
-        )
-        linewidth = _first_scalar(
-            (
-                orig_handle.get_linewidth()
-                if hasattr(orig_handle, "get_linewidth")
-                else None
-            ),
-            default=0.0,
-        )
-        legend_handle.set_facecolor(facecolor)
-        legend_handle.set_edgecolor(edgecolor)
-        legend_handle.set_linewidth(linewidth)
-        legend_handle.set_joinstyle(_patch_joinstyle(orig_handle))
-        if hasattr(orig_handle, "get_alpha"):
-            legend_handle.set_alpha(orig_handle.get_alpha())
+        _copy_patch_style(legend_handle, orig_handle)
         legend._set_artist_props(legend_handle)
         legend_handle.set_clip_box(None)
         legend_handle.set_clip_path(None)
@@ -1638,6 +1700,14 @@ def geolegend(
     ):
         """
         Build geometry legend entries and optionally draw a legend.
+
+        Notes
+        -----
+        Geometry legend entries use normalized patch proxies inside the legend
+        handle box rather than reusing the original map artist directly. This
+        preserves the general geometry shape and copied patch styling, but very
+        small or high-aspect-ratio handles can still make hatches difficult to
+        read at legend scale.
         """
         facecolor = _not_none(facecolor, rc["legend.geo.facecolor"])
         edgecolor = _not_none(edgecolor, rc["legend.geo.edgecolor"])
diff --git a/ultraplot/tests/test_legend.py b/ultraplot/tests/test_legend.py
@@ -772,6 +772,27 @@ def test_geo_axes_add_geometries_auto_legend():
     uplt.close(fig)
 
 
+def test_geo_axes_add_geometries_auto_legend_preserves_hatch():
+    ccrs = pytest.importorskip("cartopy.crs")
+    sgeom = pytest.importorskip("shapely.geometry")
+
+    fig, ax = uplt.subplots(proj="cyl")
+    ax.add_geometries(
+        [sgeom.box(-20, -10, 20, 10)],
+        ccrs.PlateCarree(),
+        facecolor="gray5",
+        edgecolor="red7",
+        alpha=0.2,
+        hatch="/",
+        label="Region",
+    )
+    leg = ax.legend(loc="best")
+    assert len(leg.legend_handles) == 1
+    assert isinstance(leg.legend_handles[0], mpatches.PathPatch)
+    assert leg.legend_handles[0].get_hatch() == "/"
+    uplt.close(fig)
+
+
 def test_geo_legend_defaults_to_bevel_joinstyle():
     fig, ax = uplt.subplots()
     leg = ax.geolegend([("shape", "triangle")], loc="best")
