0
# Image Operations
1

2
Comprehensive image processing operations including geometric transformations, filtering, color manipulation, and advanced effects. All operations support method chaining and return new Image objects, enabling efficient pipeline construction.
3

4
## Capabilities
5

6
### Geometric Transformations
7

8
Resize, rotate, and transform images with high-quality resampling and flexible options.
9

10
```python { .api }
11
def resize(self, scale: float, **kwargs) -> 'Image':
12
    """
13
    Resize image by scale factor.
14
    
15
    Parameters:
16
    - scale: float, scale factor (0.5 = half size, 2.0 = double size)
17
    - vscale: float, vertical scale factor (defaults to scale)
18
    - kernel: str, resampling kernel ('nearest', 'linear', 'cubic', 'mitchell', 'lanczos2', 'lanczos3')
19
    - centre: bool, center the image
20
    - gap: float, gap between tiles
21
    
22
    Returns:
23
    Resized Image object
24
    """
25

26
def rotate(self, angle: float, **kwargs) -> 'Image':
27
    """
28
    Rotate image by arbitrary angle.
29
    
30
    Parameters:
31
    - angle: float, rotation angle in degrees
32
    - interpolate: Interpolate, interpolation method
33
    - background: list, background color for exposed areas
34
    - odx: float, horizontal output displacement
35
    - ody: float, vertical output displacement
36
    - idx: float, horizontal input displacement  
37
    - idy: float, vertical input displacement
38
    
39
    Returns:
40
    Rotated Image object
41
    """
42

43
def affine(self, matrix: list, **kwargs) -> 'Image':
44
    """
45
    Apply affine transformation.
46
    
47
    Parameters:
48
    - matrix: list, 2x2 transformation matrix [a, b, c, d]
49
    - interpolate: Interpolate, interpolation method
50
    - oarea: list, output area [left, top, width, height]
51
    - odx: float, horizontal output displacement
52
    - ody: float, vertical output displacement
53
    - idx: float, horizontal input displacement
54
    - idy: float, vertical input displacement
55
    - background: list, background color
56
    - premultiplied: bool, images have premultiplied alpha
57
    - extend: str, edge extension method
58
    
59
    Returns:
60
    Transformed Image object
61
    """
62

63
def similarity(self, **kwargs) -> 'Image':
64
    """
65
    Apply similarity transformation (scale + rotate + translate).
66
    
67
    Parameters:
68
    - scale: float, scale factor
69
    - angle: float, rotation angle in degrees
70
    - dx: float, horizontal translation
71
    - dy: float, vertical translation
72
    - interpolate: Interpolate, interpolation method
73
    - background: list, background color
74
    - odx: float, horizontal output displacement
75
    - ody: float, vertical output displacement
76
    - idx: float, horizontal input displacement
77
    - idy: float, vertical input displacement
78
    
79
    Returns:
80
    Transformed Image object
81
    """
82
```
83

84
Example usage:
85

86
```python
87
# Basic resize
88
small = image.resize(0.5)
89
large = image.resize(2.0, kernel='lanczos3')
90

91
# Resize with different vertical scale
92
stretched = image.resize(1.0, vscale=0.5)
93

94
# Rotation
95
rotated = image.rotate(45, background=[255, 255, 255])
96

97
# Affine transformation (shear)
98
sheared = image.affine([1, 0.5, 0, 1])
99

100
# Combined scale and rotate
101
transformed = image.similarity(scale=0.8, angle=30, dx=10, dy=20)
102
```
103

104
### Image Filtering
105

106
Apply various filters for blur, sharpening, noise reduction, and artistic effects.
107

108
```python { .api }
109
def gaussblur(self, sigma: float, **kwargs) -> 'Image':
110
    """
111
    Gaussian blur filter.
112
    
113
    Parameters:
114
    - sigma: float, blur radius in pixels
115
    - min_ampl: float, minimum amplitude (default 0.2)
116
    - precision: str, computation precision ('integer', 'float', 'approximate')
117
    
118
    Returns:
119
    Blurred Image object
120
    """
121

122
def sharpen(self, **kwargs) -> 'Image':
123
    """
124
    Sharpen image with unsharp mask.
125
    
126
    Parameters:
127
    - radius: float, sharpening radius (default 1.0)
128
    - amount: float, sharpening amount (default 1.0) 
129
    - threshold: float, threshold for sharpening (default 0.05)
130
    - x1: float, flat area sharpening
131
    - y2: float, sharpening in flat areas
132
    - m1: float, sharpening slope 1
133
    - m2: float, sharpening slope 2
134
    
135
    Returns:
136
    Sharpened Image object
137
    """
138

139
def conv(self, mask: 'Image', **kwargs) -> 'Image':
140
    """
141
    Convolution with custom kernel.
142
    
143
    Parameters:
144
    - mask: Image, convolution kernel/mask
145
    - precision: str, computation precision
146
    - layers: int, number of layers in mask
147
    - cluster: int, cluster mask elements
148
    
149
    Returns:
150
    Convolved Image object
151
    """
152

153
def median(self, size: int) -> 'Image':
154
    """
155
    Median filter for noise reduction.
156
    
157
    Parameters:
158
    - size: int, filter size (must be odd)
159
    
160
    Returns:
161
    Filtered Image object
162
    """
163
```
164

