sharp 0.20.8 → 0.21.3

package/docs/api-resize.md

@@ -2,181 +2,233 @@
 
 ## resize
 
-Resize image to `width` x `height`.
-By default, the resized image is centre cropped to the exact size specified.
+Resize image to `width`, `height` or `width x height`.
 
-Possible kernels are:
+When both a `width` and `height` are provided, the possible methods by which the image should **fit** these are:
 
--   `nearest`: Use [nearest neighbour interpolation][1].
--   `cubic`: Use a [Catmull-Rom spline][2].
--   `lanczos2`: Use a [Lanczos kernel][3] with `a=2`.
+-   `cover`: Crop to cover both provided dimensions (the default).
+-   `contain`: Embed within both provided dimensions.
+-   `fill`: Ignore the aspect ratio of the input and stretch to both provided dimensions.
+-   `inside`: Preserving aspect ratio, resize the image to be as large as possible while ensuring its dimensions are less than or equal to both those specified.
+-   `outside`: Preserving aspect ratio, resize the image to be as small as possible while ensuring its dimensions are greater than or equal to both those specified.
+    Some of these values are based on the [object-fit][1] CSS property.
+
+When using a `fit` of `cover` or `contain`, the default **position** is `centre`. Other options are:
+
+-   `sharp.position`: `top`, `right top`, `right`, `right bottom`, `bottom`, `left bottom`, `left`, `left top`.
+-   `sharp.gravity`: `north`, `northeast`, `east`, `southeast`, `south`, `southwest`, `west`, `northwest`, `center` or `centre`.
+-   `sharp.strategy`: `cover` only, dynamically crop using either the `entropy` or `attention` strategy.
+    Some of these values are based on the [object-position][2] CSS property.
+
+The experimental strategy-based approach resizes so one dimension is at its target length
+then repeatedly ranks edge regions, discarding the edge with the lowest score based on the selected strategy.
+
+-   `entropy`: focus on the region with the highest [Shannon entropy][3].
+-   `attention`: focus on the region with the highest luminance frequency, colour saturation and presence of skin tones.
+
+Possible interpolation kernels are:
+
+-   `nearest`: Use [nearest neighbour interpolation][4].
+-   `cubic`: Use a [Catmull-Rom spline][5].
+-   `mitchell`: Use a [Mitchell-Netravali spline][6].
+-   `lanczos2`: Use a [Lanczos kernel][7] with `a=2`.
 -   `lanczos3`: Use a Lanczos kernel with `a=3` (the default).
 
 ### Parameters
 
