Release v0.20.3

Add test cases for more tint colours and input interpretations

.travis.yml

@@ -16,7 +16,7 @@ matrix:
     - os: linux
       dist: trusty
       sudo: false
-      node_js: "9"
+      node_js: "10"
     - os: osx
       osx_image: xcode8.3
       node_js: "4"
@@ -28,7 +28,7 @@ matrix:
       node_js: "8"
     - os: osx
       osx_image: xcode8.3
-      node_js: "9"
+      node_js: "10"
 after_success:
   - npm install coveralls
   - cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js

CONTRIBUTING.md

@@ -41,7 +41,6 @@ Any change that modifies the existing public API should be added to the relevant
 
 | Release | WIP branch |
 | ------: | :--------- |
-| v0.20.0 | prebuild   |
 | v0.21.0 | teeth      |
 | v0.22.0 | uptake     |
 
@@ -90,15 +89,6 @@ Requires [Valgrind](http://valgrind.org/).
 npm run test-leak
 ```
 
-### Packaging tests
-
-Tests the installation on a number of Linux-based operating systems.
-Requires docker.
-
-```sh
-npm run test-packaging
-```
-
 ## Finally
 
 Please feel free to ask any questions via a

README.md

@@ -22,7 +22,7 @@ As well as image resizing, operations such as
 rotation, extraction, compositing and gamma correction are available.
 
 Most modern 64-bit OS X, Windows and Linux (glibc) systems running
-Node versions 4, 6, 8 and 9
+Node versions 4, 6, 8 and 10
 do not require any additional install or runtime dependencies.
 
 ## Examples

appveyor.yml

@@ -7,10 +7,10 @@ environment:
   - nodejs_version: "4"
   - nodejs_version: "6"
   - nodejs_version: "8"
-  - nodejs_version: "9"
+  - nodejs_version: "10"
 install:
   - ps: Install-Product node $env:nodejs_version x64
-  - npm install -g npm@5.3.x
+  - npm install -g npm@5
   - npm install
 test_script:
   - npm test

docs/api-colour.md

@@ -3,10 +3,11 @@
 ### Table of Contents
 
 -   [background][1]
--   [greyscale][2]
+-   [tint][2]
--   [grayscale][3]
+-   [greyscale][3]
--   [toColourspace][4]
+-   [grayscale][4]
--   [toColorspace][5]
+-   [toColourspace][5]
+-   [toColorspace][6]
 
 ## background
 
@@ -19,10 +20,24 @@ The alpha value is a float between `0` (transparent) and `1` (opaque).
 
 **Parameters**
 
--   `rgba` **([String][6] \| [Object][7])** parsed by the [color][8] module to extract values for red, green, blue and alpha.
+-   `rgba` **([String][7] \| [Object][8])** parsed by the [color][9] module to extract values for red, green, blue and alpha.
 
 
--   Throws **[Error][9]** Invalid parameter
+-   Throws **[Error][10]** Invalid parameter
+
+Returns **Sharp** 
+
+## tint
+
+Tint the image using the provided chroma while preserving the image luminance.
+An alpha channel may be present and will be unchanged by the operation.
+
+**Parameters**
+
+-   `rgb` **([String][7] \| [Object][8])** parsed by the [color][9] module to extract chroma values.
+
+
+-   Throws **[Error][10]** Invalid parameter
 
 Returns **Sharp** 
 
@@ -37,7 +52,7 @@ An alpha channel may be present, and will be unchanged by the operation.
 
 **Parameters**
 
--   `greyscale` **[Boolean][10]**  (optional, default `true`)
+-   `greyscale` **[Boolean][11]**  (optional, default `true`)
 
 Returns **Sharp** 
 
@@ -47,7 +62,7 @@ Alternative spelling of `greyscale`.
 
 **Parameters**
 
--   `grayscale` **[Boolean][10]**  (optional, default `true`)
+-   `grayscale` **[Boolean][11]**  (optional, default `true`)
 
 Returns **Sharp** 
 
@@ -58,10 +73,10 @@ By default output image will be web-friendly sRGB, with additional channels inte
 
 **Parameters**
 
--   `colourspace` **[String][6]?** output colourspace e.g. `srgb`, `rgb`, `cmyk`, `lab`, `b-w` [...][11]
+-   `colourspace` **[String][7]?** output colourspace e.g. `srgb`, `rgb`, `cmyk`, `lab`, `b-w` [...][12]
 
 
--   Throws **[Error][9]** Invalid parameters
+-   Throws **[Error][10]** Invalid parameters
 
 Returns **Sharp** 
 
@@ -71,31 +86,33 @@ Alternative spelling of `toColourspace`.
 
 **Parameters**
 
--   `colorspace` **[String][6]?** output colorspace.
+-   `colorspace` **[String][7]?** output colorspace.
 
 
--   Throws **[Error][9]** Invalid parameters
+-   Throws **[Error][10]** Invalid parameters
 
 Returns **Sharp** 
 
 [1]: #background
 
-[2]: #greyscale
+[2]: #tint
 
-[3]: #grayscale
+[3]: #greyscale
 
-[4]: #tocolourspace
+[4]: #grayscale
 
-[5]: #tocolorspace
+[5]: #tocolourspace
 
-[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+[6]: #tocolorspace
 
-[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
 
-[8]: https://www.npmjs.org/package/color
+[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
 
-[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error
+[9]: https://www.npmjs.org/package/color
 
-[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
+[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error
 
-[11]: https://github.com/jcupitt/libvips/blob/master/libvips/iofuncs/enumtypes.c#L568
+[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
+
+[12]: https://github.com/jcupitt/libvips/blob/master/libvips/iofuncs/enumtypes.c#L568

docs/api-constructor.md

@@ -20,6 +20,7 @@
          to decode images, even if the data is corrupt or invalid. Set this flag to true
          if you'd rather halt processing and raise an error when loading invalid images. (optional, default `false`)
     -   `options.density` **[Number][9]** integral number representing the DPI for vector images. (optional, default `72`)
+    -   `options.page` **[Number][9]** page number to extract for multi-page input (GIF, TIFF) (optional, default `0`)
     -   `options.raw` **[Object][7]?** describes raw pixel input image data. See `raw()` for pixel ordering.
         -   `options.raw.width` **[Number][9]?** 
         -   `options.raw.height` **[Number][9]?** 

docs/api-output.md

@@ -31,6 +31,19 @@ A `Promise` is returned when `callback` is not provided.
     `channels` and `premultiplied` (indicating if premultiplication was used).
     When using a crop strategy also contains `cropOffsetLeft` and `cropOffsetTop`.
 
+**Examples**
+
+```javascript
+sharp(input)
+  .toFile('output.png', (err, info) => { ... });
+```
+
+```javascript
+sharp(input)
+  .toFile('output.png')
+  .then(info => { ... })
+  .catch(err => { ... });
+```
 
 -   Throws **[Error][13]** Invalid parameters
 
@@ -58,6 +71,27 @@ A `Promise` is returned when `callback` is not provided.
     -   `options.resolveWithObject` **[Boolean][16]?** Resolve the Promise with an Object containing `data` and `info` properties instead of resolving only with `data`.
 -   `callback` **[Function][12]?** 
 
+**Examples**
+
+```javascript
+sharp(input)
+  .toBuffer((err, data, info) => { ... });
+```
+
+```javascript
+sharp(input)
+  .toBuffer()
+  .then(data => { ... })
+  .catch(err => { ... });
+```
+
+```javascript
+sharp(input)
+  .toBuffer({ resolveWithObject: true })
+  .then(({ data, info }) => { ... })
+  .catch(err => { ... });
+```
+
 Returns **[Promise][14]<[Buffer][17]>** when no callback is provided
 
 ## withMetadata
@@ -71,6 +105,14 @@ This will also convert to and add a web-friendly sRGB ICC profile.
 -   `withMetadata` **[Object][15]?** 
     -   `withMetadata.orientation` **[Number][18]?** value between 1 and 8, used to update the EXIF `Orientation` tag.
 
+**Examples**
+
+```javascript
+sharp('input.jpg')
+  .withMetadata()
+  .toFile('output-with-metadata.jpg')
+  .then(info => { ... });
+```
 
 -   Throws **[Error][13]** Invalid parameters
 
@@ -92,6 +134,17 @@ Use these JPEG options for output image.
     -   `options.optimizeScans` **[Boolean][16]** alternative spelling of optimiseScans (optional, default `false`)
     -   `options.force` **[Boolean][16]** force JPEG output, otherwise attempt to use input format (optional, default `true`)
 
+**Examples**
+
+```javascript
+// Convert any input to very high quality JPEG output
+const data = await sharp(input)
+  .jpeg({
+    quality: 100,
+    chromaSubsampling: '4:4:4'
+  })
+  .toBuffer();
+```
 
 -   Throws **[Error][13]** Invalid options
 
@@ -101,6 +154,9 @@ Returns **Sharp**
 
 Use these PNG options for output image.
 
+PNG output is always full colour at 8 or 16 bits per pixel.
+Indexed PNG input at 1, 2 or 4 bits per pixel is converted to 8 bits per pixel.
+
 **Parameters**
 
 -   `options` **[Object][15]?** 
@@ -109,6 +165,14 @@ Use these PNG options for output image.
     -   `options.adaptiveFiltering` **[Boolean][16]** use adaptive row filtering (optional, default `false`)
     -   `options.force` **[Boolean][16]** force PNG output, otherwise attempt to use input format (optional, default `true`)
 
+**Examples**
+
+```javascript
+// Convert any input to PNG output
+const data = await sharp(input)
+  .png()
+  .toBuffer();
+```
 
 -   Throws **[Error][13]** Invalid options
 
@@ -127,6 +191,14 @@ Use these WebP options for output image.
     -   `options.nearLossless` **[Boolean][16]** use near_lossless compression mode (optional, default `false`)
     -   `options.force` **[Boolean][16]** force WebP output, otherwise attempt to use input format (optional, default `true`)
 
+**Examples**
+
+```javascript
+// Convert any input to lossless WebP output
+const data = await sharp(input)
+  .webp({ lossless: true })
+  .toBuffer();
+```
 
 -   Throws **[Error][13]** Invalid options
 
@@ -141,12 +213,24 @@ Use these TIFF options for output image.
 -   `options` **[Object][15]?** output options
     -   `options.quality` **[Number][18]** quality, integer 1-100 (optional, default `80`)
     -   `options.force` **[Boolean][16]** force TIFF output, otherwise attempt to use input format (optional, default `true`)
-    -   `options.compression` **[Boolean][16]** compression options: lzw, deflate, jpeg (optional, default `'jpeg'`)
+    -   `options.compression` **[Boolean][16]** compression options: lzw, deflate, jpeg, ccittfax4 (optional, default `'jpeg'`)
     -   `options.predictor` **[Boolean][16]** compression predictor options: none, horizontal, float (optional, default `'horizontal'`)
     -   `options.xres` **[Number][18]** horizontal resolution in pixels/mm (optional, default `1.0`)
     -   `options.yres` **[Number][18]** vertical resolution in pixels/mm (optional, default `1.0`)
     -   `options.squash` **[Boolean][16]** squash 8-bit images down to 1 bit (optional, default `false`)
 
+**Examples**
+
+```javascript
+// Convert SVG input to LZW-compressed, 1 bit per pixel TIFF output
+sharp('input.svg')
+  .tiff({
+    compression: 'lzw',
+    squash: true
+  })
+  .toFile('1-bpp-output.tiff')
+  .then(info => { ... });
+```
 
 -   Throws **[Error][13]** Invalid options
 
@@ -156,6 +240,15 @@ Returns **Sharp**
 
 Force output to be raw, uncompressed uint8 pixel data.
 
+**Examples**
+
+```javascript
+// Extract raw RGB pixel data from JPEG input
+const { data, info } = await sharp('input.jpg')
+  .raw()
+  .toBuffer({ resolveWithObject: true });
+```
+
 Returns **Sharp** 
 
 ## toFormat
@@ -167,6 +260,14 @@ Force output to a given format.
 -   `format` **([String][11] \| [Object][15])** as a String or an Object with an 'id' attribute
 -   `options` **[Object][15]** output options
 
+**Examples**
+
+```javascript
+// Convert any input to PNG output
+const data = await sharp(input)
+  .toFormat('png')
+  .toBuffer();
+```
 
 -   Throws **[Error][13]** unsupported format or options
 
@@ -178,6 +279,8 @@ Use tile-based deep zoom (image pyramid) output.
 Set the format and options for tile images via the `toFormat`, `jpeg`, `png` or `webp` functions.
 Use a `.zip` or `.szi` file extension with `toFile` to write to a compressed archive file format.
 
+Warning: multiple sharp instances concurrently producing tile output can expose a possible race condition in some versions of libgsf.
+
 **Parameters**
 
 -   `tile` **[Object][15]?** 

docs/changelog.md

@@ -4,6 +4,30 @@
 
 Requires libvips v8.6.1.
 
+#### v0.20.3 - 29<sup>th</sup> May 2018
+
+* Fix tint operation by ensuring LAB interpretation and allowing negative values.
+  [#1235](https://github.com/lovell/sharp/issues/1235)
+  [@wezside](https://github.com/wezside)
+
+#### v0.20.2 - 28<sup>th</sup> April 2018
+
+* Add tint operation to set image chroma.
+  [#825](https://github.com/lovell/sharp/pull/825)
+  [@rikh42](https://github.com/rikh42)
+
+* Add environment variable to ignore globally-installed libvips.
+  [#1165](https://github.com/lovell/sharp/pull/1165)
+  [@oncletom](https://github.com/oncletom)
+
+* Add support for page selection with multi-page input (GIF/TIFF).
+  [#1204](https://github.com/lovell/sharp/pull/1204)
+  [@woolite64](https://github.com/woolite64)
+
+* Add support for Group4 (CCITTFAX4) compression with TIFF output.
+  [#1208](https://github.com/lovell/sharp/pull/1208)
+  [@woolite64](https://github.com/woolite64)
+
 #### v0.20.1 - 17<sup>th</sup> March 2018
 
 * Improve installation experience when a globally-installed libvips below the minimum required version is found.

docs/index.md

@@ -14,7 +14,7 @@ As well as image resizing, operations such as
 rotation, extraction, compositing and gamma correction are available.
 
 Most 64-bit OS X, Windows and Linux (glibc) systems running
-Node versions 4, 6, 8 and 9
+Node versions 4, 6, 8 and 10
 do not require any additional install or runtime dependencies.
 
 [![Test Coverage](https://coveralls.io/repos/lovell/sharp/badge.png?branch=master)](https://coveralls.io/r/lovell/sharp?branch=master)
@@ -109,6 +109,9 @@ the help and code contributions of the following people:
 * [Oleh Aleinyk](https://github.com/oaleynik)
 * [Marcel Bretschneider](https://github.com/3epnm)
 * [Andrea Bianco](https://github.com/BiancoA)
+* [Rik Heywood](https://github.com/rikh42)
+* [Thomas Parisot](https://github.com/oncletom)
+* [Nathan Graves](https://github.com/woolite64)
 
 Thank you!
 

docs/install.md

@@ -15,7 +15,7 @@ yarn add sharp
 ### Building from source
 
 Pre-compiled binaries for sharp are provided for use with
-Node versions 4, 6, 8 and 9 on
+Node versions 4, 6, 8 and 10 on
 64-bit Windows, OS X and Linux platforms.
 
 Sharp will be built from source at install time when:
@@ -54,7 +54,7 @@ To use a globally-installed version of libvips instead of the provided binaries,
 make sure it is at least the version listed under `config.libvips` in the `package.json` file
 and that it can be located using `pkg-config --modversion vips-cpp`.
 
-If you are using non-stadard paths (anything other than `/usr` or `/usr/local`),
+If you are using non-standard paths (anything other than `/usr` or `/usr/local`),
 you might need to set `PKG_CONFIG_PATH` during `npm install`
 and `LD_LIBRARY_PATH` at runtime.
 
@@ -161,6 +161,18 @@ Set the Lambda runtime to Node.js 6.10.
 
 To get the best performance select the largest memory available. A 1536 MB function provides ~12x more CPU time than a 128 MB function.
 
+### NW.js
+
+Run the `nw-gyp` tool after installation.
+
+```sh
+cd node-modules/sharp
+nw-gyp rebuild --arch=x64 --target=[your nw version]
+node node_modules/sharp/install/dll-copy
+```
+
+See also http://docs.nwjs.io/en/latest/For%20Users/Advanced/Use%20Native%20Node%20Modules/
+
 ### Build tools
 
 * [gulp-responsive](https://www.npmjs.com/package/gulp-responsive)
@@ -211,10 +223,17 @@ to the directory containing the `policy.xml` file.
 
 ### Pre-compiled libvips binaries
 
-If a global installation of libvips that meets the
+This module will attempt to download a pre-compiled bundle of libvips
-minimum version requirement cannot be found,
+and its dependencies on Linux and Windows machines under either of these
-this module will attempt to download a pre-compiled bundle of libvips
+conditions:
-and its dependencies on Linux and Windows machines.
+
+1. If a global installation of libvips that meets the
+minimum version requirement cannot be found;
+1. If `SHARP_IGNORE_GLOBAL_LIBVIPS` environment variable is set.
+
+```sh
+SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install sharp
+```
 
 Should you need to manually download and inspect these files,
 you can do so via https://github.com/lovell/sharp-libvips/releases

install/libvips.js

@@ -29,6 +29,9 @@ try {
   } else {
     // Is this arch/platform supported?
     const arch = process.env.npm_config_arch || process.arch;
+    if (platform() === 'win32-ia32') {
+      throw new Error('Windows x86 (32-bit) node.exe is not supported');
+    }
     if (arch === 'ia32') {
       throw new Error(`Intel Architecture 32-bit systems require manual installation of libvips >= ${minimumLibvipsVersion}\n`);
     }

lib/colour.js

@@ -38,6 +38,21 @@ function background (rgba) {
   return this;
 }
 
+/**
+ * Tint the image using the provided chroma while preserving the image luminance.
+ * An alpha channel may be present and will be unchanged by the operation.
+ *
+ * @param {String|Object} rgb - parsed by the [color](https://www.npmjs.org/package/color) module to extract chroma values.
+ * @returns {Sharp}
+ * @throws {Error} Invalid parameter
+ */
+function tint (rgb) {
+  const colour = color(rgb);
+  this.options.tintA = colour.a();
+  this.options.tintB = colour.b();
+  return this;
+}
+
 /**
  * Convert to 8-bit greyscale; 256 shades of grey.
  * This is a linear operation. If the input image is in a non-linear colour space such as sRGB, use `gamma()` with `greyscale()` for the best results.
@@ -95,6 +110,7 @@ module.exports = function (Sharp) {
   // Public instance functions
   [
     background,
+    tint,
     greyscale,
     grayscale,
     toColourspace,

lib/constructor.js

@@ -97,6 +97,7 @@ const debuglog = util.debuglog('sharp');
  *  to decode images, even if the data is corrupt or invalid. Set this flag to true
  *  if you'd rather halt processing and raise an error when loading invalid images.
  * @param {Number} [options.density=72] - integral number representing the DPI for vector images.
+ * @param {Number} [options.page=0] - page number to extract for multi-page input (GIF, TIFF)
  * @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]
@@ -151,6 +152,8 @@ const Sharp = function (input, options) {
     fastShrinkOnLoad: true,
     // operations
     background: [0, 0, 0, 255],
+    tintA: 128,
+    tintB: 128,
     flatten: false,
     negate: false,
     medianSize: 0,

lib/input.js

@@ -57,6 +57,12 @@ function _createInputDescriptor (input, inputOptions, containerOptions) {
         throw new Error('Expected width, height and channels for raw pixel input');
       }
     }
+    // Page input for multi-page TIFF
+    if (is.defined(inputOptions.page)) {
+      if (is.integer(inputOptions.page) && is.inRange(inputOptions.page, 0, 100000)) {
+        inputDescriptor.page = inputOptions.page;
+      }
+    }
     // Create new image
     if (is.defined(inputOptions.create)) {
       if (

lib/libvips.js

@@ -46,6 +46,10 @@ const pkgConfigPath = function () {
 };
 
 const useGlobalLibvips = function () {
+  if (Boolean(process.env.SHARP_IGNORE_GLOBAL_LIBVIPS) === true) {
+    return false;
+  }
+
   const globalVipsVersion = globalLibvipsVersion();
   return !!globalVipsVersion && semver.gte(globalVipsVersion, minimumLibvipsVersion);
 };

lib/output.js

@@ -12,6 +12,16 @@ const sharp = require('../build/Release/sharp.node');
  *
  * A `Promise` is returned when `callback` is not provided.
  *
+ * @example
+ * sharp(input)
+ *   .toFile('output.png', (err, info) => { ... });
+ *
+ * @example
+ * sharp(input)
+ *   .toFile('output.png')
+ *   .then(info => { ... })
+ *   .catch(err => { ... });
+ *
  * @param {String} fileOut - the path to write the image data to.
  * @param {Function} [callback] - called on completion with two arguments `(err, info)`.
  * `info` contains the output image `format`, `size` (bytes), `width`, `height`,
@@ -58,6 +68,22 @@ function toFile (fileOut, callback) {
  *
  * A `Promise` is returned when `callback` is not provided.
  *
+ * @example
+ * sharp(input)
+ *   .toBuffer((err, data, info) => { ... });
+ *
+ * @example
+ * sharp(input)
+ *   .toBuffer()
+ *   .then(data => { ... })
+ *   .catch(err => { ... });
+ *
+ * @example
+ * sharp(input)
+ *   .toBuffer({ resolveWithObject: true })
+ *   .then(({ data, info }) => { ... })
+ *   .catch(err => { ... });
+ *
  * @param {Object} [options]
  * @param {Boolean} [options.resolveWithObject] Resolve the Promise with an Object containing `data` and `info` properties instead of resolving only with `data`.
  * @param {Function} [callback]
@@ -76,6 +102,13 @@ function toBuffer (options, callback) {
  * Include all metadata (EXIF, XMP, IPTC) from the input image in the output image.
  * The default behaviour, when `withMetadata` is not used, is to strip all metadata and convert to the device-independent sRGB colour space.
  * This will also convert to and add a web-friendly sRGB ICC profile.
+ *
+ * @example
+ * sharp('input.jpg')
+ *   .withMetadata()
+ *   .toFile('output-with-metadata.jpg')
+ *   .then(info => { ... });
+ *
  * @param {Object} [withMetadata]
  * @param {Number} [withMetadata.orientation] value between 1 and 8, used to update the EXIF `Orientation` tag.
  * @returns {Sharp}
@@ -97,6 +130,16 @@ function withMetadata (withMetadata) {
 
 /**
  * Use these JPEG options for output image.
+ *
+ * @example
+ * // Convert any input to very high quality JPEG output
+ * const data = await sharp(input)
+ *   .jpeg({
+ *     quality: 100,
+ *     chromaSubsampling: '4:4:4'
+ *   })
+ *   .toBuffer();
+ *
  * @param {Object} [options] - output options
  * @param {Number} [options.quality=80] - quality, integer 1-100
  * @param {Boolean} [options.progressive=false] - use progressive (interlace) scan
@@ -148,6 +191,16 @@ function jpeg (options) {
 
 /**
  * Use these PNG options for output image.
+ *
+ * PNG output is always full colour at 8 or 16 bits per pixel.
+ * Indexed PNG input at 1, 2 or 4 bits per pixel is converted to 8 bits per pixel.
+ *
+ * @example
+ * // Convert any input to PNG output
+ * const data = await sharp(input)
+ *   .png()
+ *   .toBuffer();
+ *
  * @param {Object} [options]
  * @param {Boolean} [options.progressive=false] - use progressive (interlace) scan
  * @param {Number} [options.compressionLevel=9] - zlib compression level, 0-9
@@ -177,6 +230,13 @@ function png (options) {
 
 /**
  * Use these WebP options for output image.
+ *
+ * @example
+ * // Convert any input to lossless WebP output
+ * const data = await sharp(input)
+ *   .webp({ lossless: true })
+ *   .toBuffer();
+ *
  * @param {Object} [options] - output options
  * @param {Number} [options.quality=80] - quality, integer 1-100
  * @param {Number} [options.alphaQuality=100] - quality of alpha layer, integer 0-100
@@ -212,10 +272,21 @@ function webp (options) {
 
 /**
  * Use these TIFF options for output image.
+ *
+ * @example
+ * // Convert SVG input to LZW-compressed, 1 bit per pixel TIFF output
+ * sharp('input.svg')
+ *   .tiff({
+ *     compression: 'lzw',
+ *     squash: true
+ *   })
+ *   .toFile('1-bpp-output.tiff')
+ *   .then(info => { ... });
+ *
  * @param {Object} [options] - output options
  * @param {Number} [options.quality=80] - quality, integer 1-100
  * @param {Boolean} [options.force=true] - force TIFF output, otherwise attempt to use input format
- * @param {Boolean} [options.compression='jpeg'] - compression options: lzw, deflate, jpeg
+ * @param {Boolean} [options.compression='jpeg'] - compression options: lzw, deflate, jpeg, ccittfax4
  * @param {Boolean} [options.predictor='horizontal'] - compression predictor options: none, horizontal, float
  * @param {Number} [options.xres=1.0] - horizontal resolution in pixels/mm
  * @param {Number} [options.yres=1.0] - vertical resolution in pixels/mm
@@ -255,10 +326,10 @@ function tiff (options) {
   }
   // compression
   if (is.defined(options) && is.defined(options.compression)) {
-    if (is.string(options.compression) && is.inArray(options.compression, ['lzw', 'deflate', 'jpeg', 'none'])) {
+    if (is.string(options.compression) && is.inArray(options.compression, ['lzw', 'deflate', 'jpeg', 'ccittfax4', 'none'])) {
       this.options.tiffCompression = options.compression;
     } else {
-      const message = `Invalid compression option "${options.compression}". Should be one of: lzw, deflate, jpeg, none`;
+      const message = `Invalid compression option "${options.compression}". Should be one of: lzw, deflate, jpeg, ccittfax4, none`;
       throw new Error(message);
     }
   }
@@ -276,6 +347,13 @@ function tiff (options) {
 
 /**
  * Force output to be raw, uncompressed uint8 pixel data.
+ *
+ * @example
+ * // Extract raw RGB pixel data from JPEG input
+ * const { data, info } = await sharp('input.jpg')
+ *   .raw()
+ *   .toBuffer({ resolveWithObject: true });
+ *
  * @returns {Sharp}
  */
 function raw () {
@@ -284,6 +362,13 @@ function raw () {
 
 /**
  * Force output to a given format.
+ *
+ * @example
+ * // Convert any input to PNG output
+ * const data = await sharp(input)
+ *   .toFormat('png')
+ *   .toBuffer();
+ *
  * @param {(String|Object)} format - as a String or an Object with an 'id' attribute
  * @param {Object} options - output options
  * @returns {Sharp}
@@ -305,6 +390,8 @@ function toFormat (format, options) {
  * Set the format and options for tile images via the `toFormat`, `jpeg`, `png` or `webp` functions.
  * Use a `.zip` or `.szi` file extension with `toFile` to write to a compressed archive file format.
  *
+ * Warning: multiple sharp instances concurrently producing tile output can expose a possible race condition in some versions of libgsf.
+ *
  * @example
  *  sharp('input.tiff')
  *   .png()

package.json

@@ -1,7 +1,7 @@
 {
   "name": "sharp",
   "description": "High performance Node.js image processing, the fastest module to resize JPEG, PNG, WebP and TIFF images",
-  "version": "0.20.1",
+  "version": "0.20.3",
   "author": "Lovell Fuller <npm@lovell.info>",
   "homepage": "https://github.com/lovell/sharp",
   "contributors": [
@@ -45,7 +45,10 @@
     "Kenric D'Souza <kenric.dsouza@gmail.com>",
     "Oleh Aleinyk <oleg.aleynik@gmail.com>",
     "Marcel Bretschneider <marcel.bretschneider@gmail.com>",
-    "Andrea Bianco <andrea.bianco@unibas.ch>"
+    "Andrea Bianco <andrea.bianco@unibas.ch>",
+    "Rik Heywood <rik@rik.org>",
+    "Thomas Parisot <hi@oncletom.io>",
+    "Nathan Graves <nathanrgraves+github@gmail.com>"
   ],
   "scripts": {
     "install": "(node install/libvips && node install/dll-copy && prebuild-install) || (node-gyp rebuild && node install/dll-copy)",
@@ -80,27 +83,27 @@
     "color": "^3.0.0",
     "detect-libc": "^1.0.3",
     "nan": "^2.10.0",
-    "fs-copy-file-sync": "^1.0.1",
+    "fs-copy-file-sync": "^1.1.1",
     "npmlog": "^4.1.2",
-    "prebuild-install": "^2.5.1",
+    "prebuild-install": "^4.0.0",
     "semver": "^5.5.0",
-    "simple-get": "^2.7.0",
+    "simple-get": "^2.8.1",
-    "tar": "^4.4.0",
+    "tar": "^4.4.4",
     "tunnel-agent": "^0.6.0"
   },
   "devDependencies": {
-    "async": "^2.6.0",
+    "async": "^2.6.1",
-    "cc": "^1.0.1",
+    "cc": "^1.0.2",
-    "documentation": "^6.1.0",
+    "decompress-zip": "^0.3.1",
+    "documentation": "^7.1.0",
     "exif-reader": "^1.0.2",
     "icc": "^1.0.0",
-    "mocha": "^5.0.4",
+    "mocha": "^5.2.0",
-    "nyc": "^11.6.0",
+    "nyc": "^11.8.0",
-    "prebuild": "^7.4.0",
+    "prebuild": "^7.6.0",
     "prebuild-ci": "^2.2.3",
     "rimraf": "^2.6.2",
-    "semistandard": "^12.0.1",
+    "semistandard": "^12.0.1"
-    "unzip": "^0.1.11"
   },
   "license": "Apache-2.0",
   "config": {

src/common.cc

@@ -63,6 +63,10 @@ namespace sharp {
       descriptor->rawWidth = AttrTo<uint32_t>(input, "rawWidth");
       descriptor->rawHeight = AttrTo<uint32_t>(input, "rawHeight");
     }
+    // Page input for multi-page TIFF
+    if (HasAttr(input, "page")) {
+      descriptor->page = AttrTo<uint32_t>(input, "page");
+    }
     // Create new image
     if (HasAttr(input, "createChannels")) {
       descriptor->createChannels = AttrTo<uint32_t>(input, "createChannels");
@@ -229,6 +233,9 @@ namespace sharp {
             if (imageType == ImageType::MAGICK) {
               option->set("density", std::to_string(descriptor->density).data());
             }
+            if (imageType == ImageType::TIFF) {
+             option->set("page", descriptor->page);
+            }
             image = VImage::new_from_buffer(descriptor->buffer, descriptor->bufferLength, nullptr, option);
             if (imageType == ImageType::SVG || imageType == ImageType::PDF || imageType == ImageType::MAGICK) {
               SetDensity(image, descriptor->density);
@@ -268,6 +275,9 @@ namespace sharp {
             if (imageType == ImageType::MAGICK) {
               option->set("density", std::to_string(descriptor->density).data());
             }
+            if (imageType == ImageType::TIFF) {
+             option->set("page", descriptor->page);
+            }
             image = VImage::new_from_file(descriptor->file.data(), option);
             if (imageType == ImageType::SVG || imageType == ImageType::PDF || imageType == ImageType::MAGICK) {
               SetDensity(image, descriptor->density);

src/common.h

@@ -53,6 +53,7 @@ namespace sharp {
     int rawChannels;
     int rawWidth;
     int rawHeight;
+    int page;
     int createChannels;
     int createWidth;
     int createHeight;
@@ -66,6 +67,7 @@ namespace sharp {
       rawChannels(0),
       rawWidth(0),
       rawHeight(0),
+      page(0),
       createChannels(0),
       createWidth(0),
       createHeight(0) {

src/metadata.cc

@@ -83,9 +83,9 @@ class MetadataWorker : public Nan::AsyncWorker {
         baton->iccLength = iccLength;
       }
       // IPTC
-      if (image.get_typeof(VIPS_META_IPCT_NAME) == VIPS_TYPE_BLOB) {
+      if (image.get_typeof(VIPS_META_IPTC_NAME) == VIPS_TYPE_BLOB) {
         size_t iptcLength;
-        void const *iptc = image.get_blob(VIPS_META_IPCT_NAME, &iptcLength);
+        void const *iptc = image.get_blob(VIPS_META_IPTC_NAME, &iptcLength);
         baton->iptc = static_cast<char *>(g_malloc(iptcLength));
         memcpy(baton->iptc, iptc, iptcLength);
         baton->iptcLength = iptcLength;

src/operations.cc

@@ -152,6 +152,33 @@ namespace sharp {
     return dst.bandjoin(mask.cast(dst.format()));
   }
 
+  /*
+   * Tint an image using the specified chroma, preserving the original image luminance
+   */
+  VImage Tint(VImage image, double const a, double const b) {
+    // Get original colourspace
+    VipsInterpretation typeBeforeTint = image.interpretation();
+    if (typeBeforeTint == VIPS_INTERPRETATION_RGB) {
+      typeBeforeTint = VIPS_INTERPRETATION_sRGB;
+    }
+    // Extract luminance
+    VImage luminance = image.colourspace(VIPS_INTERPRETATION_LAB)[0];
+    // Create the tinted version by combining the L from the original and the chroma from the tint
+    std::vector<double> chroma {a, b};
+    VImage tinted = luminance
+      .bandjoin(chroma)
+      .copy(VImage::option()->set("interpretation", VIPS_INTERPRETATION_LAB))
+      .colourspace(typeBeforeTint);
+    // Attach original alpha channel, if any
+    if (HasAlpha(image)) {
+      // Extract original alpha channel
+      VImage alpha = image[image.bands() - 1];
+      // Join alpha channel to normalised image
+      tinted = tinted.bandjoin(alpha);
+    }
+    return tinted;
+  }
+
   /*
    * Stretch luminance to cover full dynamic range.
    */

src/operations.h

@@ -46,6 +46,11 @@ namespace sharp {
   */
   VImage Cutout(VImage src, VImage dst, const int gravity);
 
+  /*
+   * Tint an image using the specified chroma, preserving the original image luminance
+   */
+  VImage Tint(VImage image, double const a, double const b);
+
   /*
    * Stretch luminance to cover full dynamic range.
    */

src/pipeline.cc

@@ -682,6 +682,11 @@ class PipelineWorker : public Nan::AsyncWorker {
         image = sharp::Bandbool(image, baton->bandBoolOp);
       }
 
+      // Tint the image
+      if (baton->tintA < 128.0 || baton->tintB < 128.0) {
+        image = sharp::Tint(image, baton->tintA, baton->tintB);
+      }
+
       // Extract an image channel (aka vips band)
       if (baton->extractChannel > -1) {
         if (baton->extractChannel >= image.bands()) {
@@ -1167,6 +1172,9 @@ NAN_METHOD(pipeline) {
   for (unsigned int i = 0; i < 4; i++) {
     baton->background[i] = AttrTo<double>(background, i);
   }
+  // Tint chroma
+  baton->tintA = AttrTo<double>(options, "tintA");
+  baton->tintB = AttrTo<double>(options, "tintB");
   // Overlay options
   if (HasAttr(options, "overlay")) {
     baton->overlay = CreateInputDescriptor(AttrAs<v8::Object>(options, "overlay"), buffersToPersist);

src/pipeline.h

@@ -70,6 +70,8 @@ struct PipelineBaton {
   std::string kernel;
   bool fastShrinkOnLoad;
   double background[4];
+  double tintA;
+  double tintB;
   bool flatten;
   bool negate;
   double blurSigma;
@@ -155,6 +157,8 @@ struct PipelineBaton {
     cropOffsetLeft(0),
     cropOffsetTop(0),
     premultiplied(false),
+    tintA(128.0),
+    tintB(128.0),
     flatten(false),
     negate(false),
     blurSigma(0.0),

test/fixtures/index.js

@@ -89,10 +89,12 @@ module.exports = {
   inputPngTestJoinChannel: getPath('testJoinChannel.png'),
   inputPngTruncated: getPath('truncated.png'), // gm convert 2569067123_aca715a2ee_o.jpg -resize 320x240 saw.png ; head -c 10000 saw.png > truncated.png
   inputPngEmbed: getPath('embedgravitybird.png'), // Released to sharp under a CC BY 4.0
+  inputPngRGBWithAlpha: getPath('2569067123_aca715a2ee_o.png'), // http://www.flickr.com/photos/grizdave/2569067123/ (same as inputJpg)
 
   inputWebP: getPath('4.webp'), // http://www.gstatic.com/webp/gallery/4.webp
   inputWebPWithTransparency: getPath('5_webp_a.webp'), // http://www.gstatic.com/webp/gallery3/5_webp_a.webp
   inputTiff: getPath('G31D.TIF'), // http://www.fileformat.info/format/tiff/sample/e6c9a6e5253348f4aef6d17b534360ab/index.htm
+  inputTiffMultipage: getPath('G31D_MULTI.TIF'), // gm convert G31D.TIF -resize 50% G31D_2.TIF ; tiffcp G31D.TIF G31D_2.TIF G31D_MULTI.TIF
   inputTiffCielab: getPath('cielab-dagams.tiff'), // https://github.com/lovell/sharp/issues/646
   inputTiffUncompressed: getPath('uncompressed_tiff.tiff'), // https://code.google.com/archive/p/imagetestsuite/wikis/TIFFTestSuite.wiki file: 0c84d07e1b22b76f24cccc70d8788e4a.tif
   inputTiff8BitDepth: getPath('8bit_depth.tiff'),

test/unit/io.js

@@ -528,6 +528,22 @@ describe('Input/output', function () {
       });
   });
 
+  it('TIFF file input with invalid page fails gracefully', function (done) {
+    sharp(fixtures.inputTiffMultipage, { page: 2 })
+      .toBuffer(function (err) {
+        assert.strictEqual(true, !!err);
+        done();
+      });
+  });
+
+  it('TIFF buffer input with invalid page fails gracefully', function (done) {
+    sharp(fs.readFileSync(fixtures.inputTiffMultipage), { page: 2 })
+      .toBuffer(function (err) {
+        assert.strictEqual(true, !!err);
+        done();
+      });
+  });
+
   describe('Output filename with unknown extension', function () {
     it('Match JPEG input', function (done) {
       sharp(fixtures.inputJpg)
@@ -880,6 +896,53 @@ describe('Input/output', function () {
       });
   });
 
+  it('Load multi-page TIFF\'s from file', function (done) {
+    sharp(fixtures.inputTiffMultipage) // defaults to page 0
+      .jpeg()
+      .toBuffer(function (err, defaultData, defaultInfo) {
+        if (err) throw err;
+        assert.strictEqual(true, defaultData.length > 0);
+        assert.strictEqual(defaultData.length, defaultInfo.size);
+        assert.strictEqual('jpeg', defaultInfo.format);
+
+        sharp(fixtures.inputTiffMultipage, { page: 1 }) // 50%-scale copy of page 0
+          .jpeg()
+          .toBuffer(function (err, scaledData, scaledInfo) {
+            if (err) throw err;
+            assert.strictEqual(true, scaledData.length > 0);
+            assert.strictEqual(scaledData.length, scaledInfo.size);
+            assert.strictEqual('jpeg', scaledInfo.format);
+            assert.strictEqual(defaultInfo.width, scaledInfo.width * 2);
+            assert.strictEqual(defaultInfo.height, scaledInfo.height * 2);
+            done();
+          });
+      });
+  });
+
+  it('Load multi-page TIFF\'s from Buffer', function (done) {
+    const inputTiffBuffer = fs.readFileSync(fixtures.inputTiffMultipage);
+    sharp(inputTiffBuffer) // defaults to page 0
+      .jpeg()
+      .toBuffer(function (err, defaultData, defaultInfo) {
+        if (err) throw err;
+        assert.strictEqual(true, defaultData.length > 0);
+        assert.strictEqual(defaultData.length, defaultInfo.size);
+        assert.strictEqual('jpeg', defaultInfo.format);
+
+        sharp(inputTiffBuffer, { page: 1 }) // 50%-scale copy of page 0
+          .jpeg()
+          .toBuffer(function (err, scaledData, scaledInfo) {
+            if (err) throw err;
+            assert.strictEqual(true, scaledData.length > 0);
+            assert.strictEqual(scaledData.length, scaledInfo.size);
+            assert.strictEqual('jpeg', scaledInfo.format);
+            assert.strictEqual(defaultInfo.width, scaledInfo.width * 2);
+            assert.strictEqual(defaultInfo.height, scaledInfo.height * 2);
+            done();
+          });
+      });
+  });
+
   it('Save TIFF to Buffer', function (done) {
     sharp(fixtures.inputTiff)
       .resize(320, 240)
@@ -1020,6 +1083,22 @@ describe('Input/output', function () {
       });
   });
 
+  it('TIFF ccittfax4 compression shrinks b-w test file', function (done) {
+    const startSize = fs.statSync(fixtures.inputTiff).size;
+    sharp(fixtures.inputTiff)
+      .toColourspace('b-w')
+      .tiff({
+        squash: true,
+        compression: 'ccittfax4'
+      })
+      .toFile(fixtures.outputTiff, (err, info) => {
+        if (err) throw err;
+        assert.strictEqual('tiff', info.format);
+        assert(info.size < startSize);
+        fs.unlink(fixtures.outputTiff, done);
+      });
+  });
+
   it('TIFF deflate compression with horizontal predictor shrinks test file', function (done) {
     const startSize = fs.statSync(fixtures.inputTiffUncompressed).size;
     sharp(fixtures.inputTiffUncompressed)

test/unit/libvips.js

@@ -58,5 +58,13 @@ describe('libvips binaries', function () {
       const hasVendoredLibvips = libvips.hasVendoredLibvips();
       assert.strictEqual('boolean', typeof hasVendoredLibvips);
     });
+    it('useGlobalLibvips can be ignored via an env var', function () {
+      process.env.SHARP_IGNORE_GLOBAL_LIBVIPS = 1;
+
+      const useGlobalLibvips = libvips.useGlobalLibvips();
+      assert.strictEqual(false, useGlobalLibvips);
+
+      delete process.env.SHARP_IGNORE_GLOBAL_LIBVIPS;
+    });
   });
 });

test/unit/tile.js

@@ -6,7 +6,7 @@ const assert = require('assert');
 
 const eachLimit = require('async/eachLimit');
 const rimraf = require('rimraf');
-const unzip = require('unzip');
+const DecompressZip = require('decompress-zip');
 
 const sharp = require('../../');
 const fixtures = require('../fixtures');
@@ -427,16 +427,14 @@ describe('Tile', function () {
             if (err) throw err;
             assert.strictEqual(true, stat.isFile());
             assert.strictEqual(true, stat.size > 0);
-            fs.createReadStream(container)
+            new DecompressZip(container)
-              .pipe(unzip.Extract({
+              .on('extract', function () {
-                path: path.dirname(extractTo)
+                assertDeepZoomTiles(directory, 256, 13, done);
-              }))
+              })
               .on('error', function (err) {
                 throw err;
               })
-              .on('close', function () {
+              .extract({ path: path.dirname(extractTo) });
-                assertDeepZoomTiles(directory, 256, 13, done);
-              });
           });
         });
     });
@@ -463,16 +461,14 @@ describe('Tile', function () {
             if (err) throw err;
             assert.strictEqual(true, stat.isFile());
             assert.strictEqual(true, stat.size > 0);
-            fs.createReadStream(container)
+            new DecompressZip(container)
-              .pipe(unzip.Extract({
+              .on('extract', function () {
-                path: path.dirname(extractTo)
+                assertDeepZoomTiles(directory, 256, 13, done);
-              }))
+              })
               .on('error', function (err) {
                 throw err;
               })
-              .on('close', function () {
+              .extract({ path: path.dirname(extractTo) });
-                assertDeepZoomTiles(directory, 256, 13, done);
-              });
           });
         });
     });

test/unit/tint.js

@@ -0,0 +1,102 @@
+'use strict';
+
+const assert = require('assert');
+
+const sharp = require('../../');
+const fixtures = require('../fixtures');
+
+describe('Tint', function () {
+  it('tints rgb image red', function (done) {
+    const output = fixtures.path('output.tint-red.jpg');
+    sharp(fixtures.inputJpg)
+      .resize(320, 240)
+      .tint('#FF0000')
+      .toFile(output, function (err, info) {
+        if (err) throw err;
+        assert.strictEqual(true, info.size > 0);
+        fixtures.assertMaxColourDistance(output, fixtures.expected('tint-red.jpg'), 10);
+        done();
+      });
+  });
+
+  it('tints rgb image green', function (done) {
+    const output = fixtures.path('output.tint-green.jpg');
+    sharp(fixtures.inputJpg)
+      .resize(320, 240)
+      .tint('#00FF00')
+      .toFile(output, function (err, info) {
+        if (err) throw err;
+        assert.strictEqual(true, info.size > 0);
+        fixtures.assertMaxColourDistance(output, fixtures.expected('tint-green.jpg'), 10);
+        done();
+      });
+  });
+
+  it('tints rgb image blue', function (done) {
+    const output = fixtures.path('output.tint-blue.jpg');
+    sharp(fixtures.inputJpg)
+      .resize(320, 240)
+      .tint('#0000FF')
+      .toFile(output, function (err, info) {
+        if (err) throw err;
+        assert.strictEqual(true, info.size > 0);
+        fixtures.assertMaxColourDistance(output, fixtures.expected('tint-blue.jpg'), 10);
+        done();
+      });
+  });
+
+  it('tints rgb image with sepia tone', function (done) {
+    const output = fixtures.path('output.tint-sepia.jpg');
+    sharp(fixtures.inputJpg)
+      .resize(320, 240)
+      .tint('#704214')
+      .toFile(output, function (err, info) {
+        if (err) throw err;
+        assert.strictEqual(320, info.width);
+        assert.strictEqual(240, info.height);
+        fixtures.assertMaxColourDistance(output, fixtures.expected('tint-sepia.jpg'), 10);
+        done();
+      });
+  });
+
+  it('tints rgb image with sepia tone with rgb colour', function (done) {
+    const output = fixtures.path('output.tint-sepia.jpg');
+    sharp(fixtures.inputJpg)
+      .resize(320, 240)
+      .tint([112, 66, 20])
+      .toFile(output, function (err, info) {
+        if (err) throw err;
+        assert.strictEqual(320, info.width);
+        assert.strictEqual(240, info.height);
+        fixtures.assertMaxColourDistance(output, fixtures.expected('tint-sepia.jpg'), 10);
+        done();
+      });
+  });
+
+  it('tints rgb image with alpha channel', function (done) {
+    const output = fixtures.path('output.tint-alpha.png');
+    sharp(fixtures.inputPngRGBWithAlpha)
+      .resize(320, 240)
+      .tint('#704214')
+      .toFile(output, function (err, info) {
+        if (err) throw err;
+        assert.strictEqual(320, info.width);
+        assert.strictEqual(240, info.height);
+        fixtures.assertMaxColourDistance(output, fixtures.expected('tint-alpha.png'), 10);
+        done();
+      });
+  });
+
+  it('tints cmyk image red', function (done) {
+    const output = fixtures.path('output.tint-cmyk.jpg');
+    sharp(fixtures.inputJpgWithCmykProfile)
+      .resize(320, 240)
+      .tint('#FF0000')
+      .toFile(output, function (err, info) {
+        if (err) throw err;
+        assert.strictEqual(true, info.size > 0);
+        fixtures.assertMaxColourDistance(output, fixtures.expected('tint-cmyk.jpg'), 10);
+        done();
+      });
+  });
+});