wasm-vips

libvips for the browser and Node.js, compiled to WebAssembly with Emscripten.

Programs that use wasm-vips don't manipulate images directly, instead they create pipelines of image processing operations building on a source image. When the end of the pipe is connected to a destination, the whole pipeline executes at once, streaming the image in parallel from source to destination a section at a time. Because wasm-vips is parallel, it's quick, and because it doesn't need to keep entire images in memory, it's light.

[!NOTE] This library is still under early development. See: #1.

Package Variants

This fork of wasm-vips provides different binaries in a single package to cater to different needs. Each variant is optimized for specific scenarios:

• @denodecom/wasm-vips: The default build with full features and SIMD support.

  • Supports all loaders.

• @denodecom/wasm-vips/nosimd: Build without SIMD support.

  • Supports all loaders.

• @denodecom/wasm-vips/slim: A build with reduced features and memory usage.

  • Supports only JPEG, PNG, and WebP loaders.
  • Filesystem (FS) support is not available

• @denodecom/wasm-vips/nosimd/slim: A slim build without SIMD support.

  • Supports only JPEG, PNG, and WebP loaders.
  • Filesystem (FS) support is not available

• @denodecom/wasm-vips/lowmem: A low memory build with a maximum memory limit of 256MB to avoid out-of-memory (OOM) issues on iOS.

  • Supports all loaders.

• @denodecom/wasm-vips/nosimd/lowmem: A low memory build without SIMD support, with a maximum memory limit of 256MB to avoid out-of-memory (OOM) issues on iOS.

  • Supports all loaders.

Engine support for default build

An engine that supports WebAssembly SIMD. This is present on most major browser engines.

For V8-based engines, at least version 9.1.54 is required to match the final SIMD opcodes, this corresponds to Chrome 91, Node.js 16.4.0 and Deno 1.9.0.

For Spidermonkey-based engines, the JavaScript engine used in Mozilla Firefox and whose version numbers are aligned, at least version 89 is required.

For JavaScriptCore-based engines, the built-in JavaScript engine for WebKit, at least version 615.1.17 is required. This corresponds to Safari 16.4.

| Chrome | Firefox | Safari | Edge | Node.js | Deno | |:---:|:---:|:---:|:---:|:---:|:---:| | :heavy_check_mark:version 91+ | :heavy_check_mark:version 89+ | :heavy_check_mark:version 16.4+ | :heavy_check_mark:version 91+ | :heavy_check_mark:version 16.4+ | :heavy_check_mark:version 1.9+ |

Installation

@denodecom/wasm-vips can be installed with your favorite package manager.

npm install @denodecom/wasm-vips

yarn add @denodecom/wasm-vips

Usage

Browser

Requires vips.js (or vips-es6.js) and vips.wasm to be served from the same directory.

Since wasm-vips requires the SharedArrayBuffer API, the website needs to opt-in to a cross-origin isolated state, by serving the following HTTP headers on both the main document and vips*.js script:

Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin

See https://web.dev/coop-coep/ for more information.

After that, wasm-vips can be imported and initialized like this:

<script src="vips.js"></script>
<script type="module">
  const vips = await Vips();
</script>

Or, if you prefer to use ES6 modules:

<script type="module">
  import Vips from './vips-es6.js';
  const vips = await Vips();
</script>

This requires support for import() in workers.

Node.js

On Node.js, wasm-vips is published as a dual-package, so it can be imported as both CommonJS and ES6 module:

// ES6 module
import Vips from '@denodecom/wasm-vips';

// CommonJS module
const Vips = require('@denodecom/wasm-vips');

Then, wasm-vips can be initialized like this:

// Usage with top-level await
const vips = await Vips();

// Usage with .then
Vips().then(vips => {
  // Code here
});

Deno

import Vips from 'npm:@denodecom/wasm-vips';

const vips = await Vips();

Example

// Load an image from a file
let im = vips.Image.newFromFile('owl.jpg');

// Put im at position (100, 100) in a 3000 x 3000 pixel image,
// make the other pixels in the image by mirroring im up / down /
// left / right, see
// https://libvips.github.io/libvips/API/current/libvips-conversion.html#vips-embed
im = im.embed(100, 100, 3000, 3000, {
  extend: 'mirror'
});

// Multiply the green (middle) band by 2, leave the other two alone
im = im.multiply([1, 2, 1]);

// Make an image from an array constant, convolve with it
const mask = vips.Image.newFromArray([
  [-1, -1, -1],
  [-1, 16, -1],
  [-1, -1, -1]
], 8.0);

im = im.conv(mask, {
  precision: 'integer'
});

// Finally, write the result to a buffer
const outBuffer = im.writeToBuffer('.jpg');