API: change interpolation default to 'auto'

jklymak · timhoffm · jklymak · commit 45fac07591af · 2024-07-08T13:46:02.000-07:00
Co-authored-by: Tim Hoffmann &lt;2836374+timhoffm@users.noreply.github.com&gt;
diff --git a/doc/api/next_api_changes/behavior/28061-JMK.rst b/doc/api/next_api_changes/behavior/28061-JMK.rst
@@ -1,14 +1,23 @@
-imshow *interpolation_stage* default changed to 'antialiased'
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``imshow`` *interpolation_stage* default changed to 'auto'
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The *interpolation_stage* keyword argument `~.Axes.imshow` has a new default
-value 'antialiased'.  For images that are up-sampled less than a factor of
-three or down-sampled , image interpolation will occur in 'rgba' space.  For images
-that are up-sampled by more than a factor of 3, then image interpolation occurs
+The *interpolation_stage* parameter of  `~.Axes.imshow` has a new default
+value 'auto'.  For images that are up-sampled less than a factor of
+three or down-sampled, image interpolation will occur in 'rgba' space.  For images
+that are up-sampled by a factor of 3 or more, then image interpolation occurs
 in 'data' space.
 
 The previous default was 'data', so down-sampled images may change subtly with
 the new default.  However, the new default also avoids floating point artifacts
 at sharp boundaries in a colormap when down-sampling.
 
-The previous behavior can achieved by changing :rc:`image.interpolation_stage`.
+The previous behavior can achieved by setting the *interpolation_stage* parameter
+or :rc:`image.interpolation_stage` to 'data'.
+
+imshow default *interpolation* changed to 'auto'
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The *interpolation* parameter of `~.Axes.imshow` has a new default
+value 'auto', changed from 'antialiased', for consistency with *interpolation_stage*
+and because the interpolation is only anti-aliasing during down-sampling.  Passing
+'antialiased' still works, and behaves exactly the same as 'auto', but is discouraged.
diff --git a/galleries/examples/images_contours_and_fields/image_antialiasing.py b/galleries/examples/images_contours_and_fields/image_antialiasing.py
@@ -131,10 +131,10 @@
 # colormap, it is what we perceive when a blue and red stripe are close to each
 # other.
 #
-# The default for the *interpolation* keyword argument is 'antialiased' which
+# The default for the *interpolation* keyword argument is 'auto' which
 # will choose a Hanning filter if the image is being down-sampled or up-sampled
 # by less than a factor of three.  The default *interpolation_stage* keyword
-# argument is also 'antialiased', and for images that are down-sampled or
+# argument is also 'auto', and for images that are down-sampled or
 # up-sampled by less than a factor of three it defaults to 'rgba'
 # interpolation.
 #
@@ -151,8 +151,8 @@
 # %%
 # Better anti-aliasing algorithms can reduce this effect:
 fig, ax = plt.subplots(figsize=(6.8, 6.8))
-ax.imshow(alarge, interpolation='antialiased', cmap='grey')
-ax.set_title("up-sampled by factor a 1.17, interpolation='antialiased'")
+ax.imshow(alarge, interpolation='auto', cmap='grey')
+ax.set_title("up-sampled by factor a 1.17, interpolation='auto'")
 
 # %%
 # Apart from the default 'hanning' anti-aliasing, `~.Axes.imshow` supports a
@@ -174,8 +174,8 @@
 # you do not use an anti-aliasing filter (*interpolation* set set to
 # 'nearest'), however, that makes the part of the data susceptible to Moiré
 # patterns much worse (second panel).  Therefore, we recommend the default
-# *interpolation* of 'hanning'/'antialiased', and *interpolation_stage* of
-# 'rgba'/'antialiased' for most down-sampling situations (last panel).
+# *interpolation* of 'hanning'/'auto', and *interpolation_stage* of
+# 'rgba'/'auto' for most down-sampling situations (last panel).
 
 a = alarge + 1
 cmap = plt.get_cmap('RdBu_r')
