0
# Mathematical Operations
1

2
Pixel-level mathematical operations between images including blending, compositing, arithmetic operations, and logical operations for advanced image processing workflows.
3

4
## Capabilities
5

6
### Arithmetic Operations
7

8
```python { .api }
9
def add(image1, image2, scale=1.0, offset=0):
10
    """
11
    Add two images with optional scaling and offset.
12

13
    Parameters:
14
    - image1 (Image): First image
15
    - image2 (Image): Second image  
16
    - scale (float): Scale factor for result
17
    - offset (int): Offset added to result
18

19
    Returns:
20
    Image: Result image
21
    """
22

23
def subtract(image1, image2, scale=1.0, offset=0):
24
    """
25
    Subtract second image from first.
26

27
    Parameters:
28
    - image1 (Image): First image
29
    - image2 (Image): Second image
30
    - scale (float): Scale factor for result
31
    - offset (int): Offset added to result
32

33
    Returns:
34
    Image: Result image
35
    """
36

37
def multiply(image1, image2):
38
    """
39
    Multiply two images.
40

41
    Parameters:
42
    - image1 (Image): First image
43
    - image2 (Image): Second image
44

45
    Returns:  
46
    Image: Result image
47
    """
48
```
49

50
### Blending Operations
51

52
```python { .api }
53
def blend(image1, image2, alpha):
54
    """
55
    Blend two images using alpha transparency.
56

57
    Parameters:
58
    - image1 (Image): First image
59
    - image2 (Image): Second image
60
    - alpha (float): Blend factor (0.0-1.0)
61

62
    Returns:
63
    Image: Blended image
64
    """
65

66
def composite(image1, image2, mask):
67
    """
68
    Composite two images using a mask.
69

70
    Parameters:
71
    - image1 (Image): Background image
72
    - image2 (Image): Foreground image
73
    - mask (Image): Mask image
74

75
    Returns:
76
    Image: Composite image
77
    """
78
```
79

80
### Comparison Operations
81

82
```python { .api }
83
def difference(image1, image2):
84
    """
85
    Calculate absolute difference between images.
86

87
    Parameters:
88
    - image1 (Image): First image
89
    - image2 (Image): Second image
90

91
    Returns:
92
    Image: Difference image with absolute difference values
93
    """
94

95
def darker(image1, image2):
96
    """
97
    Take darker pixels from two images.
98

99
    Parameters:
100
    - image1 (Image): First image
101
    - image2 (Image): Second image
102

103
    Returns:
104
    Image: Result with darker pixels (min values)
105
    """
106

107
def lighter(image1, image2):
108
    """
109
    Take lighter pixels from two images.
110

111
    Parameters:
112
    - image1 (Image): First image
113
    - image2 (Image): Second image
114

115
    Returns:
116
    Image: Result with lighter pixels (max values)
117
    """
118
```
119

120
### Advanced Blend Modes
121

122
Photoshop-style blend modes for sophisticated image compositing.
123

124
```python { .api }
125
def screen(image1, image2):
126
    """
127
    Screen blend mode - inverted multiply effect.
128

129
    Parameters:
130
    - image1 (Image): Base image
131
    - image2 (Image): Blend image
132

133
    Returns:
134
    Image: Screen blended result
135
    """
136

137
def soft_light(image1, image2):
138
    """
139
    Soft light blend mode for subtle lighting effects.
140

141
    Parameters:
142
    - image1 (Image): Base image
143
    - image2 (Image): Blend image
144

145
    Returns:
146
    Image: Soft light blended result
147
    """
148

149
def hard_light(image1, image2):
150
    """
151
    Hard light blend mode for dramatic lighting effects.
152

153
    Parameters:
154
    - image1 (Image): Base image
155
    - image2 (Image): Blend image
156

157
    Returns:
158
    Image: Hard light blended result
159
    """
160

161
def overlay(image1, image2):
162
    """
163
    Overlay blend mode combining multiply and screen.
164

165
    Parameters:
166
    - image1 (Image): Base image
167
    - image2 (Image): Blend image
168

169
    Returns:
170
    Image: Overlay blended result
171
    """
172
```
173

