ENH: anti-alias down-sampled images

jklymak · jklymak · commit 981818cc9c01 · 2019-07-17T10:02:38.000-07:00
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -5482,17 +5482,25 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
             The interpolation method used. If *None*
             :rc:`image.interpolation` is used, which defaults to 'nearest'.
 
-            Supported values are 'none', 'nearest', 'bilinear', 'bicubic',
-            'spline16', 'spline36', 'hanning', 'hamming', 'hermite', 'kaiser',
-            'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc',
-            'lanczos'.
+            Supported values are 'none', 'antialiased', 'nearest', 'bilinear',
+            'bicubic', 'spline16', 'spline36', 'hanning', 'hamming', 'hermite',
+            'kaiser', 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell',
+            'sinc', 'lanczos'.
 
             If *interpolation* is 'none', then no interpolation is performed
             on the Agg, ps, pdf and svg backends. Other backends will fall back
             to 'nearest'. Note that most SVG renders perform interpolation at
             rendering and that the default interpolation method they implement
             may differ.
 
+            If *interpolation* is the default 'antialiased', 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
+            smaller than 3, or the image is downsampled, then 'hanning'
+            interpolation is used to act as an anti-aliasing filter, unless the
+            image happens to be upsampled by exactly a factor of two or one.
+
             See
             :doc:`/gallery/images_contours_and_fields/interpolation_methods`
             for an overview of the supported interpolation methods.
diff --git a/lib/matplotlib/image.py b/lib/matplotlib/image.py
@@ -33,6 +33,7 @@
 
 # map interpolation strings to module constants
 _interpd_ = {
+    'antialiased': None,     # this will use nearest or Hanning if downsampled
     'none': _image.NEAREST,  # fall back to nearest when not supported
     'nearest': _image.NEAREST,
     'bilinear': _image.BILINEAR,
@@ -168,6 +169,25 @@ def _resample(
     allocating the output array and fetching the relevant properties from the
     Image object *image_obj*.
     """
+
+    # decide if we need to apply anti-aliasing if the data is upsampled:
+    # compare the number of displayed pixels to the number of
+    # the data pixels.
+    interpolation = image_obj.get_interpolation()
+    if interpolation == 'antialiased':
+        samplerate = transform.transform([A.shape[1], 0])[0] / A.shape[1]
+        # don't antialias if upsampling by an integer number or
+        # if zooming in more than a factor of 3
+        # do antialiasing....
+        # compare the number of displayed pixels to the number of
+        # the data pixels.
+        samplerate = transform.transform([A.shape[1], 0])[0] / A.shape[1]
+        if (samplerate < 3 and
+                np.abs(int(samplerate) - (samplerate)) > 0.0001):
+            interpolation = 'hanning'
+        else:
+            interpolation = 'nearest'
+
     out = np.zeros(out_shape + data.shape[2:], data.dtype)  # 2D->2D, 3D->3D.
     if resample is None:
         resample = image_obj.get_resample()
@@ -354,6 +374,20 @@ def _make_image(self, A, in_bbox, out_bbox, clip_bbox, magnification=1.0,
             out_height = int(out_height_base)
         out_shape = (out_height, out_width)
 
+        # decide if we are going to do anti-aliasing or not on the image
+        interpolation = self.get_interpolation()
+        if interpolation == 'antialiased':
+            # default
+            interpolation = 'nearest'
+            # do antialiasing....
+            # compare the number of displayed pixels to the number of
+            # the data pixels.
+            samplerate = t.transform([A.shape[1], 0])[0] / A.shape[1]
+            if (samplerate < 3 and
+                np.abs(int(samplerate) - (samplerate)) > 0.0001):
+                    # do anti-aliasing
+                    interpolation = 'hanning'
+
         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")
@@ -432,7 +466,6 @@ def _make_image(self, A, in_bbox, out_bbox, clip_bbox, magnification=1.0,
                 A_scaled += 0.1
                 # resample the input data to the correct resolution and shape
                 A_resampled = _resample(self, A_scaled, out_shape, t)
-
                 # done with A_scaled now, remove from namespace to be sure!
                 del A_scaled
                 # un-scale the resampled data to approximately the
@@ -708,9 +741,9 @@ def set_interpolation(self, s):
 
         Parameters
         ----------
-        s : {'nearest', 'bilinear', 'bicubic', 'spline16', 'spline36', \
-'hanning', 'hamming', 'hermite', 'kaiser', 'quadric', 'catrom', 'gaussian', \
-'bessel', 'mitchell', 'sinc', 'lanczos', 'none'}
+        s : {'antialiased', 'nearest', 'bilinear', 'bicubic', 'spline16',
+'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric', 'catrom', \
+'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos', 'none'}
 
         """
         if s is None:
diff --git a/lib/matplotlib/rcsetup.py b/lib/matplotlib/rcsetup.py
@@ -1100,7 +1100,7 @@ def _validate_linestyle(ls):
     'mathtext.fallback_to_cm': [True, validate_bool],
 
     'image.aspect':        ['equal', validate_aspect],  # equal, auto, a number
-    'image.interpolation': ['nearest', validate_string],
+    'image.interpolation': ['antialiased', validate_string],
     'image.cmap':          ['viridis', validate_string],  # gray, jet, etc.
     'image.lut':           [256, validate_int],  # lookup table
     'image.origin':        ['upper',
diff --git a/matplotlibrc.template b/matplotlibrc.template
@@ -557,7 +557,7 @@
 ## * IMAGES                                                                  *
 ## ***************************************************************************
 #image.aspect : equal            ## {equal, auto} or a number
-#image.interpolation  : nearest  ## see help(imshow) for options
+#image.interpolation  : antialiased  ## see help(imshow) for options
 #image.cmap   : viridis          ## A colormap name, gray etc...
 #image.lut    : 256              ## the size of the colormap lookup table
 #image.origin : upper            ## {lower, upper}
