Image Statistics

class Stat:
    def __init__(self, image_or_list: Image.Image | list[int], mask: Image.Image | None = None) -> None:
        """
        Calculate statistics for the given image or histogram data.

        Parameters:
        - image_or_list: PIL Image object or pre-calculated histogram list
        - mask: Optional mask image to limit analysis to specific regions

        Note:
        For PIL images, calculations use the histogram() method with 256 bins
        per channel. For modes I and F, values are clamped to 0-255 range.
        """

class Stat:
    @property
    def mean(self) -> list[float]:
        """
        Average (arithmetic mean) pixel level for each band.
        
        Returns:
        list[float]: Mean values for each band
        """

    @property
    def median(self) -> list[int]:
        """
        Median pixel level for each band.
        
        Returns:
        list[int]: Median values for each band
        """

class Stat:
    @property
    def extrema(self) -> list[tuple[int, int]]:
        """
        Min/max values for each band in the image.
        
        Returns:
        list[tuple[int, int]]: List of (min, max) tuples for each band
        
        Note:
        Based on histogram bins (0-255). For accurate extrema in I/F modes,
        use Image.getextrema() instead.
        """

class Stat:
    @property
    def var(self) -> list[float]:
        """
        Variance for each band in the image.
        
        Returns:
        list[float]: Variance values for each band
        """

    @property
    def stddev(self) -> list[float]:
        """
        Standard deviation for each band in the image.
        
        Returns:
        list[float]: Standard deviation values for each band
        """

    @property
    def rms(self) -> list[float]:
        """
        RMS (root-mean-square) for each band in the image.
        
        Returns:
        list[float]: RMS values for each band
        """

class Stat:
    @property
    def count(self) -> list[int]:
        """
        Total number of pixels for each band in the image.
        
        Returns:
        list[int]: Pixel counts for each band
        """

    @property
    def sum(self) -> list[float]:
        """
        Sum of all pixels for each band in the image.
        
        Returns:
        list[float]: Sum values for each band
        """

    @property
    def sum2(self) -> list[float]:
        """
        Squared sum of all pixels for each band in the image.
        
        Returns:
        list[float]: Sum of squares for each band
        """

from PIL import Image, ImageStat

# Load an image
image = Image.open("example.jpg")

# Calculate basic statistics
stats = ImageStat.Stat(image)

# Get mean values for each band
mean_values = stats.mean        # [120.5, 115.2, 108.7] for RGB

# Get extrema (min/max) for each band
extrema = stats.extrema         # [(0, 255), (5, 250), (10, 245)]

# Get variability measures
variance = stats.var            # Variance for each band
std_dev = stats.stddev          # Standard deviation
rms = stats.rms                 # Root-mean-square

# Get central tendencies
median_vals = stats.median      # Median values
pixel_counts = stats.count      # Total pixels per band

# Use with a mask to analyze specific regions
mask = Image.new("L", image.size, 0)
# ... create mask regions ...
masked_stats = ImageStat.Stat(image, mask)
masked_mean = masked_stats.mean

# Analyze pre-calculated histogram
histogram = image.histogram()
hist_stats = ImageStat.Stat(histogram)

# For grayscale analysis
gray_image = image.convert("L")
gray_stats = ImageStat.Stat(gray_image)
brightness = gray_stats.mean[0]    # Overall brightness
contrast = gray_stats.stddev[0]    # Contrast measure