@@ -206,7 +206,7 @@
 
 fig, axs = plt.subplots(1, 2, figsize=(6.5, 4), layout='compressed')
 axs[0].imshow(asmall, cmap='viridis')
-axs[0].set_title("interpolation='antialiased'\nstage='antialiased'")
+axs[0].set_title("interpolation='auto'\nstage='auto'")
 axs[1].imshow(asmall, cmap='viridis', interpolation="nearest",
               interpolation_stage="data")
 axs[1].set_title("interpolation='nearest'\nstage='data'")
@@ -218,7 +218,7 @@
 # where the filters can cause colors that are not in the colormap to be the result of
 # the interpolation.  In the following example, note that when the interpolation is
 # 'rgba' there are red colors as interpolation artifacts.  Therefore, the default
-# 'antialiased' choice for *interpolation_stage* is set to be the same as 'data'
+# 'auto' choice for *interpolation_stage* is set to be the same as 'data'
 # when up-sampling is greater than a factor of three:
 
 fig, axs = plt.subplots(1, 2, figsize=(6.5, 4), layout='compressed')
diff --git a/galleries/examples/images_contours_and_fields/interpolation_methods.py b/galleries/examples/images_contours_and_fields/interpolation_methods.py
@@ -8,14 +8,14 @@
 
 If *interpolation* is None, it defaults to the :rc:`image.interpolation`.
 If the interpolation is ``'none'``, then no interpolation is performed for the
-Agg, ps and pdf backends. Other backends will default to ``'antialiased'``.
+Agg, ps and pdf backends. Other backends will default to ``'auto'``.
 
 For the Agg, ps and pdf backends, ``interpolation='none'`` works well when a
 big image is scaled down, while ``interpolation='nearest'`` works well when
 a small image is scaled up.
 
 See :doc:`/gallery/images_contours_and_fields/image_antialiasing` for a
