Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# `ImageStat` module

The `ImageStat` module calculates global statistics for an image, or for a region of an image.

class PIL.ImageStat.Stat(image_or_list: Image | list[int], mask: Image | None = None)
  __init__(image_or_list: Image | list[int], mask: Image | None = None) → None

    Calculate statistics for the given image. If a mask is included, only the regions covered by that mask are included in the statistics. You can also pass in a previously calculated histogram.

    Parameters:

      - image –

        A PIL image, or a precalculated histogram.

        Note

        For a PIL image, calculations rely on the `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.

      - mask – An optional mask.

  property count: list[int]

    Total number of pixels for each band in the image.

  property extrema: list[tuple[int, int]]

    Min/max values for each band in the image.

    Note

    This relies on the `histogram()` method, and simply returns the low and high bins used. This is correct for images with 8 bits per channel, but fails for other modes such as `I` or `F`. Instead, use `getextrema()` to return per-band extrema for the image. This is more correct and efficient because, for non-8-bit modes, the histogram method uses `getextrema()` to determine the bins used.

  property mean: list[float]

    Average (arithmetic mean) pixel level for each band in the image.

  property median: list[int]

    Median pixel level for each band in the image.

  property rms: list[float]

    RMS (root-mean-square) for each band in the image.

  property stddev: list[float]

    Standard deviation for each band in the image.

  property sum: list[float]

    Sum of all pixels for each band in the image.

  property sum2: list[float]

    Squared sum of all pixels for each band in the image.

  property var: list[float]

    Variance for each band in the image.