0
# Color and Channels
1

2
Sharp provides comprehensive color space management and channel manipulation capabilities for professional image processing workflows.
3

4
## Capabilities
5

6
### Color Space Management
7

8
Convert between different color spaces and manage pipeline color processing.
9

10
```javascript { .api }
11
/**
12
 * Set pipeline color space for internal processing
13
 * @param colourspace - Pipeline color space identifier
14
 * @returns Sharp instance for chaining
15
 */
16
pipelineColourspace(colourspace?: string): Sharp;
17

18
/**
19
 * Alternative spelling of pipelineColourspace
20
 * @param colorspace - Pipeline color space identifier
21
 * @returns Sharp instance for chaining
22
 */
23
pipelineColorspace(colorspace?: string): Sharp;
24

25
/**
26
 * Set output color space
27
 * @param colourspace - Output color space identifier
28
 * @returns Sharp instance for chaining
29
 */
30
toColourspace(colourspace?: string): Sharp;
31

32
/**
33
 * Alternative spelling of toColourspace
34
 * @param colorspace - Output color space identifier
35
 * @returns Sharp instance for chaining
36
 */
37
toColorspace(colorspace?: string): Sharp;
38
```
39

40
**Supported Color Spaces:**
41
- `srgb` - Standard RGB (default output)
42
- `rgb` - Linear RGB
43
- `rgb16` - 16-bit RGB
44
- `scrgb` - scRGB color space
45
- `cmyk` - CMYK for print
46
- `lab` - LAB color space
47
- `lch` - LCH color space
48
- `hsv` - HSV color space
49
- `xyz` - XYZ color space
50
- `b-w` - Black and white (single channel)
51
- `grey16` - 16-bit greyscale
52
- `multiband` - Multiple bands
53

54
**Usage Examples:**
55

56
```javascript
57
// Set pipeline to work in LAB color space
58
await sharp('input.jpg')
59
  .pipelineColourspace('lab')
60
  .modulate({ lightness: 10 })
61
  .toColourspace('srgb')
62
  .toFile('lab-processed.jpg');
63

64
// Convert to CMYK for print
65
await sharp('input.jpg')
66
  .toColorspace('cmyk')
67
  .tiff()
68
  .toFile('print-ready.tiff');
69

70
// High bit depth processing
71
await sharp('input.tiff')
72
  .pipelineColorspace('rgb16')
73
  .gamma(2.2)
74
  .toColorspace('srgb')
75
  .toFile('processed-16bit.jpg');
76
```
77

78
### Color Tinting
79

80
Apply color tints to images.
81

82
```javascript { .api }
83
/**
84
 * Tint image using specified color
85
 * @param tint - Color for tinting (string or RGBA object)
86
 * @returns Sharp instance for chaining
87
 */
88
tint(tint: string | RGBA): Sharp;
89

90
interface RGBA {
91
  r?: number;
92
  g?: number;
93
  b?: number;
94
  alpha?: number;
95
}
96
```
97

98
**Usage Examples:**
99

100
```javascript
101
// Sepia tint using color string
102
await sharp('input.jpg')
103
  .tint('#704214')
104
  .toFile('sepia.jpg');
105

106
// Blue tint using RGBA object
107
await sharp('input.jpg')
108
  .tint({ r: 100, g: 150, b: 255 })
109
  .toFile('blue-tinted.jpg');
110

111
// Subtle warm tint
112
await sharp('input.jpg')
113
  .tint('rgb(255, 240, 220)')
114
  .toFile('warm-tinted.jpg');
115
```
116

117
### Greyscale Conversion
118

119
Convert images to greyscale with proper gamma handling.
120

121
```javascript { .api }
122
/**
123
 * Convert to 8-bit greyscale
124
 * @param greyscale - Enable greyscale conversion (defaults to true)
125
 * @returns Sharp instance for chaining
126
 */
127
greyscale(greyscale?: boolean): Sharp;
128

129
/**
130
 * Alternative spelling of greyscale
131
 * @param grayscale - Enable greyscale conversion (defaults to true)
132
 * @returns Sharp instance for chaining
133
 */
134
grayscale(grayscale?: boolean): Sharp;
135
```
136

