Home

Awesome

spritesmith Build status Subscribe to newsletter

Convert images into spritesheets and coordinate maps.

spritesmith is also available as:

A folder of icons processed by spritesmith:

Fork icon + GitHub icon + Twitter icon =

generates a spritesheet:

spritesheet

and a coordinate map:

{
  "/home/todd/github/spritesmith/docs/fork.png": {
    "x": 0,
    "y": 0,
    "width": 32,
    "height": 32
  },
  "/home/todd/github/spritesmith/docs/github.png": {
    "x": 32,
    "y": 0,
    "width": 32,
    "height": 32
  },
  // ...
}

Do you like spritesmith?

Support us via donations or spread word on Twitter

Breaking changes in 2.0.0

We have moved from result.image being a binary string to it being a Buffer. This is to use more canonical conventions in Node.js.

We have moved from spritesmith-engine-spec@1.1.0 to spritesmith-engine-spec@2.0.0. This means if you use an custom engine (e.g. gmsmith, canvassmith), then you will need to upgrade it.

npm install my-engine-smith@latest --save-dev

By upgrading the engine, we added support for Vinyl objects via src as well as future-proof ourselves for forwarding streaming outputs.

Breaking changes in 3.0.0

We have updated our API to return streams for images. This required moving to a constructor and splitting apart image creation and processing.

We have maintained legacy support for spritesmith via Spritesmith.run which has an identical API to the spritesmith function in spritesmith<3.0.0.

// Before
var spritesmith = require('spritesmith');
spritesmith({src: sprites}, function handleResult (err, result) { /* ... */ });

// After
var Spritesmith = require('spritesmith');
Spritesmith.run({src: sprites}, function handleResult (err, result) { /* ... */ });

Getting started

spritesmith can be installed via npm: npm install spritesmith

// Load in dependencies
var Spritesmith = require('spritesmith');

// Generate our spritesheet
var sprites = ['fork.png', 'github.png', 'twitter.png'];
Spritesmith.run({src: sprites}, function handleResult (err, result) {
  result.image; // Buffer representation of image
  result.coordinates; // Object mapping filename to {x, y, width, height} of image
  result.properties; // Object with metadata about spritesheet {width, height}
});

Usage with streaming output

We support streaming output by breaking down run into 2 parts:

// Load in dependencies
var Spritesmith = require('spritesmith');

// Create a new spritesmith and process our images
var sprites = ['fork.png', 'github.png', 'twitter.png'];
var spritesmith = new Spritesmith();
spritesmith.createImages(sprites, function handleImages (err, images) {
  images[0].width; // Width of image
  images[0].height; // Height of image

  // Create our result
  var result = spritesmith.processImages(images);
  result.image; // Readable stream outputting image
  result.coordinates; // Object mapping filename to {x, y, width, height} of image
  result.properties; // Object with metadata about spritesheet {width, height}
});

Documentation

spritesmith exports a Spritesmith constructor as its module.exports.

If you would like a faster build time or need to support an obscure image format, see params.engine.

If you would like to adjust how images are laid out, see params.algorithm and params.algorithmOpts.

Spritesmith.run(params, callback)

Helper function that initializes a new Spritesmith instance, creates images, and processes them into a spritesheet

new Spritesmith(params)

Constructor for a new Spritesmith instance

spritesmith.createImages(src, callback)

Interpret images via the spritesmith engine

spritesheet.processImages(images, options)

Place interpretted images on a canvas and export spritesheet

Returns:

Algorithms

Images can be laid out in different fashions depending on the algorithm. We use layout to provide you as many options as possible. At the time of writing, here are your options for params.algorithm:

top-downleft-rightdiagonalalt-diagonalbinary-tree
top-downleft-rightdiagonalalt-diagonalbinary-tree

More information can be found in the layout documentation:

https://github.com/twolfson/layout

Engines

An engine can greatly improve the speed of your build (e.g. canvassmith) or support obscure image formats (e.g. gmsmith).

All spritesmith engines adhere to a common specification:

https://github.com/twolfson/spritesmith-engine-spec

This repository adheres to specification version: 2.0.0

Below is a list of known engines with their tradeoffs:

