sharp/docs/api-resize.md

Table of Contents

• resize
• crop
• embed
• max
• min
• ignoreAspectRatio
• withoutEnlargement

resize

Resize image to width x height. By default, the resized image is centre cropped to the exact size specified.

Possible reduction kernels are:

• cubic: Use a Catmull-Rom spline.
• lanczos2: Use a Lanczos kernel with a=2.
• lanczos3: Use a Lanczos kernel with a=3 (the default).

Possible enlargement interpolators are:

• nearest: Use nearest neighbour interpolation.
• bilinear: Use bilinear interpolation, faster than bicubic but with less smooth results.
• vertexSplitQuadraticBasisSpline: Use the smoother VSQBS interpolation to prevent "staircasing" when enlarging.
• bicubic: Use bicubic interpolation (the default).
• locallyBoundedBicubic: Use LBB interpolation, which prevents some "acutance" but typically reduces performance by a factor of 2.
• nohalo: Use Nohalo interpolation, which prevents acutance but typically reduces performance by a factor of 3.

Parameters

• width Number? pixels wide the resultant image should be, between 1 and 16383 (0x3FFF). Use null or undefined to auto-scale the width to match the height.
• height Number? pixels high the resultant image should be, between 1 and 16383. Use null or undefined to auto-scale the height to match the width.
• options Object?
  • options.kernel String? the kernel to use for image reduction. (optional, default 'lanczos3')
  • options.interpolator String? the interpolator to use for image enlargement. (optional, default 'bicubic')
  • options.centreSampling Boolean? use *magick centre sampling convention instead of corner sampling. (optional, default false)
  • options.centerSampling Boolean? alternative spelling of centreSampling. (optional, default false)

Examples

sharp(inputBuffer)
  .resize(200, 300, {
    kernel: sharp.kernel.lanczos2,
    interpolator: sharp.interpolator.nohalo
  })
  .background('white')
  .embed()
  .toFile('output.tiff')
  .then(function() {
    // output.tiff is a 200 pixels wide and 300 pixels high image
    // containing a lanczos2/nohalo scaled version, embedded on a white canvas,
    // of the image data in inputBuffer
  });

• Throws Error Invalid parameters

Returns Sharp

crop

Crop the resized image to the exact size specified, the default behaviour.

Possible attributes of the optional sharp.gravity are north, northeast, east, southeast, south, southwest, west, northwest, center and centre.

The experimental strategy-based approach 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.

Parameters

• crop String? A member of sharp.gravity to crop to an edge/corner or sharp.strategy to crop dynamically. (optional, default 'centre')

Examples

const transformer = sharp()
  .resize(200, 200)
  .crop(sharp.strategy.entropy)
  .on('error', function(err) {
    console.log(err);
  });
// Read image data from readableStream
// Write 200px square auto-cropped image data to writableStream
readableStream.pipe(transformer).pipe(writableStream);

• Throws Error Invalid parameters

Returns Sharp

embed

Preserving aspect ratio, resize the image to the maximum width or height specified then embed on a background of the exact width and height specified.

If the background contains an alpha value then WebP and PNG format output images will contain an alpha channel, even when the input image does not.

Examples

sharp('input.gif')
  .resize(200, 300)
  .background({r: 0, g: 0, b: 0, a: 0})
  .embed()
  .toFormat(sharp.format.webp)
  .toBuffer(function(err, outputBuffer) {
    if (err) {
      throw err;
    }
    // outputBuffer contains WebP image data of a 200 pixels wide and 300 pixels high
    // containing a scaled version, embedded on a transparent canvas, of input.gif
  });

Returns Sharp

max

Preserving aspect ratio, resize the image to be as large as possible while ensuring its dimensions are less than or equal to the width and height specified.

Both width and height must be provided via resize otherwise the behaviour will default to crop.

Examples

sharp(inputBuffer)
  .resize(200, 200)
  .max()
  .toFormat('jpeg')
  .toBuffer()
  .then(function(outputBuffer) {
    // outputBuffer contains JPEG image data no wider than 200 pixels and no higher
    // than 200 pixels regardless of the inputBuffer image dimensions
  });

Returns Sharp

min

Preserving aspect ratio, resize the image to be as small as possible while ensuring its dimensions are greater than or equal to the width and height specified.

Both width and height must be provided via resize otherwise the behaviour will default to crop.

Returns Sharp

ignoreAspectRatio

Ignoring the aspect ratio of the input, stretch the image to the exact width and/or height provided via resize.

Returns Sharp

withoutEnlargement

Do not enlarge the output image if the input image width or height are already less than the required dimensions. This is equivalent to GraphicsMagick's > geometry option: "change the dimensions of the image only if its width or height exceeds the geometry specification".

Parameters

• withoutEnlargement Boolean? (optional, default true)

Returns Sharp