Skip to content

Latest commit

 

History

History
511 lines (328 loc) · 14.1 KB

api-operation.md

File metadata and controls

511 lines (328 loc) · 14.1 KB
Raw

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 angle of rotation. (optional, default auto)

  • options Object? if present, is an Object with optional attributes.

    • options.background (string | Object) parsed by the color module to extract values for red, green, blue and alpha. (optional, default "#000000")

Examples

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 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 (optional, default true)

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 (optional, default true)

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<Array<number>> | Array<number>) affine transformation matrix

  • options Object? if present, is an Object with optional attributes.

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

Examples

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 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 operation.

Parameters

  • options Object? if present, is an Object with optional attributes.

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

Examples

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

Returns Sharp

median

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

Parameters

  • size number square mask size: size x size (optional, default 3)
  • Throws Error 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? a value between 0.3 and 1000 representing the sigma of the Gaussian mask, where sigma = 1 + radius / 2.

Examples

const boxBlurred = await sharp(input)
  .blur()
  .toBuffer();
const gaussianBlurred = await sharp(input)
  .blur(5)
  .toBuffer();
  • Throws Error Invalid parameters

Returns Sharp

flatten

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

See also removeAlpha.

Parameters

  • options Object?

    • options.background (string | Object) background colour, parsed by the color module, defaults to black. (optional, default {r:0,g:0,b:0})

Examples

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 value between 1.0 and 3.0. (optional, default 2.2)
  • gammaOut number? value between 1.0 and 3.0. (optional, defaults to same as gamma)
  • Throws Error Invalid parameters

Returns Sharp

negate

Produce the "negative" of the image.

Parameters

  • options Object?

    • options.alpha Boolean Whether or not to negate any alpha channel (optional, default true)

Returns Sharp

normalise

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

Parameters

  • normalise Boolean (optional, default true)

Returns Sharp

normalize

Alternative spelling of normalise.

Parameters

  • normalize Boolean (optional, default true)

Returns Sharp

clahe

Perform contrast limiting adaptive histogram equalization CLAHE.

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

Parameters

  • options Object

    • options.width number integer width of the region in pixels.
    • options.height number integer height of the region in pixels.
    • options.maxSlope number 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)
  • Throws Error Invalid parameters

Returns Sharp

Meta

  • since: 0.28.3

convolve

Convolve the image with the specified kernel.

Parameters

  • kernel Object

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

Examples

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 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 a value in the range 0-255 representing the level at which the threshold will be applied. (optional, default 128)

  • options Object?

    • options.greyscale Boolean convert to single channel greyscale. (optional, default true)
    • options.grayscale Boolean alternative spelling for greyscale. (optional, default true)
  • Throws Error 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 | string) Buffer containing image data or string containing the path to an image file.

  • operator string one of and, or or eor to perform that bitwise operation, like the C logic operators &, | and ^ respectively.

  • options Object?

    • options.raw Object? describes operand when using raw pixel data.

  • Throws Error Invalid parameters

Returns Sharp

linear

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

Parameters

  • a number multiplier (optional, default 1.0)
  • b number offset (optional, default 0.0)
  • Throws Error Invalid parameters

Returns Sharp

recomb

Recomb the image with the specified matrix.

Parameters

Examples

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 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?

    • options.brightness number? Brightness multiplier
    • options.saturation number? Saturation multiplier
    • options.hue number? Degrees for hue rotation
    • options.lightness number? Lightness addend

Examples

sharp(input)
  .modulate({
    brightness: 2 // increase brightness by a factor of 2
  });

sharp(input)
  .modulate({
    hue: 180 // hue-rotate by 180 degrees
  });

sharp(input)
  .modulate({
    lightness: 50 // increase lightness by +50
  });

// decreate brightness and saturation while also hue-rotating by 90 degrees
sharp(input)
  .modulate({
    brightness: 0.5,
    saturation: 0.5,
    hue: 90
  });

Returns Sharp

Meta

  • since: 0.22.1