api-composite.md

composite

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.

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/

Parameters

• 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 integral number of pixels to word-wrap at. Lines of text wider than this will be broken at word boundaries. (optional, default 0)
      • images[].input.text.height number 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. (optional, default 0)
      • images[].input.text.align string text alignment ('left', 'centre', 'center', 'right'). (optional, default 'left')
      • images[].input.text.justify boolean set this to true to apply justification to the text. (optional, default false)
      • images[].input.text.dpi number the resolution (size) at which to render the text. Does not take effect if height is specified. (optional, default 72)
      • images[].input.text.rgba boolean 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>. (optional, default false)
      • images[].input.text.spacing number text line height in points. Will use the font line height if none is specified. (optional, default 0)

  • images[].blend String how to blend this image with the image below. (optional, default 'over')

  • images[].gravity String gravity at which to place the overlay. (optional, default 'centre')

  • images[].top Number? the pixel offset from the top edge.

  • images[].left Number? the pixel offset from the left edge.

  • images[].tile Boolean set to true to repeat the overlay image across the entire image with the given gravity. (optional, default false)

  • images[].premultiplied Boolean set to true to avoid premultipling the image below. Equivalent to the --premultiplied vips option. (optional, default false)

  • images[].density Number number representing the DPI for vector overlay image. (optional, default 72)

  • 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 Set to true to read all frames/pages of an animated image. (optional, default false)

  • images[].failOn string @see constructor parameters (optional, default 'warning')

  • images[].limitInputPixels (number | boolean) @see constructor parameters (optional, default 268402689)

Examples

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

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

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!
  });

• Throws Error Invalid parameters

Returns Sharp

Meta

• since: 0.22.0