Skip to content

Latest commit

 

History

History
233 lines (163 loc) · 6.83 KB

api-utility.md

File metadata and controls

233 lines (163 loc) · 6.83 KB

versions

versions

An Object containing the version numbers of sharp, libvips and (when using prebuilt binaries) its dependencies.

Example

console.log(sharp.versions);

interpolators

interpolators : enum

An Object containing the available interpolators and their proper values

Read only: true
Properties

Name Type Default Description
nearest string "nearest" Nearest neighbour interpolation. Suitable for image enlargement only.
bilinear string "bilinear" Bilinear interpolation. Faster than bicubic but with less smooth results.
bicubic string "bicubic" Bicubic interpolation (the default).
locallyBoundedBicubic string "lbb" LBB interpolation. Prevents some "acutance" but typically reduces performance by a factor of 2.
nohalo string "nohalo" Nohalo interpolation. Prevents acutance but typically reduces performance by a factor of 3.
vertexSplitQuadraticBasisSpline string "vsqbs" VSQBS interpolation. Prevents "staircasing" when enlarging.

format

format ⇒ Object

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

Example

console.log(sharp.format);

queue

queue

An EventEmitter that emits a change event when a task is either:

  • queued, waiting for libuv to provide a worker thread
  • complete

Example

sharp.queue.on('change', function(queueLength) {
  console.log('Queue contains ' + queueLength + ' task(s)');
});

cache

cache([options]) ⇒ Object

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.

Param Type Default Description
[options] Object | boolean true Object with the following attributes, or boolean where true uses default cache settings and false removes all caching
[options.memory] number 50 is the maximum memory in MB to use for this cache
[options.files] number 20 is the maximum number of files to hold open
[options.items] number 100 is the maximum number of operations to cache

Example

const stats = sharp.cache();

Example

sharp.cache( { items: 200 } );
sharp.cache( { files: 0 } );
sharp.cache(false);

concurrency

concurrency([concurrency]) ⇒ number

Gets or, when a concurrency is provided, sets the maximum number of threads libvips should use to process each image. These are from a thread pool managed by glib, which helps avoid the overhead of creating new threads.

This method always returns the current concurrency.

The default value is the number of CPU cores, except when using glibc-based Linux without jemalloc, where the default is 1 to help reduce memory fragmentation.

A value of 0 will reset this to the number of CPU cores.

Some image format libraries spawn additional threads, e.g. libaom manages its own 4 threads when encoding AVIF images, and these are independent of the value set here.

The maximum number of images that sharp can process in parallel is controlled by libuv's UV_THREADPOOL_SIZE environment variable, which defaults to 4.

https://nodejs.org/api/cli.html#uv_threadpool_sizesize

For example, by default, a machine with 8 CPU cores will process 4 images in parallel and use up to 8 threads per image, so there will be up to 32 concurrent threads.

Returns: number - concurrency

Param Type
[concurrency] number

Example

const threads = sharp.concurrency(); // 4
sharp.concurrency(2); // 2
sharp.concurrency(0); // 4

counters

counters() ⇒ Object

Provides access to internal task counters.

  • queue is the number of tasks this module has queued waiting for libuv to provide a worker thread from its pool.
  • process is the number of resize tasks currently being processed.

Example

const counters = sharp.counters(); // { queue: 2, process: 4 }

simd

simd([simd]) ⇒ 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.

Param Type Default
[simd] boolean true

Example

const simd = sharp.simd();
// simd is `true` if the runtime use of highway is currently enabled

Example

const simd = sharp.simd(false);
// prevent libvips from using highway at runtime

block

block(options)

Block libvips operations at runtime.

This is in addition to the VIPS_BLOCK_UNTRUSTED environment variable, which when set will block all "untrusted" operations.

Since: 0.32.4

Param Type Description
options Object
options.operation Array.<string> List of libvips low-level operation names to block.

Example (Block all TIFF input.)

sharp.block({
  operation: ['VipsForeignLoadTiff']
});

unblock

unblock(options)

Unblock libvips operations at runtime.

This is useful for defining a list of allowed operations.

Since: 0.32.4

Param Type Description
options Object
options.operation Array.<string> List of libvips low-level operation names to unblock.

Example (Block all input except WebP from the filesystem.)

sharp.block({
  operation: ['VipsForeignLoad']
});
sharp.unblock({
  operation: ['VipsForeignLoadWebpFile']
});

Example (Block all input except JPEG and PNG from a Buffer or Stream.)

sharp.block({
  operation: ['VipsForeignLoad']
});
sharp.unblock({
  operation: ['VipsForeignLoadJpegBuffer', 'VipsForeignLoadPngBuffer']
});