Web assembly ImageMagick

This project is not affiliated with ImageMagick , but is merely recompiling the code to be WebAssembly. I did this because I want to bring the power of ImageMagick to the browser.

Table of Contents

• Demos and examples
• Status
  • Image formats supported
  • Features not supported
• API
  • High level API and utilities
  • Accessing stdout, stderr, exitCode
  • low-level example
• Importing the library in your project
  • With npm
  • Loading directly from html file
    • Importing it as JavaScript standard module:
    • Using the UMD bundle in AMD projects (requirejs)
    • Using the UMD bundle without libraries
• Build instructions
• Run tests

Demos and examples

• Basic playground (React & TypeScript project): .

• Image Diff Example (React & TypeScript project): .

• Interactive execute context demo. Add images, execute commands using different syntaxes, manage and reuse output/input images, and choose commands examples to learn ImageMagick. Project lives here

• Playground with several transformation examples and image formats. It also shows the output of transformations made with ImageMagick in the browser to verify wasm-imagemagick output the right thing.

• Picture Frame editor.

• Simple example. See samples/rotate#code. A simple webpage that has image in array and loads magickApi.js to rotate file. Demonstration site https://knicknic.github.io/imagemagick/rotate/

• https://knicknic.github.io/imagemagick/ a commandline sample of using ImageMagick

  • For code see samples/cmdline

• Used in Croppy to split webcomics from one long vertical strip into many panels.

  • For code see https://github.com/KnicKnic/croppy.

Status

Image formats supported

Supports PNG, TIFF, JPEG, BMP, GIF, PhotoShop, GIMP, and more!

See a list of known supported formats in this demo

Features not supported

• Text
• Fourier Transforms
• Formats not listed above, particularly webp.

API

Reference API Documentation

Reference API Documentation

High level API and utilities

wasm-imagemagick comes with some easy to use APIs for creating image files from urls, executing multiple commands reusing output images and nicer command syntax, and utilities to handle files, html images, input elements, image comparison, metadata extraction, etc. Refer to API Reference Documentation for details.

import { buildInputFile, execute, loadImageElement } from 'wasm-imagemagick'

const { outputFiles, exitCode} = await execute({
  inputFiles: [await buildInputFile('http://some-cdn.com/foo/fn.png', 'image1.png')],
  commands: [
    'convert image1.png -rotate 70 image2.gif',
    // heads up: the next command uses 'image2.gif' which was the output of previous command:
    'convert image2.gif -scale 23% image3.jpg',
  ],
})
if(exitCode !== 0)
    await loadImageElement(outputFiles[0], document.getElementById('outputImage'))

Accessing stdout, stderr, exitCode

This other example executes identify command to extract information about an image. As you can see, we access stdout from the execution result and check for errors using exitCode and stderr:

import { buildInputFile, execute } from 'wasm-imagemagick'

const { stdout, stderr, exitCode } = await execute({
    inputFiles: [await buildInputFile('foo.gif')], 
    commands: `identify foo.gif`
})
if(exitCode === 0) 
    console.log('foo.gif identify output: ' + stdout.join('\n'))
else 
    console.error('foo.gif identify command failed: ' + stderr.join('\n'))

low-level example

As demonstration purposes, the following example doesn't use any helper provided by the library, only the low level call() function which only accept one command, in array syntax only:

import { call } from 'wasm-imagemagick'

// build an input file by fetching its content
const fetchedSourceImage = await fetch("assets/rotate.png")
const content = new Uint8Array(await fetchedSourceImage.arrayBuffer());
const image = { name: 'srcFile.png', content }

const command = ["convert", "srcFile.png", '-rotate', '90', '-resize', '200%', 'out.png']
const result = await call([image], command)

// is there any errors ?
if(result.exitCode !== 0)
    return alert('There was an error: ' + result.stderr.join('\n'))

// response can be multiple files (example split) here we know we just have one
const outputImage = result.processedFiles[0]

// render the output image into an existing <img> element
const outputImage = document.getElementById('outputImage')
outputImage.src = URL.createObjectURL(outputImage.blob)
outputImage.alt = outputImage.name

Importing the library in your project

With npm

npm install --save wasm-imagemagick

**IMPORTANT:

Don't forget to copy magick.wasm and magick.js files to the folder where your index.html is being served:

cp node_modules/wasm-imagemagick/dist/magick.wasm .
cp node_modules/wasm-imagemagick/dist/magick.js .

Then you are ready to import the library in your project like this:

import { execute} from 'wasm-imagemagick'

or like this if you are not using standard modules:

const execute = require('wasm-imagemagick').execute

Loading directly from html file

If you are not working in a npm development environment you can still load the library bundle .js file. It supports being imported as JavaScript standard module or as a UMD module. Again, don't forget to copy magick.js, magick.wasm in the same folder as your html file.:

Importing it as JavaScript standard module:

<script type="module">
    import { execute, loadImageElement, buildInputFile } from '../../dist/bundles/wasm-imagemagick.esm-es2018.js'
    // ... same snippet as before
</script>

Working example source code

Using the UMD bundle in AMD projects (requirejs)

<script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js"></script>
<script src="../../dist/bundles/wasm-imagemagick.umd-es5.js"></script>
<script>
require(['wasm-imagemagick'], function (WasmImagemagick) {
    const { execute, loadImageElement, buildInputFile } = WasmImagemagick
    // ... same snippet as before

Working example source code

Using the UMD bundle without libraries

<script src="../../dist/bundles/wasm-imagemagick.umd-es5.js"></script>
<script>
    const { execute, loadImageElement, buildInputFile } = window['wasm-imagemagick']
    // ... same snippet as before

Working example source code

Build instructions

git clone --recurse-submodules https://github.com/KnicKnic/WASM-ImageMagick.git

cd WASM-ImageMagick

docker build -t wasm-imagemagick-build-tools .

docker run --rm -it --workdir /code -v "$PWD":/code wasm-imagemagick-build-tools bash ./build.sh

#windows cmd
#docker run --rm -it --workdir /code -v %CD%:/code wasm-imagemagick-build-tools bash ./build.sh

Produces magick.js & magick.wasm in the current folder.

Note: npm run build will perform all the previous commands plus compiling the TypeScript project.

Run tests

npm test will run all the tests.

npm run test-browser will run spec in a headless chrome browser. These tests are located at ./spec/.

npm run test-browser-server will serve the test so you can debug them with a browser.

npm run test-browser-start will run the server and start watching for file changes, recompile and restart the server for agile development.

npm test-node will run some tests with nodejs located at ./tests/rotate.