mirror of
https://github.com/lovell/sharp.git
synced 2025-07-09 18:40:16 +02:00
265 lines
8.2 KiB
Markdown
265 lines
8.2 KiB
Markdown
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
|
|
|
|
## resize
|
|
|
|
Resize image to `width` x `height`.
|
|
By default, the resized image is centre cropped to the exact size specified.
|
|
|
|
Possible kernels are:
|
|
|
|
- `nearest`: Use [nearest neighbour interpolation][1].
|
|
- `cubic`: Use a [Catmull-Rom spline][2].
|
|
- `lanczos2`: Use a [Lanczos kernel][3] with `a=2`.
|
|
- `lanczos3`: Use a Lanczos kernel with `a=3` (the default).
|
|
|
|
### Parameters
|
|
|
|
- `width` **[Number][4]?** pixels wide the resultant image should be. Use `null` or `undefined` to auto-scale the width to match the height.
|
|
- `height` **[Number][4]?** pixels high the resultant image should be. Use `null` or `undefined` to auto-scale the height to match the width.
|
|
- `options` **[Object][5]?**
|
|
- `options.kernel` **[String][6]** the kernel to use for image reduction. (optional, default `'lanczos3'`)
|
|
- `options.fastShrinkOnLoad` **[Boolean][7]** 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(inputBuffer)
|
|
.resize(200, 300, {
|
|
kernel: sharp.kernel.nearest
|
|
})
|
|
.background('white')
|
|
.embed()
|
|
.toFile('output.tiff')
|
|
.then(function() {
|
|
// output.tiff is a 200 pixels wide and 300 pixels high image
|
|
// containing a nearest-neighbour scaled version, embedded on a white canvas,
|
|
// of the image data in inputBuffer
|
|
});
|
|
```
|
|
|
|
- Throws **[Error][8]** 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][9].
|
|
- `attention`: focus on the region with the highest luminance frequency, colour saturation and presence of skin tones.
|
|
|
|
### Parameters
|
|
|
|
- `crop` **[String][6]** A member of `sharp.gravity` to crop to an edge/corner or `sharp.strategy` to crop dynamically. (optional, default `'centre'`)
|
|
|
|
### Examples
|
|
|
|
```javascript
|
|
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][8]** 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.
|
|
|
|
### Parameters
|
|
|
|
- `embed` **[String][6]** A member of `sharp.gravity` to embed to an edge/corner. (optional, default `'centre'`)
|
|
|
|
### Examples
|
|
|
|
```javascript
|
|
sharp('input.gif')
|
|
.resize(200, 300)
|
|
.background({r: 0, g: 0, b: 0, alpha: 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
|
|
});
|
|
```
|
|
|
|
- Throws **[Error][8]** Invalid parameters
|
|
|
|
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
|
|
|
|
```javascript
|
|
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_".
|
|
Use with `max()` to preserve the image's aspect ratio.
|
|
|
|
The default behaviour _before_ function call is `false`, meaning the image will be enlarged.
|
|
|
|
### Parameters
|
|
|
|
- `withoutEnlargement` **[Boolean][7]** (optional, default `true`)
|
|
|
|
Returns **Sharp**
|
|
|
|
## extend
|
|
|
|
Extends/pads the edges of the image with the colour provided to the `background` method.
|
|
This operation will always occur after resizing and extraction, if any.
|
|
|
|
### Parameters
|
|
|
|
- `extend` **([Number][4] \| [Object][5])** single pixel count to add to all edges or an Object with per-edge counts
|
|
- `extend.top` **[Number][4]?**
|
|
- `extend.left` **[Number][4]?**
|
|
- `extend.bottom` **[Number][4]?**
|
|
- `extend.right` **[Number][4]?**
|
|
|
|
### 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)
|
|
.background({r: 0, g: 0, b: 0, alpha: 0})
|
|
.extend({top: 10, bottom: 20, left: 10, right: 10})
|
|
...
|
|
```
|
|
|
|
- Throws **[Error][8]** Invalid parameters
|
|
|
|
Returns **Sharp**
|
|
|
|
## extract
|
|
|
|
Extract 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][5]**
|
|
- `options.left` **[Number][4]** zero-indexed offset from left edge
|
|
- `options.top` **[Number][4]** zero-indexed offset from top edge
|
|
- `options.width` **[Number][4]** dimension of extracted image
|
|
- `options.height` **[Number][4]** dimension of extracted image
|
|
|
|
### 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][8]** Invalid parameters
|
|
|
|
Returns **Sharp**
|
|
|
|
## trim
|
|
|
|
Trim "boring" pixels from all edges that contain values within a percentage similarity of the top-left pixel.
|
|
|
|
### Parameters
|
|
|
|
- `tolerance` **[Number][4]** value between 1 and 99 representing the percentage similarity. (optional, default `10`)
|
|
|
|
|
|
- Throws **[Error][8]** Invalid parameters
|
|
|
|
Returns **Sharp**
|
|
|
|
[1]: http://en.wikipedia.org/wiki/Nearest-neighbor_interpolation
|
|
|
|
[2]: https://en.wikipedia.org/wiki/Centripetal_Catmull%E2%80%93Rom_spline
|
|
|
|
[3]: https://en.wikipedia.org/wiki/Lanczos_resampling#Lanczos_kernel
|
|
|
|
[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
|
|
|
|
[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
|
|
|
|
[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
|
|
|
|
[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
|
|
|
|
[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error
|
|
|
|
[9]: https://en.wikipedia.org/wiki/Entropy_%28information_theory%29
|