sharp

sharp

Version 0.33.5
Published 4 months ago
503 kB
3 dependencies
Apache-2.0 license

Install

npm i sharp

yarn add sharp

pnpm add sharp

Overview

High performance Node.js image processing, the fastest module to resize JPEG, PNG, WebP, GIF, AVIF and TIFF images

Index

Variables

variable bool

const bool: BoolEnum;

variable fit

const fit: FitEnum;

variable format

const format: FormatEnum;

Object containing nested boolean values representing the available input and output formats/methods.

variable gravity

const gravity: GravityEnum;

variable interpolators

const interpolators: Interpolators;

An Object containing the available interpolators and their proper values

variable kernel

const kernel: KernelEnum;

variable queue

const queue: NodeJS.EventEmitter;

An EventEmitter that emits a change event when a task is either queued, waiting for libuv to provide a worker thread, complete

variable strategy

const strategy: StrategyEnum;

variable versions

const versions: {
    vips: string;
    cairo?: string | undefined;
    croco?: string | undefined;
    exif?: string | undefined;
    expat?: string | undefined;
    ffi?: string | undefined;
    fontconfig?: string | undefined;
    freetype?: string | undefined;
    gdkpixbuf?: string | undefined;
    gif?: string | undefined;
    glib?: string | undefined;
    gsf?: string | undefined;
    harfbuzz?: string | undefined;
    jpeg?: string | undefined;
    lcms?: string | undefined;
    orc?: string | undefined;
    pango?: string | undefined;
    pixman?: string | undefined;
    png?: string | undefined;
    sharp?: string | undefined;
    svg?: string | undefined;
    tiff?: string | undefined;
    webp?: string | undefined;
    avif?: string | undefined;
    heif?: string | undefined;
    xml?: string | undefined;
    zlib?: string | undefined;
};

An Object containing the version numbers of sharp, libvips and its dependencies.

Functions

function block

block: (options: { operation: string[] }) => void;

Block libvips operations at runtime.
This is in addition to the VIPS_BLOCK_UNTRUSTED environment variable, which when set will block all "untrusted" operations.
0.32.4
Parameter options
Parameter
{Array} options.operation - List of libvips low-level operation names to block.
Example 1
Block all TIFF input. sharp.block({ operation: ['VipsForeignLoadTiff'] });

function cache

cache: (options?: boolean | CacheOptions) => CacheResult;

Gets or, when options are provided, sets the limits of libvips' operation cache. Existing entries in the cache will be trimmed after any change in limits. This method always returns cache statistics, useful for determining how much working memory is required for a particular task.
Parameter options
Object with the following attributes, or Boolean where true uses default cache settings and false removes all caching (optional, default true)
Returns
The cache results.

function concurrency

concurrency: (concurrency?: number) => number;

Gets or sets the number of threads libvips' should create to process each image. The default value is the number of CPU cores. A value of 0 will reset to this default. The maximum number of images that can be processed in parallel is limited by libuv's UV_THREADPOOL_SIZE environment variable.
Parameter concurrency
The new concurrency value.
Returns
The current concurrency value.

function counters

counters: () => SharpCounters;

Provides access to internal task counters.
Returns
Object containing task counters

function sharp

sharp: typeof sharp;

Creates a sharp instance from an image
Parameter input
Buffer containing JPEG, PNG, WebP, AVIF, GIF, SVG, TIFF or raw pixel image data, or String containing the path to an JPEG, PNG, WebP, AVIF, GIF, SVG or TIFF image file.
Parameter options
Object with optional attributes.
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters

function simd

simd: (enable?: boolean) => boolean;

Get and set use of SIMD vector unit instructions. Requires libvips to have been compiled with highway 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.
Parameter enable
enable or disable use of SIMD vector unit instructions
Returns
true if usage of SIMD vector unit instructions is enabled

function unblock

unblock: (options: { operation: string[] }) => void;

Unblock libvips operations at runtime.
This is useful for defining a list of allowed operations.
0.32.4
Parameter options
Parameter
{Array} options.operation - List of libvips low-level operation names to unblock.
Example 1
Block all input except WebP from the filesystem. sharp.block({ operation: ['VipsForeignLoad'] }); sharp.unblock({ operation: ['VipsForeignLoadWebpFile'] });
Example 2
Block all input except JPEG and PNG from a Buffer or Stream. sharp.block({ operation: ['VipsForeignLoad'] }); sharp.unblock({ operation: ['VipsForeignLoadJpegBuffer', 'VipsForeignLoadPngBuffer'] });

Interfaces

interface AffineOptions

interface AffineOptions {}

property background

background?: string | object | undefined;

Parsed by the color module to extract values for red, green, blue and alpha. (optional, default "#000000")

property idx

idx?: number | undefined;

Input horizontal offset (optional, default 0)

property idy

idy?: number | undefined;

Input vertical offset (optional, default 0)

property interpolator

interpolator?: Interpolators[keyof Interpolators] | undefined;

Interpolator (optional, default sharp.interpolators.bicubic)

property odx

odx?: number | undefined;

Output horizontal offset (optional, default 0)

property ody

ody?: number | undefined;

Output horizontal offset (optional, default 0)

interface AnimationOptions

interface AnimationOptions {}

property delay

delay?: number | number[] | undefined;

delay(s) between animation frames (in milliseconds), each value between 0 and 65535. (optional)

property loop

loop?: number | undefined;

Number of animation iterations, a value between 0 and 65535. Use 0 for infinite animation. (optional, default 0)

interface AvailableFormatInfo

interface AvailableFormatInfo {}

property id

id: string;

property input

input: {
    file: boolean;
    buffer: boolean;
    stream: boolean;
    fileSuffix?: string[];
};

property output

output: { file: boolean; buffer: boolean; stream: boolean; alias?: string[] };

interface AvifOptions

interface AvifOptions extends OutputOptions {}

property bitdepth

bitdepth?: 8 | 10 | 12 | undefined;

Set bitdepth to 8, 10 or 12 bit (optional, default 8)

property chromaSubsampling

chromaSubsampling?: string | undefined;

set to '4:2:0' to use chroma subsampling, requires libvips v8.11.0 (optional, default '4:4:4')

property effort

effort?: number | undefined;

Level of CPU effort to reduce file size, between 0 (fastest) and 9 (slowest) (optional, default 4)

property lossless

lossless?: boolean | undefined;

use lossless compression (optional, default false)

property quality

quality?: number | undefined;

quality, integer 1-100 (optional, default 50)

interface BlurOptions

interface BlurOptions {}

property minAmplitude

minAmplitude?: number;

A value between 0.001 and 1. A smaller value will generate a larger, more accurate mask.

property precision

precision?: Precision | undefined;

How accurate the operation should be, one of: integer, float, approximate. (optional, default "integer")

property sigma

sigma: number;

A value between 0.3 and 1000 representing the sigma of the Gaussian mask, where sigma = 1 + radius / 2

interface BoolEnum

interface BoolEnum {}

property and

and: 'and';

property eor

eor: 'eor';

property or

or: 'or';

interface CacheOptions

interface CacheOptions {}

property files

files?: number | undefined;

Is the maximum number of files to hold open (optional, default 20)

property items

items?: number | undefined;

Is the maximum number of operations to cache (optional, default 100)

property memory

memory?: number | undefined;

Is the maximum memory in MB to use for this cache (optional, default 50)

interface CacheResult

interface CacheResult {}

property files

files: { current: number; max: number };

property items

items: { current: number; max: number };

property memory

memory: { current: number; high: number; max: number };

interface ChannelStats

interface ChannelStats {}

property max

max: number;

maximum value in the channel

property maxX

maxX: number;

x-coordinate of one of the pixel where the maximum lies

property maxY

maxY: number;

y-coordinate of one of the pixel where the maximum lies

property mean

mean: number;

mean of the values in a channel

property min

min: number;

minimum value in the channel

property minX

minX: number;

x-coordinate of one of the pixel where the minimum lies

property minY

minY: number;

y-coordinate of one of the pixel where the minimum lies

property squaresSum

squaresSum: number;

sum of squared values in a channel

property stdev

stdev: number;