--   `width` **[Number][4]?** pixels wide the resultant image should be. Use `null` or `undefined` to auto-scale the width to match the height.
--   `height` **[Number][4]?** pixels high the resultant image should be. Use `null` or `undefined` to auto-scale the height to match the width.
--   `options` **[Object][5]?** 
-    -   `options.kernel` **[String][6]** the kernel to use for image reduction. (optional, default `'lanczos3'`)
-    -   `options.fastShrinkOnLoad` **[Boolean][7]** take greater advantage of the JPEG and WebP shrink-on-load feature, which can lead to a slight moiré pattern on some images. (optional, default `true`)
+-   `width` **[Number][8]?** pixels wide the resultant image should be. Use `null` or `undefined` to auto-scale the width to match the height.
+-   `height` **[Number][8]?** pixels high the resultant image should be. Use `null` or `undefined` to auto-scale the height to match the width.
+-   `options` **[Object][9]?** 
+    -   `options.width` **[String][10]?** alternative means of specifying `width`. If both are present this take priority.
+    -   `options.height` **[String][10]?** alternative means of specifying `height`. If both are present this take priority.
+    -   `options.fit` **[String][10]** how the image should be resized to fit both provided dimensions, one of `cover`, `contain`, `fill`, `inside` or `outside`. (optional, default `'cover'`)
+    -   `options.position` **[String][10]** position, gravity or strategy to use when `fit` is `cover` or `contain`. (optional, default `'centre'`)
+    -   `options.background` **([String][10] \| [Object][9])** background colour when using a `fit` of `contain`, parsed by the [color][11] module, defaults to black without transparency. (optional, default `{r:0,g:0,b:0,alpha:1}`)
+    -   `options.kernel` **[String][10]** the kernel to use for image reduction. (optional, default `'lanczos3'`)
+    -   `options.withoutEnlargement` **[Boolean][12]** do not enlarge if the width _or_ height are already less than the specified dimensions, equivalent to GraphicsMagick's `>` geometry option. (optional, default `false`)
+    -   `options.fastShrinkOnLoad` **[Boolean][12]** take greater advantage of the JPEG and WebP shrink-on-load feature, which can lead to a slight moiré pattern on some images. (optional, default `true`)
 
 ### Examples
 
 ```javascript
-sharp(inputBuffer)
+sharp(input)
+  .resize({ width: 100 })
+  .toBuffer()
+  .then(data => {
+    // 100 pixels wide, auto-scaled height
+  });
+```
+
+```javascript
+sharp(input)
+  .resize({ height: 100 })
+  .toBuffer()
+  .then(data => {
+    // 100 pixels high, auto-scaled width
+  });
+```
+
+```javascript
+sharp(input)
   .resize(200, 300, {
-    kernel: sharp.kernel.nearest
+    kernel: sharp.kernel.nearest,
+    fit: 'contain',
+    position: 'right top',
+    background: { r: 255, g: 255, b: 255, alpha: 0.5 }
   })
-  .background('white')
-  .embed()
-  .toFile('output.tiff')
-  .then(function() {
-    // output.tiff is a 200 pixels wide and 300 pixels high image
-    // containing a nearest-neighbour scaled version, embedded on a white canvas,
-    // of the image data in inputBuffer
+  .toFile('output.png')
+  .then(() => {
+    // output.png is a 200 pixels wide and 300 pixels high image
+    // containing a nearest-neighbour scaled version
+    // contained within the north-east corner of a semi-transparent white canvas
   });
 ```
 
--   Throws **[Error][8]** Invalid parameters
-
-Returns **Sharp** 
+```javascript
+const transformer = sharp()
+  .resize({
+    width: 200,
+    height: 200,
+    fit: sharp.fit.cover,
+    position: sharp.strategy.entropy
+  });
+// Read image data from readableStream
+// Write 200px square auto-cropped image data to writableStream
+readableStream
+  .pipe(transformer)
+  .pipe(writableStream);
+```
 
-## crop
+```javascript
+sharp(input)
+  .resize(200, 200, {
+    fit: sharp.fit.inside,
+    withoutEnlargement: true
+  })
+  .toFormat('jpeg')
+  .toBuffer()
+  .then(function(outputBuffer) {
+    // outputBuffer contains JPEG image data
+    // no wider and no higher than 200 pixels
+    // and no larger than the input image
+  });
+```
 
-Crop the resized image to the exact size specified, the default behaviour.
+-   Throws **[Error][13]** Invalid parameters
 
-Possible attributes of the optional `sharp.gravity` are `north`, `northeast`, `east`, `southeast`, `south`,
-`southwest`, `west`, `northwest`, `center` and `centre`.
+Returns **Sharp** 
 
-The experimental strategy-based approach resizes so one dimension is at its target length
-then repeatedly ranks edge regions, discarding the edge with the lowest score based on the selected strategy.
+## extend
 
--   `entropy`: focus on the region with the highest [Shannon entropy][9].
--   `attention`: focus on the region with the highest luminance frequency, colour saturation and presence of skin tones.
+Extends/pads the edges of the image with the provided background colour.
+This operation will always occur after resizing and extraction, if any.
 
 ### Parameters
 
