good-thumbs
v1.6.0
Published
Generate good thumbnails with using either vips, graphicsmagick, imagemagick.
Downloads
4
Maintainers
Readme
good-thumbs
Good thumbs is a thumbnail generator tool for Node.js that attempts to do a better job than previous solutions.
Get started
Install the good-thumbs
library.
$ npm install good-thumbs --save
Install either libvips or graphicsmagick
Instantiate good-thumbs
like this:
var thumbs = require('good-thumbs')({
cwd: 'images' // Root for all thumbs to look up
, cacheDir: '.cache' // Storage for generated thumbs
})
And then you are free to create a thumb like
thumbs.create('myimage.jpg', {width: 200}, function (err, thumbFilePath) {
// Process the thumbnail in thumbFilePath
})
Features
Flexible implementation
good-thumbs works with either ImageMagick, GraphicsMagick, Libvips or your own implementation which allows you to choose whatever suits you best.
var thumbs = require('good-thumbs')({
cwd: 'images'
, cacheDir: '.cache'
, system: require('good-thumbs/graphicsMagic')
// , system: require('good-thumbs/vips')
// , system: require('good-thumbs/imageMagic')
// , system: function(source, target, format, callback) { ... }
})
High-quality thumbs
Libvips has an incredible quality of antialiasing for thumbnails.
Secure lookup
good-thumbs has a cwd
property as setting to makes sure that no image request is applied outside of your working directory:
thumbs.create('../../any-image.jpg', 'small', function (err) {
// This will result in an error because any-image is
// outside of the working directory
})
Caching
Once generated it will store the cache files in the designated folder and updated them when the source file changed. To prevent excessive file access it also allows to set a checkInterval
that makes sure files are checked only once every X
milliseconds.
var thumbs = require('good-thumbs')({
cwd: 'images'
, cacheDir: '.cache'
, checkInterval: 1000 // every minute
});
(relatively) flexible formats
The formats for thumbnails are flexible in a sense that you can do this:
// will fit the width to 200 px
thumbs.create('my-image.jpg', { width: 200 })
// will fit the height to 200 px
thumbs.create('my-image.jpg', { height: 200 })
// will fit either width or height to 200px
thumbs.create('my-image.jpg', { width: 200, height: 200 })
// will fill the image into the width, height
thumbs.create('my-image.jpg', { width: 200, height: 200, fill: true })
// will make sure that it will crop from the top (default: center)
thumbs.create('my-image.jpg', { width: 200, height: 200, fill: true, gravity: require('good-thumbs/gravity/north') })
// will make sure that smaller image are not blown up
thumbs.create('my-image.jpg', { width: 200, withoutEnlargement: true })
// to get a 'png' thumbnail (with jpg input, defaults to same extension)
thumbs.create('my-image.jpg', { width: 200, type: 'png'})
Presets
You can either pass in a format as object or alternative create presets. Presets are useful if you want to make sure that only thumbnails of certain sizes are created:
var thumbs = require('good-thumbs')({
cwd: 'images'
, cacheDir: '.cache'
, presets: {
s: {width: 256}
, m: {width: 512}
, l: {width: 1024}
}
});
thumbs.createByPreset('my-image.jpg', 's', function (error, thumbFilePath) {
// ...
})
Predefined formats for your convenience
In case you need to create certain file formats there are quite a few formats already available with this library:
var thumbs = require('good-thumbs')({
cwd: 'images'
, cacheDir: '.cache'
, presets: {
s: require('good-thumbs/format/twitter/banners/mobile')
}
});
Generate all thumbs
To use this for a static site generator or to make sure that all thumbs are available at start of the application it is possible to create all possible thumbs using createAll
.
thumbs.createAll(function (err, createdThumbSet) {
for (var source in createdThumbSet) {
var sourceSet = createdThumbSet;
for (var preset in sourceSet) {
console.log("Create a '" + preset + "' for '" + source + "' at '" + sourceSet[preset] + "'");
}
}
});
You can also specify the presets that should be created:
thumbs.createAll([{width: 200}], function (err, createThumbSet) {
//...
});
Thoughts on improvement
At the current stage this is just little more than a proof-of-concept. With a little love from you I think it can be really great. Here are some thoughts of me on how to improve this baby:
- Easy integration into hapi, express, koa, sails, ...
- Optional support for png and jpg optimisation
- Watermarks
- ICC profile support (to make sure that the colors are maintained)
- Support for background-colors to make sure that transparent png's work well
- Make thumbnails that are fixed to the required size (smaller images get a background color)
- Interesting area cropping support
- Content aware streching for thumbnails
- node-canvas support
If you think you can provide any of those awesome features, please, please, please send a PR :)
Tests
This has been not much more than a proof-of-concept and a work of my idea for me, thus tests are missing - sorry for that. A PR would be nice!
License & Attribution
Copyright (c) Year 2015, Martin Heidegger <[email protected]>
Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.