Mathis/sharp
1
0
Fork 0
mirror of https://github.com/lovell/sharp.git synced 2025-07-09 18:40:16 +02:00
Code Issues Packages Projects Releases Wiki Activity
sharp/docs/api-output.md
Lovell Fuller 0d9590a9a0 Documentation refresh
2018-06-20 08:14:03 +01:00

403 lines
11 KiB
Markdown
Raw Blame History

<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
### Table of Contents
- [toFile][1]
- [Parameters][2]
- [Examples][3]
- [toBuffer][4]
- [Parameters][5]
- [Examples][6]
- [withMetadata][7]
- [Parameters][8]
- [Examples][9]
- [jpeg][10]
- [Parameters][11]
- [Examples][12]
- [png][13]
- [Parameters][14]
- [Examples][15]
- [webp][16]
- [Parameters][17]
- [Examples][18]
- [tiff][19]
- [Parameters][20]
- [Examples][21]
- [raw][22]
- [Examples][23]
- [toFormat][24]
- [Parameters][25]
- [Examples][26]
- [tile][27]
- [Parameters][28]
- [Examples][29]
## toFile
Write output image data to a file.
If an explicit output format is not selected, it will be inferred from the extension,
with JPEG, PNG, WebP, TIFF, DZI, and libvips' V format supported.
Note that raw pixel data is only supported for buffer output.
A `Promise` is returned when `callback` is not provided.
### Parameters
- `fileOut` **[String][30]** the path to write the image data to.
- `callback` **[Function][31]?** 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`.
### Examples
```javascript
sharp(input)
.toFile('output.png', (err, info) => { ... });
```
```javascript
sharp(input)
.toFile('output.png')
.then(info => { ... })
.catch(err => { ... });
```
- Throws **[Error][32]** Invalid parameters
Returns **[Promise][33]&lt;[Object][34]>** 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.
`callback`, if present, gets three arguments `(err, data, info)` where:
- `err` is an error, if any.
- `data` is the output image data.
- `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`.
A `Promise` is returned when `callback` is not provided.
### Parameters
- `options` **[Object][34]?**
- `options.resolveWithObject` **[Boolean][35]?** Resolve the Promise with an Object containing `data` and `info` properties instead of resolving only with `data`.
- `callback` **[Function][31]?**
### 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][33]&lt;[Buffer][36]>** when no callback is provided
## withMetadata
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.
### Parameters
- `withMetadata` **[Object][34]?**
- `withMetadata.orientation` **[Number][37]?** 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][32]** Invalid parameters
Returns **Sharp**
## jpeg
Use these JPEG options for output image.
### Parameters
- `options` **[Object][34]?** output options
- `options.quality` **[Number][37]** quality, integer 1-100 (optional, default `80`)
- `options.progressive` **[Boolean][35]** use progressive (interlace) scan (optional, default `false`)
- `options.chromaSubsampling` **[String][30]** set to '4:4:4' to prevent chroma subsampling when quality &lt;= 90 (optional, default `'4:2:0'`)
- `options.trellisQuantisation` **[Boolean][35]** apply trellis quantisation, requires mozjpeg (optional, default `false`)
- `options.overshootDeringing` **[Boolean][35]** apply overshoot deringing, requires mozjpeg (optional, default `false`)
- `options.optimiseScans` **[Boolean][35]** optimise progressive scans, forces progressive, requires mozjpeg (optional, default `false`)
- `options.optimizeScans` **[Boolean][35]** alternative spelling of optimiseScans (optional, default `false`)
- `options.force` **[Boolean][35]** 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][32]** Invalid options
Returns **Sharp**
## png
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][34]?**
- `options.progressive` **[Boolean][35]** use progressive (interlace) scan (optional, default `false`)
- `options.compressionLevel` **[Number][37]** zlib compression level, 0-9 (optional, default `9`)
- `options.adaptiveFiltering` **[Boolean][35]** use adaptive row filtering (optional, default `false`)
- `options.force` **[Boolean][35]** 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][32]** Invalid options
Returns **Sharp**
## webp
Use these WebP options for output image.
### Parameters
- `options` **[Object][34]?** output options
- `options.quality` **[Number][37]** quality, integer 1-100 (optional, default `80`)
- `options.alphaQuality` **[Number][37]** quality of alpha layer, integer 0-100 (optional, default `100`)
- `options.lossless` **[Boolean][35]** use lossless compression mode (optional, default `false`)
- `options.nearLossless` **[Boolean][35]** use near_lossless compression mode (optional, default `false`)
- `options.force` **[Boolean][35]** 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][32]** Invalid options
Returns **Sharp**
## tiff
Use these TIFF options for output image.
### Parameters
- `options` **[Object][34]?** output options
- `options.quality` **[Number][37]** quality, integer 1-100 (optional, default `80`)
- `options.force` **[Boolean][35]** force TIFF output, otherwise attempt to use input format (optional, default `true`)
- `options.compression` **[Boolean][35]** compression options: lzw, deflate, jpeg, ccittfax4 (optional, default `'jpeg'`)
- `options.predictor` **[Boolean][35]** compression predictor options: none, horizontal, float (optional, default `'horizontal'`)
- `options.xres` **[Number][37]** horizontal resolution in pixels/mm (optional, default `1.0`)
- `options.yres` **[Number][37]** vertical resolution in pixels/mm (optional, default `1.0`)
- `options.squash` **[Boolean][35]** 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][32]** Invalid options
Returns **Sharp**
## raw
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
Force output to a given format.
### Parameters
- `format` **([String][30] \| [Object][34])** as a String or an Object with an 'id' attribute
- `options` **[Object][34]** output options
### Examples
```javascript
// Convert any input to PNG output
const data = await sharp(input)
.toFormat('png')
.toBuffer();
```
- Throws **[Error][32]** unsupported format or options
Returns **Sharp**
## tile
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][34]?**
- `tile.size` **[Number][37]** tile size in pixels, a value between 1 and 8192. (optional, default `256`)
- `tile.overlap` **[Number][37]** tile overlap in pixels, a value between 0 and 8192. (optional, default `0`)
- `tile.angle` **[Number][37]** tile angle of rotation, must be a multiple of 90. (optional, default `0`)
- `tile.container` **[String][30]** tile container, with value `fs` (filesystem) or `zip` (compressed file). (optional, default `'fs'`)
- `tile.layout` **[String][30]** filesystem layout, possible values are `dz`, `zoomify` or `google`. (optional, default `'dz'`)
### Examples
```javascript
sharp('input.tiff')
.png()
.tile({
size: 512
})
.toFile('output.dz', function(err, info) {
// output.dzi is the Deep Zoom XML definition
// output_files contains 512x512 tiles grouped by zoom level
});
```
- Throws **[Error][32]** Invalid parameters
Returns **Sharp**
[1]: #tofile
[2]: #parameters
[3]: #examples
[4]: #tobuffer
[5]: #parameters-1
[6]: #examples-1
[7]: #withmetadata
[8]: #parameters-2
[9]: #examples-2
[10]: #jpeg
[11]: #parameters-3
[12]: #examples-3
[13]: #png
[14]: #parameters-4
[15]: #examples-4
[16]: #webp
[17]: #parameters-5
[18]: #examples-5
[19]: #tiff
[20]: #parameters-6
[21]: #examples-6
[22]: #raw
[23]: #examples-7
[24]: #toformat
[25]: #parameters-7
[26]: #examples-8
[27]: #tile
[28]: #parameters-8
[29]: #examples-9
[30]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
[31]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
[32]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error
[33]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
[34]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
[35]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
[36]: https://nodejs.org/api/buffer.html
[37]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
Reference in New Issue View Git Blame Copy Permalink