pixelsmith

pixelsmith is a node based engine that runs on top of get-pixels and save-pixels.

Key differences: Doesn't support uncommon image formats (e.g. tiff) and not as fast as a compiled library (e.g. canvassmith).

phantomjssmith

phantomjssmith is a phantomjs based engine. It was originally built to provide cross-platform compatibility but has since been succeeded by pixelsmith.

Requirements: phantomjs must be installed on your machine and on your PATH environment variable. Visit the phantomjs website for installation instructions.

Key differences: phantomjs is cross-platform and supports all image formats.

canvassmith

canvassmith is a node-canvas based engine that runs on top of Cairo.

Requirements: Cairo and [node-gyp][] must be installed on your machine.

Instructions on how to install Cairo are provided in the [node-canvas wiki][].

[node-gyp][] should be installed via npm:

npm install -g node-gyp

Key differences: canvas has the best performance (useful for over 100 sprites). However, it is UNIX only.

[node-canvas wiki]: (https://github.com/LearnBoost/node-canvas/wiki/_pages [node-gyp]: https://github.com/TooTallNate/node-gyp/

gmsmith

gmsmith is a gm based engine that runs on top of either Graphics Magick or Image Magick.

Requirements: Either Graphics Magick or Image Magick must be installed on your machine.

For the best results, install from the site rather than through a package manager (e.g. apt-get). This avoids potential transparency issues which have been reported.

Image Magick is implicitly discovered. However, you can explicitly use it via engineOpts

{
  engineOpts: {
    imagemagick: true
  }
}

Key differences: gmsmith allows for configuring image quality whereas others do not.

Examples

Algorithm

This is an example of using a custom layout via the alt-diagonal algorithm.

// Load in dependencies
var fs = require('fs');
var Spritesmith = require('spritesmith');

// Generate our spritesheet
Spritesmith.run({
  src: [
    __dirname + '/fork.png',
    __dirname + '/github.png',
    __dirname + '/twitter.png'
  ],
  algorithm: 'alt-diagonal'
}, function handleResult (err, result) {
  // If there was an error, throw it
  if (err) {
    throw err;
  }

  // Output the image
  fs.writeFileSync(__dirname + '/alt-diagonal.png', result.image);
  result.coordinates, result.properties; // Coordinates and properties
});

Result:

alt-diagonal spritesheet

Engine

This is an example of using a custom engine (canvassmith in this case).

// Inside package.json
{
    "dependencies": {
        "canvassmith": "~0.2.4"
    }
}

// In our script
// Load in dependencies
var fs = require('fs');
var Spritesmith = require('spritesmith');

// Generate our spritesheet
Spritesmith.run({
  src: [
    __dirname + '/fork.png',
    __dirname + '/github.png',
    __dirname + '/twitter.png'
  ],
  engine: require('canvassmith')
}, function handleResult (err, result) {
  // If there was an error, throw it
  if (err) {
    throw err;
  }

  // Output the image
  fs.writeFileSync(__dirname + '/canvassmith.png', result.image);
  result.coordinates, result.properties; // Coordinates and properties
});

Result:

canvassmith spritesheet

Padding

This is an example of adding padding between images.

// Load in dependencies
var fs = require('fs');
var Spritesmith = require('spritesmith');

// Generate our spritesheet
Spritesmith.run({
  src: [
    __dirname + '/fork.png',
    __dirname + '/github.png',
    __dirname + '/twitter.png'
  ],
  padding: 20 // Exaggerated for visibility, normally 1 or 2
}, function handleResult (err, result) {
  // If there was an error, throw it
  if (err) {
    throw err;
  }

  // Output the image
  fs.writeFileSync(__dirname + '/padding.png', result.image);
  result.coordinates, result.properties; // Coordinates and properties
});

Result:

padding spritesheet

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint via npm run lint and test via npm test.

Attribution

GitHub and Twitter icons were taken from Alex Peattie's JustVector Social Icons.

Fork designed by P.J. Onori from The Noun Project

Plus and Equals icons were built using the Ubuntu Light typeface.

License

Copyright (c) 2012 Todd Wolfson

Licensed under the MIT license.