0
# Operations and Filters
1

2
Sharp provides extensive image processing operations including geometric transformations, filters, and color adjustments.
3

4
## Capabilities
5

6
### Rotation and Orientation
7

8
Rotate images and handle EXIF orientation data.
9

10
```javascript { .api }
11
/**
12
 * Rotate image by specified angle or auto-orient using EXIF data
13
 * @param angle - Rotation angle in degrees (optional)
14
 * @param options - Rotation options (optional)
15
 * @returns Sharp instance for chaining
16
 */
17
rotate(angle?: number, options?: RotateOptions): Sharp;
18

19
/**
20
 * Auto-orient based on EXIF Orientation tag (alias for rotate())
21
 * @returns Sharp instance for chaining
22
 */
23
autoOrient(): Sharp;
24

25
interface RotateOptions {
26
  /** Background color for areas outside rotated image */
27
  background?: string | RGBA;
28
}
29
```
30

31
**Usage Examples:**
32

33
```javascript
34
// Rotate by specific angle
35
await sharp('input.jpg')
36
  .rotate(90)
37
  .toFile('rotated-90.jpg');
38

39
// Rotate with custom background
40
await sharp('input.jpg')
41
  .rotate(45, { background: '#ff0000' })
42
  .toFile('rotated-45-red.jpg');
43

44
// Auto-orient using EXIF data
45
await sharp('input.jpg')
46
  .rotate()
47
  .toFile('oriented.jpg');
48

49
// Explicit auto-orient
50
await sharp('input.jpg')
51
  .autoOrient()
52
  .toFile('auto-oriented.jpg');
53
```
54

55
### Flipping and Flopping
56

57
Mirror images horizontally and vertically.
58

59
```javascript { .api }
60
/**
61
 * Flip image vertically (about Y axis)
62
 * @param flip - Enable flip (defaults to true)
63
 * @returns Sharp instance for chaining
64
 */
65
flip(flip?: boolean): Sharp;
66

67
/**
68
 * Flop image horizontally (about X axis)
69
 * @param flop - Enable flop (defaults to true)
70
 * @returns Sharp instance for chaining
71
 */
72
flop(flop?: boolean): Sharp;
73
```
74

75
**Usage Examples:**
76

77
```javascript
78
// Vertical flip
79
await sharp('input.jpg')
80
  .flip()
81
  .toFile('flipped.jpg');
82

83
// Horizontal flop
84
await sharp('input.jpg')
85
  .flop()
86
  .toFile('flopped.jpg');
87

88
// Both flip and flop
89
await sharp('input.jpg')
90
  .flip()
91
  .flop()
92
  .toFile('flipped-flopped.jpg');
93
```
94

95
### Affine Transformations
96

97
Apply custom transformation matrices.
98

99
```javascript { .api }
100
/**
101
 * Apply affine transformation matrix
102
 * @param matrix - 2x2 transformation matrix or array of 4 numbers
103
 * @param options - Transformation options
104
 * @returns Sharp instance for chaining
105
 */
106
affine(matrix: [number, number, number, number] | Matrix2x2, options?: AffineOptions): Sharp;
107

108
type Matrix2x2 = [[number, number], [number, number]];
109

110
interface AffineOptions {
111
  /** Background color for new pixels */
112
  background?: string | object;
113
  /** Input horizontal offset */
114
  idx?: number;
115
  /** Input vertical offset */
116
  idy?: number;
117
  /** Output horizontal offset */
118
  odx?: number;
119
  /** Output vertical offset */
120
  ody?: number;
121
  /** Interpolation method */
122
  interpolator?: keyof Interpolators;
123
}
124
```
125

126
**Usage Examples:**
127

128
```javascript
129
// Shear transformation
130
await sharp('input.jpg')
131
  .affine([1, 0.5, 0, 1])
132
  .toFile('sheared.jpg');
133

134
// Scale and rotate transformation
135
const angle = Math.PI / 4; // 45 degrees
136
const cos = Math.cos(angle);
137
const sin = Math.sin(angle);
138
await sharp('input.jpg')
139
  .affine([[cos, -sin], [sin, cos]], {
140
    background: 'white',
141
    interpolator: sharp.interpolators.bicubic
142
  })
143
  .toFile('transformed.jpg');
144
```
145

146
### Sharpening
147

148
Enhance image sharpness with fine-grained control.
149

