repo_description: High performance Node.js image processing, the fastest module to resize JPEG, PNG, WebP, AVIF and TIFF images. Uses the libvips library.
repo_topics: avif crop exif icc image image-processing javascript jpeg libvips nodejs performance png resize sharp svg tiff webp
code: /*!
    Copyright 2013 Lovell Fuller and others.
    SPDX-License-Identifier: Apache-2.0
  */
  
  const is = require('./is');
  
  /**
   * Blend modes.
   * @member
   * @private
   */
  const blend = {
    clear: 'clear',
    source: 'source',
    over: 'over',
    in: 'in',
    out: 'out',
    atop: 'atop',
    dest: 'dest',
    'dest-over': 'dest-over',
    'dest-in': 'dest-in',
    'dest-out': 'dest-out',
    'dest-atop': 'dest-atop',
    xor: 'xor',
    add: 'add',
    saturate: 'saturate',
    multiply: 'multiply',
    screen: 'screen',
    overlay: 'overlay',
    darken: 'darken',
    lighten: 'lighten',
    'colour-dodge': 'colour-dodge',
    'color-dodge': 'colour-dodge',
    'colour-burn': 'colour-burn',
    'color-burn': 'colour-burn',
    'hard-light': 'hard-light',
    'soft-light': 'soft-light',
    difference: 'difference',
    exclusion: 'exclusion'
  };
  
  /**
   * 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`.
   *
   * Other operations in the same processing pipeline (e.g. resize, rotate, flip,
   * flop, extract) 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/enum.BlendMode.html
   * and https://www.cairographics.org/operators/
   *
   * @since 0.22.0
   *
   * @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!
   *   });
   *
   * @param {Object[]} images - Ordered list of images to composite
   * @param {Buffer|String} [images[].input] - Buffer containing image data, String containing the path to an image file, or Create object (see below)
   * @param {Object} [images[].input.create] - describes a blank overlay to be created.
   * @param {Number} [images[].input.create.width]
   * @param {Number} [images[].input.create.height]
   * @param {Number} [images[].input.create.channels] - 3-4
   * @param {String|Object} [images[].input.create.background] - parsed by the [color](https://www.npmjs.org/package/color) module to extract values for red, green, blue and alpha.
   * @param {Object} [images[].input.text] - describes a new text image to be created.
   * @param {string} [images[].input.text.text] - text to render as a UTF-8 string. It can contain Pango markup, for example `<i>Le</i>Monde`.
   * @param {string} [images[].input.text.font] - font name to render with.
   * @param {string} [images[].input.text.fontfile] - absolute filesystem path to a font file that can be used by `font`.
   * @param {number} [images[].input.text.width=0] - integral number of pixels to word-wrap at. Lines of text wider than this will be broken at word boundaries.
   * @param {number} [images[].input.text.height=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.
   * @param {string} [images[].input.text.align='left'] - text alignment (`'left'`, `'centre'`, `'center'`, `'right'`).
   * @param {boolean} [images[].input.text.justify=false] - set this to true to apply justification to the text.
   * @param {number} [images[].input.text.dpi=72] - the resolution (size) at which to render the text. Does not take effect if `height` is specified.
   * @param {boolean} [images[].input.text.rgba=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>`.
   * @param {number} [images[].input.text.spacing=0] - text line height in points. Will use the font line height if none is specified.
   * @param {Boolean} [images[].autoOrient=false] - set to true to use EXIF orientation data, if present, to orient the image.
   * @param {String} [images[].blend='over'] - how to blend this image with the image below.
   * @param {String} [images[].gravity='centre'] - gravity at which to place the overlay.
   * @param {Number} [images[].top] - the pixel offset from the top edge.
   * @param {Number} [images[].left] - the pixel offset from the left edge.
   * @param {Boolean} [images[].tile=false] - set to true to repeat the overlay image across the entire image with the given `gravity`.
   * @param {Boolean} [images[].premultiplied=false] - set to true to avoid premultiplying the image below. Equivalent to the `--premultiplied` vips option.
   * @param {Number} [images[].density=72] - number representing the DPI for vector overlay image.
   * @param {Object} [images[].raw] - describes overlay when using raw pixel data.
   * @param {Number} [images[].raw.width]
   * @param {Number} [images[].raw.height]
   * @param {Number} [images[].raw.channels]
   * @param {boolean} [images[].animated=false] - Set to `true` to read all frames/pages of an animated image.
   * @param {string} [images[].failOn='warning'] - @see {@link /api-constructor/ constructor parameters}
   * @param {number|boolean} [images[].limitInputPixels=[REDACTED_SSN]] - @see {@link /api-constructor/ constructor parameters}
   * @returns {Sharp}
   * @throws {Error} Invalid parameters
   */
  function composite (images) {
    if (!Array.isArray(images)) {
      throw is.invalidParameterError('images to composite', 'array', images);
    }
    this.options.composite = images.map(image => {
      if (!is.object(image)) {
        throw is.invalidParameterError('image to composite', 'object', image);
      }
      const inputOptions = this._inputOptionsFromObject(image);
      const composite = {
        input: this._createInputDescriptor(image.input, inputOptions, { allowStream: false }),
        blend: 'over',
        tile: false,
        left: 0,
        top: 0,
        hasOffset: false,
        gravity: 0,
        premultiplied: false
      };
      if (is.defined(image.blend)) {
        if (is.string(blend[image.blend])) {
          composite.blend = blend[image.blend];
        } else {
          throw is.invalidParameterError('blend', 'valid blend name', image.blend);
        }
      }
      if (is.defined(image.tile)) {
        if (is.bool(image.tile)) {
          composite.tile = image.tile;
        } else {
          throw is.invalidParameterError('tile', 'boolean', image.tile);
        }
      }
      if (is.defined(image.left)) {
        if (is.integer(image.left)) {
          composite.left = image.left;
        } else {
          throw is.invalidParameterError('left', 'integer', image.left);
        }
      }
      if (is.defined(image.top)) {
        if (is.integer(image.top)) {
          composite.top = image.top;
        } else {
          throw is.invalidParameterError('top', 'integer', image.top);
        }
      }
      if (is.defined(image.top) !== is.defined(image.left)) {
        throw new Error('Expected both left and top to be set');
      } else {
        composite.hasOffset = is.integer(image.top) && is.integer(image.left);
      }
      if (is.defined(image.gravity)) {
        if (is.integer(image.gravity) && is.inRange(image.gravity, 0, 8)) {
          composite.gravity = image.gravity;
        } else if (is.string(image.gravity) && is.integer(this.constructor.gravity[image.gravity])) {
          composite.gravity = this.constructor.gravity[image.gravity];
        } else {
          throw is.invalidParameterError('gravity', 'valid gravity', image.gravity);
        }
      }
      if (is.defined(image.premultiplied)) {
        if (is.bool(image.premultiplied)) {
          composite.premultiplied = image.premultiplied;
        } else {
          throw is.invalidParameterError('premultiplied', 'boolean', image.premultiplied);
        }
      }
      return composite;
    });
    return this;
  }
  
  /**
   * Decorate the Sharp prototype with composite-related functions.
   * @module Sharp
   * @private
   */
  module.exports = (Sharp) => {
    Sharp.prototype.composite = composite;
    Sharp.blend = blend;
  };
  