gulp-gm
Version:
Image manipulation with GraphicsMagick for gulp.
171 lines (109 loc) • 3.68 kB
Markdown
# [gulp](https://github.com/gulpjs/gulp)-gm [](https://travis-ci.org/scalableminds/gulp-gm)
> Image manipulation with [gm](https://github.com/aheckmann/gm). Refer to [gm's documentation](http://aheckmann.github.io/gm/docs.html) for details.
# Install
Install with [npm](https://npmjs.org/package/gulp-gm)
```
npm install --save-dev gulp-gm
```
### GraphicsMagick or ImageMagick
`gulp-gm` works best with GraphicsMagick.
However, it also supports ImageMagick, but you'll need to set the option `imageMagick: true`.
Make sure GraphicsMagick or ImageMagick is installed on your system and properly set up in your `PATH`.
Ubuntu:
```shell
apt-get install imagemagick
apt-get install graphicsmagick
```
Mac OS X (using [Homebrew](http://brew.sh/)):
```shell
brew install imagemagick
brew install graphicsmagick
```
Windows & others:
- GraphicsMagick: [http://www.graphicsmagick.org/download.html](http://www.graphicsmagick.org/download.html)
- ImageMagick: [http://www.imagemagick.org/script/binary-releases.php](http://www.imagemagick.org/script/binary-releases.php)
Confirm that GraphicsMagick or ImageMagick is properly set up by executing `gm -version` or `convert -version` in a terminal.
## Example
```js
var gulp = require('gulp');
var gm = require('gulp-gm');
gulp.task('default', function () {
gulp.src('test.png')
.pipe(gm(function (gmfile) {
return gmfile.resize(100, 100);
}))
.pipe(gulp.dest('dist'));
});
```
### Convert png to jpg
```js
gulp.src('test.png')
.pipe(gm(function (gmfile) {
return gmfile.setFormat('jpg');
}))
.pipe(gulp.dest('dist'));
```
### Async manipulation
```js
gulp.src('test.png')
.pipe(gm(function (gmfile, done) {
gmfile.size(function (err, size) {
done(null, gmfile
.stroke("blue", 6)
.fill("transparent")
.drawRectangle(0, 0, size.width, size.height));
});
}))
.pipe(gulp.dest('dist'));
```
### Using ImageMagick
```js
gulp.src('test.png')
.pipe(gm(function (gmfile) {
return gmfile.resize(100, 100);
}, {
imageMagick: true
}))
.pipe(gulp.dest('dist'));
```
## API
### gm(modifier, options)
#### modifier(gmfile, [done])
Type: `Function`
Supply a callback that manipulates the image. The first argument will the `gm` object with all original properties. [Read more in the gm documentation](http://aheckmann.github.io/gm/docs.html).
##### Sync
Make sure to return your modified `gm` object.
```js
gulp.src('test.png')
.pipe(gm(function (gmfile) {
return gmfile.blur(10);
}))
.pipe(gulp.dest('dist'));
```
##### Async
If your call back accepts a second argument (`done`), it will be treated asynchronously. Your code will then need to call `done(err, gmfile)` at some point.
```js
gulp.src('test.png')
.pipe(gm(function (gmfile, done) {
gmfile.size(function (err, size) {
done(null, gmfile.resize(
size.width * 0.5,
size.height * 0.5
));
});
}))
.pipe(gulp.dest('dist'));
```
#### options.imageMagick
Type: `Boolean`
Default value: `false`
Set to `true` when using ImageMagick instead of GraphicsMagick.
## Known Issues
* `gm.thumb(...)` is not supported because it writes to the file system directly. Consider using [gulp-image-resize](https://github.com/scalableminds/gulp-image-resize) instead.
## Tests
1. You need both ImageMagick and GraphicsMagick installed on your system to run the tests.
2. Install all npm dev dependencies `npm install`
3. Install gulp globally `npm install -g gulp`
4. Run `gulp test`
## License
MIT © [scalable minds](http://scm.io)