diff --git a/docs/api-resize.md b/docs/api-resize.md index f6d96bbdf..ed70c7f56 100644 --- a/docs/api-resize.md +++ b/docs/api-resize.md @@ -2,7 +2,7 @@ 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. +- `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. @@ -42,18 +42,18 @@ Previous calls to `resize` in the same pipeline will be ignored. | Param | Type | Default | Description | | --- | --- | --- | --- | -| [width] | number | | pixels wide the resultant image should be. Use `null` or `undefined` to auto-scale the width to match the height. | -| [height] | number | | pixels high the resultant image should be. Use `null` or `undefined` to auto-scale the height to match the width. | +| [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] | String | | alternative means of specifying `width`. If both are present this takes priority. | -| [options.height] | String | | alternative means of specifying `height`. If both are present this takes priority. | -| [options.fit] | String | 'cover' | how the image should be resized to fit both provided dimensions, one of `cover`, `contain`, `fill`, `inside` or `outside`. | -| [options.position] | String | 'centre' | position, gravity or strategy to use when `fit` is `cover` or `contain`. | +| [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](https://www.npmjs.org/package/color) module, defaults to black without transparency. | -| [options.kernel] | String | 'lanczos3' | the kernel to use for image reduction. Use the `fastShrinkOnLoad` option to control kernel vs shrink-on-load. | -| [options.withoutEnlargement] | Boolean | false | do not enlarge if the width *or* height are already less than the specified dimensions, equivalent to GraphicsMagick's `>` geometry option. | -| [options.withoutReduction] | Boolean | false | do not reduce if the width *or* height are already greater than the specified dimensions, equivalent to GraphicsMagick's `<` geometry option. | -| [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. | +| [options.kernel] | String | 'lanczos3' | The kernel to use for image reduction. 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** ```js diff --git a/lib/index.d.ts b/lib/index.d.ts index 2c6aa585d..d5dbb0be6 100644 --- a/lib/index.d.ts +++ b/lib/index.d.ts @@ -764,7 +764,7 @@ declare namespace sharp { * @throws {Error} Invalid parameters * @returns A sharp instance that can be used to chain operations */ - resize(width?: number | null, height?: number | null, options?: ResizeOptions): Sharp; + resize(widthOrOptions?: number | ResizeOptions | null, height?: number | null, options?: ResizeOptions): Sharp; /** * Shorthand for resize(null, null, options); diff --git a/lib/resize.js b/lib/resize.js index aa7a22a76..41001f9af 100644 --- a/lib/resize.js +++ b/lib/resize.js @@ -118,7 +118,7 @@ function isResizeExpected (options) { * 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. + * - `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. @@ -231,32 +231,32 @@ function isResizeExpected (options) { * .toBuffer() * ); * - * @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 {number} [width] - How many pixels wide the resultant image should be. Use `null` or `undefined` to auto-scale the width to match the height. + * @param {number} [height] - How many 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 takes priority. - * @param {String} [options.height] - alternative means of specifying `height`. If both are present this takes 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 {number} [options.width] - An alternative means of specifying `width`. If both are present this takes priority. + * @param {number} [options.height] - An alternative means of specifying `height`. If both are present this takes priority. + * @param {String} [options.fit='cover'] - How the image should be resized/cropped to fit the target dimension(s), one of `cover`, `contain`, `fill`, `inside` or `outside`. + * @param {String} [options.position='centre'] - A position, gravity or strategy to use when `fit` is `cover` or `contain`. * @param {String|Object} [options.background={r: 0, g: 0, b: 0, alpha: 1}] - background colour when `fit` is `contain`, parsed by the [color](https://www.npmjs.org/package/color) module, defaults to black without transparency. - * @param {String} [options.kernel='lanczos3'] - the kernel to use for image reduction. Use the `fastShrinkOnLoad` option to control kernel vs shrink-on-load. - * @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.withoutReduction=false] - do not reduce if the width *or* height are already greater 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 or round-down of an auto-scaled dimension. + * @param {String} [options.kernel='lanczos3'] - The kernel to use for image reduction. Use the `fastShrinkOnLoad` option to control kernel vs shrink-on-load. + * @param {Boolean} [options.withoutEnlargement=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. + * @param {Boolean} [options.withoutReduction=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. + * @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 or round-down of an auto-scaled dimension. * @returns {Sharp} * @throws {Error} Invalid parameters */ -function resize (width, height, options) { +function resize (widthOrOptions, height, options) { if (isResizeExpected(this.options)) { this.options.debuglog('ignoring previous resize options'); } - if (is.defined(width)) { - if (is.object(width) && !is.defined(options)) { - options = width; - } else if (is.integer(width) && width > 0) { - this.options.width = width; + if (is.defined(widthOrOptions)) { + if (is.object(widthOrOptions) && !is.defined(options)) { + options = widthOrOptions; + } else if (is.integer(widthOrOptions) && widthOrOptions > 0) { + this.options.width = widthOrOptions; } else { - throw is.invalidParameterError('width', 'positive integer', width); + throw is.invalidParameterError('width', 'positive integer', widthOrOptions); } } else { this.options.width = -1;