ENH: Implement gapcolor for patch edges (#30967)

pirzada-ahmadfaraz · web-flow · commit ad15a4c3dc69 · 2026-02-20T13:53:46.000-06:00
* ENH: Implement gapcolor for patch edges Add support for gapcolor property in Patches, similar to the existing gapcolor feature in Line2D and LineCollection. This allows drawing 'stripey' patch edges with two alternating colors in dashed patterns. Use case: Drawing unfilled patches on backgrounds of unknown color, where alternating black/white edges ensure visibility. Changes: - Add gapcolor parameter to Patch.__init__ - Add get_gapcolor() and set_gapcolor() methods - Add is_dashed() method to check if edge is dashed - Modify _draw_paths_with_artist_properties() to draw gaps first with inverse dash pattern when gapcolor is set - Update update_from() to copy gapcolor - Add tests for the new functionality Closes #30934 * Add baseline image for patch gapcolor visual test * Add gapcolor methods to patches.pyi type stubs * Address review feedback for patch gapcolor implementation - Renamed gapcolor to edgegapcolor for API clarity (parameter, getter, setter) - Made is_dashed() private as _has_dashed_edge() since it's only used internally - Fixed linestyle detection to handle custom linestyles by checking for non-solid styles instead of specific dashed patterns - Moved RGBA conversion to set_edgegapcolor() for better performance (avoids redundant conversions on window resize) - Moved _gapcolor initialization next to _dash_pattern for code organization - Updated type stubs and tests accordingly * Add What's New entry and versionadded directives for edgegapcolor * Use visible colors in What's New edgegapcolor example Change edgecolor/edgegapcolor from black/white to orange/blue so the gap color is actually visible against the default white background.
diff --git a/doc/release/next_whats_new/patch_edgegapcolor.rst b/doc/release/next_whats_new/patch_edgegapcolor.rst
@@ -0,0 +1,24 @@
+``edgegapcolor`` for Patches
+----------------------------
+
+`~matplotlib.patches.Patch` now supports an *edgegapcolor* parameter,
+similar to the existing *gapcolor* in `.Line2D`. This allows patches with
+dashed edges to display a secondary color in the gaps, creating a "striped"
+edge effect.
+
+This is useful when drawing unfilled patches on backgrounds of unknown color,
+where alternating edge colors ensure the patch boundary remains visible.
+
+.. plot::
+    :include-source: true
+    :alt: A rectangle with a dashed orange edge and blue gaps, demonstrating the edgegapcolor feature.
+
+    import matplotlib.pyplot as plt
+    from matplotlib.patches import Rectangle
+
+    fig, ax = plt.subplots()
+    rect = Rectangle((0.1, 0.1), 0.6, 0.6, fill=False,
+                      edgecolor='orange', edgegapcolor='blue',
+                      linestyle='--', linewidth=3)
+    ax.add_patch(rect)
+    plt.show()
diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py
@@ -57,6 +57,7 @@ def __init__(self, *,
                  capstyle=None,
                  joinstyle=None,
                  hatchcolor=None,
+                 edgegapcolor=None,
                  **kwargs):
         """
         The following kwarg properties are supported
@@ -88,13 +89,15 @@ def __init__(self, *,
         self._linewidth = 0
         self._unscaled_dash_pattern = (0, None)  # offset, dash
         self._dash_pattern = (0, None)  # offset, dash (scaled by linewidth)
+        self._gapcolor = None
 
         self.set_linestyle(linestyle)
         self.set_linewidth(linewidth)
         self.set_antialiased(antialiased)
         self.set_hatch(hatch)
         self.set_capstyle(capstyle)
         self.set_joinstyle(joinstyle)
+        self.set_edgegapcolor(edgegapcolor)
 
         if len(kwargs):
             self._internal_update(kwargs)
@@ -294,6 +297,7 @@ def update_from(self, other):
         self._hatch_color = other._hatch_color
         self._original_hatchcolor = other._original_hatchcolor
         self._unscaled_dash_pattern = other._unscaled_dash_pattern
+        self._gapcolor = other._gapcolor
         self.set_linewidth(other._linewidth)  # also sets scaled dashes
         self.set_transform(other.get_data_transform())
         # If the transform of other needs further initialization, then it will
@@ -442,6 +446,42 @@ def set_hatchcolor(self, color):
         self._original_hatchcolor = color
         self._set_hatchcolor(color)
 
+    def get_edgegapcolor(self):
+        """
+        Return the edge gap color.
+
+        .. versionadded:: 3.11
+
+        See also `~.Patch.set_edgegapcolor`.
+        """
+        return self._gapcolor
+
+    def set_edgegapcolor(self, edgegapcolor):
+        """
+        Set a color to fill the gaps in the dashed edge style.
+
+        .. versionadded:: 3.11
+
+        .. note::
+
+            Striped edges are created by drawing two interleaved dashed lines.
+            There can be overlaps between those two, which may result in
+            artifacts when using transparency.
+
+            This functionality is experimental and may change.
+
+        Parameters
+        ----------
+        edgegapcolor : :mpltype:`color` or None
+            The color with which to fill the gaps. If None, the gaps are
+            unfilled.
+        """
+        if edgegapcolor is not None:
+            self._gapcolor = colors.to_rgba(edgegapcolor, self._alpha)
+        else:
+            self._gapcolor = None
+        self.stale = True
+
     def set_alpha(self, alpha):
         # docstring inherited
         super().set_alpha(alpha)
@@ -618,6 +658,17 @@ def get_hatch_linewidth(self):
         """Return the hatch linewidth."""
         return self._hatch_linewidth
 
+    def _has_dashed_edge(self):
+        """
+        Return whether the patch edge has a dashed linestyle.
+
+        A custom linestyle is assumed to be dashed, we do not inspect the
+        ``onoffseq`` directly.
+
+        See also `~.Patch.set_linestyle`.
+        """
+        return self._linestyle not in ('solid', '-')
+
     def _draw_paths_with_artist_properties(
             self, renderer, draw_path_args_list):
         """
@@ -632,13 +683,10 @@ def _draw_paths_with_artist_properties(
         renderer.open_group('patch', self.get_gid())
         gc = renderer.new_gc()
 
-        gc.set_foreground(self._edgecolor, isRGBA=True)
-
         lw = self._linewidth
         if self._edgecolor[3] == 0 or self._linestyle == 'None':
             lw = 0
         gc.set_linewidth(lw)
-        gc.set_dashes(*self._dash_pattern)
         gc.set_capstyle(self._capstyle)
         gc.set_joinstyle(self._joinstyle)
 
@@ -661,6 +709,18 @@ def _draw_paths_with_artist_properties(
             from matplotlib.patheffects import PathEffectRenderer
             renderer = PathEffectRenderer(self.get_path_effects(), renderer)
 
+        # Draw the gaps first if gapcolor is set
+        if self._has_dashed_edge() and self._gapcolor is not None:
+            gc.set_foreground(self._gapcolor, isRGBA=True)
+            offset_gaps, gaps = mlines._get_inverse_dash_pattern(
+                *self._dash_pattern)
+            gc.set_dashes(offset_gaps, gaps)
+            for draw_path_args in draw_path_args_list:
+                renderer.draw_path(gc, *draw_path_args)
+
+        # Draw the main edge
+        gc.set_foreground(self._edgecolor, isRGBA=True)
+        gc.set_dashes(*self._dash_pattern)
         for draw_path_args in draw_path_args_list:
             renderer.draw_path(gc, *draw_path_args)
 
diff --git a/lib/matplotlib/patches.pyi b/lib/matplotlib/patches.pyi
@@ -26,6 +26,7 @@ class Patch(artist.Artist):
         capstyle: CapStyleType | None = ...,
         joinstyle: JoinStyleType | None = ...,
         hatchcolor: ColorType | Literal["edge"] | None = ...,
+        edgegapcolor: ColorType | None = ...,
         **kwargs,
     ) -> None: ...
     def get_verts(self) -> ArrayLike: ...
@@ -43,13 +44,15 @@ class Patch(artist.Artist):
     def get_antialiased(self) -> bool: ...
     def get_edgecolor(self) -> ColorType: ...
     def get_facecolor(self) -> ColorType: ...
+    def get_edgegapcolor(self) -> ColorType | None: ...
     def get_hatchcolor(self) -> ColorType: ...
     def get_linewidth(self) -> float: ...
     def get_linestyle(self) -> LineStyleType: ...
     def set_antialiased(self, aa: bool | None) -> None: ...
     def set_edgecolor(self, color: ColorType | None) -> None: ...
     def set_facecolor(self, color: ColorType | None) -> None: ...
     def set_color(self, c: ColorType | None) -> None: ...
+    def set_edgegapcolor(self, edgegapcolor: ColorType | None) -> None: ...
     def set_hatchcolor(self, color: ColorType | Literal["edge"] | None) -> None: ...
     def set_alpha(self, alpha: float | None) -> None: ...
     def set_linewidth(self, w: float | None) -> None: ...
diff --git a/lib/matplotlib/tests/baseline_images/test_patches/patch_edgegapcolor.png b/lib/matplotlib/tests/baseline_images/test_patches/patch_edgegapcolor.png
diff --git a/lib/matplotlib/tests/test_patches.py b/lib/matplotlib/tests/test_patches.py
@@ -1101,3 +1101,81 @@ def test_empty_fancyarrow():
     fig, ax = plt.subplots()
     arrow = ax.arrow([], [], [], [])
     assert arrow is not None
+
+
+def test_patch_edgegapcolor_getter_setter():
+    """Test that edgegapcolor can be set and retrieved."""
+    patch = Rectangle((0, 0), 1, 1)
+    # Default is None
+    assert patch.get_edgegapcolor() is None
+
+    # Set to a color
+    patch.set_edgegapcolor('red')
+    assert mcolors.same_color(patch.get_edgegapcolor(), 'red')
+
+    # Set back to None
+    patch.set_edgegapcolor(None)
+    assert patch.get_edgegapcolor() is None
+
+
+def test_patch_edgegapcolor_init():
+    """Test that edgegapcolor can be passed in __init__."""
+    patch = Rectangle((0, 0), 1, 1, edgegapcolor='blue')
+    assert mcolors.same_color(patch.get_edgegapcolor(), 'blue')
+
+
+def test_patch_has_dashed_edge():
+    """Test _has_dashed_edge method for patches."""
+    patch = Rectangle((0, 0), 1, 1)
+    patch.set_linestyle('solid')
+    assert not patch._has_dashed_edge()
+
+    patch.set_linestyle('--')
+    assert patch._has_dashed_edge()
+
+    patch.set_linestyle(':')
+    assert patch._has_dashed_edge()
+
+    patch.set_linestyle('-.')
+    assert patch._has_dashed_edge()
+
+    # Test custom linestyle
+    patch.set_linestyle((0, (2, 2, 10, 2)))
+    assert patch._has_dashed_edge()
+
+
+def test_patch_edgegapcolor_update_from():
+    """Test that edgegapcolor is copied in update_from."""
+    patch1 = Rectangle((0, 0), 1, 1, edgegapcolor='green')
+    patch2 = Rectangle((1, 1), 2, 2)
+
+    patch2.update_from(patch1)
+    assert mcolors.same_color(patch2.get_edgegapcolor(), 'green')
+
+
+@image_comparison(['patch_edgegapcolor.png'], remove_text=True, style='mpl20')
+def test_patch_edgegapcolor_visual():
+    """Visual test for patch edgegapcolor (striped edges)."""
+    fig, ax = plt.subplots()
+
+    # Rectangle with edgegapcolor
+    rect = Rectangle((0.1, 0.1), 0.3, 0.3, fill=False,
+                      edgecolor='blue', edgegapcolor='orange',
+                      linestyle='--', linewidth=3)
+    ax.add_patch(rect)
+
+    # Ellipse with edgegapcolor
+    ellipse = Ellipse((0.7, 0.3), 0.3, 0.2, fill=False,
+                       edgecolor='red', edgegapcolor='yellow',
+                       linestyle=':', linewidth=3)
+    ax.add_patch(ellipse)
+
+    # Polygon with edgegapcolor
+    polygon = Polygon([[0.1, 0.6], [0.3, 0.9], [0.4, 0.6]], fill=False,
+                       edgecolor='green', edgegapcolor='purple',
+                       linestyle='-.', linewidth=3)
+    ax.add_patch(polygon)
+
+    ax.set_xlim(0, 1)
+    ax.set_ylim(0, 1)
+    ax.set_aspect('equal')
