sharp/docs/api-operation.md

<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

## rotate

Rotate the output image by either an explicit angle
or auto-orient based on the EXIF `Orientation` tag.

If an angle is provided, it is converted to a valid positive degree rotation.
For example, `-450` will produce a 270deg rotation.

When rotating by an angle other than a multiple of 90,
the background colour can be provided with the `background` option.

If no angle is provided, it is determined from the EXIF data.
Mirroring is supported and may infer the use of a flip operation.

The use of `rotate` implies the removal of the EXIF `Orientation` tag, if any.

Method order is important when both rotating and extracting regions,
for example `rotate(x).extract(y)` will produce a different result to `extract(y).rotate(x)`.

### Parameters

*   `angle` **[number][1]** angle of rotation. (optional, default `auto`)
*   `options` **[Object][2]?** if present, is an Object with optional attributes.

    *   `options.background` **([string][3] | [Object][2])** parsed by the [color][4] module to extract values for red, green, blue and alpha. (optional, default `"#000000"`)

### Examples

```javascript
const pipeline = sharp()
  .rotate()
  .resize(null, 200)
  .toBuffer(function (err, outputBuffer, info) {
    // outputBuffer contains 200px high JPEG image data,
    // auto-rotated using EXIF Orientation tag
    // info.width and info.height contain the dimensions of the resized image
  });
readableStream.pipe(pipeline);
```

*   Throws **[Error][5]** Invalid parameters

Returns **Sharp** 

## flip

Flip the image about the vertical Y axis. This always occurs after rotation, if any.
The use of `flip` implies the removal of the EXIF `Orientation` tag, if any.

### Parameters

*   `flip` **[Boolean][6]**  (optional, default `true`)

### Examples

```javascript
const output = await sharp(input).flip().toBuffer();
```

Returns **Sharp** 

## flop

Flop the image about the horizontal X axis. This always occurs after rotation, if any.
The use of `flop` implies the removal of the EXIF `Orientation` tag, if any.

### Parameters

*   `flop` **[Boolean][6]**  (optional, default `true`)

### Examples

```javascript
const output = await sharp(input).flop().toBuffer();
```

Returns **Sharp** 

## affine

Perform an affine transform on an image. This operation will always occur after resizing, extraction and rotation, if any.

You must provide an array of length 4 or a 2x2 affine transformation matrix.
By default, new pixels are filled with a black background. You can provide a background color with the `background` option.
A particular interpolator may also be specified. Set the `interpolator` option to an attribute of the `sharp.interpolator` Object e.g. `sharp.interpolator.nohalo`.

In the case of a 2x2 matrix, the transform is:

*   X = `matrix[0, 0]` \* (x + `idx`) + `matrix[0, 1]` \* (y + `idy`) + `odx`
*   Y = `matrix[1, 0]` \* (x + `idx`) + `matrix[1, 1]` \* (y + `idy`) + `ody`

where:

*   x and y are the coordinates in input image.
*   X and Y are the coordinates in output image.
*   (0,0) is the upper left corner.

### Parameters

*   `matrix` **([Array][7]<[Array][7]<[number][1]>> | [Array][7]<[number][1]>)** affine transformation matrix
*   `options` **[Object][2]?** if present, is an Object with optional attributes.

    *   `options.background` **([String][3] | [Object][2])** parsed by the [color][4] module to extract values for red, green, blue and alpha. (optional, default `"#000000"`)
    *   `options.idx` **[Number][1]** input horizontal offset (optional, default `0`)
    *   `options.idy` **[Number][1]** input vertical offset (optional, default `0`)
    *   `options.odx` **[Number][1]** output horizontal offset (optional, default `0`)
    *   `options.ody` **[Number][1]** output vertical offset (optional, default `0`)
    *   `options.interpolator` **[String][3]** interpolator (optional, default `sharp.interpolators.bicubic`)

### Examples

```javascript
const pipeline = sharp()
  .affine([[1, 0.3], [0.1, 0.7]], {
     background: 'white',
     interpolate: sharp.interpolators.nohalo
  })
  .toBuffer((err, outputBuffer, info) => {
     // outputBuffer contains the transformed image
     // info.width and info.height contain the new dimensions
  });

inputStream
  .pipe(pipeline);
```

*   Throws **[Error][5]** Invalid parameters

Returns **Sharp** 

**Meta**

*   **since**: 0.27.0

## sharpen

Sharpen the image.
When used without parameters, performs a fast, mild sharpen of the output image.
When a `sigma` is provided, performs a slower, more accurate sharpen of the L channel in the LAB colour space.
Separate control over the level of sharpening in "flat" and "jagged" areas is available.

See [libvips sharpen][8] operation.

### Parameters

*   `options` **([Object][2] | [number][1])?** if present, is an Object with attributes or (deprecated) a number for `options.sigma`.

    *   `options.sigma` **[number][1]?** the sigma of the Gaussian mask, where `sigma = 1 + radius / 2`.
    *   `options.m1` **[number][1]** the level of sharpening to apply to "flat" areas. (optional, default `1.0`)
    *   `options.m2` **[number][1]** the level of sharpening to apply to "jagged" areas. (optional, default `2.0`)
    *   `options.x1` **[number][1]** threshold between "flat" and "jagged" (optional, default `2.0`)
    *   `options.y2` **[number][1]** maximum amount of brightening. (optional, default `10.0`)
    *   `options.y3` **[number][1]** maximum amount of darkening. (optional, default `20.0`)