--   `crop` **[String][6]** A member of `sharp.gravity` to crop to an edge/corner or `sharp.strategy` to crop dynamically. (optional, default `'centre'`)
+-   `extend` **([Number][8] \| [Object][9])** single pixel count to add to all edges or an Object with per-edge counts
+    -   `extend.top` **[Number][8]?** 
+    -   `extend.left` **[Number][8]?** 
+    -   `extend.bottom` **[Number][8]?** 
+    -   `extend.right` **[Number][8]?** 
+    -   `extend.background` **([String][10] \| [Object][9])** background colour, parsed by the [color][11] module, defaults to black without transparency. (optional, default `{r:0,g:0,b:0,alpha:1}`)
 
 ### Examples
 
 ```javascript
-const transformer = sharp()
-  .resize(200, 200)
-  .crop(sharp.strategy.entropy)
-  .on('error', function(err) {
-    console.log(err);
-  });
-// Read image data from readableStream
-// Write 200px square auto-cropped image data to writableStream
-readableStream.pipe(transformer).pipe(writableStream);
+// Resize to 140 pixels wide, then add 10 transparent pixels
+// to the top, left and right edges and 20 to the bottom edge
+sharp(input)
+  .resize(140)
+  .extend({
+    top: 10,
+    bottom: 20,
+    left: 10,
+    right: 10
+    background: { r: 0, g: 0, b: 0, alpha: 0 }
+  })
+  ...
 ```
 
--   Throws **[Error][8]** Invalid parameters
+-   Throws **[Error][13]** Invalid parameters
 
 Returns **Sharp** 
 
-## embed
+## extract
 
-Preserving aspect ratio, resize the image to the maximum `width` or `height` specified
-then embed on a background of the exact `width` and `height` specified.
+Extract a region of the image.
 
-If the background contains an alpha value then WebP and PNG format output images will
-contain an alpha channel, even when the input image does not.
+-   Use `extract` before `resize` for pre-resize extraction.
+-   Use `extract` after `resize` for post-resize extraction.
+-   Use `extract` before and after for both.
 
 ### Parameters
 
--   `embed` **[String][6]** A member of `sharp.gravity` to embed to an edge/corner. (optional, default `'centre'`)
+-   `options` **[Object][9]** 
+    -   `options.left` **[Number][8]** zero-indexed offset from left edge
+    -   `options.top` **[Number][8]** zero-indexed offset from top edge
+    -   `options.width` **[Number][8]** dimension of extracted image
+    -   `options.height` **[Number][8]** dimension of extracted image
 
 ### Examples
 
 ```javascript
-sharp('input.gif')
-  .resize(200, 300)
-  .background({r: 0, g: 0, b: 0, alpha: 0})
-  .embed()
-  .toFormat(sharp.format.webp)
-  .toBuffer(function(err, outputBuffer) {
-    if (err) {
-      throw err;
-    }
-    // outputBuffer contains WebP image data of a 200 pixels wide and 300 pixels high
-    // containing a scaled version, embedded on a transparent canvas, of input.gif
+sharp(input)
+  .extract({ left: left, top: top, width: width, height: height })
+  .toFile(output, function(err) {
+    // Extract a region of the input image, saving in the same format.
   });
 ```
 
--   Throws **[Error][8]** Invalid parameters
-
-Returns **Sharp** 
-
-## max
-
-Preserving aspect ratio, resize the image to be as large as possible
-while ensuring its dimensions are less than or equal to the `width` and `height` specified.
-
-Both `width` and `height` must be provided via `resize` otherwise the behaviour will default to `crop`.
-
-### Examples
-
 ```javascript
-sharp(inputBuffer)
-  .resize(200, 200)
-  .max()
-  .toFormat('jpeg')
-  .toBuffer()
-  .then(function(outputBuffer) {
-    // outputBuffer contains JPEG image data no wider than 200 pixels and no higher
-    // than 200 pixels regardless of the inputBuffer image dimensions
+sharp(input)
+  .extract({ left: leftOffsetPre, top: topOffsetPre, width: widthPre, height: heightPre })
+  .resize(width, height)
+  .extract({ left: leftOffsetPost, top: topOffsetPost, width: widthPost, height: heightPost })
+  .toFile(output, function(err) {
+    // Extract a region, resize, then extract from the resized image
   });
 ```
 
