sharp/docs/api-resize.md

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

## resize

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, 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][1] 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][2] CSS property.

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][3].
*   `attention`: focus on the region with the highest luminance frequency, colour saturation and presence of skin tones.

Possible interpolation kernels are:

*   `nearest`: Use [nearest neighbour interpolation][4].
*   `cubic`: Use a [Catmull-Rom spline][5].
*   `mitchell`: Use a [Mitchell-Netravali spline][6].
*   `lanczos2`: Use a [Lanczos kernel][7] with `a=2`.
*   `lanczos3`: Use a Lanczos kernel with `a=3` (the default).

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

### Parameters

*   `width` **[number][8]?** pixels wide the resultant image should be. Use `null` or `undefined` to auto-scale the width to match the height.
*   `height` **[number][8]?** pixels high the resultant image should be. Use `null` or `undefined` to auto-scale the height to match the width.
*   `options` **[Object][9]?**&#x20;

    *   `options.width` **[String][10]?** alternative means of specifying `width`. If both are present this takes priority.
    *   `options.height` **[String][10]?** alternative means of specifying `height`. If both are present this takes priority.
    *   `options.fit` **[String][10]** how the image should be resized to fit both provided dimensions, one of `cover`, `contain`, `fill`, `inside` or `outside`. (optional, default `'cover'`)
    *   `options.position` **[String][10]** position, gravity or strategy to use when `fit` is `cover` or `contain`. (optional, default `'centre'`)
    *   `options.background` **([String][10] | [Object][9])** background colour when `fit` is `contain`, parsed by the [color][11] module, defaults to black without transparency. (optional, default `{r:0,g:0,b:0,alpha:1}`)
    *   `options.kernel` **[String][10]** the kernel to use for image reduction. (optional, default `'lanczos3'`)
    *   `options.withoutEnlargement` **[Boolean][12]** do not enlarge if the width *or* height are already less than the specified dimensions, equivalent to GraphicsMagick's `>` geometry option. (optional, default `false`)
    *   `options.withoutReduction` **[Boolean][12]** do not reduce if the width *or* height are already greater than the specified dimensions, equivalent to GraphicsMagick's `<` geometry option. (optional, default `false`)
    *   `options.fastShrinkOnLoad` **[Boolean][12]** take greater advantage of the JPEG and WebP shrink-on-load feature, which can lead to a slight moiré pattern on some images. (optional, default `true`)

### Examples

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

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

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

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

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

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

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

*   Throws **[Error][13]** Invalid parameters

Returns **Sharp**&#x20;

## extend

Extends/pads the edges of the image with the provided background colour.
This operation will always occur after resizing and extraction, if any.

### Parameters

*   `extend` **([number][8] | [Object][9])** single pixel count to add to all edges or an Object with per-edge counts

    *   `extend.top` **[number][8]**  (optional, default `0`)
    *   `extend.left` **[number][8]**  (optional, default `0`)
    *   `extend.bottom` **[number][8]**  (optional, default `0`)
    *   `extend.right` **[number][8]**  (optional, default `0`)
    *   `extend.background` **([String][10] | [Object][9])** background colour, parsed by the [color][11] module, defaults to black without transparency. (optional, default `{r:0,g:0,b:0,alpha:1}`)

### Examples

```javascript
// 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 }
  })
  ...
```

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

*   Throws **[Error][13]** Invalid parameters

Returns **Sharp**&#x20;

## extract

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` before and after for both.

### Parameters

*   `options` **[Object][9]** describes the region to extract using integral pixel values

    *   `options.left` **[number][8]** zero-indexed offset from left edge
    *   `options.top` **[number][8]** zero-indexed offset from top edge
    *   `options.width` **[number][8]** width of region to extract
    *   `options.height` **[number][8]** height of region to extract

### Examples

```javascript
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.
  });
```

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

*   Throws **[Error][13]** Invalid parameters

Returns **Sharp**&#x20;

## trim

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, obtained from callback of `.toFile()` or `.toBuffer()`,
will contain `trimOffsetLeft` and `trimOffsetTop` properties.

### Parameters

*   `trim` **([string][10] | [number][8] | [Object][9])** the specific background colour to trim, the threshold for doing so or an Object with both.

    *   `trim.background` **([string][10] | [Object][9])** background colour, parsed by the [color][11] module, defaults to that of the top-left pixel. (optional, default `'top-left pixel'`)
    *   `trim.threshold` **[number][8]** the allowed difference from the above colour, a positive number. (optional, default `10`)

### Examples

```javascript
// Trim pixels with a colour similar to that of the top-left pixel.
sharp(input)
  .trim()
  .toFile(output, function(err, info) {
    ...
  });
```

```javascript
// Trim pixels with the exact same colour as that of the top-left pixel.
sharp(input)
  .trim(0)
  .toFile(output, function(err, info) {
    ...
  });
```

```javascript
// Trim only pixels with a similar colour to red.
sharp(input)
  .trim("#FF0000")
  .toFile(output, function(err, info) {
    ...
  });
```

```javascript
// Trim all "yellow-ish" pixels, being more lenient with the higher threshold.
sharp(input)
  .trim({
    background: "yellow",
    threshold: 42,
  })
  .toFile(output, function(err, info) {
    ...
  });
```

*   Throws **[Error][13]** Invalid parameters

Returns **Sharp**&#x20;

[1]: https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit

[2]: https://developer.mozilla.org/en-US/docs/Web/CSS/object-position

[3]: https://en.wikipedia.org/wiki/Entropy_%28information_theory%29

[4]: http://en.wikipedia.org/wiki/Nearest-neighbor_interpolation

[5]: https://en.wikipedia.org/wiki/Centripetal_Catmull%E2%80%93Rom_spline

[6]: https://www.cs.utexas.edu/~fussell/courses/cs384g-fall2013/lectures/mitchell/Mitchell.pdf

[7]: https://en.wikipedia.org/wiki/Lanczos_resampling#Lanczos_kernel

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

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

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

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

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

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