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

ISC

Copyright (c) Year 2015, Martin Heidegger <[e-mail]>
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.