+-   Throws **[Error][13]** Invalid parameters
+
 Returns **Sharp** 
 
-## min
+## trim
 
-Preserving aspect ratio, resize the image to be as small as possible
-while ensuring its dimensions are greater than or equal to the `width` and `height` specified.
+Trim "boring" pixels from all edges that contain values similar to the top-left pixel.
+The `info` response Object will contain `trimOffsetLeft` and `trimOffsetTop` properties.
 
-Both `width` and `height` must be provided via `resize` otherwise the behaviour will default to `crop`.
+### Parameters
 
-Returns **Sharp** 
+-   `threshold` **[Number][8]** the allowed difference from the top-left pixel, a number greater than zero. (optional, default `10`)
 
-## ignoreAspectRatio
 
-Ignoring the aspect ratio of the input, stretch the image to
-the exact `width` and/or `height` provided via `resize`.
+-   Throws **[Error][13]** Invalid parameters
 
 Returns **Sharp** 
 
-## withoutEnlargement
+[1]: https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit
 
-Do not enlarge the output image if the input image width _or_ height are already less than the required dimensions.
-This is equivalent to GraphicsMagick's `>` geometry option:
-"_change the dimensions of the image only if its width or height exceeds the geometry specification_".
-Use with `max()` to preserve the image's aspect ratio.
+[2]: https://developer.mozilla.org/en-US/docs/Web/CSS/object-position
 
-The default behaviour _before_ function call is `false`, meaning the image will be enlarged.
+[3]: https://en.wikipedia.org/wiki/Entropy_%28information_theory%29
 
-### Parameters
-
--   `withoutEnlargement` **[Boolean][7]**  (optional, default `true`)
-
-Returns **Sharp** 
+[4]: http://en.wikipedia.org/wiki/Nearest-neighbor_interpolation
 
-[1]: http://en.wikipedia.org/wiki/Nearest-neighbor_interpolation
+[5]: https://en.wikipedia.org/wiki/Centripetal_Catmull%E2%80%93Rom_spline
 
-[2]: https://en.wikipedia.org/wiki/Centripetal_Catmull%E2%80%93Rom_spline
+[6]: https://www.cs.utexas.edu/~fussell/courses/cs384g-fall2013/lectures/mitchell/Mitchell.pdf
 
-[3]: https://en.wikipedia.org/wiki/Lanczos_resampling#Lanczos_kernel
+[7]: https://en.wikipedia.org/wiki/Lanczos_resampling#Lanczos_kernel
 
