matplotlib · tacaswell · Oct 11, 2024 · Aug 10, 2024 · Aug 10, 2024 · Aug 10, 2024
diff --git a/doc/missing-references.json b/doc/missing-references.json
@@ -304,8 +304,8 @@
     "matplotlib.collections._CollectionWithSizes.set_sizes": [
       "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.barbs:179",
       "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.broken_barh:84",
-      "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.fill_between:120",
-      "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.fill_betweenx:120",
+      "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.fill_between:121",
+      "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.fill_betweenx:121",
       "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.hexbin:213",
       "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.pcolor:182",
       "lib/matplotlib/axes/_axes.py:docstring of matplotlib.axes._axes.Axes.quiver:215",
@@ -316,10 +316,11 @@
       "lib/matplotlib/collections.py:docstring of matplotlib.artist.PolyQuadMesh.set:44",
       "lib/matplotlib/collections.py:docstring of matplotlib.artist.RegularPolyCollection.set:44",
       "lib/matplotlib/collections.py:docstring of matplotlib.artist.StarPolygonCollection.set:44",
+      "lib/matplotlib/collections.py:docstring of matplotlib.artist.FillBetweenPolyCollection.set:45",
       "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.barbs:179",
       "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.broken_barh:84",
-      "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.fill_between:120",
-      "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.fill_betweenx:120",
+      "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.fill_between:121",
+      "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.fill_betweenx:121",
       "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.hexbin:213",
       "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.pcolor:182",
       "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.quiver:215",

diff --git a/doc/users/next_whats_new/fill_between_poly_collection.rst b/doc/users/next_whats_new/fill_between_poly_collection.rst
@@ -0,0 +1,22 @@
+``FillBetweenPolyCollection``
+-----------------------------
+
+The new class :class:`matplotlib.collections.FillBetweenPolyCollection` provides
+the ``set_data`` method, enabling e.g. resampling
+(:file:`galleries/event_handling/resample.html`).
+:func:`matplotlib.axes.Axes.fill_between` and
+:func:`matplotlib.axes.Axes.fill_betweenx` now return this new class.
+
+.. code-block:: python
+
+    import numpy as np
+    from matplotlib import pyplot as plt
+
+    t = np.linspace(0, 1)
+
+    fig, ax = plt.subplots()
+    coll = ax.fill_between(t, -t**2, t**2)
+    fig.savefig("before.png")
+
+    coll.set_data(t, -t**4, t**4)
+    fig.savefig("after.png")
diff --git a/galleries/examples/event_handling/resample.py b/galleries/examples/event_handling/resample.py
@@ -22,13 +22,19 @@
 
 # A class that will downsample the data and recompute when zoomed.
 class DataDisplayDownsampler:
-    def __init__(self, xdata, ydata):
-        self.origYData = ydata
+    def __init__(self, xdata, y1data, y2data):
+        self.origY1Data = y1data
+        self.origY2Data = y2data
         self.origXData = xdata
         self.max_points = 50
         self.delta = xdata[-1] - xdata[0]
 
-    def downsample(self, xstart, xend):
+    def plot(self, ax):
+        x, y1, y2 = self._downsample(self.origXData.min(), self.origXData.max())
+        (self.line,) = ax.plot(x, y1, 'o-')
+        self.poly_collection = ax.fill_between(x, y1, y2, step="pre", color="r")
+
+    def _downsample(self, xstart, xend):
         # get the points in the view range
         mask = (self.origXData > xstart) & (self.origXData < xend)
         # dilate the mask by one to catch the points just outside
@@ -39,36 +45,41 @@ def downsample(self, xstart, xend):
 
         # mask data
         xdata = self.origXData[mask]
-        ydata = self.origYData[mask]
+        y1data = self.origY1Data[mask]
+        y2data = self.origY2Data[mask]
 
         # downsample data
         xdata = xdata[::ratio]
-        ydata = ydata[::ratio]
+        y1data = y1data[::ratio]
+        y2data = y2data[::ratio]
 
-        print(f"using {len(ydata)} of {np.sum(mask)} visible points")
+        print(f"using {len(y1data)} of {np.sum(mask)} visible points")
 
-        return xdata, ydata
+        return xdata, y1data, y2data
 
     def update(self, ax):
-        # Update the line
+        # Update the artists
         lims = ax.viewLim
         if abs(lims.width - self.delta) > 1e-8:
             self.delta = lims.width
             xstart, xend = lims.intervalx
-            self.line.set_data(*self.downsample(xstart, xend))
+            x, y1, y2 = self._downsample(xstart, xend)
+            self.line.set_data(x, y1)
+            self.poly_collection.set_data(x, y1, y2, step="pre")
             ax.figure.canvas.draw_idle()
 
 
 # Create a signal
 xdata = np.linspace(16, 365, (365-16)*4)
-ydata = np.sin(2*np.pi*xdata/153) + np.cos(2*np.pi*xdata/127)
+y1data = np.sin(2*np.pi*xdata/153) + np.cos(2*np.pi*xdata/127)
+y2data = y1data + .2
 
-d = DataDisplayDownsampler(xdata, ydata)
+d = DataDisplayDownsampler(xdata, y1data, y2data)
 
 fig, ax = plt.subplots()
 
 # Hook up the line
-d.line, = ax.plot(xdata, ydata, 'o-')
+d.plot(ax)
 ax.set_autoscale_on(False)  # Otherwise, infinite loop
 
 # Connect for changing the view limits

diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -6,7 +6,6 @@
 
 import re
 import numpy as np
-from numpy import ma
 
 import matplotlib as mpl
 import matplotlib.category  # Register category unit converter as side effect.
@@ -5551,143 +5550,58 @@ def _fill_between_x_or_y(
             i.e. constant in between *{ind}*.  The value determines where the
             step will occur:
 
-            - 'pre': The y value is continued constantly to the left from
-              every *x* position, i.e. the interval ``(x[i-1], x[i]]`` has the
-              value ``y[i]``.
+            - 'pre': The {dep} value is continued constantly to the left from
+              every *{ind}* position, i.e. the interval ``({ind}[i-1], {ind}[i]]``
+              has the value ``{dep}[i]``.
             - 'post': The y value is continued constantly to the right from
-              every *x* position, i.e. the interval ``[x[i], x[i+1])`` has the
-              value ``y[i]``.
-            - 'mid': Steps occur half-way between the *x* positions.
+              every *{ind}* position, i.e. the interval ``[{ind}[i], {ind}[i+1])``
+              has the value ``{dep}[i]``.
+            - 'mid': Steps occur half-way between the *{ind}* positions.
 
         Returns
         -------
-        `.PolyCollection`
-            A `.PolyCollection` containing the plotted polygons.
+        `.FillBetweenPolyCollection`
+            A `.FillBetweenPolyCollection` containing the plotted polygons.
 
         Other Parameters
         ----------------
         data : indexable object, optional
             DATA_PARAMETER_PLACEHOLDER
 
         **kwargs
-            All other keyword arguments are passed on to `.PolyCollection`.
-            They control the `.Polygon` properties:
+            All other keyword arguments are passed on to
+            `.FillBetweenPolyCollection`. They control the `.Polygon` properties:
 
-            %(PolyCollection:kwdoc)s
+            %(FillBetweenPolyCollection:kwdoc)s
 
         See Also
         --------
         fill_between : Fill between two sets of y-values.
         fill_betweenx : Fill between two sets of x-values.
         """
-
-        dep_dir = {"x": "y", "y": "x"}[ind_dir]
+        dep_dir = mcoll.FillBetweenPolyCollection._f_dir_from_t(ind_dir)
 
         if not mpl.rcParams["_internal.classic_mode"]:
             kwargs = cbook.normalize_kwargs(kwargs, mcoll.Collection)
             if not any(c in kwargs for c in ("color", "facecolor")):
-                kwargs["facecolor"] = \
-                    self._get_patches_for_fill.get_next_color()
-
-        # Handle united data, such as dates
-        ind, dep1, dep2 = map(
-            ma.masked_invalid, self._process_unit_info(
-                [(ind_dir, ind), (dep_dir, dep1), (dep_dir, dep2)], kwargs))
-
-        for name, array in [
-                (ind_dir, ind), (f"{dep_dir}1", dep1), (f"{dep_dir}2", dep2)]:
-            if array.ndim > 1:
-                raise ValueError(f"{name!r} is not 1-dimensional")
+                kwargs["facecolor"] = self._get_patches_for_fill.get_next_color()
 
-        if where is None:
-            where = True
-        else:
-            where = np.asarray(where, dtype=bool)
-            if where.size != ind.size:
-                raise ValueError(f"where size ({where.size}) does not match "
-                                 f"{ind_dir} size ({ind.size})")
-        where = where & ~functools.reduce(
-            np.logical_or, map(np.ma.getmaskarray, [ind, dep1, dep2]))
-
-        ind, dep1, dep2 = np.broadcast_arrays(
-            np.atleast_1d(ind), dep1, dep2, subok=True)
-
-        polys = []
-        for idx0, idx1 in cbook.contiguous_regions(where):
-            indslice = ind[idx0:idx1]
-            dep1slice = dep1[idx0:idx1]
-            dep2slice = dep2[idx0:idx1]
-            if step is not None:
-                step_func = cbook.STEP_LOOKUP_MAP["steps-" + step]
-                indslice, dep1slice, dep2slice = \
-                    step_func(indslice, dep1slice, dep2slice)
-
-            if not len(indslice):
-                continue
+        ind, dep1, dep2 = self._fill_between_process_units(
+            ind_dir, dep_dir, ind, dep1, dep2, **kwargs)
 
-            N = len(indslice)
-            pts = np.zeros((2 * N + 2, 2))
-
-            if interpolate:
-                def get_interp_point(idx):
-                    im1 = max(idx - 1, 0)
-                    ind_values = ind[im1:idx+1]
-                    diff_values = dep1[im1:idx+1] - dep2[im1:idx+1]
-                    dep1_values = dep1[im1:idx+1]
-
-                    if len(diff_values) == 2:
-                        if np.ma.is_masked(diff_values[1]):
-                            return ind[im1], dep1[im1]
-                        elif np.ma.is_masked(diff_values[0]):
-                            return ind[idx], dep1[idx]
-
-                    diff_order = diff_values.argsort()
-                    diff_root_ind = np.interp(
-                        0, diff_values[diff_order], ind_values[diff_order])
-                    ind_order = ind_values.argsort()
-                    diff_root_dep = np.interp(
-                        diff_root_ind,
-                        ind_values[ind_order], dep1_values[ind_order])
-                    return diff_root_ind, diff_root_dep
-
-                start = get_interp_point(idx0)
-                end = get_interp_point(idx1)
-            else:
-                # Handle scalar dep2 (e.g. 0): the fill should go all
-                # the way down to 0 even if none of the dep1 sample points do.
-                start = indslice[0], dep2slice[0]
-                end = indslice[-1], dep2slice[-1]
-
-            pts[0] = start
-            pts[N + 1] = end
-
-            pts[1:N+1, 0] = indslice
-            pts[1:N+1, 1] = dep1slice
-            pts[N+2:, 0] = indslice[::-1]
-            pts[N+2:, 1] = dep2slice[::-1]
-
-            if ind_dir == "y":
-                pts = pts[:, ::-1]
-
-            polys.append(pts)
-
-        collection = mcoll.PolyCollection(polys, **kwargs)
-
-        # now update the datalim and autoscale
-        pts = np.vstack([np.hstack([ind[where, None], dep1[where, None]]),
-                         np.hstack([ind[where, None], dep2[where, None]])])
-        if ind_dir == "y":
-            pts = pts[:, ::-1]
-
-        up_x = up_y = True
-        if "transform" in kwargs:
-            up_x, up_y = kwargs["transform"].contains_branch_seperately(self.transData)
-        self.update_datalim(pts, updatex=up_x, updatey=up_y)
+        collection = mcoll.FillBetweenPolyCollection(
+            ind_dir, ind, dep1, dep2,
+            where=where, interpolate=interpolate, step=step, **kwargs)
 
-        self.add_collection(collection, autolim=False)
+        self.add_collection(collection)
         self._request_autoscale_view()
         return collection
 
+    def _fill_between_process_units(self, ind_dir, dep_dir, ind, dep1, dep2, **kwargs):
+        """Handle united data, such as dates."""
+        return map(np.ma.masked_invalid, self._process_unit_info(
+            [(ind_dir, ind), (dep_dir, dep1), (dep_dir, dep2)], kwargs))
+
     def fill_between(self, x, y1, y2=0, where=None, interpolate=False,
                      step=None, **kwargs):
         return self._fill_between_x_or_y(

diff --git a/lib/matplotlib/axes/_axes.pyi b/lib/matplotlib/axes/_axes.pyi
@@ -5,6 +5,7 @@ from matplotlib.artist import Artist
 from matplotlib.backend_bases import RendererBase
 from matplotlib.collections import (
     Collection,
+    FillBetweenPolyCollection,
     LineCollection,
     PathCollection,
     PolyCollection,
@@ -459,7 +460,7 @@ class Axes(_AxesBase):
         *,
         data=...,
         **kwargs
-    ) -> PolyCollection: ...
+    ) -> FillBetweenPolyCollection: ...
     def fill_betweenx(
         self,
         y: ArrayLike,
@@ -471,7 +472,7 @@ class Axes(_AxesBase):
         *,
         data=...,
         **kwargs
-    ) -> PolyCollection: ...
+    ) -> FillBetweenPolyCollection: ...
     def imshow(
         self,
         X: ArrayLike | PIL.Image.Image,