sharp/docs/api-composite.md

composite

composite(images) ⇒ Sharp

Composite image(s) over the processed (resized, extracted etc.) image.

The images to composite must be the same size or smaller than the processed image. If both top and left options are provided, they take precedence over gravity.

Any resize, rotate or extract operations in the same processing pipeline will always be applied to the input image before composition.

The blend option can be one of clear, source, over, in, out, atop, dest, dest-over, dest-in, dest-out, dest-atop, xor, add, saturate, multiply, screen, overlay, darken, lighten, colour-dodge, color-dodge, colour-burn,color-burn, hard-light, soft-light, difference, exclusion.

More information about blend modes can be found at https://www.libvips.org/API/current/libvips-conversion.html#VipsBlendMode and https://www.cairographics.org/operators/

Throws:

• Error Invalid parameters

Since: 0.22.0

Param	Type	Default	Description
images	Array.<Object>		Ordered list of images to composite
[images[].input]	Buffer | String		Buffer containing image data, String containing the path to an image file, or Create object (see below)
[images[].input.create]	Object		describes a blank overlay to be created.
[images[].input.create.width]	Number
[images[].input.create.height]	Number
[images[].input.create.channels]	Number		3-4
[images[].input.create.background]	String | Object		parsed by the color module to extract values for red, green, blue and alpha.
[images[].input.text]	Object		describes a new text image to be created.
[images[].input.text.text]	string		text to render as a UTF-8 string. It can contain Pango markup, for example <i>Le</i>Monde.
[images[].input.text.font]	string		font name to render with.
[images[].input.text.fontfile]	string		absolute filesystem path to a font file that can be used by font.
[images[].input.text.width]	number	0	integral number of pixels to word-wrap at. Lines of text wider than this will be broken at word boundaries.
[images[].input.text.height]	number	0	integral number of pixels high. When defined, dpi will be ignored and the text will automatically fit the pixel resolution defined by width and height. Will be ignored if width is not specified or set to 0.
[images[].input.text.align]	string	"'left'"	text alignment ('left', 'centre', 'center', 'right').
[images[].input.text.justify]	boolean	false	set this to true to apply justification to the text.
[images[].input.text.dpi]	number	72	the resolution (size) at which to render the text. Does not take effect if height is specified.
[images[].input.text.rgba]	boolean	false	set this to true to enable RGBA output. This is useful for colour emoji rendering, or support for Pango markup features like <span foreground="red">Red!</span>.
[images[].input.text.spacing]	number	0	text line height in points. Will use the font line height if none is specified.
[images[].blend]	String	'over'	how to blend this image with the image below.
[images[].gravity]	String	'centre'	gravity at which to place the overlay.
[images[].top]	Number		the pixel offset from the top edge.
[images[].left]	Number		the pixel offset from the left edge.
[images[].tile]	Boolean	false	set to true to repeat the overlay image across the entire image with the given gravity.
[images[].premultiplied]	Boolean	false	set to true to avoid premultiplying the image below. Equivalent to the --premultiplied vips option.
[images[].density]	Number	72	number representing the DPI for vector overlay image.
[images[].raw]	Object		describes overlay when using raw pixel data.
[images[].raw.width]	Number
[images[].raw.height]	Number
[images[].raw.channels]	Number
[images[].animated]	boolean	false	Set to true to read all frames/pages of an animated image.
[images[].failOn]	string	"'warning'"	@see constructor parameters
[images[].limitInputPixels]	number | boolean	268402689	@see constructor parameters

Example

await sharp(background)
  .composite([
    { input: layer1, gravity: 'northwest' },
    { input: layer2, gravity: 'southeast' },
  ])
  .toFile('combined.png');

Example

const output = await sharp('input.gif', { animated: true })
  .composite([
    { input: 'overlay.png', tile: true, blend: 'saturate' }
  ])
  .toBuffer();

Example

sharp('input.png')
  .rotate(180)
  .resize(300)
  .flatten( { background: '#ff6600' } )
  .composite([{ input: 'overlay.png', 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!
  });