spritesmith

Convert images into spritesheets and coordinate maps.

spritesmith is also available as:

• grunt plugin
• gulp plugin
• CLI utility

A folder of icons processed by spritesmith:

generates a 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

• params Object - Container for parameters
  • src String[]|Object[] - Same as src for spritesmith.createImages
  • All other parameters accepted by new Spritesmith or processImages should be passed in here (e.g. engine, algorithm)
• callback Function - Error-first function that receives compiled spritesheet and information
  • callback should have signature function (err, result)
  • err Error|null - If an error occurred, this will be it
  • result Object - Container for result items
    • Same signature as content returned by spritesmith.processImages (i.e. {image, coordinates, properties})
    • image Buffer - In-memory representation of image
    • coordinates Object - Same as coordinates returned by spritesmith.processImages
    • properties Object - Same as properties returned by spritesmith.processImages

new Spritesmith(params)

Constructor for a new Spritesmith instance

• params Object - Container for parameters
  • engine String|Object - Optional engine override to use
    • By default we use pixelsmith, a node-based spritesmith engine
    • An example usage of engine can be found in the Examples section
    • For more engine options, see the Engines section
  • engineOpts Object - Options to pass through to engine for settings
    • For example phantomjssmith accepts timeout via {engineOpts: {timeout: 10000}}
    • See your engine's documentation for available options

spritesmith.createImages(src, callback)

Interpret images via the spritesmith engine

• src String[]|Object[] - Array of filepaths for images to include in spritesheet
  • If a String is provided, then it's used as the image's filepath
  • If an Object is provided, then it should be a Vinyl object pointing to the source image
    • Depending on the engine, we may/may not use the contents (e.g. gmsmith uses filepaths only)
• callback Function - Error-first function that receives compiled spritesheet and map
  • callback should have signature function (err, images)
  • err Error|null - If an error occurred, this will be it
  • images Object[] - Array of processed images
    • Each image will be a proprietary object for the engine
    • Each image will line up with the specification from spritesmith-engine-spec
    • image Object - Metadata container about corresponding input image at same index
      • height Number - Height in pixels of corresponding input image at same index
      • width Number - Width in pixels of corresponding input image at same index

spritesheet.processImages(images, options)

Place interpretted images on a canvas and export spritesheet

• images Object[] - Images generated via spritesmith.createImages
• options Object - Container for options
  • padding Number - Padding to use between images
    • For example if 2 is provided, then there will be a 2px gap to the right and bottom between each image
    • An example usage of padding can be found in the Examples section
  • exportOpts Mixed - Options to pass through to engine for export
    • For example gmsmith supports quality via {exportOpts: {quality: 75}}
    • See your engine's documentation for available options
  • algorithm String - Optional algorithm to pack images with
    • By default we use binary-tree which packs images as efficiently as possible
    • An example usage of algorithm can be found in the Examples section
    • For more algorithm options, see the Algorithms section
  • algorithmOpts Object - Optional algorithm options to pass through to algorithm for layout
    • For example top-down supports ignoring sorting via {algorithmOpts: {sort: false}}
    • See your algorithm's documentation for available options
      • https://github.com/twolfson/layout#algorithms

Returns:

• result Object - Container for result information
  • image ReadableStream - Readable stream outputting generated image contents
  • coordinates Object - Map from filepath to coordinate information between original sprite and spritesheet
    • filepath will be the same as provided in params.src
    • [filepath] Object - Container for coordinate information
      • For those keeping track, this is result.coordinates[filepath]
      • x Number - Horizontal position of top-left corner of original sprite on spritesheet
      • y Number - Vertical position of top-left corner of original sprite on spritesheet
      • width Number - Width of original sprite
      • height Number - Height of original sprite
  • properties Object - Container for information about spritesheet
    • width Number - Width of the spritesheet
    • height Number - Height of the spritesheet