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

This makes explicit calls to `autoscale_view()` or
`_request_autoscale_view()` unnecessary.

3D Axes have a special `auto_scale_xyz()`, also there's a mixture of
`add_collection()` and `add_collection3d()`. This needs separate sorting
. I've added a private value `autolim="_datalim_only"` to keep the
behavior for 3D Axes unchanged for now. That will be resolved by a
follow-up PR. I believe it's getting too complicated if we fold this
into the 2D change.

Author: timhoffm

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/shapes_and_collections/collections.py

@@ -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)')

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)

galleries/users_explain/axes/autoscale.py

@@ -177,4 +177,3 @@
     offset_transform=ax.transData,  # Propagate transformations of the Axes
 )
 ax.add_collection(collection)
-ax.autoscale_view()

lib/matplotlib/axes/_axes.py

@@ -3028,7 +3028,6 @@ def broken_barh(self, xranges, yrange, **kwargs):
 
         col = mcoll.PolyCollection(np.array(vertices), **kwargs)
         self.add_collection(col, autolim=True)
-        self._request_autoscale_view()
 
         return col
 
@@ -5337,7 +5336,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
 
@@ -5808,7 +5806,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
@@ -5820,7 +5817,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
@@ -5980,7 +5976,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)
 
 

lib/matplotlib/tests/test_collections.py

@@ -408,7 +408,6 @@ def test_EllipseCollection():
         ww, hh, aa, units='x', offsets=XY, offset_transform=ax.transData,
         facecolors='none')
     ax.add_collection(ec)
-    ax.autoscale_view()
 
 
 def test_EllipseCollection_setter_getter():
@@ -526,7 +525,6 @@ def test_regularpolycollection_rotate():
             4, sizes=(100,), rotation=alpha,
             offsets=[xy], offset_transform=ax.transData)
         ax.add_collection(col, autolim=True)
-    ax.autoscale_view()
 
 
 @image_comparison(['regularpolycollection_scale.png'], remove_text=True)