Skip to content

kleisauke/wasm-vips

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
lib
 
 
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

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.

Engine support

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.

JavaScriptCore-based (e.g. Safari, Bun) engines are currently not supported, you can follow the status in this tracking bug.

Chrome
Chrome
Firefox
Firefox
Safari
Safari
Edge
Edge
Node.js
Node.js
Deno
Deno
✔️
version 91+
✔️
version 89+

Tracking bug
✔️
version 91+
✔️
version 16.4+
✔️
version 1.9+

Installation

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

npm install wasm-vips
yarn add wasm-vips

Usage

Browser

Requires vips.js, vips.wasm and vips.worker.js 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 the main document:

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 won't work on Firefox due to https://bugzil.la/1540913.

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 'wasm-vips';

// CommonJS module
const Vips = require('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

On Deno, the web ES6 module can be reused and imported from a CDN such as jsDelivr:

import Vips from 'https://cdn.jsdelivr.net/npm/wasm-vips/lib/vips-es6.js';

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');