DOC: Comment on the behavior of `histogram` for color images.

skimage/exposure/exposure.py

@@ -1,3 +1,4 @@
+import warnings
 import numpy as np
 
 from skimage import img_as_float
@@ -19,6 +20,10 @@ def histogram(image, nbins=256):
     does not rebin integer arrays. For integer arrays, each integer value has
     its own bin, which improves speed and intensity-resolution.
 
+    The histogram is computed on the flattened image: for color images, the
+    function should be used separately on each channel to obtain a histogram
+    for each color channel.
+
     Parameters
     ----------
     image : array
@@ -42,6 +47,11 @@ def histogram(image, nbins=256):
     >>> plt.plot(hist[1], hist[0])  # doctest: +ELLIPSIS
     [...]
     """
+    sh = image.shape
+    if len(sh) == 3 and sh[-1] < 4:
+        warnings.warn("This might be a color image. The histogram will be "
+                      "computed on the flattened image. You can instead "
+                      "apply this function to each color channel.")
 
     # For integer types, histogramming with bincount is more efficient.
     if np.issubdtype(image.dtype, np.integer):

skimage/exposure/tests/test_exposure.py

@@ -1,3 +1,5 @@
+import warnings
+
 import numpy as np
 from numpy.testing import assert_array_almost_equal as assert_close
 import skimage
@@ -112,6 +114,10 @@ def test_adapthist_color():
     '''Test an RGB color uint16 image
     '''
     img = skimage.img_as_uint(data.lena())
+    with warnings.catch_warnings(record=True) as w:
+        warnings.simplefilter('always')
+        hist, bin_centers = exposure.histogram(img)
+        assert len(w) > 0
     adapted = exposure.equalize_adapthist(img, clip_limit=0.01)
     assert_almost_equal = np.testing.assert_almost_equal
     assert adapted.min() == 0