137
**Usage Examples:**
138

139
```javascript
140
// Basic greyscale conversion
141
await sharp('input.jpg')
142
  .greyscale()
143
  .toFile('greyscale.jpg');
144

145
// Greyscale with gamma correction for better results
146
await sharp('input.jpg')
147
  .gamma(2.2)
148
  .greyscale()
149
  .gamma(1/2.2)
150
  .toFile('gamma-corrected-grey.jpg');
151

152
// Conditional greyscale
153
const shouldConvert = true;
154
await sharp('input.jpg')
155
  .grayscale(shouldConvert)
156
  .toFile('output.jpg');
157
```
158

159
### Alpha Channel Management
160

161
Control transparency channels in images.
162

163
```javascript { .api }
164
/**
165
 * Remove alpha channel if present
166
 * @returns Sharp instance for chaining
167
 */
168
removeAlpha(): Sharp;
169

170
/**
171
 * Ensure alpha channel exists
172
 * @param alpha - Transparency level (0-1, defaults to 1)
173
 * @returns Sharp instance for chaining
174
 */
175
ensureAlpha(alpha?: number): Sharp;
176

177
/**
178
 * Merge alpha channel with background
179
 * @param flatten - Enable flattening or options
180
 * @returns Sharp instance for chaining
181
 */
182
flatten(flatten?: boolean | FlattenOptions): Sharp;
183

184
/**
185
 * Make white pixels fully transparent
186
 * @returns Sharp instance for chaining
187
 */
188
unflatten(): Sharp;
189

190
interface FlattenOptions {
191
  /** Background color for flattening */
192
  background?: string | RGBA;
193
}
194
```
195

196
**Usage Examples:**
197

198
```javascript
199
// Remove alpha channel
200
await sharp('input.png')
201
  .removeAlpha()
202
  .jpeg()
203
  .toFile('no-alpha.jpg');
204

205
// Add alpha channel
206
await sharp('input.jpg')
207
  .ensureAlpha(0.8)
208
  .png()
209
  .toFile('semi-transparent.png');
210

211
// Flatten with custom background
212
await sharp('input.png')
213
  .flatten({ background: '#ffffff' })
214
  .jpeg()
215
  .toFile('flattened-white.jpg');
216

217
// Make white areas transparent
218
await sharp('input.jpg')
219
  .unflatten()
220
  .png()
221
  .toFile('white-transparent.png');
222
```
223

224
### Channel Extraction and Manipulation
225

226
Extract and manipulate individual color channels.
227

228
```javascript { .api }
229
/**
230
 * Extract single channel from multi-channel image
231
 * @param channel - Channel to extract (0-3 or color name)
232
 * @returns Sharp instance for chaining
233
 */
234
extractChannel(channel: 0 | 1 | 2 | 3 | 'red' | 'green' | 'blue' | 'alpha'): Sharp;
235

236
/**
237
 * Join additional channels to image
238
 * @param images - Channel images to join
239
 * @param options - Options for channel images
240
 * @returns Sharp instance for chaining
241
 */
242
joinChannel(images: string | Buffer | (string | Buffer)[], options?: SharpOptions): Sharp;
243

244
/**
245
 * Perform bitwise boolean operation on all channels
246
 * @param boolOp - Boolean operation type
247
 * @returns Sharp instance for chaining
248
 */
249
bandbool(boolOp: 'and' | 'or' | 'eor'): Sharp;
250
```
251

252
**Usage Examples:**
253

254
```javascript
255
// Extract red channel
256
await sharp('input.jpg')
257
  .extractChannel('red')
258
  .toFile('red-channel.jpg');
259

260
// Extract alpha channel
261
await sharp('input.png')
262
  .extractChannel(3)
263
  .toFile('alpha-mask.png');
264

265
// Join additional channels
266
const baseImage = sharp('rgb-input.jpg');
267
const alphaChannel = sharp('alpha-mask.png');
268

269
await baseImage
270
  .joinChannel(alphaChannel.toBuffer(), { raw: { width: 800, height: 600, channels: 1 } })
271
  .png()
272
  .toFile('rgba-output.png');
273

274
// Boolean operation across channels
275
await sharp('input.png')
276
  .bandbool('and')
277
  .toFile('channels-and.png');
278
```
279

