Add composite op, supporting multiple images and blend modes #728

lib/composite.js

@@ -1,21 +1,66 @@
 'use strict';
 
+const deprecate = require('util').deprecate;
+
 const is = require('./is');
 
 /**
- * Overlay (composite) an image over the processed (resized, extracted etc.) image.
+ * 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 overlay image must be the same size or smaller than the processed 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`.
  *
- * If the overlay image contains an alpha channel then composition with premultiplication will occur.
+ * 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://libvips.github.io/libvips/API/current/libvips-conversion.html#VipsBlendMode
+ * and https://www.cairographics.org/operators/
  *
  * @example
  * sharp('input.png')
  *   .rotate(180)
  *   .resize(300)
  *   .flatten( { background: '#ff6600' } )
- *   .overlayWith('overlay.png', { gravity: sharp.gravity.southeast } )
+ *   .composite([{ input: 'overlay.png', gravity: 'southeast' }])
  *   .sharpen()
  *   .withMetadata()
  *   .webp( { quality: 90 } )
@@ -26,70 +71,104 @@ const is = require('./is');
  *     // sharpened, with metadata, 90% quality WebP image data. Phew!
  *   });
  *
- * @param {(Buffer|String)} [overlay] - Buffer containing image data or String containing the path to an image file.
- * @param {Object} [options]
- * @param {String} [options.gravity='centre'] - gravity at which to place the overlay.
- * @param {Number} [options.top] - the pixel offset from the top edge.
- * @param {Number} [options.left] - the pixel offset from the left edge.
- * @param {Boolean} [options.tile=false] - set to true to repeat the overlay image across the entire image with the given `gravity`.
- * @param {Boolean} [options.cutout=false] - 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.
- * @param {Number} [options.density=72] - number representing the DPI for vector overlay image.
- * @param {Object} [options.raw] - describes overlay when using raw pixel data.
- * @param {Number} [options.raw.width]
- * @param {Number} [options.raw.height]
- * @param {Number} [options.raw.channels]
- * @param {Object} [options.create] - describes a blank overlay to be created.
- * @param {Number} [options.create.width]
- * @param {Number} [options.create.height]
- * @param {Number} [options.create.channels] - 3-4
- * @param {String|Object} [options.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 - Ordered list of images to composite
+ * @param {Buffer|String} [images[].input] - Buffer containing image data or String containing the path to an image file.
+ * @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 {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 {Object} [images[].create] - describes a blank overlay to be created.
+ * @param {Number} [images[].create.width]
+ * @param {Number} [images[].create.height]
+ * @param {Number} [images[].create.channels] - 3-4
+ * @param {String|Object} [images[].create.background] - parsed by the [color](https://www.npmjs.org/package/color) module to extract values for red, green, blue and alpha.
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */
-function overlayWith (overlay, options) {
-  this.options.overlay = this._createInputDescriptor(overlay, options, {
-    allowStream: false
-  });
-  if (is.object(options)) {
-    if (is.defined(options.tile)) {
-      if (is.bool(options.tile)) {
-        this.options.overlayTile = options.tile;
-      } else {
-        throw new Error('Invalid overlay tile ' + options.tile);
-      }
-    }
-    if (is.defined(options.cutout)) {
-      if (is.bool(options.cutout)) {
-        this.options.overlayCutout = options.cutout;
-      } else {
-        throw new Error('Invalid overlay cutout ' + options.cutout);
-      }
-    }
-    if (is.defined(options.left) || is.defined(options.top)) {
-      if (is.integer(options.left) && options.left >= 0 && is.integer(options.top) && options.top >= 0) {
-        this.options.overlayXOffset = options.left;
-        this.options.overlayYOffset = options.top;
-      } else {
-        throw new Error('Invalid overlay left ' + options.left + ' and/or top ' + options.top);
-      }
-    }
-    if (is.defined(options.gravity)) {
-      if (is.integer(options.gravity) && is.inRange(options.gravity, 0, 8)) {
-        this.options.overlayGravity = options.gravity;
-      } else if (is.string(options.gravity) && is.integer(this.constructor.gravity[options.gravity])) {
-        this.options.overlayGravity = this.constructor.gravity[options.gravity];
-      } else {
-        throw new Error('Unsupported overlay gravity ' + options.gravity);
-      }
-    }
+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 { raw, density } = image;
+    const inputOptions = (raw || density) ? { raw, density } : undefined;
+    const composite = {
+      input: this._createInputDescriptor(image.input, inputOptions, { allowStream: false }),
+      blend: 'over',
+      tile: false,
+      left: -1,
+      top: -1,
+      gravity: 0
+    };
+    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) && image.left >= 0) {
+        composite.left = image.left;
+      } else {
+        throw is.invalidParameterError('left', 'positive integer', image.left);
+      }
+    }
+    if (is.defined(image.top)) {
+      if (is.integer(image.top) && image.top >= 0) {
+        composite.top = image.top;
+      } else {
+        throw is.invalidParameterError('top', 'positive integer', image.top);
+      }
+    }
+    if (composite.left !== composite.top && Math.min(composite.left, composite.top) === -1) {
+      throw new Error('Expected both left and top to be set');
+    }
+    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);
+      }
+    }
+    return composite;
+  });
   return this;
 }
 
+/**
+ * @deprecated
+ * @private
+ */
+function overlayWith (input, options) {
+  const blend = (is.object(options) && options.cutout) ? 'dest-in' : 'over';
+  return this.composite([Object.assign({ input, blend }, options)]);
+}
+
 /**
  * Decorate the Sharp prototype with composite-related functions.
  * @private
  */
 module.exports = function (Sharp) {
-  Sharp.prototype.overlayWith = overlayWith;
+  Sharp.prototype.composite = composite;
+  Sharp.prototype.overlayWith = deprecate(overlayWith, 'overlayWith(input, options) is deprecated, use composite([{ input, ...options }]) instead');
+  Sharp.blend = blend;
 };

lib/constructor.js

@@ -145,12 +145,7 @@ const Sharp = function (input, options) {
     removeAlpha: false,
     ensureAlpha: false,
     colourspace: 'srgb',
-    // overlay
-    overlayGravity: 0,
-    overlayXOffset: -1,
-    overlayYOffset: -1,
-    overlayTile: false,
-    overlayCutout: false,
+    composite: [],
     // output
     fileOut: '',
     formatOut: 'input',