Image operations

rotate

rotate([angle], [options]) ⇒ Sharp

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 270 degree 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 without an angle will remove the EXIF Orientation tag, if any.

Only one rotation can occur per pipeline. Previous calls to rotate in the same pipeline will be ignored.

Multi-page images can only be rotated by 180 degrees.

Method order is important when rotating, resizing and/or extracting regions, for example [.rotate(x).extract(y)] will produce a different result to [.extract(y).rotate(x)].

Throws:

• Error Invalid parameters

Example

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);

Example

const rotateThenResize = await sharp(input)
  .rotate(90)
  .resize({ width: 16, height: 8, fit: 'fill' })
  .toBuffer();
const resizeThenRotate = await sharp(input)
  .resize({ width: 16, height: 8, fit: 'fill' })
  .rotate(90)
  .toBuffer();

flip

flip([flip]) ⇒ Sharp

Mirror the image vertically (up-down) about the x-axis. This always occurs before rotation, if any.

This operation does not work correctly with multi-page images.

Example

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

flop

flop([flop]) ⇒ Sharp

Mirror the image horizontally (left-right) about the y-axis. This always occurs before rotation, if any.

Example

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

affine

affine(matrix, [options]) ⇒ Sharp

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.interpolators Object e.g. sharp.interpolators.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.

Throws:

• Error Invalid parameters

Since: 0.27.0

Example

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

inputStream
  .pipe(pipeline);

sharpen

sharpen([options], [flat], [jagged]) ⇒ Sharp

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. Fine-grained control over the level of sharpening in "flat" (m1) and "jagged" (m2) areas is available.

See libvips sharpen  operation.

Throws:

• Error Invalid parameters

Example

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

Example

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

Example

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

median

median([size]) ⇒ Sharp

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

Throws:

• Error Invalid parameters

Example

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

Example

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

blur

blur([sigma]) ⇒ Sharp

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.

Throws:

• Error Invalid parameters

Example

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

Example

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

flatten

flatten([options]) ⇒ Sharp

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

See also removeAlpha.

Example

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

unflatten

unflatten()

Ensure the image has an alpha channel with all white pixel values made fully transparent.

Existing alpha channel values for non-white pixels remain unchanged.

This feature is experimental and the API may change.

Since: 0.32.1

Example

await sharp(rgbInput)
  .unflatten()
  .toBuffer();

Example

await sharp(rgbInput)
  .threshold(128, { grayscale: false }) // converter bright pixels to white
  .unflatten()
  .toBuffer();

gamma

gamma([gamma], [gammaOut]) ⇒ Sharp

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.

Throws:

• Error Invalid parameters

negate

negate([options]) ⇒ Sharp

Produce the "negative" of the image.

Example

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

Example

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

normalise

normalise([options]) ⇒ Sharp

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

Uses a histogram-based approach, taking a default range of 1% to 99% to reduce sensitivity to noise at the extremes.

Luminance values below the lower percentile will be underexposed by clipping to zero. Luminance values above the upper percentile will be overexposed by clipping to the max pixel value.

Example

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

Example

const output = await sharp(input)
  .normalise({ lower: 0, upper: 100 })
  .toBuffer();

normalize

normalize([options]) ⇒ Sharp

Alternative spelling of normalise.

Example

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

clahe

clahe(options) ⇒ Sharp

Perform contrast limiting adaptive histogram equalization CLAHE .

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

Throws:

• Error Invalid parameters

Since: 0.28.3

Example

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

convolve

convolve(kernel) ⇒ Sharp

Convolve the image with the specified kernel.

Throws:

• Error Invalid parameters

Example

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
  });

threshold

threshold([threshold], [options]) ⇒ Sharp

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

Throws:

• Error Invalid parameters

boolean

boolean(operand, operator, [options]) ⇒ Sharp

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.

Throws:

• Error Invalid parameters

linear

linear([a], [b]) ⇒ Sharp

Apply the linear formula a * input + b to the image to adjust image levels.

When a single number is provided, it will be used for all image channels. When an array of numbers is provided, the array length must match the number of channels.

Throws:

• Error Invalid parameters

Example

await sharp(input)
  .linear(0.5, 2)
  .toBuffer();

Example

await sharp(rgbInput)
  .linear(
    [0.25, 0.5, 0.75],
    [150, 100, 50]
  )
  .toBuffer();

recomb

recomb(inputMatrix) ⇒ Sharp

Recombine the image with the specified matrix.

Throws:

• Error Invalid parameters

Since: 0.21.1

Example

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 matrix
    // With this example input, a sepia filter has been applied
  });

modulate

modulate([options]) ⇒ Sharp

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.

Since: 0.22.1

Example

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

Example

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

Example

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

Example

// decrease 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();