Merge pull request #6106 from radarhere/imagestat

Document that histogram() uses 256 bins per channel

Author: hugovk

docs/reference/ImageStat.rst

@@ -14,6 +14,16 @@ for a region of an image.
     statistics. You can also pass in a previously calculated histogram.
 
     :param image: A PIL image, or a precalculated histogram.
+
+        .. note::
+
+            For a PIL image, calculations rely on the
+            :py:meth:`~PIL.Image.Image.histogram` method. The pixel counts are
+            grouped into 256 bins, even if the image has more than 8 bits per
+            channel. So ``I`` and ``F`` mode images have a maximum ``mean``,
+            ``median`` and ``rms`` of 255, and cannot have an ``extrema`` maximum
+            of more than 255.
+
     :param mask: An optional mask.
 
     .. py:attribute:: extrema

src/PIL/Image.py

@@ -1492,11 +1492,12 @@ def getprojection(self):
 
     def histogram(self, mask=None, extrema=None):
         """
-        Returns a histogram for the image. The histogram is returned as
-        a list of pixel counts, one for each pixel value in the source
-        image. If the image has more than one band, the histograms for
-        all bands are concatenated (for example, the histogram for an
-        "RGB" image contains 768 values).
+        Returns a histogram for the image. The histogram is returned as a
+        list of pixel counts, one for each pixel value in the source
+        image. Counts are grouped into 256 bins for each band, even if
+        the image has more than 8 bits per band. If the image has more
+        than one band, the histograms for all bands are concatenated (for
+        example, the histogram for an "RGB" image contains 768 values).
 
         A bilevel image (mode "1") is treated as a greyscale ("L") image
         by this method.