Clip RGB data to vaild range in Axes.imshow

Zac-HD · Zac-HD · commit 129059406a1d · 2018-01-11T11:33:35.000+11:00
diff --git a/doc/users/credits.rst b/doc/users/credits.rst
@@ -386,6 +386,7 @@ Yu Feng,
 Yunfei Yang,
 Yuri D'Elia,
 Yuval Langer,
+Zac Hatfield-Dodds,
 Zach Pincus,
 Zair Mubashar,
 alex,
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
@@ -0,0 +1,7 @@
+`Axes.imshow` clips RGB values to the valid range
+-------------------------------------------------
+
+When `Axes.imshow` is passed an RGB or RGBA value with out-of-range
+values, it now issues a warning and clips them to the valid range.
+The old behaviour, wrapping back in to the range, often hid outliers
+and made interpreting RGB images unreliable.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -5228,10 +5228,14 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
             - MxNx3 -- RGB (float or uint8)
             - MxNx4 -- RGBA (float or uint8)
 
-            The value for each component of MxNx3 and MxNx4 float arrays
-            should be in the range 0.0 to 1.0. MxN arrays are mapped
-            to colors based on the `norm` (mapping scalar to scalar)
-            and the `cmap` (mapping the normed scalar to a color).
+            MxN arrays are mapped to colors based on the `norm` (mapping
+            scalar to scalar) and the `cmap` (mapping the normed scalar to
+            a color).
+
+            Elements of RGB and RGBA arrays represent pixels of an MxN image.
+            All values should be in the range [0 .. 1] for floats or
+            [0 .. 255] for 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
@@ -5273,7 +5277,8 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
             settings for `vmin` and `vmax` will be ignored.
 
         alpha : scalar, optional, default: None
-            The alpha blending value, between 0 (transparent) and 1 (opaque)
+            The alpha blending value, between 0 (transparent) and 1 (opaque).
+            The ``alpha`` argument is ignored for RGBA input data.
 
         origin : ['upper' | 'lower'], optional, default: None
             Place the [0,0] index of the array in the upper left or lower left
diff --git a/lib/matplotlib/cm.py b/lib/matplotlib/cm.py
@@ -259,7 +259,7 @@ def to_rgba(self, x, alpha=None, bytes=False, norm=True):
                         xx = (xx * 255).astype(np.uint8)
                 elif xx.dtype == np.uint8:
                     if not bytes:
-                        xx = xx.astype(float) / 255
+                        xx = xx.astype(np.float32) / 255
                 else:
                     raise ValueError("Image RGB array must be uint8 or "
                                      "floating point; found %s" % xx.dtype)
diff --git a/lib/matplotlib/image.py b/lib/matplotlib/image.py
@@ -13,6 +13,7 @@
 
 from math import ceil
 import os
+import warnings
 
 import numpy as np
 
@@ -610,6 +611,23 @@ def set_data(self, A):
                 or self._A.ndim == 3 and self._A.shape[-1] in [3, 4]):
             raise TypeError("Invalid dimensions for image data")
 
+        if self._A.ndim == 3:
+            # 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 = 255 if np.issubdtype(self._A.dtype, np.integer) else 1
+            if self._A.min() < 0 or high < self._A.max():
+                warnings.warn(
+                    'Clipping input data to the valid range for imshow with '
+                    'RGB data ([0..1] for floats or [0..255] for integers).'
+                )
+                self._A = np.clip(self._A, 0, high)
+            # Cast unsupported integer types to uint8
+            if self._A.dtype != np.uint8 and np.issubdtype(self._A.dtype,
+                                                           np.integer):
+                self._A = self._A.astype(np.uint8)
+
         self._imcache = None
         self._rgbacache = None
         self.stale = True