150
```javascript { .api }
151
/**
152
 * Sharpen image with configurable parameters
153
 * @param options - Sharpening options
154
 * @returns Sharp instance for chaining
155
 */
156
sharpen(options?: SharpenOptions): Sharp;
157

158
interface SharpenOptions {
159
  /** Gaussian mask sigma (1 + radius / 2) */
160
  sigma: number;
161
  /** Sharpening level for flat areas */
162
  m1?: number;
163
  /** Sharpening level for jagged areas */
164
  m2?: number;
165
  /** Threshold between flat and jagged */
166
  x1?: number;
167
  /** Maximum brightening */
168
  y2?: number;
169
  /** Maximum darkening */
170
  y3?: number;
171
}
172
```
173

174
**Usage Examples:**
175

176
```javascript
177
// Mild sharpening
178
await sharp('input.jpg')
179
  .sharpen()
180
  .toFile('sharpened-mild.jpg');
181

182
// Custom sharpening
183
await sharp('input.jpg')
184
  .sharpen({
185
    sigma: 1.5,
186
    m1: 1.2,
187
    m2: 2.5,
188
    x1: 3.0,
189
    y2: 15.0,
190
    y3: 25.0
191
  })
192
  .toFile('sharpened-custom.jpg');
193
```
194

195
### Blurring
196

197
Apply Gaussian blur with precision controls.
198

199
```javascript { .api }
200
/**
201
 * Blur image using Gaussian convolution
202
 * @param sigma - Blur amount or blur options
203
 * @returns Sharp instance for chaining
204
 */
205
blur(sigma?: number | boolean | BlurOptions): Sharp;
206

207
interface BlurOptions {
208
  /** Gaussian mask sigma (0.3-1000) */
209
  sigma: number;
210
  /** Minimum amplitude for mask accuracy */
211
  minAmplitude?: number;
212
  /** Operation precision */
213
  precision?: 'integer' | 'float' | 'approximate';
214
}
215
```
216

217
**Usage Examples:**
218

219
```javascript
220
// Mild blur
221
await sharp('input.jpg')
222
  .blur()
223
  .toFile('blurred-mild.jpg');
224

225
// Custom blur strength
226
await sharp('input.jpg')
227
  .blur(5.0)
228
  .toFile('blurred-medium.jpg');
229

230
// High-precision blur
231
await sharp('input.jpg')
232
  .blur({
233
    sigma: 3.0,
234
    precision: 'float'
235
  })
236
  .toFile('blurred-precise.jpg');
237
```
238

239
### Median Filtering
240

241
Reduce noise using median filter.
242

243
```javascript { .api }
244
/**
245
 * Apply median filter for noise reduction
246
 * @param size - Filter mask size (defaults to 3)
247
 * @returns Sharp instance for chaining
248
 */
249
median(size?: number): Sharp;
250
```
251

252
**Usage Example:**
253

254
```javascript
255
// Noise reduction
256
await sharp('noisy-input.jpg')
257
  .median(5)
258
  .toFile('denoised.jpg');
259
```
260

261
### Morphological Operations
262

263
Expand or shrink foreground objects.
264

265
```javascript { .api }
266
/**
267
 * Expand foreground objects (morphological dilation)
268
 * @param width - Dilation width in pixels (defaults to 1)
269
 * @returns Sharp instance for chaining
270
 */
271
dilate(width?: number): Sharp;
272

273
/**
274
 * Shrink foreground objects (morphological erosion)
275
 * @param width - Erosion width in pixels (defaults to 1)
276
 * @returns Sharp instance for chaining
277
 */
278
erode(width?: number): Sharp;
279
```
280

281
**Usage Examples:**
282

283
```javascript
284
// Expand white areas
285
await sharp('binary-input.png')
286
  .dilate(3)
287
  .toFile('dilated.png');
288

289
// Shrink white areas  
290
await sharp('binary-input.png')
291
  .erode(2)
292
  .toFile('eroded.png');
293

294
// Open operation (erode then dilate)
295
await sharp('binary-input.png')
296
  .erode(2)
297
  .dilate(2)
298
  .toFile('opened.png');
299
```
300

301
### Gamma Correction
302

303
Adjust image gamma for brightness perception.
304