-[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
+[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
 
-[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
 
-[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
 
-[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
+[11]: https://www.npmjs.org/package/color
 
-[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error
+[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
 
-[9]: https://en.wikipedia.org/wiki/Entropy_%28information_theory%29
+[13]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error

package/docs/api-utility.md

@@ -77,23 +77,20 @@ Requires libvips to have been compiled with liborc support.
 Improves the performance of `resize`, `blur` and `sharpen` operations
 by taking advantage of the SIMD vector unit of the CPU, e.g. Intel SSE and ARM NEON.
 
-This feature is currently off by default but future versions may reverse this.
-Versions of liborc prior to 0.4.25 are known to segfault under heavy load.
-
 ### Parameters
 
--   `simd` **[Boolean][2]**  (optional, default `false`)
+-   `simd` **[Boolean][2]**  (optional, default `true`)
 
 ### Examples
 
 ```javascript
 const simd = sharp.simd();
-// simd is `true` if SIMD is currently enabled
+// simd is `true` if the runtime use of liborc is currently enabled
 ```
 
 ```javascript
-const simd = sharp.simd(true);
-// attempts to enable the use of SIMD, returning true if available
+const simd = sharp.simd(false);
+// prevent libvips from using liborc at runtime
 ```
 
 Returns **[Boolean][2]** 

package/docs/changelog.md

@@ -1,5 +1,107 @@
 # Changelog
 
+### v0.21 - "*teeth*"
+
+Requires libvips v8.7.0.
+
+#### v0.21.3 - 19<sup>th</sup> January 2019
+
+* Input image decoding now fails fast, set `failOnError` to change this behaviour.
+
+* Failed filesystem-based input now separates missing file and invalid format errors.
+  [#1542](https://github.com/lovell/sharp/issues/1542)
+
+#### v0.21.2 - 13<sup>th</sup> January 2019
+
+* Ensure all metadata is removed from PNG output unless `withMetadata` used.
+
+* Ensure shortest edge is at least one pixel after resizing.
+  [#1003](https://github.com/lovell/sharp/issues/1003)
+
+* Add `ensureAlpha` operation to add an alpha channel, if missing.
+  [#1153](https://github.com/lovell/sharp/issues/1153)
+
+* Expose `pages` and `pageHeight` metadata for multi-page input images.
+  [#1205](https://github.com/lovell/sharp/issues/1205)
+
+* Expose PNG output options requiring libimagequant.
+  [#1484](https://github.com/lovell/sharp/issues/1484)
+
+* Expose underlying error message for invalid input.
+  [#1505](https://github.com/lovell/sharp/issues/1505)
+
+* Prevent mutatation of options passed to `jpeg`.
+  [#1516](https://github.com/lovell/sharp/issues/1516)
+
+* Ensure forced output format applied correctly when output chaining.
+  [#1528](https://github.com/lovell/sharp/issues/1528)
+
+#### v0.21.1 - 7<sup>th</sup> December 2018
+
+* Install: support `sharp_dist_base_url` npm config, like existing `SHARP_DIST_BASE_URL`.
+  [#1422](https://github.com/lovell/sharp/pull/1422)
+  [@SethWen](https://github.com/SethWen)
+
+* Ensure `channel` metadata is correct for raw, greyscale output.
+  [#1425](https://github.com/lovell/sharp/issues/1425)
+
+* Add support for the "mitchell" kernel for image reductions.
+  [#1438](https://github.com/lovell/sharp/pull/1438)
+  [@Daiz](https://github.com/Daiz)
+
+* Allow separate parameters for gamma encoding and decoding.
+  [#1439](https://github.com/lovell/sharp/pull/1439)
+  [@Daiz](https://github.com/Daiz)
+
+* Build prototype with `Object.assign` to allow minification.
+  [#1475](https://github.com/lovell/sharp/pull/1475)
+  [@jaubourg](https://github.com/jaubourg)
+
+* Expose libvips' recombination matrix operation.
+  [#1477](https://github.com/lovell/sharp/pull/1477)
+  [@fromkeith](https://github.com/fromkeith)
+
+* Expose libvips' pyramid/tile options for TIFF output.
+  [#1483](https://github.com/lovell/sharp/pull/1483)
+  [@mbklein](https://github.com/mbklein)
+
+#### v0.21.0 - 4<sup>th</sup> October 2018
+
+* Deprecate the following resize-related functions:
+    `crop`, `embed`, `ignoreAspectRatio`, `max`, `min` and `withoutEnlargement`.
+  Access to these is now via options passed to the `resize` function.
+  For example:
+    `embed('north')` is now `resize(width, height, { fit: 'contain', position: 'north' })`,
+    `crop('attention')` is now `resize(width, height, { fit: 'cover', position: 'attention' })`,
+    `max().withoutEnlargement()` is now `resize(width, height, { fit: 'inside', withoutEnlargement: true })`.
+  [#1135](https://github.com/lovell/sharp/issues/1135)
+
+* Deprecate the `background` function.
+    Per-operation `background` options added to `resize`, `extend` and `flatten` operations.
+  [#1392](https://github.com/lovell/sharp/issues/1392)
+
+* Add `size` to `metadata` response (Stream and Buffer input only).
+  [#695](https://github.com/lovell/sharp/issues/695)
+
+* Switch from custom trim operation to `vips_find_trim`.
+  [#914](https://github.com/lovell/sharp/issues/914)
+
+* Add `chromaSubsampling` and `isProgressive` properties to `metadata` response.
+  [#1186](https://github.com/lovell/sharp/issues/1186)
+
+* Drop Node 4 support.
+  [#1212](https://github.com/lovell/sharp/issues/1212)
+
+* Enable SIMD convolution by default.
+  [#1213](https://github.com/lovell/sharp/issues/1213)
+
+* Add experimental prebuilt binaries for musl-based Linux.
+  [#1379](https://github.com/lovell/sharp/issues/1379)
+
+* Add support for arbitrary rotation angle via vips_rotate.
+  [#1385](https://github.com/lovell/sharp/pull/1385)
+  [@freezy](https://github.com/freezy)
+
 ### v0.20 - "*prebuild*"
 
 Requires libvips v8.6.1.

package/docs/image/sharp-logo.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="86 86 550 550">
+<!-- Copyright 2019 Lovell Fuller. This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) License. -->
+<path fill="none" stroke="#9c0" stroke-width="80" d="M258.411 285.777l200.176-26.8M244.113 466.413L451.44 438.66M451.441 438.66V238.484M451.441 88.363v171.572l178.725-23.917M270.323 255.602V477.22M272.71 634.17V462.591L93.984 486.515"/>
+<path fill="none" stroke="#090" stroke-width="80" d="M451.441 610.246V438.66l178.725-23.91M269.688 112.59v171.58L90.964 308.093"/>
+</svg>

package/docs/index.md

@@ -1,5 +1,7 @@
 # sharp
 
+<img src="image/sharp-logo.svg" width="160" height="160" alt="sharp logo" align="right">
+
 The typical use case for this high speed Node.js module
 is to convert large images in common formats to
 smaller, web-friendly JPEG, PNG and WebP images of varying dimensions.
@@ -13,8 +15,8 @@ Lanczos resampling ensures quality is not sacrificed for speed.
 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 10
+Most modern 64-bit OS X, Windows and Linux systems running
+Node versions 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)
@@ -37,7 +39,7 @@ and [Leaflet](https://github.com/turban/Leaflet.Zoomify).
 ### Fast
 
 This module is powered by the blazingly fast
-[libvips](https://github.com/jcupitt/libvips) image processing library,
+[libvips](https://github.com/libvips/libvips) image processing library,
 originally created in 1989 at Birkbeck College
 and currently maintained by
 [John Cupitt](https://github.com/jcupitt).
@@ -118,17 +120,21 @@ the help and code contributions of the following people:
 * [Alun Davies](https://github.com/alundavies)
 * [Aidan Hoolachan](https://github.com/ajhool)
 * [Axel Eirola](https://github.com/aeirola)
+* [Freezy](https://github.com/freezy)
+* [Julian Aubourg](https://github.com/jaubourg)
+* [Keith Belovay](https://github.com/fromkeith)
+* [Michael B. Klein](https://github.com/mbklein)
 
 Thank you!
 
-### Licence
+### Licensing
 
-Copyright 2013, 2014, 2015, 2016, 2017, 2018 Lovell Fuller and contributors.
+Copyright 2013, 2014, 2015, 2016, 2017, 2018, 2019 Lovell Fuller and contributors.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at
-[http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0.html)
+[https://www.apache.org/licenses/LICENSE-2.0](https://www.apache.org/licenses/LICENSE-2.0)
 
 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,