sharp 0.25.1 → 0.26.0

package/lib/input.js

@@ -4,6 +4,17 @@ const color = require('color');
 const is = require('./is');
 const sharp = require('../build/Release/sharp.node');
 
+/**
+ * Extract input options, if any, from an object.
+ * @private
+ */
+function _inputOptionsFromObject (obj) {
+  const { raw, density, limitInputPixels, sequentialRead, failOnError } = obj;
+  return [raw, density, limitInputPixels, sequentialRead, failOnError].some(is.defined)
+    ? { raw, density, limitInputPixels, sequentialRead, failOnError }
+    : undefined;
+}
+
 /**
  * Create Object containing input and input-related options.
  * @private
@@ -23,12 +34,12 @@ function _createInputDescriptor (input, inputOptions, containerOptions) {
   } else if (is.plainObject(input) && !is.defined(inputOptions)) {
     // Plain Object descriptor, e.g. create
     inputOptions = input;
-    if (is.plainObject(inputOptions.raw) || is.bool(inputOptions.failOnError)) {
-      // Raw Stream
+    if (_inputOptionsFromObject(inputOptions)) {
+      // Stream with options
       inputDescriptor.buffer = [];
     }
   } else if (!is.defined(input) && !is.defined(inputOptions) && is.object(containerOptions) && containerOptions.allowStream) {
-    // Stream
+    // Stream without options
     inputDescriptor.buffer = [];
   } else {
     throw new Error(`Unsupported input '${input}' of type ${typeof input}${
@@ -88,6 +99,13 @@ function _createInputDescriptor (input, inputOptions, containerOptions) {
       }
     }
     // Multi-page input (GIF, TIFF, PDF)
+    if (is.defined(inputOptions.animated)) {
+      if (is.bool(inputOptions.animated)) {
+        inputDescriptor.pages = inputOptions.animated ? -1 : 1;
+      } else {
+        throw is.invalidParameterError('animated', 'boolean', inputOptions.animated);
+      }
+    }
     if (is.defined(inputOptions.pages)) {
       if (is.integer(inputOptions.pages) && is.inRange(inputOptions.pages, -1, 100000)) {
         inputDescriptor.pages = inputOptions.pages;
@@ -102,6 +120,14 @@ function _createInputDescriptor (input, inputOptions, containerOptions) {
         throw is.invalidParameterError('page', 'integer between 0 and 100000', inputOptions.page);
       }
     }
+    // Multi-level input (OpenSlide)
+    if (is.defined(inputOptions.level)) {
+      if (is.integer(inputOptions.level) && is.inRange(inputOptions.level, 0, 256)) {
+        inputDescriptor.level = inputOptions.level;
+      } else {
+        throw is.invalidParameterError('level', 'integer between 0 and 256', inputOptions.level);
+      }
+    }
     // Create new image
     if (is.defined(inputOptions.create)) {
       if (
@@ -136,7 +162,7 @@ function _createInputDescriptor (input, inputOptions, containerOptions) {
  * Handle incoming Buffer chunk on Writable Stream.
  * @private
  * @param {Buffer} chunk
- * @param {String} encoding - unused
+ * @param {string} encoding - unused
  * @param {Function} callback
  */
 function _write (chunk, encoding, callback) {
@@ -172,7 +198,7 @@ function _flattenBufferIn () {
 /**
  * Are we expecting Stream-based input?
  * @private
- * @returns {Boolean}
+ * @returns {boolean}
  */
 function _isStreamInput () {
   return Array.isArray(this.options.input.buffer);
@@ -197,6 +223,7 @@ function _isStreamInput () {
  * - `loop`: Number of times to loop an animated image, zero refers to a continuous loop.
  * - `delay`: Delay in ms between each page in an animated image, provided as an array of integers.
  * - `pagePrimary`: Number of the primary page in a HEIF image
+ * - `levels`: Details of each level in a multi-level image provided as an array of objects, requires libvips compiled with support for OpenSlide
  * - `hasProfile`: Boolean indicating the presence of an embedded ICC profile
  * - `hasAlpha`: Boolean indicating the presence of an alpha transparency channel
  * - `orientation`: Number value of the EXIF Orientation header, if present
@@ -279,6 +306,8 @@ function metadata (callback) {
  *     - `maxY` (y-coordinate of one of the pixel where the maximum lies)
  * - `isOpaque`: Is the image fully opaque? Will be `true` if the image has no alpha channel or if every pixel is fully opaque.
  * - `entropy`: Histogram-based estimation of greyscale entropy, discarding alpha channel if any (experimental)
+ * - `sharpness`: Estimation of greyscale sharpness based on the standard deviation of a Laplacian convolution, discarding alpha channel if any (experimental)
+ * - `dominant`: Object containing most dominant sRGB colour based on a 4096-bin 3D histogram (experimental)
  *
  * @example
  * const image = sharp(inputJpg);
@@ -288,6 +317,10 @@ function metadata (callback) {
  *      // stats contains the channel-wise statistics array and the isOpaque value
  *   });
  *
+ * @example
+ * const { entropy, sharpness, dominant } = await sharp(input).stats();
+ * const { r, g, b } = dominant;
+ *
  * @param {Function} [callback] - called with the arguments `(err, stats)`
  * @returns {Promise<Object>}
  */
@@ -337,6 +370,7 @@ function stats (callback) {
 module.exports = function (Sharp) {
   Object.assign(Sharp.prototype, {
     // Private
+    _inputOptionsFromObject,
     _createInputDescriptor,
     _write,
     _flattenBufferIn,

package/lib/is.js

@@ -21,7 +21,7 @@ const object = function (val) {
  * @private
  */
 const plainObject = function (val) {
-  return object(val) && Object.prototype.toString.call(val) === '[object Object]';
+  return Object.prototype.toString.call(val) === '[object Object]';
 };
 
 /**
@@ -45,7 +45,7 @@ const bool = function (val) {
  * @private
  */
 const buffer = function (val) {
-  return object(val) && val instanceof Buffer;
+  return val instanceof Buffer;
 };
 
 /**
@@ -69,7 +69,7 @@ const number = function (val) {
  * @private
  */
 const integer = function (val) {
-  return number(val) && val % 1 === 0;
+  return Number.isInteger(val);
 };
 
 /**
@@ -85,14 +85,14 @@ const inRange = function (val, min, max) {
  * @private
  */
 const inArray = function (val, list) {
-  return list.indexOf(val) !== -1;
+  return list.includes(val);
 };
 
 /**
  * Create an Error with a message relating to an invalid parameter.
  *
- * @param {String} name - parameter name.
- * @param {String} expected - description of the type/value/range expected.
+ * @param {string} name - parameter name.
+ * @param {string} expected - description of the type/value/range expected.
  * @param {*} actual - the value received.
  * @returns {Error} Containing the formatted message.
  * @private

package/lib/libvips.js

@@ -48,24 +48,18 @@ const globalLibvipsVersion = function () {
 
 const hasVendoredLibvips = function () {
   const currentPlatformId = platform();
-  const vendorPath = path.join(__dirname, '..', 'vendor');
-  let vendorVersionId;
+  const vendorPath = path.join(__dirname, '..', 'vendor', minimumLibvipsVersion);
   let vendorPlatformId;
   try {
-    vendorVersionId = require(path.join(vendorPath, 'versions.json')).vips;
     vendorPlatformId = require(path.join(vendorPath, 'platform.json'));
   } catch (err) {}
-  /* istanbul ignore if */
-  if (vendorVersionId && vendorVersionId !== minimumLibvipsVersion) {
-    throw new Error(`Found vendored libvips v${vendorVersionId} but require v${minimumLibvipsVersion}. Please remove the 'node_modules/sharp/vendor' directory and run 'npm install'.`);
-  }
   /* istanbul ignore else */
   if (vendorPlatformId) {
     /* istanbul ignore else */
     if (currentPlatformId === vendorPlatformId) {
       return true;
     } else {
-      throw new Error(`'${vendorPlatformId}' binaries cannot be used on the '${currentPlatformId}' platform. Please remove the 'node_modules/sharp/vendor' directory and run 'npm install'.`);
+      throw new Error(`'${vendorPlatformId}' binaries cannot be used on the '${currentPlatformId}' platform. Please remove the 'node_modules/sharp' directory and run 'npm install' on the '${currentPlatformId}' platform.`);
     }
   } else {
     return false;

package/lib/operation.js

@@ -32,9 +32,9 @@ const is = require('./is');
  *   });
  * readableStream.pipe(pipeline);
  *
- * @param {Number} [angle=auto] angle of rotation.
+ * @param {number} [angle=auto] angle of rotation.
  * @param {Object} [options] - if present, is an Object with optional attributes.
- * @param {String|Object} [options.background="#000000"] parsed by the [color](https://www.npmjs.org/package/color) module to extract values for red, green, blue and alpha.
+ * @param {string|Object} [options.background="#000000"] 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
  */
@@ -88,9 +88,9 @@ function flop (flop) {
  * When a `sigma` is provided, performs a slower, more accurate sharpen of the L channel in the LAB colour space.
  * Separate control over the level of sharpening in "flat" and "jagged" areas is available.
  *
- * @param {Number} [sigma] - the sigma of the Gaussian mask, where `sigma = 1 + radius / 2`.
- * @param {Number} [flat=1.0] - the level of sharpening to apply to "flat" areas.
- * @param {Number} [jagged=2.0] - the level of sharpening to apply to "jagged" areas.
+ * @param {number} [sigma] - the sigma of the Gaussian mask, where `sigma = 1 + radius / 2`.
+ * @param {number} [flat=1.0] - the level of sharpening to apply to "flat" areas.
+ * @param {number} [jagged=2.0] - the level of sharpening to apply to "jagged" areas.
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */
@@ -129,7 +129,7 @@ function sharpen (sigma, flat, jagged) {
 /**
  * Apply median filter.
  * When used without parameters the default window is 3x3.
- * @param {Number} [size=3] square mask size: size x size
+ * @param {number} [size=3] square mask size: size x size
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */
@@ -150,7 +150,7 @@ function median (size) {
  * Blur the image.
  * When used without parameters, performs a fast, mild blur of the output image.
  * When a `sigma` is provided, performs a slower, more accurate Gaussian blur.
- * @param {Number} [sigma] a value between 0.3 and 1000 representing the sigma of the Gaussian mask, where `sigma = 1 + radius / 2`.
+ * @param {number} [sigma] a value between 0.3 and 1000 representing the sigma of the Gaussian mask, where `sigma = 1 + radius / 2`.
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */
@@ -173,7 +173,7 @@ function blur (sigma) {
 /**
  * Merge alpha transparency channel, if any, with a background.
  * @param {Object} [options]
- * @param {String|Object} [options.background={r: 0, g: 0, b: 0}] - background colour, parsed by the [color](https://www.npmjs.org/package/color) module, defaults to black.
+ * @param {string|Object} [options.background={r: 0, g: 0, b: 0}] - background colour, parsed by the [color](https://www.npmjs.org/package/color) module, defaults to black.
  * @returns {Sharp}
  */
 function flatten (options) {
@@ -193,8 +193,8 @@ function flatten (options) {
  *
  * Supply a second argument to use a different output gamma value, otherwise the first value is used in both cases.
  *
- * @param {Number} [gamma=2.2] value between 1.0 and 3.0.
- * @param {Number} [gammaOut] value between 1.0 and 3.0. (optional, defaults to same as `gamma`)
+ * @param {number} [gamma=2.2] value between 1.0 and 3.0.
+ * @param {number} [gammaOut] value between 1.0 and 3.0. (optional, defaults to same as `gamma`)
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */
@@ -264,11 +264,11 @@ function normalize (normalize) {
  *   });
  *
  * @param {Object} kernel
- * @param {Number} kernel.width - width of the kernel in pixels.
- * @param {Number} kernel.height - width of the kernel in pixels.
- * @param {Array<Number>} kernel.kernel - Array of length `width*height` containing the kernel values.
- * @param {Number} [kernel.scale=sum] - the scale of the kernel in pixels.
- * @param {Number} [kernel.offset=0] - the offset of the kernel in pixels.
+ * @param {number} kernel.width - width of the kernel in pixels.
+ * @param {number} kernel.height - width of the kernel in pixels.
+ * @param {Array<number>} kernel.kernel - Array of length `width*height` containing the kernel values.
+ * @param {number} [kernel.scale=sum] - the scale of the kernel in pixels.
+ * @param {number} [kernel.offset=0] - the offset of the kernel in pixels.
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */
@@ -300,7 +300,7 @@ function convolve (kernel) {
 
 /**
  * Any pixel value greather than or equal to the threshold value will be set to 255, otherwise it will be set to 0.
- * @param {Number} [threshold=128] - a value in the range 0-255 representing the level at which the threshold will be applied.
+ * @param {number} [threshold=128] - a value in the range 0-255 representing the level at which the threshold will be applied.
  * @param {Object} [options]
  * @param {Boolean} [options.greyscale=true] - convert to single channel greyscale.
  * @param {Boolean} [options.grayscale=true] - alternative spelling for greyscale.
@@ -331,13 +331,13 @@ function threshold (threshold, options) {
  * This operation creates an output image where each pixel is the result of
  * the selected bitwise boolean `operation` between the corresponding pixels of the input images.
  *
- * @param {Buffer|String} operand - Buffer containing image data or String containing the path to an image file.
- * @param {String} operator - one of `and`, `or` or `eor` to perform that bitwise operation, like the C logic operators `&`, `|` and `^` respectively.
+ * @param {Buffer|string} operand - Buffer containing image data or string containing the path to an image file.
+ * @param {string} operator - one of `and`, `or` or `eor` to perform that bitwise operation, like the C logic operators `&`, `|` and `^` respectively.
  * @param {Object} [options]
  * @param {Object} [options.raw] - describes operand when using raw pixel data.
- * @param {Number} [options.raw.width]
- * @param {Number} [options.raw.height]
- * @param {Number} [options.raw.channels]
+ * @param {number} [options.raw.width]
+ * @param {number} [options.raw.height]
+ * @param {number} [options.raw.channels]
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */
@@ -353,8 +353,8 @@ function boolean (operand, operator, options) {
 
 /**
  * Apply the linear formula a * input + b to the image (levels adjustment)
- * @param {Number} [a=1.0] multiplier
- * @param {Number} [b=0.0] offset
+ * @param {number} [a=1.0] multiplier
+ * @param {number} [b=0.0] offset
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */
@@ -394,7 +394,7 @@ function linear (a, b) {
  *     // With this example input, a sepia filter has been applied
  *   });
  *
- * @param {Array<Array<Number>>} 3x3 Recombination matrix
+ * @param {Array<Array<number>>} inputMatrix - 3x3 Recombination matrix
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */
@@ -440,9 +440,9 @@ function recomb (inputMatrix) {
  *   });
  *
  * @param {Object} [options]
- * @param {Number} [options.brightness] Brightness multiplier
- * @param {Number} [options.saturation] Saturation multiplier
- * @param {Number} [options.hue] Degrees for hue rotation
+ * @param {number} [options.brightness] Brightness multiplier
+ * @param {number} [options.saturation] Saturation multiplier
+ * @param {number} [options.hue] Degrees for hue rotation
  * @returns {Sharp}
  */
 function modulate (options) {