165
Example usage:
166

167
```python
168
# Gaussian blur
169
blurred = image.gaussblur(2.0)
170
soft_blur = image.gaussblur(5.0, precision='approximate')
171

172
# Sharpening
173
sharp = image.sharpen()
174
very_sharp = image.sharpen(radius=2.0, amount=2.0)
175

176
# Custom convolution kernel
177
kernel = pyvips.Image.new_from_array([
178
    [-1, -1, -1],
179
    [-1,  8, -1], 
180
    [-1, -1, -1]
181
])
182
edge_detected = image.conv(kernel)
183

184
# Noise reduction
185
denoised = image.median(3)
186
```
187

188
### Color and Tone Operations
189

190
Color space conversions, tone adjustments, and color manipulation operations.
191

192
```python { .api }
193
def colourspace(self, space: str, **kwargs) -> 'Image':
194
    """
195
    Convert to different color space.
196
    
197
    Parameters:
198
    - space: str, target color space ('srgb', 'rgb', 'cmyk', 'lab', 'xyz', 'grey16', etc.)
199
    - source_space: str, source color space (auto-detected if not specified)
200
    
201
    Returns:
202
    Converted Image object
203
    """
204

205
def icc_import(self, **kwargs) -> 'Image':
206
    """
207
    Import from ICC profile.
208
    
209
    Parameters:
210
    - input_profile: str, input profile filename
211
    - pcs: str, profile connection space ('lab', 'xyz')
212
    - intent: str, rendering intent ('perceptual', 'relative', 'saturation', 'absolute')
213
    - black_point_compensation: bool, use black point compensation
214
    - embedded: bool, use embedded profile
215
    
216
    Returns:
217
    Color-corrected Image object
218
    """
219

220
def icc_export(self, **kwargs) -> 'Image':
221
    """
222
    Export with ICC profile.
223
    
224
    Parameters:
225
    - output_profile: str, output profile filename
226
    - pcs: str, profile connection space
227
    - intent: str, rendering intent
228
    - black_point_compensation: bool, use black point compensation
229
    - depth: int, output bit depth
230
    
231
    Returns:
232
    Exported Image object
233
    """
234

235
def linear(self, a: list, b: list) -> 'Image':
236
    """
237
    Apply linear transformation: out = a * in + b
238
    
239
    Parameters:
240
    - a: list, multiplication coefficients per band
241
    - b: list, addition coefficients per band
242
    
243
    Returns:
244
    Transformed Image object
245
    """
246

247
def gamma(self, **kwargs) -> 'Image':
248
    """
249
    Apply gamma correction.
250
    
251
    Parameters:
252
    - gamma: float, gamma value (default 2.4)
253
    - exponent: float, exponent for gamma curve
254
    
255
    Returns:
256
    Gamma-corrected Image object
257
    """
258
```
259

260
Example usage:
261

262
```python
263
# Color space conversion
264
srgb = image.colourspace('srgb')
265
cmyk = image.colourspace('cmyk')
266
grayscale = image.colourspace('grey16')
267

268
# ICC profile handling
269
corrected = image.icc_import(input_profile='input.icc')
270
ready_for_print = corrected.icc_export(output_profile='printer.icc')
271

272
# Linear tone adjustment
273
brightened = image.linear([1.2, 1.2, 1.2], [10, 10, 10])
274

275
# Gamma correction
276
gamma_corrected = image.gamma(gamma=2.2)
277
```
278

279
### Size and Cropping
280

281
Thumbnail generation, cropping, and smart resizing operations.
282