-discussion on the default ``interpolation='antialiased'`` option.
+discussion on the default ``interpolation='auto'`` option.
 """
 
 import matplotlib.pyplot as plt
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -5799,7 +5799,7 @@ def imshow(self, X, cmap=None, norm=None, *, aspect=None,
         interpolation : str, default: :rc:`image.interpolation`
             The interpolation method used.
 
-            Supported values are 'none', 'antialiased', 'nearest', 'bilinear',
+            Supported values are 'none', 'auto', 'nearest', 'bilinear',
             'bicubic', 'spline16', 'spline36', 'hanning', 'hamming', 'hermite',
             'kaiser', 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell',
             'sinc', 'lanczos', 'blackman'.
@@ -5814,7 +5814,7 @@ def imshow(self, X, cmap=None, norm=None, *, aspect=None,
             pdf, and svg viewers may display these raw pixels differently. On
             other backends, 'none' is the same as 'nearest'.
 
-            If *interpolation* is the default 'antialiased', then 'nearest'
+            If *interpolation* is the default 'auto', then 'nearest'
             interpolation is used if the image is upsampled by more than a
             factor of three (i.e. the number of display pixels is at least
             three times the size of the data array).  If the upsampling rate is
@@ -5832,14 +5832,18 @@ 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 : {'antialiased', 'data', 'rgba'}, default: 'antialiased'
-            If 'data', interpolation is carried out on the data provided by the user,
-            useful if interpolating between pixels during upsampling.
-            If 'rgba', the interpolation is carried out in RGBA-space after the
-            color-mapping has been applied, useful if downsampling and combining
-            pixels visually. The default 'antialiased' is appropriate for most
-            applications where 'rgba' is used when downsampling, or upsampling at a
-            rate less than 3, and 'data' is used when upsampling at a higher rate.
+        interpolation_stage : {'auto', 'data', 'rgba'}, default: 'auto'
+            Supported values:
+
+            - 'data': Interpolation is carried out on the data provided by the user
+              This is useful if interpolating between pixels during upsampling.
+            - 'rgba': The interpolation is carried out in RGBA-space after the
+              color-mapping has been applied. This is useful if downsampling and
+              combining pixels visually.
+            - 'auto': Select a suitable interpolation stage automatically. This uses
+              'rgba' when downsampling, or upsampling at a rate less than 3, and
+              'data' when upsampling at a higher rate.
+
             See :doc:`/gallery/images_contours_and_fields/image_antialiasing` for
             a discussion of image antialiasing.
 
diff --git a/lib/matplotlib/axes/_axes.pyi b/lib/matplotlib/axes/_axes.pyi
@@ -492,7 +492,7 @@ class Axes(_AxesBase):
         vmax: float | None = ...,
         origin: Literal["upper", "lower"] | None = ...,
         extent: tuple[float, float, float, float] | None = ...,
-        interpolation_stage: Literal["data", "rgba"] | None = ...,
+        interpolation_stage: Literal["data", "rgba", "auto"] | None = ...,
         filternorm: bool = ...,
         filterrad: float = ...,
         resample: bool | None = ...,
diff --git a/lib/matplotlib/image.py b/lib/matplotlib/image.py
@@ -31,7 +31,7 @@
 
 # map interpolation strings to module constants
 _interpd_ = {
-    'antialiased': _image.NEAREST,  # this will use nearest or Hanning...
+    'auto': _image.NEAREST,  # this will use nearest or Hanning...
     'none': _image.NEAREST,  # fall back to nearest when not supported
     'nearest': _image.NEAREST,
     'bilinear': _image.BILINEAR,
@@ -50,6 +50,7 @@
     'sinc': _image.SINC,
     'lanczos': _image.LANCZOS,
     'blackman': _image.BLACKMAN,
+    'antialiased': _image.NEAREST,  # this will use nearest or Hanning...
 }
 
 interpolations_names = set(_interpd_)
@@ -186,7 +187,7 @@ def _resample(
     # compare the number of displayed pixels to the number of
     # the data pixels.
     interpolation = image_obj.get_interpolation()
-    if interpolation == 'antialiased':
+    if interpolation in ['antialiased', 'auto']:
         # don't antialias if upsampling by an integer number or
         # if zooming in more than a factor of 3
         pos = np.array([[0, 0], [data.shape[1], data.shape[0]]])
@@ -425,7 +426,7 @@ def _make_image(self, A, in_bbox, out_bbox, clip_bbox, magnification=1.0,
             # if antialiased, this needs to change as window sizes
             # change:
             interpolation_stage = self._interpolation_stage
-            if interpolation_stage == 'antialiased':
+            if interpolation_stage in ['antialiased', 'auto']:
                 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]
@@ -758,9 +759,9 @@ def get_interpolation(self):
         """
         Return the interpolation method the image uses when resizing.
 
-        One of 'antialiased', 'nearest', 'bilinear', 'bicubic', 'spline16',
-        'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric',
-        'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos',
+        One of 'auto', 'antialiased', 'nearest', 'bilinear', 'bicubic',
+        'spline16', 'spline36', 'hanning', 'hamming', 'hermite', 'kaiser',
+        'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos',
         or 'none'.
         """
         return self._interpolation
@@ -776,7 +777,7 @@ def set_interpolation(self, s):
 
         Parameters
         ----------
-        s : {'antialiased', 'nearest', 'bilinear', 'bicubic', 'spline16', \
+        s : {'auto', 'nearest', 'bilinear', 'bicubic', 'spline16', \
 'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric', 'catrom', \
 'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos', 'none'} or None
         """
@@ -799,14 +800,14 @@ def set_interpolation_stage(self, s):
 
         Parameters
         ----------
-        s : {'data', 'rgba', 'antialiased'} or None
+        s : {'data', 'rgba', 'auto'} 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
+            If 'auto' 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', 'antialiased'], s=s)
+        _api.check_in_list(['data', 'rgba', 'auto'], s=s)
         self._interpolation_stage = s
         self.stale = True
 
@@ -886,7 +887,7 @@ class AxesImage(_ImageBase):
     norm : str or `~matplotlib.colors.Normalize`
         Maps luminance to 0-1.
     interpolation : str, default: :rc:`image.interpolation`
