diff --git a/docs/api-resize.md b/docs/api-resize.md index 80252ff3..f6d96bbd 100644 --- a/docs/api-resize.md +++ b/docs/api-resize.md @@ -146,7 +146,8 @@ const scaleByHalf = await sharp(input) ## extend -Extends/pads the edges of the image with the provided background colour. +Extend / pad / extrude one or more edges of the image with either +the provided background colour or pixels derived from the image. This operation will always occur after resizing and extraction, if any. @@ -162,6 +163,7 @@ This operation will always occur after resizing and extraction, if any. | [extend.left] | number | 0 | | | [extend.bottom] | number | 0 | | | [extend.right] | number | 0 | | +| [extend.extendWith] | String | 'background' | populate new pixels using this method, one of: background, copy, repeat, mirror. | | [extend.background] | String \| Object | {r: 0, g: 0, b: 0, alpha: 1} | background colour, parsed by the [color](https://www.npmjs.org/package/color) module, defaults to black without transparency. | **Example** @@ -189,6 +191,16 @@ sharp(input) }) ... ``` +**Example** +```js +// Extrude image by 8 pixels to the right, mirroring existing right hand edge +sharp(input) + .extend({ + right: 8, + background: 'mirror' + }) + ... +``` ## extract diff --git a/docs/changelog.md b/docs/changelog.md index d579c9dc..898587fd 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -49,6 +49,10 @@ Requires libvips v8.14.0 [#3548](https://github.com/lovell/sharp/pull/3548) [@kapouer](https://github.com/kapouer) +* Add support to `extend` operation for `extendWith` to allow copy/mirror/repeat. + [#3556](https://github.com/lovell/sharp/pull/3556) + [@janaz](https://github.com/janaz) + ## v0.31 - *eagle* Requires libvips v8.13.3 diff --git a/docs/humans.txt b/docs/humans.txt index d43e700e..6f5be3dc 100644 --- a/docs/humans.txt +++ b/docs/humans.txt @@ -266,3 +266,6 @@ GitHub: https://github.com/marcosc90 Name: Emanuel Jöbstl GitHub: https://github.com/ejoebstl + +Name: Tomasz Janowski +GitHub: https://github.com/janaz diff --git a/lib/index.d.ts b/lib/index.d.ts index bc0e881e..ecacde4d 100644 --- a/lib/index.d.ts +++ b/lib/index.d.ts @@ -755,7 +755,8 @@ declare namespace sharp { resize(options: ResizeOptions): Sharp; /** - * Extends/pads the edges of the image with either the provided background colour or pixels derived from the image. + * Extend / pad / extrude one or more edges of the image with either + * the provided background colour or pixels derived from the image. * This operation will always occur after resizing and extraction, if any. * @param extend single pixel count to add to all edges or an Object with per-edge counts * @throws {Error} Invalid parameters diff --git a/lib/resize.js b/lib/resize.js index 3c8544ec..e2222416 100644 --- a/lib/resize.js +++ b/lib/resize.js @@ -334,7 +334,8 @@ function resize (width, height, options) { } /** - * Extends/pads the edges of the image with the provided background colour. + * Extend / pad / extrude one or more edges of the image with either + * the provided background colour or pixels derived from the image. * This operation will always occur after resizing and extraction, if any. * * @example @@ -360,11 +361,21 @@ function resize (width, height, options) { * }) * ... * + * @example + * // Extrude image by 8 pixels to the right, mirroring existing right hand edge + * sharp(input) + * .extend({ + * right: 8, + * background: 'mirror' + * }) + * ... + * * @param {(number|Object)} extend - single pixel count to add to all edges or an Object with per-edge counts * @param {number} [extend.top=0] * @param {number} [extend.left=0] * @param {number} [extend.bottom=0] * @param {number} [extend.right=0] + * @param {String} [extend.extendWith='background'] - populate new pixels using this method, one of: background, copy, repeat, mirror. * @param {String|Object} [extend.background={r: 0, g: 0, b: 0, alpha: 1}] - background colour, parsed by the [color](https://www.npmjs.org/package/color) module, defaults to black without transparency. * @returns {Sharp} * @throws {Error} Invalid parameters @@ -409,7 +420,7 @@ function extend (extend) { if (is.string(extendWith[extend.extendWith])) { this.options.extendWith = extendWith[extend.extendWith]; } else { - throw is.invalidParameterError('extendWith', 'valid value', extend.extendWith); + throw is.invalidParameterError('extendWith', 'one of: background, copy, repeat, mirror', extend.extendWith); } } } else { diff --git a/test/unit/extend.js b/test/unit/extend.js index ef77cddc..2ce2abb2 100644 --- a/test/unit/extend.js +++ b/test/unit/extend.js @@ -147,7 +147,7 @@ describe('Extend', function () { it('invalid extendWith fails', () => { assert.throws( () => sharp().extend({ extendWith: 'invalid-value' }), - /Expected valid value for extendWith but received invalid-value of type string/ + /Expected one of: background, copy, repeat, mirror for extendWith but received invalid-value of type string/ ); }); it('can set all edges apart from right', () => {