ImageMagick's Magick++ binding for Node.
Features
- Native bindings to the C/C++ Magick++ library
- Async, sync, and stream API
- Support for
convert
,identify
,composite
, and other utility functions
Table of contents
- Examples
- Convert formats (PNG to JPEG)
- Blur
- Resize
- Rotate, flip, and mirror
- API Reference
- Installation
- Performance
- License
Convert from one format to another with quality control:
fs.writeFileSync('after.png', imagemagick.convert({
srcData: fs.readFileSync('before.jpg'),
format: 'PNG',
quality: 100 // (best) to 1 (worst)
}));
Original JPEG:
Converted to PNG:
quality 100 | quality 50 | quality 1 |
---|---|---|
Image courtesy of David Yu.
Blur image:
fs.writeFileSync('after.jpg', imagemagick.convert({
srcData: fs.readFileSync('before.jpg'),
blur: 5
}));
Image courtesy of Tambako The Jaguar.
Resized images by specifying width
and height
. There are three resizing styles:
aspectfill
: Default. The resulting image will be exactly the specified size, and may be cropped.aspectfit
: Scales the image so that it will not have to be cropped.fill
: Squishes or stretches the image so that it fills exactly the specified size.
fs.writeFileSync('after_resize.jpg', imagemagick.convert({
srcData: fs.readFileSync('before_resize.jpg'),
width: 100,
height: 100,
resizeStyle: 'aspectfill', // is the default, or 'aspectfit' or 'fill'
gravity: 'Center' // optional: position crop area when using 'aspectfill'
}));
Original:
Resized:
aspectfill | aspectfit | fill |
---|---|---|
Image courtesy of Christoph.
Rotate and flip images, and combine the two to mirror:
fs.writeFileSync('after_rotateflip.jpg', imagemagick.convert({
srcData: fs.readFileSync('before_rotateflip.jpg'),
rotate: 180,
flip: true
}));
Original:
Modified:
rotate 90 degrees | rotate 180 degrees | flip | flip + rotate 180 degrees = mirror |
---|---|---|---|
Image courtesy of Bill Gracey.
Convert a buffer provided as options.srcData
and return a Buffer.
The options
argument can have following values:
{
srcData: required. Buffer with binary image data
srcFormat: optional. force source format if not detected (e.g. 'ICO'), one of http://www.imagemagick.org/script/formats.php
quality: optional. 1-100 integer, default 75. JPEG/MIFF/PNG compression level.
crop: optional. Format: "WIDTHxHEIGHT+offsetX+offsetY". Offsets are optional.
Crops area of the image using specified geometry. Applied before trim, resize and filters.
trim: optional. default: false. trims edges that are the background color.
trimFuzz: optional. [0-1) float, default 0. trimmed color distance to edge color, 0 is exact.
width: optional. px.
height: optional. px.
density optional. Integer dpi value to convert
resizeStyle: optional. default: 'aspectfill'. can be 'aspectfit', 'fill'
aspectfill: keep aspect ratio, get the exact provided size.
aspectfit: keep aspect ratio, get maximum image that fits inside provided size
fill: forget aspect ratio, get the exact provided size
gravity: optional. default: 'Center'. used to position the crop area when resizeStyle is 'aspectfill'
can be 'NorthWest', 'North', 'NorthEast', 'West',
'Center', 'East', 'SouthWest', 'South', 'SouthEast', 'None'
format: optional. output format, ex: 'JPEG'. see below for candidates
filter: optional. resize filter. ex: 'Lagrange', 'Lanczos'. see below for candidates
blur: optional. ex: 0.8
strip: optional. default: false. strips comments out from image.
rotate: optional. degrees.
flip: optional. vertical flip, true or false.
debug: optional. true or false
ignoreWarnings: optional. true or false
}
Notes
An optional callback
argument can be provided, in which case convert
will run asynchronously. When it is done, callback
will be called with the error and the result buffer:
imagemagick.convert({
// options
}, function (err, buffer) {
// check err, use buffer
});
There is also a stream version:
fs.createReadStream('input.png').pipe(imagemagick.streams.convert({
// options
})).pipe(fs.createWriteStream('output.png'));
Identify a buffer provided as srcData
and return an object.
The options
argument can have following values:
{
srcData: required. Buffer with binary image data
debug: optional. true or false
ignoreWarnings: optional. true or false
}
An optional callback
argument can be provided, in which case identify
will run asynchronously. When it is done, callback
will be called with the error and the result object:
imagemagick.identify({
// options
}, function (err, result) {
// check err, use result
});
The method returns an object similar to:
{
format: 'JPEG',
width: 3904,
height: 2622,
depth: 8,
density : {
width : 300,
height : 300
},
exif: {
orientation: 0 // if none exists or e.g. 3 (portrait iPad pictures)
}
}
Quantize the image to a specified amount of colors from a buffer provided as srcData
and return an array.
The options
argument can have following values:
{
srcData: required. Buffer with binary image data
colors: required. number of colors to extract, defaults to 5
debug: optional. true or false
ignoreWarnings: optional. true or false
}
The method returns an array similar to:
[
{
r: 83,
g: 56,
b: 35,
hex: '533823'
},
{
r: 149,
g: 110,
b: 73,
hex: '956e49'
},
{
r: 165,
g: 141,
b: 111,
hex: 'a58d6f'
}
]
Composite a buffer provided as options.compositeData
on a buffer provided as options.srcData
with gravity specified by options.gravity
and return a Buffer.
The options
argument can have following values:
{
srcData: required. Buffer with binary image data
compositeData: required. Buffer with binary image data
gravity: optional. Can be one of 'CenterGravity' 'EastGravity' 'ForgetGravity' 'NorthEastGravity' 'NorthGravity' 'NorthWestGravity' 'SouthEastGravity' 'SouthGravity' 'SouthWestGravity' 'WestGravity'
debug: optional. true or false
ignoreWarnings: optional. true or false
}
An optional callback
argument can be provided, in which case composite
will run asynchronously. When it is done, callback
will be called with the error and the result buffer:
imagemagick.composite(options, function (err, buffer) {
// check err, use buffer
});
This library currently provide only these, please try node-imagemagick if you want more.
Get pixels of provided rectangular region.
The options
argument can have following values:
{
srcData: required. Buffer with binary image data
x: required. x,y,columns,rows provide the area of interest.
y: required.
columns: required.
rows: required.
}
Example usage:
// retrieve first pixel of image
var pixels = imagemagick.getConstPixels({
srcData: imageBuffer, // white image
x: 0,
y: 0,
columns: 1,
rows: 1
});
Returns:
[ { red: 65535, green: 65535, blue: 65535, opacity: 65535 } ]
Where each color value's size is imagemagick.quantumDepth
bits.
Return ImageMagick's QuantumDepth, which is defined in compile time.
ex: 16
Return ImageMagick's version as string.
ex: '6.7.7'
Install ImageMagick with headers before installing this module. Tested with ImageMagick 6.7.7 on CentOS 6 and Mac OS X Lion, Ubuntu 12.04 .
brew install imagemagick
or
sudo yum install ImageMagick-c++ ImageMagick-c++-devel
or
sudo apt-get install libmagick++-dev
Make sure you can find Magick++-config in your PATH. Then:
npm install imagemagick-native
Installation notes
- RHEL/CentOS: If the version of ImageMagick required by
node-imagemagick-native
is not available in an official RPM repository, please try the-last
version offered by Les RPM de Remi, for example:
sudo yum remove -y ImageMagick
sudo yum install -y http://rpms.famillecollet.com/enterprise/remi-release-6.rpm
sudo yum install -y --enablerepo=remi ImageMagick-last-c++-devel
- Mac OS X: You might need to install
pkgconfig
first:
brew install pkgconfig
Tested on Windows 7 x64.
-
Install Python 2.7.3 only 2.7.3 nothing else works quite right!
If you use Cygwin ensure you don't have Python installed in Cygwin setup as there will be some confusion about what version to use.
-
Install Visual Studio C++ 2010 Express
-
(64-bit only) Install Windows 7 64-bit SDK
-
Install Imagemagick dll binary x86 Q16 or Imagemagick dll binary x64 Q16, check for libraries and includes during install.
Then:
npm install imagemagick-native
imagemagick: 16.09ms per iteration
imagemagick-native: 0.89ms per iteration
See node test/benchmark.js
for details.
Note: node-imagemagick-native
's primary advantage is that it uses ImageMagick's API directly rather than by executing one of its command line tools. This means that it will be much faster when the amount of time spent inside the library is small and less so otherwise. See issue #46 for discussion.
Copyright (c) Masakazu Ohtsuka http://maaash.jp/
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.