standard deviation for the values in a channel

property sum

sum: number;

sum of all values in a channel

interface ClaheOptions

interface ClaheOptions {}

property height

height: number;

height of the region

property maxSlope

maxSlope?: number | undefined;

max slope of the cumulative contrast. A value of 0 disables contrast limiting. Valid values are integers in the range 0-100 (inclusive) (optional, default 3)

property width

width: number;

width of the region

interface ColourspaceEnum

interface ColourspaceEnum {}

property 'b-w'

'b-w': string;

property bw

bw: string;

property cmyk

cmyk: string;

property multiband

multiband: string;

property srgb

srgb: string;

interface CommentsMetadata

interface CommentsMetadata {}

property keyword

keyword: string;

property text

text: string;

interface Create

interface Create {}

property background

background: Color;

Parsed by the [color](https://www.npmjs.org/package/color) module to extract values for red, green, blue and alpha.

property channels

channels: Channels;

Number of bands e.g. 3 for RGB, 4 for RGBA

property height

height: number;

Number of pixels high.

property noise

noise?: Noise | undefined;

Describes a noise to be created.

property width

width: number;

Number of pixels wide.

interface CreateRaw

interface CreateRaw extends Raw {}

property premultiplied

premultiplied?: boolean | undefined;

Specifies that the raw input has already been premultiplied, set to true to avoid sharp premultiplying the image. (optional, default false)

interface CreateText

interface CreateText {}

property align

align?: TextAlign;

Text alignment ('left', 'centre', 'center', 'right'). (optional, default 'left')

property dpi

dpi?: number;

The resolution (size) at which to render the text. Does not take effect if height is specified. (optional, default 72)

property font

font?: string;

Font name to render with.

property fontfile

fontfile?: string;

Absolute filesystem path to a font file that can be used by font.

property height

height?: number;

Integral number of pixels high. When defined, dpi will be ignored and the text will automatically fit the pixel resolution defined by width and height. Will be ignored if width is not specified or set to 0. (optional, default 0)

property justify

justify?: boolean;

Set this to true to apply justification to the text. (optional, default false)

property rgba

rgba?: boolean;

Set this to true to enable RGBA output. This is useful for colour emoji rendering, or support for pango markup features like <span foreground="red">Red!</span>. (optional, default false)

property spacing

spacing?: number;

Text line height in points. Will use the font line height if none is specified. (optional, default 0)

property text

text: string;

Text to render as a UTF-8 string. It can contain Pango markup, for example <i>Le</i>Monde.

property width

width?: number;

Integral number of pixels to word-wrap at. Lines of text wider than this will be broken at word boundaries. (optional, default 0)

property wrap

wrap?: TextWrap;

Word wrapping style when width is provided, one of: 'word', 'char', 'word-char' (prefer word, fallback to char) or 'none'

interface Exif

interface Exif {}

property 'IFD0'

IFD0?: ExifDir;

property 'IFD1'

IFD1?: ExifDir;

property 'IFD2'

IFD2?: ExifDir;

property 'IFD3'

IFD3?: ExifDir;

interface ExifDir

interface ExifDir {}

index signature

[k: string]: string;

interface ExtendOptions

interface ExtendOptions {}

property background

background?: Color | undefined;

background colour, parsed by the color module, defaults to black without transparency. (optional, default {r:0,g:0,b:0,alpha:1})

property bottom

bottom?: number | undefined;

single pixel count to bottom edge (optional, default 0)

property extendWith

extendWith?: ExtendWith | undefined;

how the extension is done, one of: "background", "copy", "repeat", "mirror" (optional, default 'background')

property left

left?: number | undefined;

single pixel count to left edge (optional, default 0)

property right

right?: number | undefined;

single pixel count to right edge (optional, default 0)

property top

top?: number | undefined;

single pixel count to top edge (optional, default 0)

interface FitEnum

interface FitEnum {}

property contain

contain: 'contain';

property cover

cover: 'cover';

property fill

fill: 'fill';

property inside

inside: 'inside';

property outside

outside: 'outside';

interface FlattenOptions

interface FlattenOptions {}

property background

background?: Color | undefined;

background colour, parsed by the color module, defaults to black. (optional, default {r:0,g:0,b:0})

interface FormatEnum

interface FormatEnum {}

property avif

avif: AvailableFormatInfo;

property dz

dz: AvailableFormatInfo;

property fits

fits: AvailableFormatInfo;

property gif

gif: AvailableFormatInfo;

property heif

heif: AvailableFormatInfo;

property input

input: AvailableFormatInfo;

property jp2

jp2: AvailableFormatInfo;

property jpeg

jpeg: AvailableFormatInfo;

property jpg

jpg: AvailableFormatInfo;

property jxl

jxl: AvailableFormatInfo;

property magick

magick: AvailableFormatInfo;

property openslide

openslide: AvailableFormatInfo;

property pdf

pdf: AvailableFormatInfo;

property png

png: AvailableFormatInfo;

property ppm

ppm: AvailableFormatInfo;

property raw

raw: AvailableFormatInfo;

property svg

svg: AvailableFormatInfo;

property tif

tif: AvailableFormatInfo;

property tiff

tiff: AvailableFormatInfo;

property v

v: AvailableFormatInfo;

property webp

webp: AvailableFormatInfo;

interface GifOptions

interface GifOptions extends OutputOptions, AnimationOptions {}

property colors

colors?: number | undefined;

Alternative spelling of "colours". Maximum number of palette entries, including transparency, between 2 and 256 (optional, default 256)

property colours

colours?: number | undefined;

Maximum number of palette entries, including transparency, between 2 and 256 (optional, default 256)

property dither

dither?: number | undefined;

Level of Floyd-Steinberg error diffusion, between 0 (least) and 1 (most) (optional, default 1.0)

property effort

effort?: number | undefined;

Level of CPU effort to reduce file size, between 1 (fastest) and 10 (slowest) (optional, default 7)

property interFrameMaxError

interFrameMaxError?: number;

Maximum inter-frame error for transparency, between 0 (lossless) and 32 (optional, default 0)

property interPaletteMaxError

interPaletteMaxError?: number;

Maximum inter-palette error for palette reuse, between 0 and 256 (optional, default 3)

property progressive

progressive?: boolean | undefined;

Use progressive (interlace) scan

property reuse

reuse?: boolean | undefined;

Re-use existing palette, otherwise generate new (slow)

interface GravityEnum

interface GravityEnum {}

property center

center: number;

property centre

centre: number;

property east

east: number;

property north

north: number;

property northeast

northeast: number;

property northwest

northwest: number;

property south

south: number;

property southeast

southeast: number;

property southwest

southwest: number;

property west

west: number;

interface HeifOptions

interface HeifOptions extends OutputOptions {}

property bitdepth

bitdepth?: 8 | 10 | 12 | undefined;

Set bitdepth to 8, 10 or 12 bit (optional, default 8)

property chromaSubsampling

chromaSubsampling?: string | undefined;

set to '4:2:0' to use chroma subsampling (optional, default '4:4:4')

property compression

compression?: 'av1' | 'hevc' | undefined;

compression format: av1, hevc (optional, default 'av1')

property effort

effort?: number | undefined;

Level of CPU effort to reduce file size, between 0 (fastest) and 9 (slowest) (optional, default 4)

property lossless

lossless?: boolean | undefined;

use lossless compression (optional, default false)

property quality

quality?: number | undefined;

quality, integer 1-100 (optional, default 50)

interface Interpolators

interface Interpolators {}

property bicubic

bicubic: 'bicubic';

[Bicubic interpolation](http://en.wikipedia.org/wiki/Bicubic_interpolation) (the default).

property bilinear

bilinear: 'bilinear';

[Bilinear interpolation](http://en.wikipedia.org/wiki/Bilinear_interpolation). Faster than bicubic but with less smooth results.

property locallyBoundedBicubic

locallyBoundedBicubic: 'lbb';

[LBB interpolation](https://github.com/libvips/libvips/blob/master/libvips/resample/lbb.cpp#L100). Prevents some "[acutance](http://en.wikipedia.org/wiki/Acutance)" but typically reduces performance by a factor of 2.

property nearest

nearest: 'nearest';

[Nearest neighbour interpolation](http://en.wikipedia.org/wiki/Nearest-neighbor_interpolation). Suitable for image enlargement only.

property nohalo

nohalo: 'nohalo';

[Nohalo interpolation](http://eprints.soton.ac.uk/268086/). Prevents acutance but typically reduces performance by a factor of 3.

property vertexSplitQuadraticBasisSpline

vertexSplitQuadraticBasisSpline: 'vsqbs';

[VSQBS interpolation](https://github.com/libvips/libvips/blob/master/libvips/resample/vsqbs.cpp#L48). Prevents "staircasing" when enlarging.

interface Jp2Options

interface Jp2Options extends OutputOptions {}

property chromaSubsampling

chromaSubsampling?: '4:4:4' | '4:2:0';

Set to '4:2:0' to enable chroma subsampling (optional, default '4:4:4')

property lossless

lossless?: boolean;

Use lossless compression mode (optional, default false)

property quality

quality?: number;

Quality, integer 1-100 (optional, default 80)

property tileHeight

tileHeight?: number;

Vertical tile size (optional, default 512)

property tileWidth

tileWidth?: number;

Horizontal tile size (optional, default 512)

interface JpegOptions

interface JpegOptions extends OutputOptions {}

property chromaSubsampling

chromaSubsampling?: string | undefined;

Set to '4:4:4' to prevent chroma subsampling when quality <= 90 (optional, default '4:2:0')

property mozjpeg

mozjpeg?: boolean | undefined;

Use mozjpeg defaults (optional, default false)

property optimiseCoding

optimiseCoding?: boolean | undefined;

Optimise Huffman coding tables (optional, default true)

property optimiseScans

optimiseScans?: boolean | undefined;

Optimise progressive scans, forces progressive (optional, default false)

property optimizeCoding

optimizeCoding?: boolean | undefined;

Alternative spelling of optimiseCoding (optional, default true)

property optimizeScans

optimizeScans?: boolean | undefined;

Alternative spelling of optimiseScans (optional, default false)

property overshootDeringing

overshootDeringing?: boolean | undefined;

Apply overshoot deringing (optional, default false)

property progressive

progressive?: boolean | undefined;

Use progressive (interlace) scan (optional, default false)

property quality

quality?: number | undefined;

Quality, integer 1-100 (optional, default 80)

property quantisationTable

quantisationTable?: number | undefined;

Quantization table to use, integer 0-8 (optional, default 0)

property quantizationTable

quantizationTable?: number | undefined;

Alternative spelling of quantisationTable (optional, default 0)

property trellisQuantisation

trellisQuantisation?: boolean | undefined;

Apply trellis quantisation (optional, default false)

interface JxlOptions

interface JxlOptions extends OutputOptions {}

property decodingTier

decodingTier?: number;

Target decode speed tier, between 0 (highest quality) and 4 (lowest quality) (optional, default 0)

property distance

distance?: number;

Maximum encoding error, between 0 (highest quality) and 15 (lowest quality) (optional, default 1.0)

property effort

effort?: number | undefined;

CPU effort, between 3 (fastest) and 9 (slowest) (optional, default 7)

property lossless

lossless?: boolean;

Use lossless compression (optional, default false)

property quality

quality?: number;

Calculate distance based on JPEG-like quality, between 1 and 100, overrides distance if specified

interface Kernel

interface Kernel {}

property height

height: number;

height of the kernel in pixels.

property kernel

kernel: ArrayLike<number>;

Array of length width*height containing the kernel values.

property offset

offset?: number | undefined;

the offset of the kernel in pixels. (optional, default 0)

property scale

scale?: number | undefined;

the scale of the kernel in pixels. (optional, default sum)

property width

width: number;

width of the kernel in pixels.

interface KernelEnum

interface KernelEnum {}

property cubic

cubic: 'cubic';

property lanczos2

lanczos2: 'lanczos2';

property lanczos3

lanczos3: 'lanczos3';

property mitchell

mitchell: 'mitchell';

property nearest

nearest: 'nearest';

interface LevelMetadata

interface LevelMetadata {}

property height

height: number;

property width

width: number;

interface Metadata

interface Metadata {}

property background

background?: { r: number; g: number; b: number } | number;

Default background colour, if present, for PNG (bKGD) and GIF images, either an RGB Object or a single greyscale value

property channels

channels?: Channels | undefined;

Number of bands e.g. 3 for sRGB, 4 for CMYK

property chromaSubsampling

chromaSubsampling?: string | undefined;

String containing JPEG chroma subsampling, 4:2:0 or 4:4:4 for RGB, 4:2:0:4 or 4:4:4:4 for CMYK

property comments

comments?: CommentsMetadata[] | undefined;

Array of keyword/text pairs representing PNG text blocks, if present.

property compression

compression?: 'av1' | 'hevc';

The encoder used to compress an HEIF file, av1 (AVIF) or hevc (HEIC)

property delay

delay?: number[] | undefined;

Delay in ms between each page in an animated image, provided as an array of integers.

property density

density?: number | undefined;

Number of pixels per inch (DPI), if present

property depth

depth?: string | undefined;

Name of pixel depth format e.g. uchar, char, ushort, float ...

property exif

exif?: Buffer | undefined;

Buffer containing raw EXIF data, if present

property format

format?: keyof FormatEnum | undefined;

Name of decoder used to decompress image data e.g. jpeg, png, webp, gif, svg

property formatMagick

formatMagick?: string | undefined;

String containing format for images loaded via *magick

property hasAlpha

hasAlpha?: boolean | undefined;

Boolean indicating the presence of an alpha transparency channel

property hasProfile

hasProfile?: boolean | undefined;

Boolean indicating the presence of an embedded ICC profile

property height

height?: number | undefined;

Number of pixels high (EXIF orientation is not taken into consideration)

property icc

icc?: Buffer | undefined;

Buffer containing raw ICC profile data, if present

property iptc

iptc?: Buffer | undefined;

Buffer containing raw IPTC data, if present

property isProgressive

isProgressive?: boolean | undefined;

Boolean indicating whether the image is interlaced using a progressive scan

property levels

levels?: LevelMetadata[] | undefined;

Details of each level in a multi-level image provided as an array of objects, requires libvips compiled with support for OpenSlide

property loop

loop?: number | undefined;

Number of times to loop an animated image, zero refers to a continuous loop.

property orientation

orientation?: number | undefined;

Number value of the EXIF Orientation header, if present

property pageHeight

pageHeight?: number | undefined;

Number of pixels high each page in a multi-page image will be.

property pagePrimary

pagePrimary?: number | undefined;

Number of the primary page in a HEIF image

property pages

pages?: number | undefined;

Number of pages/frames contained within the image, with support for TIFF, HEIF, PDF, animated GIF and animated WebP

property resolutionUnit

resolutionUnit?: 'inch' | 'cm' | undefined;

The unit of resolution (density)

property size

size?: number | undefined;

Total size of image in bytes, for Stream and Buffer input only

property space

space?: keyof ColourspaceEnum | undefined;

Name of colour space interpretation

property subifds

subifds?: number | undefined;

Number of Sub Image File Directories in an OME-TIFF image

property tifftagPhotoshop

tifftagPhotoshop?: Buffer | undefined;

Buffer containing raw TIFFTAG_PHOTOSHOP data, if present

property width

width?: number | undefined;

Number of pixels wide (EXIF orientation is not taken into consideration)

property xmp

xmp?: Buffer | undefined;

Buffer containing raw XMP data, if present

interface NegateOptions

interface NegateOptions {}

property alpha

alpha?: boolean | undefined;

whether or not to negate any alpha channel. (optional, default true)

interface Noise

interface Noise {}

property mean

mean?: number | undefined;

mean of pixels in generated noise.

property sigma

sigma?: number | undefined;

standard deviation of pixels in generated noise.

property type

type?: 'gaussian' | undefined;

type of generated noise, currently only gaussian is supported.

interface NormaliseOptions

interface NormaliseOptions {}

property lower

lower?: number | undefined;

Percentile below which luminance values will be underexposed.

property upper

upper?: number | undefined;

Percentile above which luminance values will be overexposed.

interface OutputInfo

interface OutputInfo {}

property attentionX

attentionX?: number | undefined;

When using the attention crop strategy, the focal point of the cropped region

property attentionY

attentionY?: number | undefined;

property channels

channels: 1 | 2 | 3 | 4;

property cropOffsetLeft

cropOffsetLeft?: number | undefined;

Only defined when using a crop strategy

property cropOffsetTop

cropOffsetTop?: number | undefined;

Only defined when using a crop strategy

property format

format: string;

property height

height: number;

property premultiplied

premultiplied: boolean;

indicating if premultiplication was used

property size

size: number;

property textAutofitDpi

textAutofitDpi?: number | undefined;

DPI the font was rendered at, only defined when using text input

property trimOffsetLeft

trimOffsetLeft?: number | undefined;

Only defined when using a trim method

property trimOffsetTop

trimOffsetTop?: number | undefined;

Only defined when using a trim method

property width

width: number;

interface OutputOptions

interface OutputOptions {}

property force

force?: boolean | undefined;

Force format output, otherwise attempt to use input format (optional, default true)

interface OverlayOptions

interface OverlayOptions extends SharpOptions {}

property animated

animated?: boolean | undefined;

Set to true to read all frames/pages of an animated image. (optional, default false)

property blend

blend?: Blend | undefined;

how to blend this image with the image below. (optional, default 'over')

property density

density?: number | undefined;

number representing the DPI for vector overlay image. (optional, default 72)

property failOn

failOn?: FailOnOptions | undefined;

see sharp() constructor, (optional, default 'warning')

property gravity

gravity?: Gravity | undefined;

gravity at which to place the overlay. (optional, default 'centre')

property input

input?:
    | string
    | Buffer
    | { create: Create }
    | { text: CreateText }
    | { raw: CreateRaw }
    | undefined;

Buffer containing image data, String containing the path to an image file, or Create object

property left

left?: number | undefined;

the pixel offset from the left edge.

property limitInputPixels

limitInputPixels?: number | boolean | undefined;

see sharp() constructor, (optional, default 268402689)

property premultiplied

premultiplied?: boolean | undefined;

Set to true to avoid premultipling the image below. Equivalent to the --premultiplied vips option.

property tile

tile?: boolean | undefined;

set to true to repeat the overlay image across the entire image with the given gravity. (optional, default false)

property top

top?: number | undefined;

the pixel offset from the top edge.

interface PngOptions

interface PngOptions extends OutputOptions {}

property adaptiveFiltering

adaptiveFiltering?: boolean | undefined;

Use adaptive row filtering (optional, default false)

property colors

colors?: number | undefined;

Alternative Spelling of "colours". Maximum number of palette entries (optional, default 256)

property colours

colours?: number | undefined;

Maximum number of palette entries (optional, default 256)

property compressionLevel

compressionLevel?: number | undefined;

zlib compression level, 0-9 (optional, default 6)

property dither

dither?: number | undefined;

Level of Floyd-Steinberg error diffusion (optional, default 1.0)

property effort

effort?: number | undefined;

Level of CPU effort to reduce file size, between 1 (fastest) and 10 (slowest), sets palette to true (optional, default 7)

property palette

palette?: boolean | undefined;

Quantise to a palette-based image with alpha transparency support (optional, default false)

property progressive

progressive?: boolean | undefined;

Use progressive (interlace) scan (optional, default false)

property quality

quality?: number | undefined;

Use the lowest number of colours needed to achieve given quality (optional, default 100)

interface PresetEnum

interface PresetEnum {}

property default

default: 'default';

property drawing

drawing: 'drawing';

property icon

icon: 'icon';

property photo

photo: 'photo';

property picture

picture: 'picture';

property text

text: 'text';

interface Raw

interface Raw {}

property channels

channels: 1 | 2 | 3 | 4;

property height

height: number;

property width

width: number;

interface RawOptions

interface RawOptions {}

property depth

depth?:
    | 'char'
    | 'uchar'
    | 'short'
    | 'ushort'
    | 'int'
    | 'uint'
    | 'float'
    | 'complex'
    | 'double'
    | 'dpcomplex';

interface Region

interface Region {}

property height

height: number;

dimension of extracted image

property left

left: number;

zero-indexed offset from left edge

property top

top: number;

zero-indexed offset from top edge

property width

width: number;

dimension of extracted image

interface ResizeOptions

interface ResizeOptions {}

property background

background?: Color | undefined;

Background colour when using a fit of contain, parsed by the color module, defaults to black without transparency. (optional, default {r:0,g:0,b:0,alpha:1})

property fastShrinkOnLoad

fastShrinkOnLoad?: boolean | undefined;

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)

property fit

fit?: keyof FitEnum | undefined;

How the image should be resized to fit both provided dimensions, one of cover, contain, fill, inside or outside. (optional, default 'cover')

property height

height?: number | undefined;

Alternative means of specifying height. If both are present this takes priority.

property kernel

kernel?: keyof KernelEnum | undefined;

The kernel to use for image reduction. (optional, default 'lanczos3')

property position

position?: number | string | undefined;

Position, gravity or strategy to use when fit is cover or contain. (optional, default 'centre')

property width

width?: number | undefined;

Alternative means of specifying width. If both are present this takes priority.

property withoutEnlargement

withoutEnlargement?: boolean | undefined;

Do not enlarge if the width or height are already less than the specified dimensions, equivalent to GraphicsMagick's > geometry option. (optional, default false)

property withoutReduction

withoutReduction?: boolean | undefined;

Do not reduce if the width or height are already greater than the specified dimensions, equivalent to GraphicsMagick's < geometry option. (optional, default false)

interface RGBA

interface RGBA {}

property alpha

alpha?: number | undefined;

property b

b?: number | undefined;

property g

g?: number | undefined;

property r

r?: number | undefined;

interface RotateOptions

interface RotateOptions {}

property background

background?: Color | undefined;

parsed by the color module to extract values for red, green, blue and alpha. (optional, default "#000000")

interface Sharp

interface Sharp extends Duplex {}

method affine

affine: (
    matrix: [number, number, number, number] | Matrix2x2,
    options?: AffineOptions
) => Sharp;

Perform an affine transform on an image. This operation will always occur after resizing, extraction and rotation, if any. You must provide an array of length 4 or a 2x2 affine transformation matrix. By default, new pixels are filled with a black background. You can provide a background color with the background option. A particular interpolator may also be specified. Set the interpolator option to an attribute of the sharp.interpolators Object e.g. sharp.interpolators.nohalo.
In the case of a 2x2 matrix, the transform is: X = matrix[0, 0] * (x + idx) + matrix[0, 1] * (y + idy) + odx Y = matrix[1, 0] * (x + idx) + matrix[1, 1] * (y + idy) + ody
where:
x and y are the coordinates in input image. X and Y are the coordinates in output image. (0,0) is the upper left corner.
Parameter matrix
Affine transformation matrix, may either by a array of length four or a 2x2 matrix array
Parameter options
if present, is an Object with optional attributes.
Returns
A sharp instance that can be used to chain operations

method avif

avif: (options?: AvifOptions) => Sharp;

Use these AVIF options for output image.
Parameter options
Output options.
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid options

method bandbool

bandbool: (boolOp: keyof BoolEnum) => Sharp;

Perform a bitwise boolean operation on all input image channels (bands) to produce a single channel output image.
Parameter boolOp
one of "and", "or" or "eor" to perform that bitwise operation, like the C logic operators &, | and ^ respectively.
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters

method blur

blur: (sigma?: number | boolean | BlurOptions) => Sharp;

Blur the image. When used without parameters, performs a fast, mild blur of the output image. When a sigma is provided, performs a slower, more accurate Gaussian blur. When a boolean sigma is provided, ether blur mild or disable blur
Parameter sigma
a value between 0.3 and 1000 representing the sigma of the Gaussian mask, where sigma = 1 + radius / 2.
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters

method boolean

boolean: (
    operand: string | Buffer,
    operator: keyof BoolEnum,
    options?: { raw: Raw }
) => Sharp;

Perform a bitwise boolean operation with operand image. This operation creates an output image where each pixel is the result of the selected bitwise boolean operation between the corresponding pixels of the input images.
Parameter operand
Buffer containing image data or String containing the path to an image file.
Parameter operator
one of "and", "or" or "eor" to perform that bitwise operation, like the C logic operators &, | and ^ respectively.
Parameter options
describes operand when using raw pixel data.
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters

method clahe

clahe: (options: ClaheOptions) => Sharp;

Perform contrast limiting adaptive histogram equalization (CLAHE)
This will, in general, enhance the clarity of the image by bringing out darker details. Please read more about CLAHE here: https://en.wikipedia.org/wiki/Adaptive_histogram_equalization#Contrast_Limited_AHE
Parameter options
clahe options

method clone

clone: () => Sharp;

Take a "snapshot" of the Sharp instance, returning a new instance. Cloned instances inherit the input of their parent instance. This allows multiple output Streams and therefore multiple processing pipelines to share a single input Stream.
Returns
A sharp instance that can be used to chain operations

method composite

composite: (images: OverlayOptions[]) => Sharp;

Composite image(s) over the processed (resized, extracted etc.) image.
The images to composite must be the same size or smaller than the processed image. If both top and left options are provided, they take precedence over gravity.
Parameter images
Ordered list of images to composite
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters

method convolve

convolve: (kernel: Kernel) => Sharp;

Convolve the image with the specified kernel.
Parameter kernel
the specified kernel
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters

method ensureAlpha

ensureAlpha: (alpha?: number) => Sharp;

Ensure alpha channel, if missing. The added alpha channel will be fully opaque. This is a no-op if the image already has an alpha channel.
Parameter alpha
transparency level (0=fully-transparent, 1=fully-opaque) (optional, default 1).
Returns
A sharp instance that can be used to chain operations

method extend

extend: (extend: number | ExtendOptions) => Sharp;

Extend / pad / extrude one or more edges of the image with either the provided background colour or pixels derived from the image. This operation will always occur after resizing and extraction, if any.
Parameter extend
single pixel count to add to all edges or an Object with per-edge counts
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters

method extract

extract: (region: Region) => Sharp;

Extract a region of the image. - Use extract() before resize() for pre-resize extraction. - Use extract() after resize() for post-resize extraction. - Use extract() before and after for both.
Parameter region
The region to extract
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters

method extractChannel

extractChannel: (
    channel: 0 | 1 | 2 | 3 | 'red' | 'green' | 'blue' | 'alpha'
) => Sharp;

Extract a single channel from a multi-channel image.
Parameter channel
zero-indexed channel/band number to extract, or red, green, blue or alpha.
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid channel

method flatten

flatten: (flatten?: boolean | FlattenOptions) => Sharp;

Merge alpha transparency channel, if any, with background.
Parameter flatten
true to enable and false to disable (defaults to true)
Returns
A sharp instance that can be used to chain operations

method flip

flip: (flip?: boolean) => Sharp;

Flip the image about the vertical Y axis. This always occurs after rotation, if any. The use of flip implies the removal of the EXIF Orientation tag, if any.
Parameter flip
true to enable and false to disable (defaults to true)
Returns
A sharp instance that can be used to chain operations

method flop

flop: (flop?: boolean) => Sharp;

Flop the image about the horizontal X axis. This always occurs after rotation, if any. The use of flop implies the removal of the EXIF Orientation tag, if any.
Parameter flop
true to enable and false to disable (defaults to true)
Returns
A sharp instance that can be used to chain operations

method gamma

gamma: (gamma?: number, gammaOut?: number) => Sharp;

Apply a gamma correction by reducing the encoding (darken) pre-resize at a factor of 1/gamma then increasing the encoding (brighten) post-resize at a factor of gamma. This can improve the perceived brightness of a resized image in non-linear colour spaces. JPEG and WebP input images will not take advantage of the shrink-on-load performance optimisation when applying a gamma correction. Supply a second argument to use a different output gamma value, otherwise the first value is used in both cases.
Parameter gamma
value between 1.0 and 3.0. (optional, default 2.2)
Parameter gammaOut
value between 1.0 and 3.0. (optional, defaults to same as gamma)
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters

method gif

gif: (options?: GifOptions) => Sharp;

Use these GIF options for output image. Requires libvips compiled with support for ImageMagick or GraphicsMagick. The prebuilt binaries do not include this - see installing a custom libvips.
Parameter options
Output options.
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid options

method grayscale

grayscale: (grayscale?: boolean) => Sharp;

Alternative spelling of greyscale().
Parameter grayscale
true to enable and false to disable (defaults to true)
Returns
A sharp instance that can be used to chain operations

method greyscale

greyscale: (greyscale?: boolean) => Sharp;

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. By default the output image will be web-friendly sRGB and contain three (identical) color channels. This may be overridden by other sharp operations such as toColourspace('b-w'), which will produce an output image containing one color channel. An alpha channel may be present, and will be unchanged by the operation.
Parameter greyscale
true to enable and false to disable (defaults to true)
Returns
A sharp instance that can be used to chain operations

method heif

heif: (options?: HeifOptions) => Sharp;

Use these HEIF options for output image. Support for patent-encumbered HEIC images requires the use of a globally-installed libvips compiled with support for libheif, libde265 and x265.
Parameter options
Output options.
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid options

method joinChannel

joinChannel: (
    images: string | Buffer | ArrayLike<string | Buffer>,
    options?: SharpOptions
) => Sharp;

Join one or more channels to the image. The meaning of the added channels depends on the output colourspace, set with toColourspace(). By default the output image will be web-friendly sRGB, with additional channels interpreted as alpha channels. Channel ordering follows vips convention: - sRGB: 0: Red, 1: Green, 2: Blue, 3: Alpha. - CMYK: 0: Magenta, 1: Cyan, 2: Yellow, 3: Black, 4: Alpha.
Buffers may be any of the image formats supported by sharp. For raw pixel input, the options object should contain a raw attribute, which follows the format of the attribute of the same name in the sharp() constructor.
Parameter images
one or more images (file paths, Buffers).
Parameter options
image options, see sharp() constructor.
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters

method jp2

jp2: (options?: Jp2Options) => Sharp;

Use these JP2 (JPEG 2000) options for output image.
Parameter options
Output options.
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid options

method jpeg

jpeg: (options?: JpegOptions) => Sharp;

Use these JPEG options for output image.
Parameter options
Output options.
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid options

method jxl

jxl: (options?: JxlOptions) => Sharp;

Use these JPEG-XL (JXL) options for output image. This feature is experimental, please do not use in production systems. Requires libvips compiled with support for libjxl. The prebuilt binaries do not include this. Image metadata (EXIF, XMP) is unsupported.
Parameter options
Output options.
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid options

method keepExif

keepExif: () => Sharp;

Keep all EXIF metadata from the input image in the output image. EXIF metadata is unsupported for TIFF output.
Returns
A sharp instance that can be used to chain operations

method keepIccProfile

keepIccProfile: () => Sharp;

Keep ICC profile from the input image in the output image where possible.
Returns
A sharp instance that can be used to chain operations

method keepMetadata

keepMetadata: () => Sharp;

Keep all metadata (EXIF, ICC, XMP, IPTC) from the input image in the output image.
Returns
A sharp instance that can be used to chain operations

method linear

linear: (a?: number | number[] | null, b?: number | number[]) => Sharp;

Apply the linear formula a * input + b to the image (levels adjustment)
Parameter a
multiplier (optional, default 1.0)
Parameter b
offset (optional, default 0.0)
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters

method median

median: (size?: number) => Sharp;

Apply median filter. When used without parameters the default window is 3x3.
Parameter size
square mask size: size x size (optional, default 3)
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters

method metadata

metadata: {
    (callback: (err: Error, metadata: Metadata) => void): Sharp;
    (): Promise<Metadata>;
};

Fast access to (uncached) image metadata without decoding any compressed image data.
Returns
A sharp instance that can be used to chain operations
Fast access to (uncached) image metadata without decoding any compressed image data.
Returns
A promise that resolves with a metadata object

method modulate

modulate: (options?: {
    brightness?: number | undefined;
    saturation?: number | undefined;
    hue?: number | undefined;
    lightness?: number | undefined;
}) => Sharp;

Transforms the image using brightness, saturation, hue rotation and lightness. Brightness and lightness both operate on luminance, with the difference being that brightness is multiplicative whereas lightness is additive.
Parameter options
describes the modulation
Returns
A sharp instance that can be used to chain operations

method negate

negate: (negate?: boolean | NegateOptions) => Sharp;

Produce the "negative" of the image.
Parameter negate
true to enable and false to disable, or an object of options (defaults to true)
Returns
A sharp instance that can be used to chain operations

method normalise

normalise: (normalise?: NormaliseOptions) => Sharp;

Enhance output image contrast by stretching its luminance to cover a full dynamic range.
Uses a histogram-based approach, taking a default range of 1% to 99% to reduce sensitivity to noise at the extremes.
Luminance values below the lower percentile will be underexposed by clipping to zero. Luminance values above the upper percentile will be overexposed by clipping to the max pixel value.
Parameter normalise
options
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters

method normalize

normalize: (normalize?: NormaliseOptions) => Sharp;

Alternative spelling of normalise.
Parameter normalize
options
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters

method pipelineColorspace

pipelineColorspace: (colorspace?: string) => Sharp;

Alternative spelling of pipelineColourspace
Parameter colorspace
pipeline colourspace e.g. rgb16, scrgb, lab, grey16 ...
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters

method pipelineColourspace

pipelineColourspace: (colourspace?: string) => Sharp;

Set the pipeline colourspace. The input image will be converted to the provided colourspace at the start of the pipeline. All operations will use this colourspace before converting to the output colourspace, as defined by toColourspace. This feature is experimental and has not yet been fully-tested with all operations.
Parameter colourspace
pipeline colourspace e.g. rgb16, scrgb, lab, grey16 ...
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters

method png

png: (options?: PngOptions) => 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.
Parameter options
Output options.
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid options

method raw

raw: (options?: RawOptions) => Sharp;

Force output to be raw, uncompressed uint8 pixel data.
Parameter options
Raw output options.
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid options

method recomb

recomb: (inputMatrix: Matrix3x3 | Matrix4x4) => Sharp;

Recomb the image with the specified matrix.
Parameter inputMatrix
3x3 Recombination matrix or 4x4 Recombination matrix
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters

method removeAlpha

removeAlpha: () => Sharp;

Remove alpha channel, if any. This is a no-op if the image does not have an alpha channel.
Returns
A sharp instance that can be used to chain operations

method resize

resize: {
    (
        widthOrOptions?: number | ResizeOptions | null,
        height?: number | null,
        options?: ResizeOptions
    ): Sharp;
    (options: ResizeOptions): Sharp;
};

Resize image to width, height or width x height.
When both a width and height are provided, the possible methods by which the image should fit these are: - 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 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 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. - 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. - cubic: Use a Catmull-Rom spline. - lanczos2: Use a Lanczos kernel with a=2. - lanczos3: Use a Lanczos kernel with a=3 (the default).
Parameter width
pixels wide the resultant image should be. Use null or undefined to auto-scale the width to match the height.
Parameter height
pixels high the resultant image should be. Use null or undefined to auto-scale the height to match the width.
Parameter options
resize options
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters
Shorthand for resize(null, null, options);
Parameter options
resize options
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters

method rotate

rotate: (angle?: number, options?: RotateOptions) => Sharp;

Rotate the output image by either an explicit angle or auto-orient based on the EXIF Orientation tag.
If an angle is provided, it is converted to a valid positive degree rotation. For example, -450 will produce a 270deg rotation.
When rotating by an angle other than a multiple of 90, the background colour can be provided with the background option.
If no angle is provided, it is determined from the EXIF data. Mirroring is supported and may infer the use of a flip operation.
The use of rotate implies the removal of the EXIF Orientation tag, if any.
Method order is important when both rotating and extracting regions, for example rotate(x).extract(y) will produce a different result to extract(y).rotate(x).
Parameter angle
angle of rotation. (optional, default auto)
Parameter options
if present, is an Object with optional attributes.
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters

method sharpen

sharpen: {
    (options?: SharpenOptions): Sharp;
    (sigma?: number, flat?: number, jagged?: number): Sharp;
};

Sharpen the image. When used without parameters, performs a fast, mild sharpen of the output image. When a sigma is provided, performs a slower, more accurate sharpen of the L channel in the LAB colour space. Fine-grained control over the level of sharpening in "flat" (m1) and "jagged" (m2) areas is available.
Parameter options
if present, is an Object with optional attributes
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters
Sharpen the image. When used without parameters, performs a fast, mild sharpen of the output image. When a sigma is provided, performs a slower, more accurate sharpen of the L channel in the LAB colour space. Fine-grained control over the level of sharpening in "flat" (m1) and "jagged" (m2) areas is available.
Parameter sigma
the sigma of the Gaussian mask, where sigma = 1 + radius / 2.
Parameter flat
the level of sharpening to apply to "flat" areas. (optional, default 1.0)
Parameter jagged
the level of sharpening to apply to "jagged" areas. (optional, default 2.0)
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters
Deprecated
Use the object parameter sharpen({sigma, m1, m2, x1, y2, y3}) instead

method stats

stats: {
    (callback: (err: Error, stats: Stats) => void): Sharp;
    (): Promise<Stats>;
};

Access to pixel-derived image statistics for every channel in the image.
Returns
A sharp instance that can be used to chain operations
Access to pixel-derived image statistics for every channel in the image.
Returns
A promise that resolves with a stats object

method threshold

threshold: (threshold?: number, options?: ThresholdOptions) => Sharp;

Any pixel value greather than or equal to the threshold value will be set to 255, otherwise it will be set to 0.
Parameter threshold
a value in the range 0-255 representing the level at which the threshold will be applied. (optional, default 128)
Parameter options
threshold options
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters

method tiff

tiff: (options?: TiffOptions) => Sharp;

Use these TIFF options for output image.
Parameter options
Output options.
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid options

method tile

tile: (tile?: TileOptions) => Sharp;

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.
Parameter tile
tile options
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid options

method timeout

timeout: (options: TimeoutOptions) => Sharp;

Set a timeout for processing, in seconds. Use a value of zero to continue processing indefinitely, the default behaviour. The clock starts when libvips opens an input image for processing. Time spent waiting for a libuv thread to become available is not included.
Parameter options
Object with a seconds attribute between 0 and 3600 (number)
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid options

method tint

tint: (tint: Color) => Sharp;

Tint the image using the provided colour. An alpha channel may be present and will be unchanged by the operation.
Parameter tint
Parsed by the color module.
Returns
A sharp instance that can be used to chain operations

method toBuffer

toBuffer: {
    (callback: (err: Error, buffer: Buffer, info: OutputInfo) => void): Sharp;
    (options?: { resolveWithObject: false }): Promise<Buffer>;
    (options: { resolveWithObject: true }): Promise<{
        data: Buffer;
        info: OutputInfo;
    }>;
};

Write output to a Buffer. JPEG, PNG, WebP, AVIF, TIFF, GIF and RAW output are supported. By default, the format will match the input image, except SVG input which becomes PNG output.
Parameter callback
Callback function called on completion with three arguments (err, buffer, info).
Returns
A sharp instance that can be used to chain operations
Write output to a Buffer. JPEG, PNG, WebP, AVIF, TIFF, GIF and RAW output are supported. By default, the format will match the input image, except SVG input which becomes PNG output.
Parameter options
resolve options
Parameter
options.resolveWithObject Resolve the Promise with an Object containing data and info properties instead of resolving only with data.
Returns
A promise that resolves with the Buffer data.
Write output to a Buffer. JPEG, PNG, WebP, AVIF, TIFF, GIF and RAW output are supported. By default, the format will match the input image, except SVG input which becomes PNG output.
Parameter options
resolve options
Parameter
options.resolveWithObject Resolve the Promise with an Object containing data and info properties instead of resolving only with data.
Returns
A promise that resolves with an object containing the Buffer data and an info object containing the output image format, size (bytes), width, height and channels

method toColorspace

toColorspace: (colorspace: string) => Sharp;

Alternative spelling of toColourspace().
Parameter colorspace
output colorspace e.g. srgb, rgb, cmyk, lab, b-w ...
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters

method toColourspace

toColourspace: (colourspace?: string) => Sharp;

Set the output colourspace. By default output image will be web-friendly sRGB, with additional channels interpreted as alpha channels.
Parameter colourspace
output colourspace e.g. srgb, rgb, cmyk, lab, b-w ...
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters

method toFile

toFile: {
    (fileOut: string, callback: (err: Error, info: OutputInfo) => void): Sharp;
    (fileOut: string): Promise<OutputInfo>;
};

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, AVIF, TIFF, DZI, and libvips' V format supported. Note that raw pixel data is only supported for buffer output.
Parameter fileOut
The path to write the image data to.
Parameter callback
Callback function called on completion with two arguments (err, info). info contains the output image format, size (bytes), width, height and channels.
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters
Write output image data to a file.
Parameter fileOut
The path to write the image data to.
Returns
A promise that fulfills with an object containing information on the resulting file
Throws
{Error} Invalid parameters

method toFormat

toFormat: (
    format: keyof FormatEnum | AvailableFormatInfo,
    options?:
        | OutputOptions
        | JpegOptions
        | PngOptions
        | WebpOptions
        | AvifOptions
        | HeifOptions
        | JxlOptions
        | GifOptions
        | Jp2Options
        | TiffOptions
) => Sharp;

Force output to a given format.
Parameter format
a String or an Object with an 'id' attribute
Parameter options
output options
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Unsupported format or options

method trim

trim: (options?: TrimOptions) => Sharp;

Trim pixels from all edges that contain values similar to the given background colour, which defaults to that of the top-left pixel. Images with an alpha channel will use the combined bounding box of alpha and non-alpha channels. The info response Object will contain trimOffsetLeft and trimOffsetTop properties.
Parameter options
trim options
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters

method unflatten

unflatten: () => Sharp;

Ensure the image has an alpha channel with all white pixel values made fully transparent. Existing alpha channel values for non-white pixels remain unchanged.
Returns
A sharp instance that can be used to chain operations

method webp

webp: (options?: WebpOptions) => Sharp;

Use these WebP options for output image.
Parameter options
Output options.
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid options

method withExif

withExif: (exif: Exif) => Sharp;

Set EXIF metadata in the output image, ignoring any EXIF in the input image.
Parameter exif
Object keyed by IFD0, IFD1 etc. of key/value string pairs to write as EXIF data.
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters

method withExifMerge

withExifMerge: (exif: Exif) => Sharp;

Update EXIF metadata from the input image in the output image.
Parameter exif
Object keyed by IFD0, IFD1 etc. of key/value string pairs to write as EXIF data.
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters

method withIccProfile

withIccProfile: (icc: string, options?: WithIccProfileOptions) => Sharp;

Transform using an ICC profile and attach to the output image.
Parameter icc
Absolute filesystem path to output ICC profile or built-in profile name (srgb, p3, cmyk).
Returns
A sharp instance that can be used to chain operations
Throws
{Error} Invalid parameters

method withMetadata

withMetadata: (withMetadata?: WriteableMetadata) => Sharp;

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.
Parameter withMetadata
Throws
{Error} Invalid parameters.

interface SharpCounters

interface SharpCounters {}

property process

process: number;

The number of resize tasks currently being processed.

property queue

queue: number;

The number of tasks this module has queued waiting for libuv to provide a worker thread from its pool.

interface SharpenOptions

interface SharpenOptions {}

property m1

m1?: number | undefined;

The level of sharpening to apply to "flat" areas, between 0 and 1000000 (optional, default 1.0)

property m2

m2?: number | undefined;

The level of sharpening to apply to "jagged" areas, between 0 and 1000000 (optional, default 2.0)

property sigma

sigma: number;

The sigma of the Gaussian mask, where sigma = 1 + radius / 2, between 0.000001 and 10000

property x1

x1?: number | undefined;

Threshold between "flat" and "jagged", between 0 and 1000000 (optional, default 2.0)

property y2

y2?: number | undefined;

Maximum amount of brightening, between 0 and 1000000 (optional, default 10.0)

property y3

y3?: number | undefined;

Maximum amount of darkening, between 0 and 1000000 (optional, default 20.0)

interface SharpOptions

interface SharpOptions {}

property animated

animated?: boolean | undefined;

Set to true to read all frames/pages of an animated image (equivalent of setting pages to -1). (optional, default false)

property create

create?: Create | undefined;

Describes a new image to be created.

property density

density?: number | undefined;

Number representing the DPI for vector images in the range 1 to 100000. (optional, default 72)

property failOn

failOn?: FailOnOptions | undefined;

When to abort processing of invalid pixel data, one of (in order of sensitivity): 'none' (least), 'truncated', 'error' or 'warning' (most), highers level imply lower levels, invalid metadata will always abort. (optional, default 'warning')

property failOnError

failOnError?: boolean | undefined;

By default halt processing and raise an error when loading invalid images. Set this flag to false if you'd rather apply a "best effort" to decode images, even if the data is corrupt or invalid. (optional, default true)
Deprecated
Use failOn instead

property ignoreIcc

ignoreIcc?: boolean | undefined;

Should the embedded ICC profile, if any, be ignored.

property level

level?: number | undefined;

Level to extract from a multi-level input (OpenSlide), zero based. (optional, default 0)

property limitInputPixels

limitInputPixels?: number | boolean | undefined;

Do not process input images where the number of pixels (width x height) exceeds this limit. Assumes image dimensions contained in the input metadata can be trusted. An integral Number of pixels, zero or false to remove limit, true to use default limit of 268402689 (0x3FFF x 0x3FFF). (optional, default 268402689)

property page

page?: number | undefined;

Page number to start extracting from for multi-page input (GIF, TIFF, PDF), zero based. (optional, default 0)

property pages

pages?: number | undefined;

Number of pages to extract for multi-page input (GIF, TIFF, PDF), use -1 for all pages

property raw

raw?: CreateRaw | undefined;

Describes raw pixel input image data. See raw() for pixel ordering.

property sequentialRead

sequentialRead?: boolean | undefined;

Set this to false to use random access rather than sequential read. Some operations will do this automatically.

property subifd

subifd?: number | undefined;

subIFD (Sub Image File Directory) to extract for OME-TIFF, defaults to main image. (optional, default -1)

property text

text?: CreateText | undefined;

Describes a new text image to be created.

property unlimited

unlimited?: boolean | undefined;

Set this to true to remove safety features that help prevent memory exhaustion (SVG, PNG). (optional, default false)

interface Stats

interface Stats {}

property channels

channels: ChannelStats[];

Array of channel statistics for each channel in the image.

property dominant

dominant: { r: number; g: number; b: number };

Object containing most dominant sRGB colour based on a 4096-bin 3D histogram (experimental)

property entropy

entropy: number;

Histogram-based estimation of greyscale entropy, discarding alpha channel if any (experimental)

property isOpaque

isOpaque: boolean;

Value to identify if the image is opaque or transparent, based on the presence and use of alpha channel

property sharpness

sharpness: number;

Estimation of greyscale sharpness based on the standard deviation of a Laplacian convolution, discarding alpha channel if any (experimental)

interface StrategyEnum

interface StrategyEnum {}

property attention

attention: number;

property entropy

entropy: number;

interface ThresholdOptions

interface ThresholdOptions {}

property grayscale

grayscale?: boolean | undefined;

alternative spelling for greyscale. (optional, default true)

property greyscale

greyscale?: boolean | undefined;

convert to single channel greyscale. (optional, default true)

interface TiffOptions

interface TiffOptions extends OutputOptions {}

property bitdepth

bitdepth?: 1 | 2 | 4 | 8 | undefined;

Reduce bitdepth to 1, 2 or 4 bit (optional, default 8)

property compression

compression?: string | undefined;

Compression options: none, jpeg, deflate, packbits, ccittfax4, lzw, webp, zstd, jp2k (optional, default 'jpeg')

property miniswhite

miniswhite?: boolean | undefined;

Write 1-bit images as miniswhite (optional, default false)

property predictor

predictor?: string | undefined;

Compression predictor options: none, horizontal, float (optional, default 'horizontal')

property pyramid

pyramid?: boolean | undefined;

Write an image pyramid (optional, default false)

property quality

quality?: number | undefined;

Quality, integer 1-100 (optional, default 80)

property resolutionUnit

resolutionUnit?: 'inch' | 'cm' | undefined;

Resolution unit options: inch, cm (optional, default 'inch')

property tile

tile?: boolean | undefined;

Write a tiled tiff (optional, default false)

property tileHeight

tileHeight?: number | undefined;

Vertical tile size (optional, default 256)

property tileWidth

tileWidth?: number | undefined;

Horizontal tile size (optional, default 256)

property xres

xres?: number | undefined;

Horizontal resolution in pixels/mm (optional, default 1.0)

property yres

yres?: number | undefined;

Vertical resolution in pixels/mm (optional, default 1.0)

interface TileOptions

interface TileOptions {}

property angle

angle?: number | undefined;

Tile angle of rotation, must be a multiple of 90. (optional, default 0)

property background

background?: string | RGBA | undefined;

background colour, parsed by the color module, defaults to white without transparency. (optional, default {r:255,g:255,b:255,alpha:1})

property basename

basename?: string | undefined;

The name of the directory within the zip file when container is zip.

property center

center?: boolean | undefined;

Alternative spelling of centre. (optional, default false)

property centre

centre?: boolean | undefined;

Centre image in tile. (optional, default false)

property container

container?: TileContainer | undefined;

Tile container, with value fs (filesystem) or zip (compressed file). (optional, default 'fs')

property depth

depth?: string | undefined;

How deep to make the pyramid, possible values are "onepixel", "onetile" or "one" (default based on layout)

property id

id?: string | undefined;

When layout is iiif/iiif3, sets the @id/id attribute of info.json (optional, default 'https://example.com/iiif')

property layout

layout?: TileLayout | undefined;

Filesystem layout, possible values are dz, iiif, iiif3, zoomify or google. (optional, default 'dz')

property overlap

overlap?: number | undefined;

Tile overlap in pixels, a value between 0 and 8192. (optional, default 0)

property size

size?: number | undefined;

Tile size in pixels, a value between 1 and 8192. (optional, default 256)

property skipBlanks

skipBlanks?: number | undefined;

Threshold to skip tile generation, a value 0 - 255 for 8-bit images or 0 - 65535 for 16-bit images

interface TimeoutOptions

interface TimeoutOptions {}

property seconds

seconds: number;

Number of seconds after which processing will be stopped (default 0, eg disabled)

interface TrimOptions

interface TrimOptions {}

property background

background?: Color | undefined;

Background colour, parsed by the color module, defaults to that of the top-left pixel. (optional)

property lineArt

lineArt?: boolean | undefined;

Does the input more closely resemble line art (e.g. vector) rather than being photographic? (optional, default false)

property threshold

threshold?: number | undefined;

Allowed difference from the above colour, a positive number. (optional, default 10)

interface WebpOptions

interface WebpOptions extends OutputOptions, AnimationOptions {}

property alphaQuality

alphaQuality?: number | undefined;

Quality of alpha layer, number from 0-100 (optional, default 100)

property effort

effort?: number | undefined;

Level of CPU effort to reduce file size, integer 0-6 (optional, default 4)

property lossless

lossless?: boolean | undefined;

Use lossless compression mode (optional, default false)

property minSize

minSize?: boolean;

Prevent use of animation key frames to minimise file size (slow) (optional, default false)

property mixed

mixed?: boolean;

Allow mixture of lossy and lossless animation frames (slow) (optional, default false)

property nearLossless

nearLossless?: boolean | undefined;

Use near_lossless compression mode (optional, default false)

property preset

preset?: keyof PresetEnum | undefined;

Preset options: one of default, photo, picture, drawing, icon, text (optional, default 'default')

property quality

quality?: number | undefined;

Quality, integer 1-100 (optional, default 80)

property smartSubsample

smartSubsample?: boolean | undefined;

Use high quality chroma subsampling (optional, default false)

interface WithIccProfileOptions

interface WithIccProfileOptions {}

property attach

attach?: boolean | undefined;

Should the ICC profile be included in the output image metadata? (optional, default true)

interface WriteableMetadata

interface WriteableMetadata {}

property density

density?: number | undefined;

Number of pixels per inch (DPI)

property exif

exif?: Exif | undefined;

Object keyed by IFD0, IFD1 etc. of key/value string pairs to write as EXIF data.
Deprecated
Use withExif() or withExifMerge() instead.

property icc

icc?: string | undefined;

Filesystem path to output ICC profile, defaults to sRGB.
Deprecated
Use withIccProfile() instead.

property orientation

orientation?: number | undefined;

Value between 1 and 8, used to update the EXIF Orientation tag.

Type Aliases

type Blend

type Blend =
    | 'clear'
    | 'source'
    | 'over'
    | 'in'
    | 'out'
    | 'atop'
    | 'dest'
    | 'dest-over'
    | 'dest-in'
    | 'dest-out'
    | 'dest-atop'
    | 'xor'
    | 'add'
    | 'saturate'
    | 'multiply'
    | 'screen'
    | 'overlay'
    | 'darken'
    | 'lighten'
    | 'color-dodge'
    | 'colour-dodge'
    | 'color-burn'
    | 'colour-burn'
    | 'hard-light'
    | 'soft-light'
    | 'difference'
    | 'exclusion';

type Channels

type Channels = 3 | 4;

3 for sRGB, 4 for CMYK

type Color

type Color = string | RGBA;

type ExtendWith

type ExtendWith = 'background' | 'copy' | 'repeat' | 'mirror';

type FailOnOptions

type FailOnOptions = 'none' | 'truncated' | 'error' | 'warning';

type Gravity

type Gravity = number | string;

type Matrix2x2

type Matrix2x2 = [[number, number], [number, number]];

type Matrix3x3

type Matrix3x3 = [
    [number, number, number],
    [number, number, number],
    [number, number, number]
];

type Matrix4x4

type Matrix4x4 = [
    [number, number, number, number],
    [number, number, number, number],
    [number, number, number, number],
    [number, number, number, number]
];

type Precision

type Precision = 'integer' | 'float' | 'approximate';

type TextAlign

type TextAlign = 'left' | 'centre' | 'center' | 'right';

type TextWrap

type TextWrap = 'word' | 'char' | 'word-char' | 'none';

type TileContainer

type TileContainer = 'fs' | 'zip';

type TileLayout

type TileLayout = 'dz' | 'iiif' | 'iiif3' | 'zoomify' | 'google';

Package Files (1)

lib/index.d.ts

Dependencies (3)

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this oneto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/sharp.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/sharp)

HTML

<a href="https://www.jsdocs.io/package/sharp"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated 4 months ago.
Package analyzed in 7977 ms.
Missing or incorrect documentation? Open an issue for this package.

sharp

Install

Overview

Index

Variables

Functions

Interfaces

Type Aliases

Variables

variable bool

variable fit

variable format

variable gravity

variable interpolators

variable kernel

variable queue

variable strategy

variable versions

Functions

function block

Parameter options

Parameter

Example 1

function cache

Parameter options

Returns

function concurrency

Parameter concurrency

Returns

function counters

Returns

function sharp

Parameter input

Parameter options

Returns

Throws

function simd

Parameter enable

Returns

function unblock

Parameter options

Parameter

Example 1

Example 2

Interfaces

interface AffineOptions

property background

property idx

property idy

property interpolator

property odx

property ody

interface AnimationOptions

property delay

property loop

interface AvailableFormatInfo

property id

property input

property output

interface AvifOptions

property bitdepth

property chromaSubsampling

property effort

property lossless

property quality

interface BlurOptions

property minAmplitude

property precision

property sigma

interface BoolEnum

property and

property eor

property or

interface CacheOptions

property files

property items

property memory

interface CacheResult

property files

property items