305
```javascript { .api }
306
/**
307
 * Apply gamma correction
308
 * @param gamma - Input gamma value (1.0-3.0, defaults to 2.2)
309
 * @param gammaOut - Output gamma value (defaults to same as gamma)
310
 * @returns Sharp instance for chaining
311
 */
312
gamma(gamma?: number, gammaOut?: number): Sharp;
313
```
314

315
**Usage Examples:**
316

317
```javascript
318
// Standard gamma correction
319
await sharp('input.jpg')
320
  .gamma(2.2)
321
  .toFile('gamma-corrected.jpg');
322

323
// Custom input/output gamma
324
await sharp('input.jpg')
325
  .gamma(1.8, 2.4)
326
  .toFile('custom-gamma.jpg');
327
```
328

329
### Negation
330

331
Invert image colors.
332

333
```javascript { .api }
334
/**
335
 * Produce negative of image
336
 * @param negate - Enable negation or options object
337
 * @returns Sharp instance for chaining
338
 */
339
negate(negate?: boolean | NegateOptions): Sharp;
340

341
interface NegateOptions {
342
  /** Whether to negate alpha channel */
343
  alpha?: boolean;
344
}
345
```
346

347
**Usage Examples:**
348

349
```javascript
350
// Basic negative
351
await sharp('input.jpg')
352
  .negate()
353
  .toFile('negative.jpg');
354

355
// Negate without affecting alpha
356
await sharp('input.png')
357
  .negate({ alpha: false })
358
  .toFile('negative-preserve-alpha.png');
359
```
360

361
### Normalization
362

363
Enhance contrast by stretching luminance.
364

365
```javascript { .api }
366
/**
367
 * Normalize image contrast
368
 * @param options - Normalization options
369
 * @returns Sharp instance for chaining
370
 */
371
normalise(options?: NormaliseOptions): Sharp;
372

373
// Alternative spelling
374
normalize(options?: NormaliseOptions): Sharp;
375

376
interface NormaliseOptions {
377
  /** Lower percentile for underexposure clipping */
378
  lower?: number;
379
  /** Upper percentile for overexposure clipping */
380
  upper?: number;
381
}
382
```
383

384
**Usage Examples:**
385

386
```javascript
387
// Default normalization (1%-99%)
388
await sharp('low-contrast.jpg')
389
  .normalise()
390
  .toFile('normalized.jpg');
391

392
// Custom percentiles
393
await sharp('low-contrast.jpg')
394
  .normalize({
395
    lower: 2,
396
    upper: 98
397
  })
398
  .toFile('custom-normalized.jpg');
399
```
400

401
### CLAHE (Contrast Limited Adaptive Histogram Equalization)
402

403
Enhance local contrast while preventing over-amplification.
404

405
```javascript { .api }
406
/**
407
 * Apply Contrast Limited Adaptive Histogram Equalization
408
 * @param options - CLAHE parameters
409
 * @returns Sharp instance for chaining
410
 */
411
clahe(options: ClaheOptions): Sharp;
412

413
interface ClaheOptions {
414
  /** Region width for local histogram */
415
  width: number;
416
  /** Region height for local histogram */
417
  height: number;
418
  /** Maximum contrast amplification (0-100) */
419
  maxSlope?: number;
420
}
421
```
422

423
**Usage Example:**
424

425
```javascript
426
// Enhance local contrast
427
await sharp('low-contrast.jpg')
428
  .clahe({
429
    width: 64,
430
    height: 64,
431
    maxSlope: 3
432
  })
433
  .toFile('clahe-enhanced.jpg');
434
```
435

436
### Linear Adjustment
437

438
Apply linear levels adjustment.
439

440
```javascript { .api }
441
/**
442
 * Apply linear formula: a * input + b
443
 * @param a - Multiplier (defaults to 1.0)
444
 * @param b - Offset (defaults to 0.0)
445
 * @returns Sharp instance for chaining
446
 */
447
linear(a?: number | number[], b?: number | number[]): Sharp;
448
```
449

450
**Usage Examples:**
451

452
```javascript
453
// Increase brightness
454
await sharp('input.jpg')
455
  .linear(1.0, 50)
456
  .toFile('brighter.jpg');
457

458
// Increase contrast
459
await sharp('input.jpg')
460
  .linear(1.5, 0)
461
  .toFile('higher-contrast.jpg');
462

463
// Per-channel adjustment
464
await sharp('input.jpg')
465
  .linear([1.2, 1.0, 0.8], [10, -5, 20])
466
  .toFile('channel-adjusted.jpg');
467
```
468

