mirror of
https://github.com/lovell/sharp.git
synced 2025-07-09 18:40:16 +02:00
69 lines
3.1 KiB
Markdown
69 lines
3.1 KiB
Markdown
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
|
|
|
|
## overlayWith
|
|
|
|
Overlay (composite) an image over the processed (resized, extracted etc.) image.
|
|
|
|
The overlay image must be the same size or smaller than the processed image.
|
|
If both `top` and `left` options are provided, they take precedence over `gravity`.
|
|
|
|
If the overlay image contains an alpha channel then composition with premultiplication will occur.
|
|
|
|
### Parameters
|
|
|
|
- `overlay` **([Buffer][1] \| [String][2])** Buffer containing image data or String containing the path to an image file.
|
|
- `options` **[Object][3]?**
|
|
- `options.gravity` **[String][2]** gravity at which to place the overlay. (optional, default `'centre'`)
|
|
- `options.top` **[Number][4]?** the pixel offset from the top edge.
|
|
- `options.left` **[Number][4]?** the pixel offset from the left edge.
|
|
- `options.tile` **[Boolean][5]** set to true to repeat the overlay image across the entire image with the given `gravity`. (optional, default `false`)
|
|
- `options.cutout` **[Boolean][5]** set to true to apply only the alpha channel of the overlay image to the input image, giving the appearance of one image being cut out of another. (optional, default `false`)
|
|
- `options.density` **[Number][4]** number representing the DPI for vector overlay image. (optional, default `72`)
|
|
- `options.raw` **[Object][3]?** describes overlay when using raw pixel data.
|
|
- `options.raw.width` **[Number][4]?**
|
|
- `options.raw.height` **[Number][4]?**
|
|
- `options.raw.channels` **[Number][4]?**
|
|
- `options.create` **[Object][3]?** describes a blank overlay to be created.
|
|
- `options.create.width` **[Number][4]?**
|
|
- `options.create.height` **[Number][4]?**
|
|
- `options.create.channels` **[Number][4]?** 3-4
|
|
- `options.create.background` **([String][2] \| [Object][3])?** parsed by the [color][6] module to extract values for red, green, blue and alpha.
|
|
|
|
### Examples
|
|
|
|
```javascript
|
|
sharp('input.png')
|
|
.rotate(180)
|
|
.resize(300)
|
|
.flatten()
|
|
.background('#ff6600')
|
|
.overlayWith('overlay.png', { gravity: sharp.gravity.southeast } )
|
|
.sharpen()
|
|
.withMetadata()
|
|
.webp( { quality: 90 } )
|
|
.toBuffer()
|
|
.then(function(outputBuffer) {
|
|
// outputBuffer contains upside down, 300px wide, alpha channel flattened
|
|
// onto orange background, composited with overlay.png with SE gravity,
|
|
// sharpened, with metadata, 90% quality WebP image data. Phew!
|
|
});
|
|
```
|
|
|
|
- Throws **[Error][7]** Invalid parameters
|
|
|
|
Returns **Sharp**
|
|
|
|
[1]: https://nodejs.org/api/buffer.html
|
|
|
|
[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
|
|
|
|
[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
|
|
|
|
[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
|
|
|
|
[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
|
|
|
|
[6]: https://www.npmjs.org/package/color
|
|
|
|
[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error
|