280
### Advanced Channel Operations
281

282
Perform bitwise operations between images.
283

284
```javascript { .api }
285
/**
286
 * Perform bitwise boolean operation with operand image
287
 * @param operand - Operand image (Buffer or file path)
288
 * @param operator - Boolean operation type
289
 * @param options - Options for raw pixel data
290
 * @returns Sharp instance for chaining
291
 */
292
boolean(operand: string | Buffer, operator: 'and' | 'or' | 'eor', options?: BooleanOptions): Sharp;
293

294
interface BooleanOptions {
295
  /** Raw pixel data description */
296
  raw?: Raw;
297
}
298

299
interface Raw {
300
  width: number;
301
  height: number;
302
  channels: 1 | 2 | 3 | 4;
303
}
304
```
305

306
**Usage Examples:**
307

308
```javascript
309
// AND operation with mask
310
await sharp('input.png')
311
  .boolean('mask.png', 'and')
312
  .toFile('masked.png');
313

314
// XOR operation for difference detection
315
await sharp('image1.png')
316
  .boolean('image2.png', 'eor')
317
  .toFile('differences.png');
318

319
// OR operation for combining masks
320
await sharp('mask1.png')
321
  .boolean('mask2.png', 'or')
322
  .toFile('combined-mask.png');
323
```
324

325
## Color Constants and Utilities
326

327
Sharp provides constants for color-related operations.
328

329
```javascript { .api }
330
// Available via sharp.bool
331
interface BoolEnum {
332
  and: 'and';
333
  or: 'or';
334
  eor: 'eor';
335
}
336

337
// Available color spaces
338
interface ColourspaceEnum {
339
  'b-w': string;
340
  'cmc': string;
341
  'cmyk': string;
342
  'fourier': string;
343
  'grey16': string;
344
  'histogram': string;
345
  'hsv': string;
346
  'lab': string;
347
  'labq': string;
348
  'labs': string;
349
  'lch': string;
350
  'matrix': string;
351
  'multiband': string;
352
  'rgb': string;
353
  'rgb16': string;
354
  'scrgb': string;
355
  'srgb': string;
356
  'xyz': string;
357
  'yxy': string;
358
}
359
```
360

361
**Usage Example:**
362

363
```javascript
364
// Using boolean constants
365
await sharp('input.png')
366
  .boolean('mask.png', sharp.bool.and)
367
  .toFile('result.png');
368
```
369

370
## Color Processing Patterns
371

372
**Color Grading Workflow:**
373

374
```javascript
375
const colorGrade = async (input, output) => {
376
  await sharp(input)
377
    .pipelineColourspace('lab')
378
    .modulate({
379
      brightness: 1.05,
380
      saturation: 1.1
381
    })
382
    .linear([1.02, 0.98, 1.01], [5, -2, 8])
383
    .toColourspace('srgb')
384
    .toFile(output);
385
};
386
```
387

388
**Channel Mixing for B&W:**
389

390
```javascript
391
const customBW = async (input, output) => {
392
  await sharp(input)
393
    .recomb([
394
      [0.299, 0.587, 0.114],  // Luminance weights
395
      [0.299, 0.587, 0.114],
396
      [0.299, 0.587, 0.114]
397
    ])
398
    .toFile(output);
399
};
400
```
401

402
**Alpha Compositing:**
403

404
```javascript
405
const alphaComposite = async (base, overlay, output) => {
406
  const baseImage = sharp(base);
407
  const overlayWithAlpha = await sharp(overlay)
408
    .ensureAlpha(0.7)
409
    .toBuffer();
410
    
411
  await baseImage
412
    .composite([{
413
      input: overlayWithAlpha,
414
      blend: 'over'
415
    }])
416
    .toFile(output);
417
};
418
```
419

420
## Type Definitions
421

422
```javascript { .api }
423
type Colour = string | RGBA;
424
type Color = Colour; // Alternative spelling
425

426
interface RGBA {
427
  r?: number;
428
  g?: number;
429
  b?: number;
430
  alpha?: number;
431
}
432

433
type Channels = 1 | 2 | 3 | 4;
434
```