python-pillow/Pillow
1
1
Fork 0
mirror of https://github.com/python-pillow/Pillow.git synced 2025-02-03 21:24:31 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #7952 from nulano/types-imagestat

Browse Source
This commit is contained in:
Hugo van Kemenade 2024-04-16 20:57:14 +03:00 committed by GitHub
commit 0e90c1c9ae
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 71 additions and 101 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
docs/reference/ImageStat.rst
View File

@ -7,67 +7,6 @@
The :py:mod:`~PIL.ImageStat` module calculates global statistics for an image, or The :py:mod:`~PIL.ImageStat` module calculates global statistics for an image, or
for a region of an image. for a region of an image.
.. py:class:: Stat(image_or_list, mask=None) .. autoclass:: Stat
:members:
Calculate statistics for the given image. If a mask is included, :special-members: __init__
only the regions covered by that mask are included in the
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
Min/max values for each band in the image.
.. note::
This relies on the :py:meth:`~PIL.Image.Image.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 :py:meth:`~PIL.Image.Image.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
:py:meth:`~PIL.Image.Image.getextrema` to determine the bins used.
.. py:attribute:: count
Total number of pixels for each band in the image.
.. py:attribute:: sum
Sum of all pixels for each band in the image.
.. py:attribute:: sum2
Squared sum of all pixels for each band in the image.
.. py:attribute:: mean
Average (arithmetic mean) pixel level for each band in the image.
.. py:attribute:: median
Median pixel level for each band in the image.
.. py:attribute:: rms
RMS (root-mean-square) for each band in the image.
.. py:attribute:: var
Variance for each band in the image.
.. py:attribute:: stddev
Standard deviation for each band in the image.

105
src/PIL/ImageStat.py
View File

@ -23,35 +23,58 @@
from __future__ import annotations from __future__ import annotations
import math import math
from functools import cached_property
from . import Image
class Stat: class Stat:
def __init__(self, image_or_list, mask=None): def __init__(
try: self, image_or_list: Image.Image | list[int], mask: Image.Image | None = None
if mask: ) -> None:
self.h = image_or_list.histogram(mask) """
else: Calculate statistics for the given image. If a mask is included,
self.h = image_or_list.histogram() only the regions covered by that mask are included in the
except AttributeError: statistics. You can also pass in a previously calculated histogram.
self.h = image_or_list # assume it to be a histogram list
if not isinstance(self.h, list): :param image: A PIL image, or a precalculated histogram.
msg = "first argument must be image or list"
.. 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.
"""
if isinstance(image_or_list, Image.Image):
self.h = image_or_list.histogram(mask)
elif isinstance(image_or_list, list):
self.h = image_or_list
else:
msg = "first argument must be image or list" # type: ignore[unreachable]
raise TypeError(msg) raise TypeError(msg)
self.bands = list(range(len(self.h) // 256)) self.bands = list(range(len(self.h) // 256))
def __getattr__(self, id): @cached_property
"""Calculate missing attribute""" def extrema(self) -> list[tuple[int, int]]:
if id[:4] == "_get": """
raise AttributeError(id) Min/max values for each band in the image.
# calculate missing attribute
v = getattr(self, "_get" + id)()
setattr(self, id, v)
return v
def _getextrema(self): .. note::
"""Get min/max values for each band in the image""" This relies on the :py:meth:`~PIL.Image.Image.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 :py:meth:`~PIL.Image.Image.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
:py:meth:`~PIL.Image.Image.getextrema` to determine the bins used.
"""
def minmax(histogram): def minmax(histogram: list[int]) -> tuple[int, int]:
res_min, res_max = 255, 0 res_min, res_max = 255, 0
for i in range(256): for i in range(256):
if histogram[i]: if histogram[i]:
@ -65,12 +88,14 @@ class Stat:
return [minmax(self.h[i:]) for i in range(0, len(self.h), 256)] return [minmax(self.h[i:]) for i in range(0, len(self.h), 256)]
def _getcount(self): @cached_property
"""Get total number of pixels in each layer""" def count(self) -> list[int]:
"""Total number of pixels for each band in the image."""
return [sum(self.h[i : i + 256]) for i in range(0, len(self.h), 256)] return [sum(self.h[i : i + 256]) for i in range(0, len(self.h), 256)]
def _getsum(self): @cached_property
"""Get sum of all pixels in each layer""" def sum(self) -> list[float]:
"""Sum of all pixels for each band in the image."""
v = [] v = []
for i in range(0, len(self.h), 256): for i in range(0, len(self.h), 256):
@ -80,8 +105,9 @@ class Stat:
v.append(layer_sum) v.append(layer_sum)
return v return v
def _getsum2(self): @cached_property
"""Get squared sum of all pixels in each layer""" def sum2(self) -> list[float]:
"""Squared sum of all pixels for each band in the image."""
v = [] v = []
for i in range(0, len(self.h), 256): for i in range(0, len(self.h), 256):
@ -91,12 +117,14 @@ class Stat:
v.append(sum2) v.append(sum2)
return v return v
def _getmean(self): @cached_property
"""Get average pixel level for each layer""" def mean(self) -> list[float]:
"""Average (arithmetic mean) pixel level for each band in the image."""
return [self.sum[i] / self.count[i] for i in self.bands] return [self.sum[i] / self.count[i] for i in self.bands]
def _getmedian(self): @cached_property
"""Get median pixel level for each layer""" def median(self) -> list[int]:
"""Median pixel level for each band in the image."""
v = [] v = []
for i in self.bands: for i in self.bands:
@ -110,19 +138,22 @@ class Stat:
v.append(j) v.append(j)
return v return v
def _getrms(self): @cached_property
"""Get RMS for each layer""" def rms(self) -> list[float]:
"""RMS (root-mean-square) for each band in the image."""
return [math.sqrt(self.sum2[i] / self.count[i]) for i in self.bands] return [math.sqrt(self.sum2[i] / self.count[i]) for i in self.bands]
def _getvar(self): @cached_property
"""Get variance for each layer""" def var(self) -> list[float]:
"""Variance for each band in the image."""
return [ return [
(self.sum2[i] - (self.sum[i] ** 2.0) / self.count[i]) / self.count[i] (self.sum2[i] - (self.sum[i] ** 2.0) / self.count[i]) / self.count[i]
for i in self.bands for i in self.bands
] ]
def _getstddev(self): @cached_property
"""Get standard deviation for each layer""" def stddev(self) -> list[float]:
"""Standard deviation for each band in the image."""
return [math.sqrt(self.var[i]) for i in self.bands] return [math.sqrt(self.var[i]) for i in self.bands]