*   `flat` **[number][1]?** (deprecated) see `options.m1`.
*   `jagged` **[number][1]?** (deprecated) see `options.m2`.

### Examples

```javascript
const data = await sharp(input).sharpen().toBuffer();
```

```javascript
const data = await sharp(input).sharpen({ sigma: 2 }).toBuffer();
```

```javascript
const data = await sharp(input)
  .sharpen({
    sigma: 2,
    m1: 0,
    m2: 3,
    x1: 3,
    y2: 15,
    y3: 15,
  })
  .toBuffer();
```

*   Throws **[Error][5]** Invalid parameters

Returns **Sharp** 

## median

Apply median filter.
When used without parameters the default window is 3x3.

### Parameters

*   `size` **[number][1]** square mask size: size x size (optional, default `3`)

### Examples

```javascript
const output = await sharp(input).median().toBuffer();
```

```javascript
const output = await sharp(input).median(5).toBuffer();
```

*   Throws **[Error][5]** Invalid parameters

Returns **Sharp** 

## blur

Blur the image.

When used without parameters, performs a fast 3x3 box blur (equivalent to a box linear filter).

When a `sigma` is provided, performs a slower, more accurate Gaussian blur.

### Parameters

*   `sigma` **[number][1]?** a value between 0.3 and 1000 representing the sigma of the Gaussian mask, where `sigma = 1 + radius / 2`.

### Examples

```javascript
const boxBlurred = await sharp(input)
  .blur()
  .toBuffer();
```

```javascript
const gaussianBlurred = await sharp(input)
  .blur(5)
  .toBuffer();
```

*   Throws **[Error][5]** Invalid parameters

Returns **Sharp** 

## flatten

Merge alpha transparency channel, if any, with a background, then remove the alpha channel.

See also [removeAlpha][9].

### Parameters

*   `options` **[Object][2]?** 

    *   `options.background` **([string][3] | [Object][2])** background colour, parsed by the [color][4] module, defaults to black. (optional, default `{r:0,g:0,b:0}`)

### Examples

```javascript
await sharp(rgbaInput)
  .flatten({ background: '#F0A703' })
  .toBuffer();
```

Returns **Sharp** 

## gamma

Apply a gamma correction by reducing the encoding (darken) pre-resize at a factor of `1/gamma`
then increasing the encoding (brighten) post-resize at a factor of `gamma`.
This can improve the perceived brightness of a resized image in non-linear colour spaces.
JPEG and WebP input images will not take advantage of the shrink-on-load performance optimisation
when applying a gamma correction.

Supply a second argument to use a different output gamma value, otherwise the first value is used in both cases.

### Parameters

*   `gamma` **[number][1]** value between 1.0 and 3.0. (optional, default `2.2`)
*   `gammaOut` **[number][1]?** value between 1.0 and 3.0. (optional, defaults to same as `gamma`)

<!---->

*   Throws **[Error][5]** Invalid parameters

Returns **Sharp** 

## negate

Produce the "negative" of the image.

### Parameters

*   `options` **[Object][2]?** 

    *   `options.alpha` **[Boolean][6]** Whether or not to negate any alpha channel (optional, default `true`)

### Examples

```javascript
const output = await sharp(input)
  .negate()
  .toBuffer();
```

```javascript
const output = await sharp(input)
  .negate({ alpha: false })
  .toBuffer();
```

Returns **Sharp** 

## normalise

Enhance output image contrast by stretching its luminance to cover the full dynamic range.

### Parameters

*   `normalise` **[Boolean][6]**  (optional, default `true`)

### Examples

```javascript
const output = await sharp(input).normalise().toBuffer();
```

Returns **Sharp** 

## normalize

Alternative spelling of normalise.

### Parameters

*   `normalize` **[Boolean][6]**  (optional, default `true`)

### Examples

```javascript
const output = await sharp(input).normalize().toBuffer();
```

Returns **Sharp** 

## clahe

Perform contrast limiting adaptive histogram equalization
[CLAHE][10].

This will, in general, enhance the clarity of the image by bringing out darker details.

### Parameters

*   `options` **[Object][2]** 

    *   `options.width` **[number][1]** integer width of the region in pixels.
    *   `options.height` **[number][1]** integer height of the region in pixels.
    *   `options.maxSlope` **[number][1]** maximum value for the slope of the
        cumulative histogram. A value of 0 disables contrast limiting. Valid values
        are integers in the range 0-100 (inclusive) (optional, default `3`)

### Examples

```javascript
const output = await sharp(input)
  .clahe({
    width: 3,
    height: 3,
  })
  .toBuffer();
```

*   Throws **[Error][5]** Invalid parameters

Returns **Sharp** 

**Meta**

*   **since**: 0.28.3

## convolve

