Utility that takes image files and generates spritesheets and coordinate maps.
Once you have satisfied the requirements, spritesmith can be installed via npm install spritesmith
.
Spritesmith is also available as a grunt plugin, gulp plugin, and CLI utility.
var sprites = ['sprite1.png', 'sprite2.jpg', 'sprite3.png'];
spritesmith({'src': sprites}, function (err, result) {
result.image; // Binary string representation of image
result.coordinates; // Object mapping filename to {x, y, width, height} of image
result.properties; // Object with metadata about spritesheet {width, height}
});
Installation
spritesmith
can be installed via npm: npm install spritesmith
Each engine has system level depedencies. Visit the requirements section for more information.
You'll also need to install the engine for the image processing library you choose, for example:
npm install --save gmsmith
Documentation
Spritesmith is a standalone function
/**
* Spritesmith generation function
* @param {Object} params Parameters for spritesmith
* @param {String[]} [params.src] Images to generate into sprite sheet
* @param {String} [params.engine="auto"] Engine to use
(phantomjs, canvas, gm, pngsmith or user-defined via Spritesmith.addEngine)
* @param {String} [params.algorithm="top-down"] Algorithm to pack images with
* @param {Number} [params.padding] Padding to use between images
* @param {Mixed} [params.engineOpts] Options to pass through to engine for settings
* @param {Mixed} [params.algorithmOpts] Options to pass through to algorithm for layout
* @param {Mixed} [params.exportOpts] Options to pass through to engine for export
* @param {Function} callback Function that receives compiled spritesheet and map
* @returns {Mixed} callback[0] err If an error was encountered, this will be returned to callback
* @returns {Object} callback[1] result Result object of spritesmith
* @returns {String} callback[1].image Binary string representation of image
* @returns {Object} callback[1].coordinates Map from file name to an object containing x, y, height, and width information about the source image
* @returns {Object} callback[1].properties Properties about the spritesheet itself
* @returns {Object} callback[1].properties.width Width of the spritesheet
* @returns {Object} callback[1].properties.height Height of the spritesheet
*/
PhantomJS export options
For the phantomjs
engine, the current output options are:
{
'timeout': 10000 // Milliseconds to wait until terminating PhantomJS script
}
Canvas export options
For the canvas
engine, the current output options are:
{
'format': 'png' // Format to export the canvas to (png or jpeg)
}
gm export options
For the gm
engine, the current output options are:
{
'format': 'png', // Format to export the canvas to (png or jpeg)
'quality': 75 // Quality of the output image
}
Available packing algorithms
The available packing algorithms are: top-down
, left-right
, diagonal
(\ format), alt-diagonal
(/ format), binary-tree
(best packing possible).
algorithmOpts
All algorithms provide the current options:
{
'sort': false // Stops sorting of images (default for all algorithms)
}
Adding new engines
Engine specifications can be found in spritesmith-engine-test.
New engines can be added via Spritesmith.addEngine(name, engine);
.
Some existing engines are:
Adding new packing algorithms
Algorithms are maintained inside of twolfson/layout. Example algorithms can be found in twolfson/layout/lib/algorithms.
New algorithms can be added via Spritesmith.Layout.addAlgorithm(name, algorithm);
.
Requirements
For cross-platform accessibility, spritesmith
has and supports multiple sprite engines. However, each of these current engines has a different set of external dependencies.
pngsmith
The pngsmith
engine uses pngparse
, an JavaScript png
parser, to interpret images into ndarrays
. This requires no additional steps before installation.
Key differences: It requires no additional installation steps but you are limited to .png
files for your source files.
phantomjs
The phantomjs
engine relies on having phantomjs installed on your machine. Visit the phantomjs website for installation instructions.
Key differences: phantomjs
is the easiest engine to install that supports all image formats.
spritesmith
has been tested against phantomjs@1.9.0
.
canvas
The canvas
engine uses node-canvas which has a dependency on Cairo.
Key differences: canvas
has the best performance (useful for over 100 sprites). However, it is UNIX
only.
Instructions on how to install Cairo are provided in the node-canvas wiki.
Additionally, you will need to install node-gyp for the C++ bindings.
sudo npm install -g node-gyp
gm (Graphics Magick / Image Magick)
The gm
engine depends on Graphics Magick or Image Magick.
Key differences: gm
has the most options for export via imgOpts
.
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.
spritesmith
has been developed and tested against 1.3.17
.
Image Magick is implicitly discovered. However, you can explicitly use it via engineOpts
{
'engineOpts': {
'imagemagick': true
}
}
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 grunt and test via npm test
.
Donating
Support this project and others by twolfson via gittip.
License
Copyright (c) 2012 - 2013 Ensighten
Licensed under the MIT license.