sharp/docs/api-output.md

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 Promises/A+ promise is returned when callback is not provided.

Parameters

• fileOut String the path to write the image data to.

• callback [Function] called on completion with two arguments (err, info). info contains the output image format, size (bytes), width, height and channels.

• Throws Error Invalid parameters

Returns Promise when no callback is provided

toBuffer

Write output to a Buffer. By default, the format will match the input image. JPEG, PNG, WebP, and RAW are supported. callback, if present, gets three arguments (err, buffer, info) where:

• err is an error message, if any.
• buffer is the output image data.
• info contains the output image format, size (bytes), width, height and channels. A Promises/A+ promise is returned when callback is not provided.

Parameters

• callback [Function]

Returns Promise 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]

  • withMetadata.orientation [Number] value between 1 and 8, used to update the EXIF Orientation tag.

• Throws Error Invalid parameters

Returns Sharp

jpeg

Use these JPEG options for output image.

Parameters

• options [Object] output options

  • options.quality [Number] quality, integer 1-100 (optional, default 80)
  • options.progressive [Boolean] use progressive (interlace) scan (optional, default false)
  • options.chromaSubsampling [String] set to '4:4:4' to prevent chroma subsampling when quality <= 90 (optional, default '4:2:0')
  • options.force [Boolean] force JPEG output, otherwise attempt to use input format (optional, default true)

• trellisQuantisation [Boolean] apply trellis quantisation, requires mozjpeg (optional, default false)

• overshootDeringing [Boolean] apply overshoot deringing, requires mozjpeg (optional, default false)

• optimiseScans [Boolean] optimise progressive scans, forces progressive, requires mozjpeg (optional, default false)

• Throws Error Invalid options

Returns Sharp

png

Use these PNG options for output image.

Parameters

• options [Object]

  • options.progressive [Boolean] use progressive (interlace) scan (optional, default false)
  • options.compressionLevel [Number] zlib compression level (optional, default 6)
  • options.adaptiveFiltering [Boolean] use adaptive row filtering (optional, default true)
  • options.force [Boolean] force PNG output, otherwise attempt to use input format (optional, default true)

• Throws Error Invalid options

Returns Sharp

webp

Use these WebP options for output image.

Parameters

• options [Object] output options

  • options.quality [Number] quality, integer 1-100 (optional, default 80)
  • options.force [Boolean] force WebP output, otherwise attempt to use input format (optional, default true)

• Throws Error Invalid options

Returns Sharp

tiff

Use these TIFF options for output image.

Parameters

• options [Object] output options

  • options.quality [Number] quality, integer 1-100 (optional, default 80)
  • options.force [Boolean] force TIFF output, otherwise attempt to use input format (optional, default true)

• Throws Error Invalid options

Returns Sharp

raw

Force output to be raw, uncompressed uint8 pixel data.

Returns Sharp

toFormat

Force output to a given format.

Parameters

• format (String | Object) as a String or an Object with an 'id' attribute

• options Object output options

• Throws Error unsupported format or options

Returns Sharp

tile

Use tile-based deep zoom (image pyramid) output. You can also use a .zip or .szi file extension with toFile to write to a compressed archive file format.

Parameters

• tile [Object]
  • tile.size [Number] tile size in pixels, a value between 1 and 8192. (optional, default 256)
  • tile.overlap [Number] tile overlap in pixels, a value between 0 and 8192. (optional, default 0)
  • tile.container [String] tile container, with value fs (filesystem) or zip (compressed file). (optional, default 'fs')
  • tile.layout [String] filesystem layout, possible values are dz, zoomify or google. (optional, default 'dz')

Examples

sharp('input.tiff')
  .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 Invalid parameters

Returns Sharp