Convolve the image with the specified kernel.

### Parameters

*   `kernel` **[Object][2]** 

    *   `kernel.width` **[number][1]** width of the kernel in pixels.
    *   `kernel.height` **[number][1]** height of the kernel in pixels.
    *   `kernel.kernel` **[Array][7]<[number][1]>** Array of length `width*height` containing the kernel values.
    *   `kernel.scale` **[number][1]** the scale of the kernel in pixels. (optional, default `sum`)
    *   `kernel.offset` **[number][1]** the offset of the kernel in pixels. (optional, default `0`)

### Examples

```javascript
sharp(input)
  .convolve({
    width: 3,
    height: 3,
    kernel: [-1, 0, 1, -2, 0, 2, -1, 0, 1]
  })
  .raw()
  .toBuffer(function(err, data, info) {
    // data contains the raw pixel data representing the convolution
    // of the input image with the horizontal Sobel operator
  });
```

*   Throws **[Error][5]** Invalid parameters

Returns **Sharp** 

## threshold

Any pixel value greater than or equal to the threshold value will be set to 255, otherwise it will be set to 0.

### Parameters

*   `threshold` **[number][1]** a value in the range 0-255 representing the level at which the threshold will be applied. (optional, default `128`)
*   `options` **[Object][2]?** 

    *   `options.greyscale` **[Boolean][6]** convert to single channel greyscale. (optional, default `true`)
    *   `options.grayscale` **[Boolean][6]** alternative spelling for greyscale. (optional, default `true`)

<!---->

*   Throws **[Error][5]** Invalid parameters

Returns **Sharp** 

## boolean

Perform a bitwise boolean operation with operand image.

This operation creates an output image where each pixel is the result of
the selected bitwise boolean `operation` between the corresponding pixels of the input images.

### Parameters

*   `operand` **([Buffer][11] | [string][3])** Buffer containing image data or string containing the path to an image file.
*   `operator` **[string][3]** one of `and`, `or` or `eor` to perform that bitwise operation, like the C logic operators `&`, `|` and `^` respectively.
*   `options` **[Object][2]?** 

    *   `options.raw` **[Object][2]?** describes operand when using raw pixel data.

        *   `options.raw.width` **[number][1]?** 
        *   `options.raw.height` **[number][1]?** 
        *   `options.raw.channels` **[number][1]?** 

<!---->

*   Throws **[Error][5]** Invalid parameters

Returns **Sharp** 

## linear

Apply the linear formula a \* input + b to the image (levels adjustment)

### Parameters

*   `a` **[number][1]** multiplier (optional, default `1.0`)
*   `b` **[number][1]** offset (optional, default `0.0`)

<!---->

*   Throws **[Error][5]** Invalid parameters

Returns **Sharp** 

## recomb

Recomb the image with the specified matrix.

### Parameters

*   `inputMatrix` **[Array][7]<[Array][7]<[number][1]>>** 3x3 Recombination matrix

### Examples

```javascript
sharp(input)
  .recomb([
   [0.3588, 0.7044, 0.1368],
   [0.2990, 0.5870, 0.1140],
   [0.2392, 0.4696, 0.0912],
  ])
  .raw()
  .toBuffer(function(err, data, info) {
    // data contains the raw pixel data after applying the recomb
    // With this example input, a sepia filter has been applied
  });
```

*   Throws **[Error][5]** Invalid parameters

Returns **Sharp** 

**Meta**

*   **since**: 0.21.1

## modulate

Transforms the image using brightness, saturation, hue rotation, and lightness.
Brightness and lightness both operate on luminance, with the difference being that
brightness is multiplicative whereas lightness is additive.

### Parameters

*   `options` **[Object][2]?** 

    *   `options.brightness` **[number][1]?** Brightness multiplier
    *   `options.saturation` **[number][1]?** Saturation multiplier
    *   `options.hue` **[number][1]?** Degrees for hue rotation
    *   `options.lightness` **[number][1]?** Lightness addend

### Examples

```javascript
// increase brightness by a factor of 2
const output = await sharp(input)
  .modulate({
    brightness: 2
  })
  .toBuffer();
```

```javascript
// hue-rotate by 180 degrees
const output = await sharp(input)
  .modulate({
    hue: 180
  })
  .toBuffer();
```

```javascript
// increase lightness by +50
const output = await sharp(input)
  .modulate({
    lightness: 50
  })
  .toBuffer();
```

```javascript
// decreate brightness and saturation while also hue-rotating by 90 degrees
const output = await sharp(input)
  .modulate({
    brightness: 0.5,
    saturation: 0.5,
    hue: 90,
  })
  .toBuffer();
```

Returns **Sharp** 

**Meta**

*   **since**: 0.22.1

[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number

[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object

[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String

[4]: https://www.npmjs.org/package/color

[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error

[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean

[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array

[8]: https://www.libvips.org/API/current/libvips-convolution.html#vips-sharpen

[9]: /api-channel#removealpha

[10]: https://en.wikipedia.org/wiki/Adaptive_histogram_equalization#Contrast_Limited_AHE

[11]: https://nodejs.org/api/buffer.html