-        Supported values are 'none', 'antialiased', 'nearest', 'bilinear',
+        Supported values are 'none', 'auto', 'nearest', 'bilinear',
         'bicubic', 'spline16', 'spline36', 'hanning', 'hamming', 'hermite',
         'kaiser', 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell',
         'sinc', 'lanczos', 'blackman'.
diff --git a/lib/matplotlib/image.pyi b/lib/matplotlib/image.pyi
@@ -73,7 +73,7 @@ class _ImageBase(martist.Artist, cm.ScalarMappable):
         filterrad: float = ...,
         resample: bool | None = ...,
         *,
-        interpolation_stage: Literal["data", "rgba"] | None = ...,
+        interpolation_stage: Literal["data", "rgba", "auto"] | None = ...,
         **kwargs
     ) -> None: ...
     def get_size(self) -> tuple[int, int]: ...
@@ -89,8 +89,8 @@ class _ImageBase(martist.Artist, cm.ScalarMappable):
     def get_shape(self) -> tuple[int, int, int]: ...
     def get_interpolation(self) -> str: ...
     def set_interpolation(self, s: str | None) -> None: ...
-    def get_interpolation_stage(self) -> Literal["data", "rgba"]: ...
-    def set_interpolation_stage(self, s: Literal["data", "rgba"]) -> None: ...
+    def get_interpolation_stage(self) -> Literal["data", "rgba", "auto"]: ...
+    def set_interpolation_stage(self, s: Literal["data", "rgba", "auto"]) -> None: ...
     def can_composite(self) -> bool: ...
     def set_resample(self, v: bool | None) -> None: ...
     def get_resample(self) -> bool: ...
@@ -112,7 +112,7 @@ class AxesImage(_ImageBase):
         filternorm: bool = ...,
         filterrad: float = ...,
         resample: bool = ...,
-        interpolation_stage: Literal["data", "rgba"] | None = ...,
+        interpolation_stage: Literal["data", "rgba", "auto"] | None = ...,
         **kwargs
     ) -> None: ...
     def get_window_extent(self, renderer: RendererBase | None = ...) -> Bbox: ...
diff --git a/lib/matplotlib/mpl-data/matplotlibrc b/lib/matplotlib/mpl-data/matplotlibrc
@@ -602,8 +602,8 @@
 ## * IMAGES                                                                  *
 ## ***************************************************************************
 #image.aspect:          equal        # {equal, auto} or a number
-#image.interpolation:   antialiased  # see help(imshow) for options
-#image.interpolation_stage: antialiased     # see help(imshow) for options
+#image.interpolation:   auto         # see help(imshow) for options
+#image.interpolation_stage: auto     # see help(imshow) for options
 #image.cmap:            viridis      # A colormap name (plasma, magma, etc.)
 #image.lut:             256          # the size of the colormap lookup table
 #image.origin:          upper        # {lower, upper}
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -3565,7 +3565,7 @@ def imshow(
     vmax: float | None = None,
     origin: Literal["upper", "lower"] | None = None,
     extent: tuple[float, float, float, float] | None = None,
-    interpolation_stage: Literal["data", "rgba"] | None = None,
+    interpolation_stage: Literal["data", "rgba", "auto"] | None = None,
     filternorm: bool = True,
     filterrad: float = 4.0,
     resample: bool | None = None,
diff --git a/lib/matplotlib/rcsetup.py b/lib/matplotlib/rcsetup.py
@@ -1053,7 +1053,7 @@ def _convert_validator_spec(key, conv):
 
     "image.aspect":              validate_aspect,  # equal, auto, a number
     "image.interpolation":       validate_string,
-    "image.interpolation_stage": ["antialiased", "data", "rgba"],
+    "image.interpolation_stage": ["auto", "data", "rgba"],
     "image.cmap":                _validate_cmap,  # gray, jet, etc.
     "image.lut":                 validate_int,  # lookup table
     "image.origin":              ["upper", "lower"],
diff --git a/lib/matplotlib/tests/test_image.py b/lib/matplotlib/tests/test_image.py
diff --git a/lib/matplotlib/tests/test_png.py b/lib/matplotlib/tests/test_png.py