469
### Modulation
470

471
Adjust brightness, saturation, hue, and lightness.
472

473
```javascript { .api }
474
/**
475
 * Modulate image brightness, saturation, hue, and lightness
476
 * @param options - Modulation parameters
477
 * @returns Sharp instance for chaining
478
 */
479
modulate(options?: ModulateOptions): Sharp;
480

481
interface ModulateOptions {
482
  /** Brightness multiplier */
483
  brightness?: number;
484
  /** Saturation multiplier */
485
  saturation?: number;
486
  /** Hue rotation in degrees */
487
  hue?: number;
488
  /** Lightness adjustment */
489
  lightness?: number;
490
}
491
```
492

493
**Usage Examples:**
494

495
```javascript
496
// Increase brightness and saturation
497
await sharp('input.jpg')
498
  .modulate({
499
    brightness: 1.2,
500
    saturation: 1.3
501
  })
502
  .toFile('enhanced.jpg');
503

504
// Hue shift
505
await sharp('input.jpg')
506
  .modulate({
507
    hue: 45
508
  })
509
  .toFile('hue-shifted.jpg');
510

511
// Combined adjustments
512
await sharp('input.jpg')
513
  .modulate({
514
    brightness: 1.1,
515
    saturation: 0.9,
516
    hue: -15,
517
    lightness: 5
518
  })
519
  .toFile('color-graded.jpg');
520
```
521

522
### Advanced Operations
523

524
#### Convolution
525

526
Apply custom convolution kernels.
527

528
```javascript { .api }
529
/**
530
 * Apply custom convolution kernel
531
 * @param kernel - Convolution kernel definition
532
 * @returns Sharp instance for chaining
533
 */
534
convolve(kernel: Kernel): Sharp;
535

536
interface Kernel {
537
  /** Kernel width in pixels */
538
  width: number;
539
  /** Kernel height in pixels */
540
  height: number;
541
  /** Kernel values array (length: width * height) */
542
  kernel: number[];
543
  /** Kernel scale (defaults to sum of kernel values) */
544
  scale?: number;
545
  /** Kernel offset (defaults to 0) */
546
  offset?: number;
547
}
548
```
549

550
**Usage Example:**
551

552
```javascript
553
// Edge detection kernel
554
await sharp('input.jpg')
555
  .convolve({
556
    width: 3,
557
    height: 3,
558
    kernel: [
559
      -1, -1, -1,
560
      -1,  8, -1,
561
      -1, -1, -1
562
    ]
563
  })
564
  .toFile('edges.jpg');
565
```
566

567
#### Thresholding
568

569
Convert to binary image based on threshold.
570

571
```javascript { .api }
572
/**
573
 * Apply threshold to create binary image
574
 * @param threshold - Threshold value (0-255, defaults to 128)
575
 * @param options - Threshold options
576
 * @returns Sharp instance for chaining
577
 */
578
threshold(threshold?: number, options?: ThresholdOptions): Sharp;
579

580
interface ThresholdOptions {
581
  /** Convert to single channel greyscale */
582
  greyscale?: boolean;
583
  /** Alternative spelling of greyscale */
584
  grayscale?: boolean;
585
}
586
```
587

588
#### Matrix Recombination
589

590
Recombine image channels using transformation matrix.
591

592
```javascript { .api }
593
/**
594
 * Recombine image channels using matrix
595
 * @param matrix - 3x3 or 4x4 recombination matrix
596
 * @returns Sharp instance for chaining
597
 */
598
recomb(matrix: Matrix3x3 | Matrix4x4): Sharp;
599

600
type Matrix3x3 = [[number, number, number], [number, number, number], [number, number, number]];
601
type Matrix4x4 = [[number, number, number, number], [number, number, number, number], [number, number, number, number], [number, number, number, number]];
602
```
603

604
**Usage Example:**
605

606
```javascript
607
// Custom color mixing
608
await sharp('input.jpg')
609
  .recomb([
610
    [0.3588, 0.7044, 0.1368],
611
    [0.2990, 0.5870, 0.1140],
612
    [0.2392, 0.4696, 0.0912]
613
  ])
614
  .toFile('custom-mixed.jpg');
615
```