174
### Modulo Arithmetic
175

176
Arithmetic operations without clipping, using modulo wrap-around.
177

178
```python { .api }
179
def add_modulo(image1, image2):
180
    """
181
    Add two images with modulo wrap-around (no clipping).
182

183
    Parameters:
184
    - image1 (Image): First image
185
    - image2 (Image): Second image
186

187
    Returns:
188
    Image: Result with modulo addition
189
    """
190

191
def subtract_modulo(image1, image2):
192
    """
193
    Subtract two images with modulo wrap-around (no clipping).
194

195
    Parameters:
196
    - image1 (Image): First image
197
    - image2 (Image): Second image
198

199
    Returns:
200
    Image: Result with modulo subtraction
201
    """
202
```
203

204
### Logical Operations
205

206
Boolean operations for binary (mode "1") images.
207

208
```python { .api }
209
def logical_and(image1, image2):
210
    """
211
    Logical AND between two binary images.
212

213
    Parameters:
214
    - image1 (Image): First binary image (mode "1")
215
    - image2 (Image): Second binary image (mode "1")
216

217
    Returns:
218
    Image: Logical AND result
219

220
    Note:
221
    Both images must be mode "1" (binary)
222
    """
223

224
def logical_or(image1, image2):
225
    """
226
    Logical OR between two binary images.
227

228
    Parameters:
229
    - image1 (Image): First binary image (mode "1")
230
    - image2 (Image): Second binary image (mode "1")
231

232
    Returns:
233
    Image: Logical OR result
234

235
    Note:
236
    Both images must be mode "1" (binary)
237
    """
238

239
def logical_xor(image1, image2):
240
    """
241
    Logical XOR between two binary images.
242

243
    Parameters:
244
    - image1 (Image): First binary image (mode "1")
245
    - image2 (Image): Second binary image (mode "1")
246

247
    Returns:
248
    Image: Logical XOR result
249

250
    Note:
251
    Both images must be mode "1" (binary)
252
    """
253
```
254

255
### Utility Operations
256

257
Basic image manipulation utilities.
258

259
```python { .api }
260
def constant(image, value):
261
    """
262
    Fill a channel with a constant gray level.
263

264
    Parameters:
265
    - image (Image): Template image for size
266
    - value (int): Gray level value (0-255)
267

268
    Returns:
269
    Image: New grayscale image filled with constant value
270
    """
271

272
def duplicate(image):
273
    """
274
    Create a copy of an image.
275

276
    Parameters:
277
    - image (Image): Source image
278

279
    Returns:
280
    Image: Copy of the source image
281
    """
282

283
def invert(image):
284
    """
285
    Invert an image (photographic negative).
286

287
    Parameters:
288
    - image (Image): Source image
289

290
    Returns:
291
    Image: Inverted image
292
    """
293

294
def offset(image, xoffset, yoffset=None):
295
    """
296
    Shift image pixels with wrap-around.
297

298
    Parameters:
299
    - image (Image): Source image
300
    - xoffset (int): Horizontal offset in pixels
301
    - yoffset (int): Vertical offset in pixels (defaults to xoffset)
302

303
    Returns:
304
    Image: Offset image with wrapped pixels
305
    """
306
```
307

308
## Usage Examples
309

310
```python
311
from PIL import Image, ImageChops
312

313
# Load two images
314
img1 = Image.open("image1.jpg")
315
img2 = Image.open("image2.jpg")
316

317
# Blend images
318
blended = ImageChops.blend(img1, img2, 0.5)
319

320
# Calculate difference
321
diff = ImageChops.difference(img1, img2)
322

323
# Add images
324
added = ImageChops.add(img1, img2, scale=0.5)
325

326
blended.save("blended.jpg")
327
diff.save("difference.jpg")
328
added.save("added.jpg")
329
```