magick-cli
v2.0.0
Published
Native ImageMagick CLI for Node.js
Downloads
27
Readme
MagickCLI
Native ImageMagick CLI for Node.js
- Introduction
- Motivations
- Prerequisites
- Installation
- Installation options
- Usage
- Code of conduct
- Team
- Acknowledgements
- License
Introduction
ImageMagick is a free and open-source software suite for displaying, converting, and editing raster and vector image files. It utilizes multiple computational threads to increase performance and can read, process, or write mega-, giga-, or tera-pixel image sizes.
More resource and info about ImageMagick
Motivations
At the time i created this module i was not able to find any module on npm that execute ImageMagick command through its C API, otherwise there were some module that call ImageMagick through the execution of the corresponding shell command. This is a good way to start using some library from node, but there are the following drawbacks:
Performance - The call to the shell command take more time and more resources than calling a library C or C++ API directly from Node.js environment.
Errror handler - Sometimes you cannot intercept and handle errors in a good and a proper way.
To fit all needs MagickCLI has sync and async methods so it could be used in a web application where it's very important to not block the event loop, so all requests will be served without any delay originated by our application.
Understanding Node.js event loop
Prerequisites
Before installing MagickCLI you need to assure you have the following prerequisites:
Node.JS see: Installing Node.js via package manager
Node.js native addon build tool see: node-gyp
ImageMagick for your Operating System.
At the moment MagickCLI is fully compatible with ImageMagick from version 7.0.1 to 7.0.8
Linux
You can install ImageMagick from binary or directly from source:
Maybe your linux distribution has already packaged ImageMagick version 7.0.1 or above so you can install it using your package manager and all is more simple.
Windows
Download the installer for your platform from this link ImageMagick Windows Installer
Install ImageMagick on your system.
macOS
Install Homebrew following the official guide here
Open terminal and install ImageMagick
brew install imagemagick
- Open terminal and install pkg-info
brew install pkg-info
Installation
If you want to use MagickCLI you have to install it. There are two methods for that:
In dependencies of your package.json
add the following item:
"magick-cli": "version"
then digit
npm install
Example:
"magick-cli": "*" for the latest version
"magick-cli": "1.0.0" for the version 1.0.0
OR
launch this command:
npm install magick-cli --save
Usage
'use strict'
const MagickCLI = require('magick-cli')
try {
// Take decision based on ImageMagick version
const version = MagickCLI.version()
console.log(version)
MagickCLI.executeSync('magick input.png -resize 50% output.png')
} catch (err) {
// Handle error
throw err
}
API
version
version() method returns an string that represent the version of ImageMagick library installed on the system. It is important in those circumstances where you have to take decision based on different version.
Example - version
'use strict'
const MagickCLI = require('magick-cli')
try {
const version = MagickCLI.version()
console.log(version)
// Take decision based on ImageMagick version
if (version != '7.0.1') {
// ... some stuff
} else {
// ... other stuff
}
} catch (err) {
// Handle error
throw err
}
executeSync
executeSync(cmd) method takes the ImageMagick command parameters in input as a string and executes in a synchronous way. If something wrong happens in calling this method an Error with description and code error will be thrown.
Example - executeSync
'use strict'
const MagickCLI = require('magick-cli')
try {
MagickCLI.executeSync('magick input.png -resize 50% output.png')
} catch (err) {
// Handle error
throw err
}
execute
execute(cmd, callback) method takes in input the ImageMagick command parameters as a string and an optional callback. The execution will be asynchronous so this ensure better performance especially in a web application enviroment, because it'll not block the Node.Js event loop. This method has an optional callback function as input, in that case, a possible error will be handled by this function. If noone function will be provided the method returns a Promise that will be resolved or rejected as reported in the following example.
Example - execute
'use strict'
const MagickCLI = require('magick-cli')
let cmd = 'magick input.png -resize 50% output.png'
MagickCLI.execute(cmd, function (err) {
if (err) {
console.log("Ooops... something wrong happened")
}
})
'use strict'
const MagickCLI = require('magick-cli')
let cmd = '-magick input.png -resize 50% output.png'
MagickCLI.execute(cmd)
.then(() => {
console.log("All is ok")
})
.catch((err) => {
console.log("Ooops... something wrong happened")
})
Error
The error raised from magick-cli in all of its method is an instance of Error object that cointains a message that describes what happened and at the same time cointains the ImageMagick error code so you can inspect what happened in a better way.
Min and Max supported revision
This module was built based on ImageMagick C API that is compatible with some specifics versions. The module has two properties MIN_SUPPORTED_REVISION and MAX_SUPPORTED_REVISION which respectively indicate the minimum and maximum supported ImageMagick's version.
Example - Min and Max supported revision
'use strict'
const MagickCLI = require('magick-cli')
console.log(MagickCLI.MIN_SUPPORTED_REVISION)
console.log(MagickCLI.MAX_SUPPORTED_REVISION)
The Team
Nicola Del Gobbo
https://www.npmjs.com/~nicknaso
Mauro Doganieri
https://www.npmjs.com/~mauro-d
https://twitter.com/maurodoganieri
Acknowledgements
Thank you to all people that encourage me every day.
License
Licensed under Apache license V2