From ba46ad1fd9f9bea37fdc2146989e17ea55074ac1 Mon Sep 17 00:00:00 2001 From: Lovell Fuller Date: Wed, 25 Sep 2019 16:56:52 +0100 Subject: [PATCH] Docs: mention removal of metadata in output methods --- docs/api-output.md | 177 ++++++++++++++++++++++++--------------------- lib/output.js | 9 ++- 2 files changed, 101 insertions(+), 85 deletions(-) diff --git a/docs/api-output.md b/docs/api-output.md index 9802c6c6..96e5f6f0 100644 --- a/docs/api-output.md +++ b/docs/api-output.md @@ -8,12 +8,15 @@ If an explicit output format is not selected, it will be inferred from the exten with JPEG, PNG, WebP, TIFF, DZI, and libvips' V format supported. Note that raw pixel data is only supported for buffer output. +By default all metadata will be removed, which includes EXIF-based orientation. +See [withMetadata][1] for control over this. + A `Promise` is returned when `callback` is not provided. ### Parameters -- `fileOut` **[String][1]** the path to write the image data to. -- `callback` **[Function][2]?** called on completion with two arguments `(err, info)`. +- `fileOut` **[String][2]** the path to write the image data to. +- `callback` **[Function][3]?** called on completion with two arguments `(err, info)`. `info` contains the output image `format`, `size` (bytes), `width`, `height`, `channels` and `premultiplied` (indicating if premultiplication was used). When using a crop strategy also contains `cropOffsetLeft` and `cropOffsetTop`. @@ -32,15 +35,19 @@ sharp(input) .catch(err => { ... }); ``` -- Throws **[Error][3]** Invalid parameters +- Throws **[Error][4]** Invalid parameters -Returns **[Promise][4]<[Object][5]>** when no callback is provided +Returns **[Promise][5]<[Object][6]>** when no callback is provided ## toBuffer Write output to a Buffer. JPEG, PNG, WebP, TIFF and RAW output are supported. -By default, the format will match the input image, except GIF and SVG input which become PNG output. + +If no explicit format is set, the output format will match the input image, except GIF and SVG input which become PNG output. + +By default all metadata will be removed, which includes EXIF-based orientation. +See [withMetadata][1] for control over this. `callback`, if present, gets three arguments `(err, data, info)` where: @@ -54,9 +61,9 @@ A `Promise` is returned when `callback` is not provided. ### Parameters -- `options` **[Object][5]?** - - `options.resolveWithObject` **[Boolean][6]?** Resolve the Promise with an Object containing `data` and `info` properties instead of resolving only with `data`. -- `callback` **[Function][2]?** +- `options` **[Object][6]?** + - `options.resolveWithObject` **[Boolean][7]?** Resolve the Promise with an Object containing `data` and `info` properties instead of resolving only with `data`. +- `callback` **[Function][3]?** ### Examples @@ -79,7 +86,7 @@ sharp(input) .catch(err => { ... }); ``` -Returns **[Promise][4]<[Buffer][7]>** when no callback is provided +Returns **[Promise][5]<[Buffer][8]>** when no callback is provided ## withMetadata @@ -89,8 +96,8 @@ This will also convert to and add a web-friendly sRGB ICC profile. ### Parameters -- `options` **[Object][5]?** - - `options.orientation` **[Number][8]?** value between 1 and 8, used to update the EXIF `Orientation` tag. +- `options` **[Object][6]?** + - `options.orientation` **[Number][9]?** value between 1 and 8, used to update the EXIF `Orientation` tag. ### Examples @@ -101,7 +108,7 @@ sharp('input.jpg') .then(info => { ... }); ``` -- Throws **[Error][3]** Invalid parameters +- Throws **[Error][4]** Invalid parameters Returns **Sharp** @@ -111,19 +118,19 @@ Use these JPEG options for output image. ### Parameters -- `options` **[Object][5]?** output options - - `options.quality` **[Number][8]** quality, integer 1-100 (optional, default `80`) - - `options.progressive` **[Boolean][6]** use progressive (interlace) scan (optional, default `false`) - - `options.chromaSubsampling` **[String][1]** set to '4:4:4' to prevent chroma subsampling when quality <= 90 (optional, default `'4:2:0'`) - - `options.trellisQuantisation` **[Boolean][6]** apply trellis quantisation, requires libvips compiled with support for mozjpeg (optional, default `false`) - - `options.overshootDeringing` **[Boolean][6]** apply overshoot deringing, requires libvips compiled with support for mozjpeg (optional, default `false`) - - `options.optimiseScans` **[Boolean][6]** optimise progressive scans, forces progressive, requires libvips compiled with support for mozjpeg (optional, default `false`) - - `options.optimizeScans` **[Boolean][6]** alternative spelling of optimiseScans (optional, default `false`) - - `options.optimiseCoding` **[Boolean][6]** optimise Huffman coding tables (optional, default `true`) - - `options.optimizeCoding` **[Boolean][6]** alternative spelling of optimiseCoding (optional, default `true`) - - `options.quantisationTable` **[Number][8]** quantization table to use, integer 0-8, requires libvips compiled with support for mozjpeg (optional, default `0`) - - `options.quantizationTable` **[Number][8]** alternative spelling of quantisationTable (optional, default `0`) - - `options.force` **[Boolean][6]** force JPEG output, otherwise attempt to use input format (optional, default `true`) +- `options` **[Object][6]?** output options + - `options.quality` **[Number][9]** quality, integer 1-100 (optional, default `80`) + - `options.progressive` **[Boolean][7]** use progressive (interlace) scan (optional, default `false`) + - `options.chromaSubsampling` **[String][2]** set to '4:4:4' to prevent chroma subsampling when quality <= 90 (optional, default `'4:2:0'`) + - `options.trellisQuantisation` **[Boolean][7]** apply trellis quantisation, requires libvips compiled with support for mozjpeg (optional, default `false`) + - `options.overshootDeringing` **[Boolean][7]** apply overshoot deringing, requires libvips compiled with support for mozjpeg (optional, default `false`) + - `options.optimiseScans` **[Boolean][7]** optimise progressive scans, forces progressive, requires libvips compiled with support for mozjpeg (optional, default `false`) + - `options.optimizeScans` **[Boolean][7]** alternative spelling of optimiseScans (optional, default `false`) + - `options.optimiseCoding` **[Boolean][7]** optimise Huffman coding tables (optional, default `true`) + - `options.optimizeCoding` **[Boolean][7]** alternative spelling of optimiseCoding (optional, default `true`) + - `options.quantisationTable` **[Number][9]** quantization table to use, integer 0-8, requires libvips compiled with support for mozjpeg (optional, default `0`) + - `options.quantizationTable` **[Number][9]** alternative spelling of quantisationTable (optional, default `0`) + - `options.force` **[Boolean][7]** force JPEG output, otherwise attempt to use input format (optional, default `true`) ### Examples @@ -137,7 +144,7 @@ const data = await sharp(input) .toBuffer(); ``` -- Throws **[Error][3]** Invalid options +- Throws **[Error][4]** Invalid options Returns **Sharp** @@ -150,16 +157,16 @@ Indexed PNG input at 1, 2 or 4 bits per pixel is converted to 8 bits per pixel. ### Parameters -- `options` **[Object][5]?** - - `options.progressive` **[Boolean][6]** use progressive (interlace) scan (optional, default `false`) - - `options.compressionLevel` **[Number][8]** zlib compression level, 0-9 (optional, default `9`) - - `options.adaptiveFiltering` **[Boolean][6]** use adaptive row filtering (optional, default `false`) - - `options.palette` **[Boolean][6]** quantise to a palette-based image with alpha transparency support, requires libvips compiled with support for libimagequant (optional, default `false`) - - `options.quality` **[Number][8]** use the lowest number of colours needed to achieve given quality, requires libvips compiled with support for libimagequant (optional, default `100`) - - `options.colours` **[Number][8]** maximum number of palette entries, requires libvips compiled with support for libimagequant (optional, default `256`) - - `options.colors` **[Number][8]** alternative spelling of `options.colours`, requires libvips compiled with support for libimagequant (optional, default `256`) - - `options.dither` **[Number][8]** level of Floyd-Steinberg error diffusion, requires libvips compiled with support for libimagequant (optional, default `1.0`) - - `options.force` **[Boolean][6]** force PNG output, otherwise attempt to use input format (optional, default `true`) +- `options` **[Object][6]?** + - `options.progressive` **[Boolean][7]** use progressive (interlace) scan (optional, default `false`) + - `options.compressionLevel` **[Number][9]** zlib compression level, 0-9 (optional, default `9`) + - `options.adaptiveFiltering` **[Boolean][7]** use adaptive row filtering (optional, default `false`) + - `options.palette` **[Boolean][7]** quantise to a palette-based image with alpha transparency support, requires libvips compiled with support for libimagequant (optional, default `false`) + - `options.quality` **[Number][9]** use the lowest number of colours needed to achieve given quality, requires libvips compiled with support for libimagequant (optional, default `100`) + - `options.colours` **[Number][9]** maximum number of palette entries, requires libvips compiled with support for libimagequant (optional, default `256`) + - `options.colors` **[Number][9]** alternative spelling of `options.colours`, requires libvips compiled with support for libimagequant (optional, default `256`) + - `options.dither` **[Number][9]** level of Floyd-Steinberg error diffusion, requires libvips compiled with support for libimagequant (optional, default `1.0`) + - `options.force` **[Boolean][7]** force PNG output, otherwise attempt to use input format (optional, default `true`) ### Examples @@ -170,7 +177,7 @@ const data = await sharp(input) .toBuffer(); ``` -- Throws **[Error][3]** Invalid options +- Throws **[Error][4]** Invalid options Returns **Sharp** @@ -180,14 +187,14 @@ Use these WebP options for output image. ### Parameters -- `options` **[Object][5]?** output options - - `options.quality` **[Number][8]** quality, integer 1-100 (optional, default `80`) - - `options.alphaQuality` **[Number][8]** quality of alpha layer, integer 0-100 (optional, default `100`) - - `options.lossless` **[Boolean][6]** use lossless compression mode (optional, default `false`) - - `options.nearLossless` **[Boolean][6]** use near_lossless compression mode (optional, default `false`) - - `options.smartSubsample` **[Boolean][6]** use high quality chroma subsampling (optional, default `false`) - - `options.reductionEffort` **[Number][8]** level of CPU effort to reduce file size, integer 0-6 (optional, default `4`) - - `options.force` **[Boolean][6]** force WebP output, otherwise attempt to use input format (optional, default `true`) +- `options` **[Object][6]?** output options + - `options.quality` **[Number][9]** quality, integer 1-100 (optional, default `80`) + - `options.alphaQuality` **[Number][9]** quality of alpha layer, integer 0-100 (optional, default `100`) + - `options.lossless` **[Boolean][7]** use lossless compression mode (optional, default `false`) + - `options.nearLossless` **[Boolean][7]** use near_lossless compression mode (optional, default `false`) + - `options.smartSubsample` **[Boolean][7]** use high quality chroma subsampling (optional, default `false`) + - `options.reductionEffort` **[Number][9]** level of CPU effort to reduce file size, integer 0-6 (optional, default `4`) + - `options.force` **[Boolean][7]** force WebP output, otherwise attempt to use input format (optional, default `true`) ### Examples @@ -198,7 +205,7 @@ const data = await sharp(input) .toBuffer(); ``` -- Throws **[Error][3]** Invalid options +- Throws **[Error][4]** Invalid options Returns **Sharp** @@ -208,18 +215,18 @@ Use these TIFF options for output image. ### Parameters -- `options` **[Object][5]?** output options - - `options.quality` **[Number][8]** quality, integer 1-100 (optional, default `80`) - - `options.force` **[Boolean][6]** force TIFF output, otherwise attempt to use input format (optional, default `true`) - - `options.compression` **[Boolean][6]** compression options: lzw, deflate, jpeg, ccittfax4 (optional, default `'jpeg'`) - - `options.predictor` **[Boolean][6]** compression predictor options: none, horizontal, float (optional, default `'horizontal'`) - - `options.pyramid` **[Boolean][6]** write an image pyramid (optional, default `false`) - - `options.tile` **[Boolean][6]** write a tiled tiff (optional, default `false`) - - `options.tileWidth` **[Boolean][6]** horizontal tile size (optional, default `256`) - - `options.tileHeight` **[Boolean][6]** vertical tile size (optional, default `256`) - - `options.xres` **[Number][8]** horizontal resolution in pixels/mm (optional, default `1.0`) - - `options.yres` **[Number][8]** vertical resolution in pixels/mm (optional, default `1.0`) - - `options.squash` **[Boolean][6]** squash 8-bit images down to 1 bit (optional, default `false`) +- `options` **[Object][6]?** output options + - `options.quality` **[Number][9]** quality, integer 1-100 (optional, default `80`) + - `options.force` **[Boolean][7]** force TIFF output, otherwise attempt to use input format (optional, default `true`) + - `options.compression` **[Boolean][7]** compression options: lzw, deflate, jpeg, ccittfax4 (optional, default `'jpeg'`) + - `options.predictor` **[Boolean][7]** compression predictor options: none, horizontal, float (optional, default `'horizontal'`) + - `options.pyramid` **[Boolean][7]** write an image pyramid (optional, default `false`) + - `options.tile` **[Boolean][7]** write a tiled tiff (optional, default `false`) + - `options.tileWidth` **[Boolean][7]** horizontal tile size (optional, default `256`) + - `options.tileHeight` **[Boolean][7]** vertical tile size (optional, default `256`) + - `options.xres` **[Number][9]** horizontal resolution in pixels/mm (optional, default `1.0`) + - `options.yres` **[Number][9]** vertical resolution in pixels/mm (optional, default `1.0`) + - `options.squash` **[Boolean][7]** squash 8-bit images down to 1 bit (optional, default `false`) ### Examples @@ -234,7 +241,7 @@ sharp('input.svg') .then(info => { ... }); ``` -- Throws **[Error][3]** Invalid options +- Throws **[Error][4]** Invalid options Returns **Sharp** @@ -251,13 +258,13 @@ Most versions of libheif support only the patent-encumbered HEVC compression for ### Parameters -- `options` **[Object][5]?** output options - - `options.quality` **[Number][8]** quality, integer 1-100 (optional, default `80`) - - `options.compression` **[Boolean][6]** compression format: hevc, avc, jpeg, av1 (optional, default `'hevc'`) - - `options.lossless` **[Boolean][6]** use lossless compression (optional, default `false`) +- `options` **[Object][6]?** output options + - `options.quality` **[Number][9]** quality, integer 1-100 (optional, default `80`) + - `options.compression` **[Boolean][7]** compression format: hevc, avc, jpeg, av1 (optional, default `'hevc'`) + - `options.lossless` **[Boolean][7]** use lossless compression (optional, default `false`) -- Throws **[Error][3]** Invalid options +- Throws **[Error][4]** Invalid options Returns **Sharp** @@ -282,8 +289,8 @@ Force output to a given format. ### Parameters -- `format` **([String][1] \| [Object][5])** as a String or an Object with an 'id' attribute -- `options` **[Object][5]** output options +- `format` **([String][2] \| [Object][6])** as a String or an Object with an 'id' attribute +- `options` **[Object][6]** output options ### Examples @@ -294,7 +301,7 @@ const data = await sharp(input) .toBuffer(); ``` -- Throws **[Error][3]** unsupported format or options +- Throws **[Error][4]** unsupported format or options Returns **Sharp** @@ -308,14 +315,14 @@ Warning: multiple sharp instances concurrently producing tile output can expose ### Parameters -- `options` **[Object][5]?** - - `options.size` **[Number][8]** tile size in pixels, a value between 1 and 8192. (optional, default `256`) - - `options.overlap` **[Number][8]** tile overlap in pixels, a value between 0 and 8192. (optional, default `0`) - - `options.angle` **[Number][8]** tile angle of rotation, must be a multiple of 90. (optional, default `0`) - - `options.depth` **[String][1]?** how deep to make the pyramid, possible values are `onepixel`, `onetile` or `one`, default based on layout. - - `options.skipBlanks` **[Number][8]** threshold to skip tile generation, a value 0 - 255 for 8-bit images or 0 - 65535 for 16-bit images (optional, default `-1`) - - `options.container` **[String][1]** tile container, with value `fs` (filesystem) or `zip` (compressed file). (optional, default `'fs'`) - - `options.layout` **[String][1]** filesystem layout, possible values are `dz`, `zoomify` or `google`. (optional, default `'dz'`) +- `options` **[Object][6]?** + - `options.size` **[Number][9]** tile size in pixels, a value between 1 and 8192. (optional, default `256`) + - `options.overlap` **[Number][9]** tile overlap in pixels, a value between 0 and 8192. (optional, default `0`) + - `options.angle` **[Number][9]** tile angle of rotation, must be a multiple of 90. (optional, default `0`) + - `options.depth` **[String][2]?** how deep to make the pyramid, possible values are `onepixel`, `onetile` or `one`, default based on layout. + - `options.skipBlanks` **[Number][9]** threshold to skip tile generation, a value 0 - 255 for 8-bit images or 0 - 65535 for 16-bit images (optional, default `-1`) + - `options.container` **[String][2]** tile container, with value `fs` (filesystem) or `zip` (compressed file). (optional, default `'fs'`) + - `options.layout` **[String][2]** filesystem layout, possible values are `dz`, `zoomify` or `google`. (optional, default `'dz'`) ### Examples @@ -331,22 +338,24 @@ sharp('input.tiff') }); ``` -- Throws **[Error][3]** Invalid parameters +- Throws **[Error][4]** Invalid parameters Returns **Sharp** -[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String +[1]: #withmetadata -[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function +[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String -[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error +[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function -[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise +[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error -[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object +[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise -[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean +[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object -[7]: https://nodejs.org/api/buffer.html +[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean -[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number +[8]: https://nodejs.org/api/buffer.html + +[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number diff --git a/lib/output.js b/lib/output.js index 15e3e0c0..b37664a2 100644 --- a/lib/output.js +++ b/lib/output.js @@ -10,6 +10,9 @@ const sharp = require('../build/Release/sharp.node'); * with JPEG, PNG, WebP, TIFF, DZI, and libvips' V format supported. * Note that raw pixel data is only supported for buffer output. * + * By default all metadata will be removed, which includes EXIF-based orientation. + * See {@link withMetadata} for control over this. + * * A `Promise` is returned when `callback` is not provided. * * @example @@ -57,7 +60,11 @@ function toFile (fileOut, callback) { /** * Write output to a Buffer. * JPEG, PNG, WebP, TIFF and RAW output are supported. - * By default, the format will match the input image, except GIF and SVG input which become PNG output. + * + * If no explicit format is set, the output format will match the input image, except GIF and SVG input which become PNG output. + * + * By default all metadata will be removed, which includes EXIF-based orientation. + * See {@link withMetadata} for control over this. * * `callback`, if present, gets three arguments `(err, data, info)` where: * - `err` is an error, if any.