Deprecate background, add op-specific prop to resize/extend/flatten #1392

lib/resize.js

@@ -130,18 +130,18 @@ const mapFitToCanvas = {
  *   });
  *
  * @example
- * sharp(inputBuffer)
+ * sharp(input)
  *   .resize(200, 300, {
  *     kernel: sharp.kernel.nearest,
  *     fit: 'contain',
- *     position: 'right top'
+ *     position: 'right top',
+ *     background: { r: 255, g: 255, b: 255, alpha: 0.5 }
  *   })
- *   .background('white')
- *   .toFile('output.tiff')
+ *   .toFile('output.png')
  *   .then(() => {
- *     // output.tiff is a 200 pixels wide and 300 pixels high image
+ *     // output.png is a 200 pixels wide and 300 pixels high image
  *     // containing a nearest-neighbour scaled version
- *     // embedded in the north-east corner of a white canvas
+ *     // contained within the north-east corner of a semi-transparent white canvas
  *   });
  *
  * @example
@@ -159,7 +159,7 @@ const mapFitToCanvas = {
  *   .pipe(writableStream);
  *
  * @example
- * sharp(inputBuffer)
+ * sharp(input)
  *   .resize(200, 200, {
  *     fit: sharp.fit.inside,
  *     withoutEnlargement: true
@@ -178,6 +178,7 @@ const mapFitToCanvas = {
  * @param {String} [options.height] - alternative means of specifying `height`. If both are present this take priority.
  * @param {String} [options.fit='cover'] - how the image should be resized to fit both provided dimensions, one of `cover`, `contain`, `fill`, `inside` or `outside`.
  * @param {String} [options.position='centre'] - position, gravity or strategy to use when `fit` is `cover` or `contain`.
+ * @param {String|Object} [options.background={r: 0, g: 0, b: 0, alpha: 1}] - background colour when using a `fit` of `contain`, parsed by the [color](https://www.npmjs.org/package/color) module, defaults to black without transparency.
  * @param {String} [options.kernel='lanczos3'] - the kernel to use for image reduction.
  * @param {Boolean} [options.withoutEnlargement=false] - do not enlarge if the width *or* height are already less than the specified dimensions, equivalent to GraphicsMagick's `>` geometry option.
  * @param {Boolean} [options.fastShrinkOnLoad=true] - take greater advantage of the JPEG and WebP shrink-on-load feature, which can lead to a slight moiré pattern on some images.
@@ -234,6 +235,10 @@ function resize (width, height, options) {
         throw is.invalidParameterError('position', 'valid position/gravity/strategy', options.position);
       }
     }
+    // Background
+    if (is.defined(options.background)) {
+      this._setColourOption('resizeBackground', options.background);
+    }
     // Kernel
     if (is.defined(options.kernel)) {
       if (is.string(kernel[options.kernel])) {
@@ -255,7 +260,7 @@ function resize (width, height, options) {
 }
 
 /**
- * Extends/pads the edges of the image with the colour provided to the `background` method.
+ * Extends/pads the edges of the image with the provided background colour.
  * This operation will always occur after resizing and extraction, if any.
  *
  * @example
@@ -263,8 +268,14 @@ function resize (width, height, options) {
  * // to the top, left and right edges and 20 to the bottom edge
  * sharp(input)
  *   .resize(140)
- *   .background({r: 0, g: 0, b: 0, alpha: 0})
- *   .extend({top: 10, bottom: 20, left: 10, right: 10})
+ *   .)
+ *   .extend({
+ *     top: 10,
+ *     bottom: 20,
+ *     left: 10,
+ *     right: 10
+ *     background: { r: 0, g: 0, b: 0, alpha: 0 }
+ *   })
  *   ...
  *
  * @param {(Number|Object)} extend - single pixel count to add to all edges or an Object with per-edge counts
@@ -272,6 +283,7 @@ function resize (width, height, options) {
  * @param {Number} [extend.left]
  * @param {Number} [extend.bottom]
  * @param {Number} [extend.right]
+ * @param {String|Object} [extend.background={r: 0, g: 0, b: 0, alpha: 1}] - background colour, parsed by the [color](https://www.npmjs.org/package/color) module, defaults to black without transparency.
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
 */
@@ -292,6 +304,7 @@ function extend (extend) {
     this.options.extendBottom = extend.bottom;
     this.options.extendLeft = extend.left;
     this.options.extendRight = extend.right;
+    this._setColourOption('extendBackground', extend.background);
   } else {
     throw new Error('Invalid edge extension ' + extend);
   }