api-resize.md

resize

resize([width], [height], [options]) ⇒ Sharp

Resize image to width, height or width x height.

When both a width and height are provided, the possible methods by which the image should fit these are:

• cover: (default) Preserving aspect ratio, attempt to ensure the image covers both provided dimensions by cropping/clipping to fit.
• contain: Preserving aspect ratio, contain within both provided dimensions using "letterboxing" where necessary.
• fill: Ignore the aspect ratio of the input and stretch to both provided dimensions.
• inside: Preserving aspect ratio, resize the image to be as large as possible while ensuring its dimensions are less than or equal to both those specified.
• outside: Preserving aspect ratio, resize the image to be as small as possible while ensuring its dimensions are greater than or equal to both those specified.

Some of these values are based on the object-fit CSS property.

When using a fit of cover or contain, the default position is centre. Other options are:

• sharp.position: top, right top, right, right bottom, bottom, left bottom, left, left top.
• sharp.gravity: north, northeast, east, southeast, south, southwest, west, northwest, center or centre.
• sharp.strategy: cover only, dynamically crop using either the entropy or attention strategy.

Some of these values are based on the object-position CSS property.

The strategy-based approach initially resizes so one dimension is at its target length then repeatedly ranks edge regions, discarding the edge with the lowest score based on the selected strategy.

• entropy: focus on the region with the highest Shannon entropy.
• attention: focus on the region with the highest luminance frequency, colour saturation and presence of skin tones.

Possible downsizing kernels are:

• nearest: Use nearest neighbour interpolation.
• linear: Use a triangle filter.
• cubic: Use a Catmull-Rom spline.
• mitchell: Use a Mitchell-Netravali spline.
• lanczos2: Use a Lanczos kernel with a=2.
• lanczos3: Use a Lanczos kernel with a=3 (the default).

When upsampling, these kernels map to nearest, linear and cubic interpolators. Downsampling kernels without a matching upsampling interpolator map to cubic.

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

Throws:

• Error Invalid parameters

Param	Type	Default	Description
[width]	number		How many pixels wide the resultant image should be. Use null or undefined to auto-scale the width to match the height.
[height]	number		How many pixels high the resultant image should be. Use null or undefined to auto-scale the height to match the width.
[options]	Object
[options.width]	number		An alternative means of specifying width. If both are present this takes priority.
[options.height]	number		An alternative means of specifying height. If both are present this takes priority.
[options.fit]	String	'cover'	How the image should be resized/cropped to fit the target dimension(s), one of cover, contain, fill, inside or outside.
[options.position]	String	'centre'	A position, gravity or strategy to use when fit is cover or contain.
[options.background]	String | Object	{r: 0, g: 0, b: 0, alpha: 1}	background colour when fit is contain, parsed by the color module, defaults to black without transparency.
[options.kernel]	String	'lanczos3'	The kernel to use for image reduction and the inferred interpolator to use for upsampling. Use the fastShrinkOnLoad option to control kernel vs shrink-on-load.
[options.withoutEnlargement]	Boolean	false	Do not scale up if the width or height are already less than the target dimensions, equivalent to GraphicsMagick's > geometry option. This may result in output dimensions smaller than the target dimensions.
[options.withoutReduction]	Boolean	false	Do not scale down if the width or height are already greater than the target dimensions, equivalent to GraphicsMagick's < geometry option. This may still result in a crop to reach the target dimensions.
[options.fastShrinkOnLoad]	Boolean	true	Take greater advantage of the JPEG and WebP shrink-on-load feature, which can lead to a slight moiré pattern or round-down of an auto-scaled dimension.

Example

sharp(input)
  .resize({ width: 100 })
  .toBuffer()
  .then(data => {
    // 100 pixels wide, auto-scaled height
  });

Example

sharp(input)
  .resize({ height: 100 })
  .toBuffer()
  .then(data => {
    // 100 pixels high, auto-scaled width
  });

Example

sharp(input)
  .resize(200, 300, {
    kernel: sharp.kernel.nearest,
    fit: 'contain',
    position: 'right top',
    background: { r: 255, g: 255, b: 255, alpha: 0.5 }
  })
  .toFile('output.png')
  .then(() => {
    // output.png is a 200 pixels wide and 300 pixels high image
    // containing a nearest-neighbour scaled version
    // contained within the north-east corner of a semi-transparent white canvas
  });

Example

const transformer = sharp()
  .resize({
    width: 200,
    height: 200,
    fit: sharp.fit.cover,
    position: sharp.strategy.entropy
  });
// Read image data from readableStream
// Write 200px square auto-cropped image data to writableStream
readableStream
  .pipe(transformer)
  .pipe(writableStream);

Example

