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', () => {