0
# Image Statistics
1

2
Comprehensive statistical analysis capabilities for images, providing detailed metrics about pixel distributions, central tendencies, and variability across image bands.
3

4
## Capabilities
5

6
### Statistical Analysis
7

8
Calculate comprehensive statistics for images including histograms, central tendencies, and distribution measures.
9

10
```python { .api }
11
class Stat:
12
    def __init__(self, image_or_list: Image.Image | list[int], mask: Image.Image | None = None) -> None:
13
        """
14
        Calculate statistics for the given image or histogram data.
15

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

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

26
### Central Tendency Measures
27

28
Statistical measures of the central tendency of pixel values.
29

30
```python { .api }
31
class Stat:
32
    @property
33
    def mean(self) -> list[float]:
34
        """
35
        Average (arithmetic mean) pixel level for each band.
36
        
37
        Returns:
38
        list[float]: Mean values for each band
39
        """
40

41
    @property
42
    def median(self) -> list[int]:
43
        """
44
        Median pixel level for each band.
45
        
46
        Returns:
47
        list[int]: Median values for each band
48
        """
49
```
50

51
### Distribution Range
52

53
Measures of the range and extremes of pixel value distributions.
54

55
```python { .api }
56
class Stat:
57
    @property
58
    def extrema(self) -> list[tuple[int, int]]:
59
        """
60
        Min/max values for each band in the image.
61
        
62
        Returns:
63
        list[tuple[int, int]]: List of (min, max) tuples for each band
64
        
65
        Note:
66
        Based on histogram bins (0-255). For accurate extrema in I/F modes,
67
        use Image.getextrema() instead.
68
        """
69
```
70

71
### Variability Measures
72

73
Statistical measures of pixel value variability and distribution spread.
74

75
```python { .api }
76
class Stat:
77
    @property
78
    def var(self) -> list[float]:
79
        """
80
        Variance for each band in the image.
81
        
82
        Returns:
83
        list[float]: Variance values for each band
84
        """
85

86
    @property
87
    def stddev(self) -> list[float]:
88
        """
89
        Standard deviation for each band in the image.
90
        
91
        Returns:
92
        list[float]: Standard deviation values for each band
93
        """
94

95
    @property
96
    def rms(self) -> list[float]:
97
        """
98
        RMS (root-mean-square) for each band in the image.
99
        
100
        Returns:
101
        list[float]: RMS values for each band
102
        """
103
```
104

105
### Raw Statistical Data
106

107
Access to underlying statistical calculations and counts.
108

109
```python { .api }
110
class Stat:
111
    @property
112
    def count(self) -> list[int]:
113
        """
114
        Total number of pixels for each band in the image.
115
        
116
        Returns:
117
        list[int]: Pixel counts for each band
118
        """
119

120
    @property
121
    def sum(self) -> list[float]:
122
        """
123
        Sum of all pixels for each band in the image.
124
        
125
        Returns:
126
        list[float]: Sum values for each band
127
        """
128

129
    @property
130
    def sum2(self) -> list[float]:
131
        """
132
        Squared sum of all pixels for each band in the image.
133
        
134
        Returns:
135
        list[float]: Sum of squares for each band
136
        """
137
```
138

139
### Usage Examples
140

141
```python
142
from PIL import Image, ImageStat
143

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

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

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

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

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

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

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

171
# Analyze pre-calculated histogram
172
histogram = image.histogram()
173
hist_stats = ImageStat.Stat(histogram)
174

175
# For grayscale analysis
176
gray_image = image.convert("L")
177
gray_stats = ImageStat.Stat(gray_image)
178
brightness = gray_stats.mean[0]    # Overall brightness
179
contrast = gray_stats.stddev[0]    # Contrast measure
180
```
181

182
### Multi-band Analysis
183

184
For multi-band images (RGB, RGBA, CMYK, etc.), all statistical measures return lists with one value per band:
185

186
- **RGB Image**: 3 values (Red, Green, Blue)
187
- **RGBA Image**: 4 values (Red, Green, Blue, Alpha)
188
- **Grayscale (L)**: 1 value
189
- **CMYK Image**: 4 values (Cyan, Magenta, Yellow, Black)
190

191
### Performance Notes
192

193
- Statistics are calculated lazily using cached properties
194
- Calculations are based on 256-bin histograms regardless of original bit depth
195
- For high-precision analysis of 16-bit or float images, consider alternative approaches
196
- Masked statistics only include pixels where the mask is non-zero