283
```python { .api }
284
def thumbnail_image(self, width: int, **kwargs) -> 'Image':
285
    """
286
    Generate thumbnail maintaining aspect ratio.
287
    
288
    Parameters:
289
    - width: int, maximum width in pixels
290
    - height: int, maximum height in pixels (defaults to width)
291
    - size: str, sizing behavior ('both', 'up', 'down', 'force')
292
    - no_rotate: bool, don't auto-rotate using EXIF
293
    - crop: str, crop mode ('none', 'centre', 'attention', 'entropy', 'smart')
294
    - linear: bool, reduce in linear light
295
    - import_profile: str, fallback import profile
296
    - export_profile: str, export profile
297
    - intent: str, rendering intent
298
    
299
    Returns:
300
    Thumbnail Image object
301
    """
302

303
def crop(self, left: int, top: int, width: int, height: int) -> 'Image':
304
    """
305
    Crop rectangular area from image.
306
    
307
    Parameters:
308
    - left: int, left edge of crop area
309
    - top: int, top edge of crop area  
310
    - width: int, width of crop area
311
    - height: int, height of crop area
312
    
313
    Returns:
314
    Cropped Image object
315
    """
316

317
def smartcrop(self, width: int, height: int, **kwargs) -> 'Image':
318
    """
319
    Smart crop using attention or entropy.
320
    
321
    Parameters:
322
    - width: int, target width
323
    - height: int, target height
324
    - interesting: str, area selection method ('none', 'centre', 'entropy', 'attention')
325
    - premultiplied: bool, images have premultiplied alpha
326
    
327
    Returns:
328
    Smart-cropped Image object
329
    """
330
```
331

332
Example usage:
333

334
```python
335
# Thumbnail with max width
336
thumb = image.thumbnail_image(200)
337

338
# Thumbnail with max dimensions
339
thumb = image.thumbnail_image(200, height=150)
340

341
# Smart thumbnail with cropping
342
thumb = image.thumbnail_image(200, crop='attention')
343

344
# Basic crop
345
cropped = image.crop(100, 100, 400, 300)
346

347
# Smart crop using entropy
348
smart = image.smartcrop(300, 200, interesting='entropy')
349
```
350

351
### Arithmetic and Logical Operations
352

353
Mathematical operations between images and with constants.
354

355
```python { .api }
356
def add(self, other) -> 'Image':
357
    """Add another image or constant."""
358

359
def subtract(self, other) -> 'Image':
360
    """Subtract another image or constant."""
361

362
def multiply(self, other) -> 'Image':  
363
    """Multiply by another image or constant."""
364

365
def divide(self, other) -> 'Image':
366
    """Divide by another image or constant."""
367

368
def remainder(self, other) -> 'Image':
369
    """Remainder after division."""
370

371
def relational(self, other, operation: str) -> 'Image':
372
    """
373
    Relational operation with image or constant.
374
    
375
    Parameters:
376
    - other: Image or constant
377
    - operation: str, comparison ('equal', 'noteq', 'less', 'lesseq', 'more', 'moreeq')
378
    
379
    Returns:
380
    Binary mask Image
381
    """
382

383
def boolean(self, other, operation: str) -> 'Image':
384
    """
385
    Boolean operation with image or constant.
386
    
387
    Parameters:
388
    - other: Image or constant  
389
    - operation: str, boolean op ('and', 'or', 'eor', 'lshift', 'rshift')
390
    
391
    Returns:
392
    Result Image
393
    """
394
```
395

396
Example usage:
397

398
```python
399
# Arithmetic with constants
400
brightened = image + 50
401
darkened = image - 30
402
scaled = image * 1.2
403
normalized = image / 255.0
404

405
# Arithmetic with other images
406
combined = image1 + image2
407
difference = image1 - image2
408
blended = image1 * 0.7 + image2 * 0.3
409

410
# Logical operations
411
mask = image > 128
412
result = image.boolean(mask, 'and')
413

414
# Comparisons
415
equal_mask = image1.relational(image2, 'equal')
416
```
417

418
## Operation Chaining
419

420
All operations return new Image objects, enabling efficient method chaining:
421

422
```python
423
# Chain multiple operations
424
result = (image
425
    .resize(0.8)
426
    .rotate(45)
427
    .gaussblur(1.0)
428
    .sharpen(radius=1.5)
429
    .colourspace('srgb')
430
    .linear([1.1, 1.1, 1.1], [0, 0, 0]))
431

432
# Complex processing pipeline
433
processed = (pyvips.Image.new_from_file('input.jpg')
434
    .thumbnail_image(800, crop='attention')
435
    .icc_import()
436
    .gaussblur(0.5)
437
    .sharpen()
438
    .gamma(gamma=2.2)
439
    .colourspace('srgb')
440
    .linear([1.05, 1.0, 0.95], [5, 0, -5]))
441
```
442

443
## Performance Notes
444

445
- Operations are lazy and form processing pipelines
446
- Pixel data is computed only when needed (e.g., during write operations)
447
- Sequential access is faster for large images
448
- Use `.copy_memory()` to force evaluation if needed
449
- Chain operations for maximum efficiency
450
- libvips automatically optimizes operation sequences