spritesmith
v3.5.1
Published
Utility that takes images and creates a spritesheet with JSON sprite data
Downloads
273,080
Readme
spritesmith
Convert images into spritesheets and coordinate maps.
spritesmith
is also available as:
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 [email protected] to [email protected]. 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 assrc
forspritesmith.createImages
- All other parameters accepted by
new Spritesmith
orprocessImages
should be passed in here (e.g.engine
,algorithm
)
- src
- callback
Function
- Error-first function that receives compiled spritesheet and informationcallback
should have signaturefunction (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 ascoordinates
returned byspritesmith.processImages
- properties
Object
- Same asproperties
returned byspritesmith.processImages
- Same signature as content returned by
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-basedspritesmith
engine - An example usage of
engine
can be found in the Examples section - For more engine options, see the Engines section
- By default we use
- engineOpts
Object
- Options to pass through to engine for settings- For example
phantomjssmith
acceptstimeout
via{engineOpts: {timeout: 10000}}
- See your engine's documentation for available options
- For example
- engine
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)
- Depending on the engine, we may/may not use the contents (e.g.
- If a
- callback
Function
- Error-first function that receives compiled spritesheet and mapcallback
should have signaturefunction (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
- height
- Each
spritesheet.processImages(images, options)
Place interpretted images on a canvas and export spritesheet
- images
Object[]
- Images generated viaspritesmith.createImages
- options
Object
- Container for options- padding
Number
- Padding to use between images- For example if
2
is provided, then there will be a2px
gap to the right and bottom between each image - An example usage of
padding
can be found in the Examples section
- For example if
- exportOpts
Mixed
- Options to pass through to engine for export- For example
gmsmith
supportsquality
via{exportOpts: {quality: 75}}
- See your engine's documentation for available options
- For example
- 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
- By default we use
- 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
- For example
- padding
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 spritesheetfilepath
will be the same as provided inparams.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
- For those keeping track, this is
- properties
Object
- Container for information about spritesheet- width
Number
- Width of the spritesheet - height
Number
- Height of the spritesheet
- width
- image
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-down
| left-right
| diagonal
| alt-diagonal
| binary-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:
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:
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:
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.