API: add antialiased to interpolation-stage in image

lib/matplotlib/axes/_axes.py

@@ -5791,11 +5791,14 @@ def imshow(self, X, cmap=None, norm=None, *, aspect=None,
             which can be set by *filterrad*. Additionally, the antigrain image
             resize filter is controlled by the parameter *filternorm*.
 
-        interpolation_stage : {'data', 'rgba'}, default: 'data'
-            If 'data', interpolation
-            is carried out on the data provided by the user.  If 'rgba', the
-            interpolation is carried out after the colormapping has been
-            applied (visual interpolation).
+        interpolation_stage : {'antialiased', 'data', 'rgba'}, default: 'antialiased'
+            If 'data', interpolation is carried out on the data provided by the user.
+            If 'rgba', the interpolation is carried out in RGBA-space after the
+            color-mapping has been applied (visual interpolation).  If 'antialiased',
+            then 'rgba' is used if downsampling, or upsampling at a rate less than 3.
+            If upsampling at a higher rate, then 'data' is used.
+            See :doc:`/gallery/images_contours_and_fields/image_antialiasing` for
+            a discussion of image antialiasing.
 
         alpha : float or array-like, optional
             The alpha blending value, between 0 (transparent) and 1 (opaque).

lib/matplotlib/image.py

@@ -421,7 +421,21 @@ def _make_image(self, A, in_bbox, out_bbox, clip_bbox, magnification=1.0,
         if not unsampled:
             if not (A.ndim == 2 or A.ndim == 3 and A.shape[-1] in (3, 4)):
                 raise ValueError(f"Invalid shape {A.shape} for image data")
-            if A.ndim == 2 and self._interpolation_stage != 'rgba':
+
+            # if antialiased, this needs to change as window sizes
+            # change:
+            interpolation_stage = self._interpolation_stage
+            if interpolation_stage == 'antialiased':
+                pos = np.array([[0, 0], [A.shape[1], A.shape[0]]])
+                disp = t.transform(pos)
+                dispx = np.abs(np.diff(disp[:, 0])) / A.shape[1]
+                dispy = np.abs(np.diff(disp[:, 1])) / A.shape[0]
+                if (dispx < 3) or (dispy < 3):
+                    interpolation_stage = 'rgba'
+                else:
+                    interpolation_stage = 'data'
+
+            if A.ndim == 2 and interpolation_stage == 'data':
                 # if we are a 2D array, then we are running through the
                 # norm + colormap transformation.  However, in general the
                 # input data is not going to match the size on the screen so we
@@ -552,7 +566,7 @@ def _make_image(self, A, in_bbox, out_bbox, clip_bbox, magnification=1.0,
                      cbook._setattr_cm(self.norm, vmin=s_vmin, vmax=s_vmax):
                     output = self.norm(resampled_masked)
             else:
-                if A.ndim == 2:  # _interpolation_stage == 'rgba'
+                if A.ndim == 2:  # interpolation_stage == 'rgba'
                     self.norm.autoscale_None(A)
                     A = self.to_rgba(A)
                 alpha = self._get_scalar_alpha()
@@ -787,12 +801,14 @@ def set_interpolation_stage(self, s):
 
         Parameters
         ----------
-        s : {'data', 'rgba'} or None
+        s : {'data', 'rgba', 'antialiased'} or None
             Whether to apply up/downsampling interpolation in data or RGBA
             space.  If None, use :rc:`image.interpolation_stage`.
+            If 'antialiased' we will check upsampling rate and if less
+            than 3 then use 'rgba', otherwise use 'data'.
         """
         s = mpl._val_or_rc(s, 'image.interpolation_stage')
-        _api.check_in_list(['data', 'rgba'], s=s)
+        _api.check_in_list(['data', 'rgba', 'antialiased'], s=s)
         self._interpolation_stage = s
         self.stale = True