Create blank image (width, height, channels, background) #470

lib/composite.js

@@ -38,6 +38,11 @@ const is = require('./is');
  * @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.
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */

lib/constructor.js

@@ -54,16 +54,35 @@ let versions = {
  *   });
  * readableStream.pipe(transformer).pipe(writableStream);
  *
+ * @example
+ * // Create a blank 300x200 PNG image of semi-transluent red pixels
+ * sharp(null, {
+ *   create: {
+ *     width: 300,
+ *     height: 200,
+ *     channels: 4,
+ *     background: { r: 255, g: 0, b: 0, alpha: 128 }
+ *   }
+ * })
+ * .png()
+ * .toBuffer()
+ * .then( ... );
+ *
  * @param {(Buffer|String)} [input] - if present, can be
  *  a Buffer containing JPEG, PNG, WebP, GIF, SVG, TIFF or raw pixel image data, or
  *  a String containing the path to an JPEG, PNG, WebP, GIF, SVG or TIFF image file.
  *  JPEG, PNG, WebP, GIF, SVG, TIFF or raw pixel image data can be streamed into the object when null or undefined.
  * @param {Object} [options] - if present, is an Object with optional attributes.
  * @param {Number} [options.density=72] - integral number representing the DPI for vector images.
- * @param {Object} [options.raw] - describes raw pixel image data. See `raw()` for pixel ordering.
+ * @param {Object} [options.raw] - describes raw pixel input image data. See `raw()` for pixel ordering.
  * @param {Number} [options.raw.width]
  * @param {Number} [options.raw.height]
- * @param {Number} [options.raw.channels]
+ * @param {Number} [options.raw.channels] - 1-4
+ * @param {Object} [options.create] - describes a new image 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.
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */

lib/input.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const util = require('util');
+const color = require('color');
 const is = require('./is');
 const sharp = require('../build/Release/sharp.node');
 
@@ -46,6 +47,30 @@ const _createInputDescriptor = function _createInputDescriptor (input, inputOpti
         throw new Error('Expected width, height and channels for raw pixel input');
       }
     }
+    // Create new image
+    if (is.defined(inputOptions.create)) {
+      if (
+        is.object(inputOptions.create) &&
+        is.integer(inputOptions.create.width) && is.inRange(inputOptions.create.width, 1, this.constructor.maximum.width) &&
+        is.integer(inputOptions.create.height) && is.inRange(inputOptions.create.height, 1, this.constructor.maximum.height) &&
+        is.integer(inputOptions.create.channels) && is.inRange(inputOptions.create.channels, 3, 4) &&
+        is.defined(inputOptions.create.background)
+      ) {
+        inputDescriptor.createWidth = inputOptions.create.width;
+        inputDescriptor.createHeight = inputOptions.create.height;
+        inputDescriptor.createChannels = inputOptions.create.channels;
+        const background = color(inputOptions.create.background);
+        inputDescriptor.createBackground = [
+          background.red(),
+          background.green(),
+          background.blue(),
+          Math.round(background.alpha() * 255)
+        ];
+        delete inputDescriptor.buffer;
+      } else {
+        throw new Error('Expected width, height, channels and background to create a new input image');
+      }
+    }
   } else if (is.defined(inputOptions)) {
     throw new Error('Invalid input options ' + inputOptions);
   }