sharp(input)
  .resize(200, 200, {
    fit: sharp.fit.inside,
    withoutEnlargement: true
  })
  .toFormat('jpeg')
  .toBuffer()
  .then(function(outputBuffer) {
    // outputBuffer contains JPEG image data
    // no wider and no higher than 200 pixels
    // and no larger than the input image
  });

Example

sharp(input)
  .resize(200, 200, {
    fit: sharp.fit.outside,
    withoutReduction: true
  })
  .toFormat('jpeg')
  .toBuffer()
  .then(function(outputBuffer) {
    // outputBuffer contains JPEG image data
    // of at least 200 pixels wide and 200 pixels high while maintaining aspect ratio
    // and no smaller than the input image
  });

Example

const scaleByHalf = await sharp(input)
  .metadata()
  .then(({ width }) => sharp(input)
    .resize(Math.round(width * 0.5))
    .toBuffer()
  );

extend

extend(extend) ⇒ Sharp

Extend / pad / extrude one or more edges of the image with either the provided background colour or pixels derived from the image. This operation will always occur after resizing and extraction, if any.

Throws:

• Error Invalid parameters

Param	Type	Default	Description
extend	number | Object		single pixel count to add to all edges or an Object with per-edge counts
[extend.top]	number	0
[extend.left]	number	0
[extend.bottom]	number	0
[extend.right]	number	0
[extend.extendWith]	String	'background'	populate new pixels using this method, one of: background, copy, repeat, mirror.
[extend.background]	String | Object	{r: 0, g: 0, b: 0, alpha: 1}	background colour, parsed by the color module, defaults to black without transparency.

Example

// Resize to 140 pixels wide, then add 10 transparent pixels
// to the top, left and right edges and 20 to the bottom edge
sharp(input)
  .resize(140)
  .extend({
    top: 10,
    bottom: 20,
    left: 10,
    right: 10,
    background: { r: 0, g: 0, b: 0, alpha: 0 }
  })
  ...

Example

// Add a row of 10 red pixels to the bottom
sharp(input)
  .extend({
    bottom: 10,
    background: 'red'
  })
  ...

Example

// Extrude image by 8 pixels to the right, mirroring existing right hand edge
sharp(input)
  .extend({
    right: 8,
    background: 'mirror'
  })
  ...

extract

extract(options) ⇒ Sharp

Extract/crop a region of the image.

• Use extract before resize for pre-resize extraction.
• Use extract after resize for post-resize extraction.
• Use extract twice and resize once for extract-then-resize-then-extract in a fixed operation order.

Throws:

• Error Invalid parameters

Param	Type	Description
options	Object	describes the region to extract using integral pixel values
options.left	number	zero-indexed offset from left edge
options.top	number	zero-indexed offset from top edge
options.width	number	width of region to extract
options.height	number	height of region to extract

Example

sharp(input)
  .extract({ left: left, top: top, width: width, height: height })
  .toFile(output, function(err) {
    // Extract a region of the input image, saving in the same format.
  });

Example

sharp(input)
  .extract({ left: leftOffsetPre, top: topOffsetPre, width: widthPre, height: heightPre })
  .resize(width, height)
  .extract({ left: leftOffsetPost, top: topOffsetPost, width: widthPost, height: heightPost })
  .toFile(output, function(err) {
    // Extract a region, resize, then extract from the resized image
  });

trim

trim([options]) ⇒ Sharp

Trim pixels from all edges that contain values similar to the given background colour, which defaults to that of the top-left pixel.

Images with an alpha channel will use the combined bounding box of alpha and non-alpha channels.

If the result of this operation would trim an image to nothing then no change is made.

The info response Object will contain trimOffsetLeft and trimOffsetTop properties.

Throws:

• Error Invalid parameters

Param	Type	Default	Description
[options]	Object
[options.background]	string | Object	"'top-left pixel'"	Background colour, parsed by the color module, defaults to that of the top-left pixel.
[options.threshold]	number	10	Allowed difference from the above colour, a positive number.
[options.lineArt]	boolean	false	Does the input more closely resemble line art (e.g. vector) rather than being photographic?

Example

// Trim pixels with a colour similar to that of the top-left pixel.
await sharp(input)
  .trim()
  .toFile(output);

Example

// Trim pixels with the exact same colour as that of the top-left pixel.
await sharp(input)
  .trim({
    threshold: 0
  })
  .toFile(output);

Example

// Assume input is line art and trim only pixels with a similar colour to red.
const output = await sharp(input)
  .trim({
    background: "#FF0000",
    lineArt: true
  })
  .toBuffer();

Example

// Trim all "yellow-ish" pixels, being more lenient with the higher threshold.
const output = await sharp(input)
  .trim({
    background: "yellow",
    threshold: 42,
  })
  .toBuffer();