mirror of
https://github.com/lovell/sharp.git
synced 2025-12-19 15:25:07 +01:00
Deprecate crop, embed, ignoreAspectRatio, max, min, withoutEnlargement.
These become options of the resize operation instead. #1135
This commit is contained in:
Lovell Fuller
424
lib/resize.js
424
lib/resize.js
@@ -1,9 +1,10 @@
|
||||
'use strict';
|
||||
|
||||
const deprecate = require('util').deprecate;
|
||||
const is = require('./is');
|
||||
|
||||
/**
|
||||
* Weighting to apply to image crop.
|
||||
* Weighting to apply when using contain/cover fit.
|
||||
* @member
|
||||
* @private
|
||||
*/
|
||||
@@ -21,7 +22,23 @@ const gravity = {
|
||||
};
|
||||
|
||||
/**
|
||||
* Strategies for automagic crop behaviour.
|
||||
* Position to apply when using contain/cover fit.
|
||||
* @member
|
||||
* @private
|
||||
*/
|
||||
const position = {
|
||||
top: 1,
|
||||
right: 2,
|
||||
bottom: 3,
|
||||
left: 4,
|
||||
'right top': 5,
|
||||
'right bottom': 6,
|
||||
'left bottom': 7,
|
||||
'left top': 8
|
||||
};
|
||||
|
||||
/**
|
||||
* Strategies for automagic cover behaviour.
|
||||
* @member
|
||||
* @private
|
||||
*/
|
||||
@@ -43,40 +60,135 @@ const kernel = {
|
||||
};
|
||||
|
||||
/**
|
||||
* Resize image to `width` x `height`.
|
||||
* By default, the resized image is centre cropped to the exact size specified.
|
||||
* Methods by which an image can be resized to fit the provided dimensions.
|
||||
* @member
|
||||
* @private
|
||||
*/
|
||||
const fit = {
|
||||
contain: 'contain',
|
||||
cover: 'cover',
|
||||
fill: 'fill',
|
||||
inside: 'inside',
|
||||
outside: 'outside'
|
||||
};
|
||||
|
||||
/**
|
||||
* Map external fit property to internal canvas property.
|
||||
* @member
|
||||
* @private
|
||||
*/
|
||||
const mapFitToCanvas = {
|
||||
contain: 'embed',
|
||||
cover: 'crop',
|
||||
fill: 'ignore_aspect',
|
||||
inside: 'max',
|
||||
outside: 'min'
|
||||
};
|
||||
|
||||
/**
|
||||
* Resize image to `width`, `height` or `width x height`.
|
||||
*
|
||||
* Possible kernels are:
|
||||
* When both a `width` and `height` are provided, the possible methods by which the image should **fit** these are:
|
||||
* - `cover`: Crop to cover both provided dimensions (the default).
|
||||
* - `contain`: Embed within both provided dimensions.
|
||||
* - `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](https://developer.mozilla.org/en-US/docs/Web/CSS/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](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position) 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](https://en.wikipedia.org/wiki/Entropy_%28information_theory%29).
|
||||
* - `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](http://en.wikipedia.org/wiki/Nearest-neighbor_interpolation).
|
||||
* - `cubic`: Use a [Catmull-Rom spline](https://en.wikipedia.org/wiki/Centripetal_Catmull%E2%80%93Rom_spline).
|
||||
* - `lanczos2`: Use a [Lanczos kernel](https://en.wikipedia.org/wiki/Lanczos_resampling#Lanczos_kernel) with `a=2`.
|
||||
* - `lanczos3`: Use a Lanczos kernel with `a=3` (the default).
|
||||
*
|
||||
* @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(inputBuffer)
|
||||
* .resize(200, 300, {
|
||||
* kernel: sharp.kernel.nearest
|
||||
* kernel: sharp.kernel.nearest,
|
||||
* fit: 'contain',
|
||||
* position: 'right top'
|
||||
* })
|
||||
* .background('white')
|
||||
* .embed()
|
||||
* .toFile('output.tiff')
|
||||
* .then(function() {
|
||||
* .then(() => {
|
||||
* // 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
|
||||
* // containing a nearest-neighbour scaled version
|
||||
* // embedded in the north-east corner of a 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(inputBuffer)
|
||||
* .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
|
||||
* });
|
||||
*
|
||||
* @param {Number} [width] - pixels wide the resultant image should be. Use `null` or `undefined` to auto-scale the width to match the height.
|
||||
* @param {Number} [height] - pixels high the resultant image should be. Use `null` or `undefined` to auto-scale the height to match the width.
|
||||
* @param {Object} [options]
|
||||
* @param {String} [options.width] - alternative means of specifying `width`. If both are present this take priority.
|
||||
* @param {String} [options.height] - alternative means of specifying `height`. If both are present this take priority.
|
||||
* @param {String} [options.fit='cover'] - how the image should be resized to fit both provided dimensions, one of `cover`, `contain`, `fill`, `inside` or `outside`.
|
||||
* @param {String} [options.position='centre'] - position, gravity or strategy to use when `fit` is `cover` or `contain`.
|
||||
* @param {String} [options.kernel='lanczos3'] - the kernel to use for image reduction.
|
||||
* @param {Boolean} [options.withoutEnlargement=false] - do not enlarge if the width *or* height are already less than the specified dimensions, equivalent to GraphicsMagick's `>` geometry option.
|
||||
* @param {Boolean} [options.fastShrinkOnLoad=true] - take greater advantage of the JPEG and WebP shrink-on-load feature, which can lead to a slight moiré pattern on some images.
|
||||
* @returns {Sharp}
|
||||
* @throws {Error} Invalid parameters
|
||||
*/
|
||||
function resize (width, height, options) {
|
||||
if (is.defined(width)) {
|
||||
if (is.integer(width) && width > 0) {
|
||||
if (is.object(width) && !is.defined(options)) {
|
||||
options = width;
|
||||
} else if (is.integer(width) && width > 0) {
|
||||
this.options.width = width;
|
||||
} else {
|
||||
throw is.invalidParameterError('width', 'positive integer', width);
|
||||
@@ -94,6 +206,34 @@ function resize (width, height, options) {
|
||||
this.options.height = -1;
|
||||
}
|
||||
if (is.object(options)) {
|
||||
// Width
|
||||
if (is.integer(options.width) && options.width > 0) {
|
||||
this.options.width = options.width;
|
||||
}
|
||||
// Height
|
||||
if (is.integer(options.height) && options.height > 0) {
|
||||
this.options.height = options.height;
|
||||
}
|
||||
// Fit
|
||||
if (is.defined(options.fit)) {
|
||||
const canvas = mapFitToCanvas[options.fit];
|
||||
if (is.string(canvas)) {
|
||||
this.options.canvas = canvas;
|
||||
} else {
|
||||
throw is.invalidParameterError('fit', 'valid fit', options.fit);
|
||||
}
|
||||
}
|
||||
// Position
|
||||
if (is.defined(options.position)) {
|
||||
const pos = is.integer(options.position)
|
||||
? options.position
|
||||
: strategy[options.position] || position[options.position] || gravity[options.position];
|
||||
if (is.integer(pos) && (is.inRange(pos, 0, 8) || is.inRange(pos, 16, 17))) {
|
||||
this.options.position = pos;
|
||||
} else {
|
||||
throw is.invalidParameterError('position', 'valid position/gravity/strategy', options.position);
|
||||
}
|
||||
}
|
||||
// Kernel
|
||||
if (is.defined(options.kernel)) {
|
||||
if (is.string(kernel[options.kernel])) {
|
||||
@@ -102,6 +242,10 @@ function resize (width, height, options) {
|
||||
throw is.invalidParameterError('kernel', 'valid kernel name', options.kernel);
|
||||
}
|
||||
}
|
||||
// Without enlargement
|
||||
if (is.defined(options.withoutEnlargement)) {
|
||||
this._setBooleanOption('withoutEnlargement', options.withoutEnlargement);
|
||||
}
|
||||
// Shrink on load
|
||||
if (is.defined(options.fastShrinkOnLoad)) {
|
||||
this._setBooleanOption('fastShrinkOnLoad', options.fastShrinkOnLoad);
|
||||
@@ -110,161 +254,6 @@ function resize (width, height, options) {
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* 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](https://en.wikipedia.org/wiki/Entropy_%28information_theory%29).
|
||||
* - `attention`: focus on the region with the highest luminance frequency, colour saturation and presence of skin tones.
|
||||
*
|
||||
* @example
|
||||
* 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);
|
||||
*
|
||||
* @param {String} [crop='centre'] - A member of `sharp.gravity` to crop to an edge/corner or `sharp.strategy` to crop dynamically.
|
||||
* @returns {Sharp}
|
||||
* @throws {Error} Invalid parameters
|
||||
*/
|
||||
function crop (crop) {
|
||||
this.options.canvas = 'crop';
|
||||
if (!is.defined(crop)) {
|
||||
// Default
|
||||
this.options.crop = gravity.center;
|
||||
} else if (is.integer(crop) && is.inRange(crop, 0, 8)) {
|
||||
// Gravity (numeric)
|
||||
this.options.crop = crop;
|
||||
} else if (is.string(crop) && is.integer(gravity[crop])) {
|
||||
// Gravity (string)
|
||||
this.options.crop = gravity[crop];
|
||||
} else if (is.integer(crop) && crop >= strategy.entropy) {
|
||||
// Strategy
|
||||
this.options.crop = crop;
|
||||
} else if (is.string(crop) && is.integer(strategy[crop])) {
|
||||
// Strategy (string)
|
||||
this.options.crop = strategy[crop];
|
||||
} else {
|
||||
throw is.invalidParameterError('crop', 'valid crop id/name/strategy', crop);
|
||||
}
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*
|
||||
* @example
|
||||
* 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
|
||||
* });
|
||||
* @param {String} [embed='centre'] - A member of `sharp.gravity` to embed to an edge/corner.
|
||||
* @returns {Sharp}
|
||||
* @throws {Error} Invalid parameters
|
||||
*/
|
||||
function embed (embed) {
|
||||
this.options.canvas = 'embed';
|
||||
|
||||
if (!is.defined(embed)) {
|
||||
// Default
|
||||
this.options.embed = gravity.center;
|
||||
} else if (is.integer(embed) && is.inRange(embed, 0, 8)) {
|
||||
// Gravity (numeric)
|
||||
this.options.embed = embed;
|
||||
} else if (is.string(embed) && is.integer(gravity[embed])) {
|
||||
// Gravity (string)
|
||||
this.options.embed = gravity[embed];
|
||||
} else {
|
||||
throw is.invalidParameterError('embed', 'valid embed id/name', embed);
|
||||
}
|
||||
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* 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`.
|
||||
*
|
||||
* @example
|
||||
* 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}
|
||||
*/
|
||||
function max () {
|
||||
this.options.canvas = 'max';
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* 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}
|
||||
*/
|
||||
function min () {
|
||||
this.options.canvas = 'min';
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Ignoring the aspect ratio of the input, stretch the image to
|
||||
* the exact `width` and/or `height` provided via `resize`.
|
||||
* @returns {Sharp}
|
||||
*/
|
||||
function ignoreAspectRatio () {
|
||||
this.options.canvas = 'ignore_aspect';
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*
|
||||
* @param {Boolean} [withoutEnlargement=true]
|
||||
* @returns {Sharp}
|
||||
*/
|
||||
function withoutEnlargement (withoutEnlargement) {
|
||||
this.options.withoutEnlargement = is.bool(withoutEnlargement) ? withoutEnlargement : true;
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* 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.
|
||||
@@ -373,6 +362,92 @@ function trim (tolerance) {
|
||||
return this;
|
||||
}
|
||||
|
||||
// Deprecated functions
|
||||
|
||||
/**
|
||||
* @deprecated
|
||||
* @private
|
||||
*/
|
||||
function crop (crop) {
|
||||
this.options.canvas = 'crop';
|
||||
if (!is.defined(crop)) {
|
||||
// Default
|
||||
this.options.position = gravity.center;
|
||||
} else if (is.integer(crop) && is.inRange(crop, 0, 8)) {
|
||||
// Gravity (numeric)
|
||||
this.options.position = crop;
|
||||
} else if (is.string(crop) && is.integer(gravity[crop])) {
|
||||
// Gravity (string)
|
||||
this.options.position = gravity[crop];
|
||||
} else if (is.integer(crop) && crop >= strategy.entropy) {
|
||||
// Strategy
|
||||
this.options.position = crop;
|
||||
} else if (is.string(crop) && is.integer(strategy[crop])) {
|
||||
// Strategy (string)
|
||||
this.options.position = strategy[crop];
|
||||
} else {
|
||||
throw is.invalidParameterError('crop', 'valid crop id/name/strategy', crop);
|
||||
}
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* @deprecated
|
||||
* @private
|
||||
*/
|
||||
function embed (embed) {
|
||||
this.options.canvas = 'embed';
|
||||
if (!is.defined(embed)) {
|
||||
// Default
|
||||
this.options.position = gravity.center;
|
||||
} else if (is.integer(embed) && is.inRange(embed, 0, 8)) {
|
||||
// Gravity (numeric)
|
||||
this.options.position = embed;
|
||||
} else if (is.string(embed) && is.integer(gravity[embed])) {
|
||||
// Gravity (string)
|
||||
this.options.position = gravity[embed];
|
||||
} else {
|
||||
throw is.invalidParameterError('embed', 'valid embed id/name', embed);
|
||||
}
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* @deprecated
|
||||
* @private
|
||||
*/
|
||||
function max () {
|
||||
this.options.canvas = 'max';
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* @deprecated
|
||||
* @private
|
||||
*/
|
||||
function min () {
|
||||
this.options.canvas = 'min';
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* @deprecated
|
||||
* @private
|
||||
*/
|
||||
function ignoreAspectRatio () {
|
||||
this.options.canvas = 'ignore_aspect';
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* @deprecated
|
||||
* @private
|
||||
*/
|
||||
function withoutEnlargement (withoutEnlargement) {
|
||||
this.options.withoutEnlargement = is.bool(withoutEnlargement) ? withoutEnlargement : true;
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Decorate the Sharp prototype with resize-related functions.
|
||||
* @private
|
||||
@@ -380,12 +455,6 @@ function trim (tolerance) {
|
||||
module.exports = function (Sharp) {
|
||||
[
|
||||
resize,
|
||||
crop,
|
||||
embed,
|
||||
max,
|
||||
min,
|
||||
ignoreAspectRatio,
|
||||
withoutEnlargement,
|
||||
extend,
|
||||
extract,
|
||||
trim
|
||||
@@ -396,4 +465,13 @@ module.exports = function (Sharp) {
|
||||
Sharp.gravity = gravity;
|
||||
Sharp.strategy = strategy;
|
||||
Sharp.kernel = kernel;
|
||||
Sharp.fit = fit;
|
||||
Sharp.position = position;
|
||||
// Deprecated functions, to be removed in v0.22.0
|
||||
Sharp.prototype.crop = deprecate(crop, 'crop(position) is deprecated, use resize({ fit: "cover", position }) instead');
|
||||
Sharp.prototype.embed = deprecate(embed, 'embed(position) is deprecated, use resize({ fit: "contain", position }) instead');
|
||||
Sharp.prototype.max = deprecate(max, 'max() is deprecated, use resize({ fit: "inside" }) instead');
|
||||
Sharp.prototype.min = deprecate(min, 'min() is deprecated, use resize({ fit: "outside" }) instead');
|
||||
Sharp.prototype.ignoreAspectRatio = deprecate(ignoreAspectRatio, 'ignoreAspectRatio() is deprecated, use resize({ fit: "fill" }) instead');
|
||||
Sharp.prototype.withoutEnlargement = deprecate(withoutEnlargement, 'withoutEnlargement() is deprecated, use resize({ withoutEnlargement: true }) instead');
|
||||
};
|
||||
|
||||
Reference in New Issue
Block a user