Merge pull request matplotlib#29958 from timhoffm/add_collection_viewlims

ENH: ax.add_collection(..., autolim=True) updates view limits

Author: QuLogic

doc/api/next_api_changes/behavior/29958-TH.rst

@@ -0,0 +1,8 @@
+``Axes.add_collection(..., autolim=True)`` updates view limits
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``Axes.add_collection(..., autolim=True)`` has so far only updated the data limits.
+Users needed to additionally call `.Axes.autoscale_view` to update the view limits.
+View limits are now updated as well if ``autolim=True``, using a lazy internal
+update mechanism, so that the costs only apply once also if you add multiple
+collections.

galleries/examples/lines_bars_and_markers/multicolored_line.py

@@ -72,7 +72,6 @@ def colored_line(x, y, c, ax=None, **lc_kwargs):
     # Plot the line collection to the axes
     ax = ax or plt.gca()
     ax.add_collection(lc)
-    ax.autoscale_view()
 
     return lc
 

galleries/examples/shapes_and_collections/collections.py

@@ -1,7 +1,7 @@
 """
-=========================================================
-Line, Poly and RegularPoly Collection with autoscaling
-=========================================================
+=====================================
+Line, Poly and RegularPoly Collection
+=====================================
 
 For the first two subplots, we will use spirals.  Their size will be set in
 plot units, not data units.  Their positions will be set in data units by using
@@ -38,7 +38,7 @@
 # Make some offsets
 xyo = rs.randn(npts, 2)
 
-# Make a list of colors cycling through the default series.
+# Make a list of colors from the default color cycle.
 colors = plt.rcParams['axes.prop_cycle'].by_key()['color']
 
 fig, ((ax1, ax2), (ax3, ax4)) = plt.subplots(2, 2)
@@ -59,14 +59,12 @@
 # but it is good enough to generate a plot that you can use
 # as a starting point.  If you know beforehand the range of
 # x and y that you want to show, it is better to set them
-# explicitly, leave out the *autolim* keyword argument (or set it to False),
-# and omit the 'ax1.autoscale_view()' call below.
+# explicitly, set the *autolim* keyword argument to False.
 
 # Make a transform for the line segments such that their size is
 # given in points:
 col.set_color(colors)
 
-ax1.autoscale_view()  # See comment above, after ax1.add_collection.
 ax1.set_title('LineCollection using offsets')
 
 
@@ -79,7 +77,6 @@
 col.set_color(colors)
 
 
-ax2.autoscale_view()
 ax2.set_title('PolyCollection using offsets')
 
 # 7-sided regular polygons
@@ -90,7 +87,6 @@
 col.set_transform(trans)  # the points to pixels transform
 ax3.add_collection(col, autolim=True)
 col.set_color(colors)
-ax3.autoscale_view()
 ax3.set_title('RegularPolyCollection using offsets')
 
 
@@ -114,7 +110,6 @@
 col = collections.LineCollection(segs, offsets=offs)
 ax4.add_collection(col, autolim=True)
 col.set_color(colors)
-ax4.autoscale_view()
 ax4.set_title('Successive data offsets')
 ax4.set_xlabel('Zonal velocity component (m/s)')
 ax4.set_ylabel('Depth (m)')
@@ -136,6 +131,5 @@
 #    - `matplotlib.collections.LineCollection`
 #    - `matplotlib.collections.RegularPolyCollection`
 #    - `matplotlib.axes.Axes.add_collection`
-#    - `matplotlib.axes.Axes.autoscale_view`
 #    - `matplotlib.transforms.Affine2D`
 #    - `matplotlib.transforms.Affine2D.scale`

galleries/examples/shapes_and_collections/ellipse_collection.py

@@ -30,7 +30,6 @@
                        offset_transform=ax.transData)
 ec.set_array((X + Y).ravel())
 ax.add_collection(ec)
-ax.autoscale_view()
 ax.set_xlabel('X')
 ax.set_ylabel('y')
 cbar = plt.colorbar(ec)
@@ -47,5 +46,4 @@
 #    - `matplotlib.collections`
 #    - `matplotlib.collections.EllipseCollection`
 #    - `matplotlib.axes.Axes.add_collection`
-#    - `matplotlib.axes.Axes.autoscale_view`
 #    - `matplotlib.cm.ScalarMappable.set_array`

galleries/users_explain/axes/autoscale.py

@@ -18,7 +18,6 @@
 import matplotlib.pyplot as plt
 import numpy as np
 
-import matplotlib as mpl
 
 x = np.linspace(-2 * np.pi, 2 * np.pi, 100)
 y = np.sinc(x)
@@ -159,22 +158,3 @@
 ax.autoscale(enable=None, axis="x", tight=True)
 
 print(ax.margins())
-
-# %%
-# Working with collections
-# ------------------------
-#
-# Autoscale works out of the box for all lines, patches, and images added to
-# the Axes. One of the artists that it won't work with is a `.Collection`.
-# After adding a collection to the Axes, one has to manually trigger the
-# `~matplotlib.axes.Axes.autoscale_view()` to recalculate
-# axes limits.
-
-fig, ax = plt.subplots()
-collection = mpl.collections.StarPolygonCollection(
-    5, rotation=0, sizes=(250,),  # five point star, zero angle, size 250px
-    offsets=np.column_stack([x, y]),  # Set the positions
-    offset_transform=ax.transData,  # Propagate transformations of the Axes
-)
-ax.add_collection(collection)
-ax.autoscale_view()

lib/matplotlib/axes/_axes.py

@@ -3044,7 +3044,6 @@ def broken_barh(self, xranges, yrange, align="bottom", **kwargs):
 
         col = mcoll.PolyCollection(np.array(vertices), **kwargs)
         self.add_collection(col, autolim=True)
-        self._request_autoscale_view()
 
         return col
 
@@ -5353,7 +5352,6 @@ def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
                 self.set_ymargin(0.05)
 
         self.add_collection(collection)
-        self._request_autoscale_view()
 
         return collection
 
@@ -5824,7 +5822,6 @@ def quiver(self, *args, **kwargs):
         args = self._quiver_units(args, kwargs)
         q = mquiver.Quiver(self, *args, **kwargs)
         self.add_collection(q, autolim=True)
-        self._request_autoscale_view()
         return q
 
     # args can be some combination of X, Y, U, V, C and all should be replaced
@@ -5836,7 +5833,6 @@ def barbs(self, *args, **kwargs):
         args = self._quiver_units(args, kwargs)
         b = mquiver.Barbs(self, *args, **kwargs)
         self.add_collection(b, autolim=True)
-        self._request_autoscale_view()
         return b
 
     # Uses a custom implementation of data-kwarg handling in
@@ -5996,7 +5992,6 @@ def _fill_between_x_or_y(
             where=where, interpolate=interpolate, step=step, **kwargs)
 
         self.add_collection(collection)
-        self._request_autoscale_view()
         return collection
 
     def _fill_between_process_units(self, ind_dir, dep_dir, ind, dep1, dep2, **kwargs):

lib/matplotlib/axes/_base.py

@@ -2336,6 +2336,23 @@ def add_child_axes(self, ax):
     def add_collection(self, collection, autolim=True):
         """
         Add a `.Collection` to the Axes; return the collection.
