Easy to setup and use, ImageMagick Node.js and Browser API and Command Line Interface.
- Playground & demos
- Command line
- Reference API
- TODO / Road map
Playground & demos
- Magica Playground (WIP) - Playground with LOTS of ImageMagick script examples to experiment with, edit and share by url.
- Magica Canvas (WIP) - Renders transformations in canvas as fast as possible to show that for images width<1000px it's instantaneous. See transformations happen on mouse move, and on streaming video. https://cancerberosgx.github.io/demos/magica/images/magica-canvas-demo.mp4
- Desktop sample application . Use https://libyue.com for cross platform native GUI.
- Command line interface which supports simple straightforwards translation between ImageMagick utilities command line interface (like
- Easy/Quick setup, no emscripten build needed.
- Includes ImageMagick WebAssembly bundle (wasm - see sub project magick-wasm. It's also compatible with IM COmmand line utilities based API such as wasm-imagemagick.
- So no build is necessary. Just
npm installand you are ready to go, both in node.js and the browser.
- So no build is necessary. Just
- Supports most of ImageMagick delegate libraries, such as gif, png, tiff, jpg, webp, fonts ttf/otf, raw, pdf, fftw, lcms, cypher, openjpeg, jp2, jpc (jpeg 2000), lcms (.icc profiles) and a lot more.
- Speed and memory consumption are acceptable for images below 1000x1000. Then a resize could take .5 or more...
- Supports all ImageMagick Command line Utilities such as convert, identify, montage, stc
- See TODO.md for progress, supported features / libraries ported , things not supported yet and and roadmap.
- Most libraries and features supported. Each has a test (formats, features, commands)
npm install magica
If you only will use the Command Line Interface perhaps a better option is installing it globally:
npm install -g magica
The command line interface will let you use the same Image Magick commands. The only difference is that you will need to explicitly list the input files paths.
In the following example we execute
$ magica --command "convert foo.tiff -scale 30% -rotate 33 output/img/bar.png" --input ../img/foo.tiff$ magica --command "identify bar.png" --input output/img/bar.pngbar.png PNG 109x145 109x145+0+0 8-bit sRGB 39796B 0.000u 0:00.000
Notice that besides passing the ImageMagick command with
--command we also passed the image files using
--input. It is important that the basename of given input files match the file names referenced in the command (
Some other examples:
magica --input "frames_*.jpg" --command "convert 'frames_[0-9].gif' -scale 44% tmp.gif"
TODO: verify that works
--inputcan be a glob of files, useful for batch multiple images or to build gifs from several images.
- For quoteing arguments inside
--commanduse single quotes
In the following example we convert an image in Node.js. (Checkout
run() for a flexible script-like syntax below)
The following example is analog to the previous one but in the browser:
- IMPORTANT: make sure
dist/src/imageMagick/compiled/magick.wasmis located at the same folder of your .js bundle file.
- the rest of the files you can be bundled with any technology like browserify, parcel, webpack etc.
- See npm script "browser-sample". Run "npm run browser-sample" and look samples at
- browser tests can be executed (run with puppeteer) with
npm run test-browser
WASM file in different location
If you need to load magick.wasm from a different location than your index.html and even from magick.js it can be done by declaring a global variable with its url or adding a parameter in magica.js script src attribute:
Script src attribute with a parameter
Of course in the browser you will want to use a web-worker to process images. Just pass the command object as a message, execute
main() in the worker and return back the result.
Both the command and result objects are designed to transfer data between main thread and worker optimally.
npm run test-worker script for a working simple example.
run(): command script/template syntax
While ImageMagick provides a syntax to run complex commands performing several operations,
main() will be enough most of the time.
Nevertheless magica also supports
run() which accept allows to create scripts to execute several commands, just like bash scripts
It supports comments, command splitting in mutiple lines by ending them with
\, just like bash scripts:
TODO: show one command divided with
\\ and with comments
The most useful feature of
run() is that it will run the commands serially, and each command output files will be available to next commands as input files automatically:
TODO: example of multiple commands consuming output files
TODO: document templates <%= %> in run scripts. the syntax, available context properties and template helpers, how to add new context properties and how to add new template helpers.
Commands pre processors
TODO: update with run() and script()
Options are the same for the command line and the API:
--input: string: (command line only) Input file paths. It can also be glob patterns. For passing more than one use
--inputmultiple times. It's important that the base name of these paths match the file names given in the command.
--command: string | string: An ImageMagick command, for example:
"convert foo.png -scale 50% bar.gif".
--inputFiles?: string | string: (API only) The list of input files referenced in given command. It's important that the name of this files match the file names given in the command. If string and a file exists (node.js) then that file will be used. Otherwise it will be considered a url. In later cases, the filename will be the base name of file or url.
--help?: boolean: (command line only)
disableNodeFs?: boolean: (node.js only) Don't use system's filesystem in Node.js but memory filesystem (just like in the browser). This could be faster if read/write many images but consumes more memory.
- Support node.js without having two separate distribution or using different technologies / APIs.
- Although the principles of the API are the same, this project aims to simplifies some parts of it.
- Clearly de couple the wasm build process and its internal details from the user API assuming a well known, simple API (see below).
- Although currently wasm-imagemagick is the most mature (and I would working) ImageMagick emscripten port, there are other initiatives which could support more features or have better performance. This library is designed to easily support these emscripten wasm "binaries" without big changes (or even switch between them)
- Don't want to be responsible of compiling .wasm, so this project includes and uses wasm-imagemagick files directly.
src/imageMagick/compiled/can be generated from that project executing
npm run test-node.
- I believe the end user API should be built on top of this, in an independent project that assumes only a simple ImageMagick API is supported. Currently this API is the Command Line interface of ImageMagick command line utilities like
mogrify, etc. (Notice that is not the C/C++ API like MagickCore, MagickWand, etc, but the Command line interface of utilities like
convertwhich IMO covers 99% of use cases and is easy to use (compared to the C/C++ APIs).
- If a ImageMagick emscripten port supports this ImageMagick utilities Command line interface, then it should be automatically used by this project. (just replacing the .wasm should be enough)
- I wanted have tests in Node.js and Browser and a easy/scalable framework for that.
TODO / Road map