Clip invalid values in RGB imshow to bounds

Zac-HD · Zac-HD · commit bdb5be1c6572 · 2018-01-11T00:46:08.000+11:00
diff --git a/doc/users/next_whats_new/2018_01_11_imshow-rgb-scaling-clipping.rst b/doc/users/next_whats_new/2018_01_11_imshow-rgb-scaling-clipping.rst
@@ -4,3 +4,7 @@
 `Axes.imshow` can now apply the ``norm`` or ``vmin`` and ``vmax`` arguments
 to RGB images, allowing easy display of high-bit-depth data, or adjustments
 of brightness and contrast.
+
+Out-of-range values in un-normalised RGB and RGBA images are now clipped to
+the nearest bound, rather than being wrapped.  This bug often hid outliers,
+and could make interpretation of the plotted image entirely unreliable.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -5237,7 +5237,7 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
             Elements of RGB and RGBA arrays represent pixels of an MxN image.
             All values - unless normalised with `norm` or `vmin` and `vmax` -
             should be in the range [0 .. 1] for floats or [0 .. 255] for
-            integers.
+            integers.  Out-of-range values will be clipped to these bounds.
 
         cmap : `~matplotlib.colors.Colormap`, optional, default: None
             If None, default to rc `image.cmap` value. `cmap` is ignored
@@ -5362,6 +5362,20 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
                 # Disable later styling based on these values
                 norm, vmin, vmax = None, None, None
 
+            # If the input data has values outside the valid range (after
+            # normalisation), we issue a warning and then clip X to the bounds
+            # - otherwise casting wraps extreme values, hiding outliers and
+            # making reliable interpretation impossible.
+            high_bound = 255 if np.issubdtype(X.dtype, np.integer) else 1
+            if X.min() < 0 or high_bound < X.max():
+                warnings.warn(
+                    'Clipping input data to the valid range for imshow with '
+                    'RGB data ([0..1] for floats or [0..255] for integers).  '
+                    'Pass the `norm`, `vmin`, or `vmax` arguments to avoid '
+                    'this error.'
+                )
+                X = np.clip(X, 0, high_bound)
+
         im = mimage.AxesImage(self, cmap, norm, interpolation, origin, extent,
                               filternorm=filternorm, filterrad=filterrad,
                               resample=resample, **kwargs)