+
+        Parameters
+        ----------
+        collection : `.Collection`
+            The collection to add.
+        autolim : bool
+            Whether to update data and view limits.
+
+            .. versionchanged:: 3.11
+
+               This now also updates the view limits, making explicit
+               calls to `~.Axes.autoscale_view` unnecessary.
+
+            As an implementation detail, the value "_datalim_only" is
+            supported to smooth the internal transition from pre-3.11
+            behavior. This is not a public interface and will be removed
+            again in the future.
         """
         _api.check_isinstance(mcoll.Collection, collection=collection)
         if not collection.get_label():
@@ -2371,6 +2388,8 @@ def add_collection(self, collection, autolim=True):
                 updatex=x_is_data or ox_is_data,
                 updatey=y_is_data or oy_is_data,
             )
+            if autolim != "_datalim_only":
+                self._request_autoscale_view()
 
         self.stale = True
         return collection

lib/matplotlib/axes/_base.pyi

@@ -234,7 +234,7 @@ class _AxesBase(martist.Artist):
     def add_artist(self, a: Artist) -> Artist: ...
     def add_child_axes(self, ax: _AxesBase) -> _AxesBase: ...
     def add_collection(
-        self, collection: Collection, autolim: bool = ...
+        self, collection: Collection, autolim: bool | Literal["_datalim_only"] = ...
     ) -> Collection: ...
     def add_image(self, image: AxesImage) -> AxesImage: ...
     def add_line(self, line: Line2D) -> Line2D: ...

lib/matplotlib/colorbar.py

@@ -373,7 +373,7 @@ def __init__(
             colors=[mpl.rcParams['axes.edgecolor']],
             linewidths=[0.5 * mpl.rcParams['axes.linewidth']],
             clip_on=False)
-        self.ax.add_collection(self.dividers)
+        self.ax.add_collection(self.dividers, autolim=False)
 
         self._locator = None
         self._minorlocator = None
@@ -807,7 +807,7 @@ def add_lines(self, *args, **kwargs):
         xy = self.ax.transAxes.inverted().transform(inches.transform(xy))
         col.set_clip_path(mpath.Path(xy, closed=True),
                           self.ax.transAxes)
-        self.ax.add_collection(col)
+        self.ax.add_collection(col, autolim=False)
         self.stale = True
 
     def update_ticks(self):

lib/matplotlib/tests/test_backend_ps.py

@@ -354,7 +354,11 @@ def test_path_collection():
     sizes = [0.02, 0.04]
     pc = mcollections.PathCollection(paths, sizes, zorder=-1,
                                      facecolors='yellow', offsets=offsets)
-    ax.add_collection(pc)
+    # Note: autolim=False is used to keep the view limits as is for now,
+    # given the updated behavior of autolim=True to also update the view
+    # limits. It may be reasonable to test the limits handling in the future
+    # as well. This will require regenerating the reference image.
+    ax.add_collection(pc, autolim=False)
     ax.set_xlim(0, 1)