$ npm install 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
},
// ...
}
spritesmith
?Support us via donations or spread word on Twitter
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.
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) { /* ... */ });
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}
});
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}
});
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
Object
- Container for parameters
String[]|Object[]
- Same as src
for spritesmith.createImages
new Spritesmith
or processImages
should be passed in here (e.g. engine
, algorithm
)Function
- Error-first function that receives compiled spritesheet and information
callback
should have signature function (err, result)
Error|null
- If an error occurred, this will be itObject
- Container for result items
spritesmith.processImages
(i.e. {image, coordinates, properties}
)Buffer
- In-memory representation of imageObject
- Same as coordinates
returned by spritesmith.processImages
Object
- Same as properties
returned by spritesmith.processImages
new Spritesmith(params)
Constructor for a new Spritesmith
instance
Object
- Container for parameters
String|Object
- Optional engine override to use
pixelsmith
, a node-based spritesmith
engineengine
can be found in the Examples sectionObject
- Options to pass through to engine for settings
phantomjssmith
accepts timeout
via {engineOpts: {timeout: 10000}}
spritesmith.createImages(src, callback)
Interpret images via the spritesmith
engine
String[]|Object[]
- Array of filepaths for images to include in spritesheet
String
is provided, then it's used as the image's filepathObject
is provided, then it should be a Vinyl object pointing to the source image
gmsmith
uses filepaths only)Function
- Error-first function that receives compiled spritesheet and map
callback
should have signature function (err, images)
Error|null
- If an error occurred, this will be itObject[]
- Array of processed images
image
will be a proprietary object for the engineimage
will line up with the specification from spritesmith-engine-specObject
- Metadata container about corresponding input image at same index
Number
- Height in pixels of corresponding input image at same indexNumber
- Width in pixels of corresponding input image at same indexspritesheet.processImages(images, options)
Place interpretted images on a canvas and export spritesheet
Object[]
- Images generated via spritesmith.createImages
Object
- Container for options
Number
- Padding to use between images
2
is provided, then there will be a 2px
gap to the right and bottom between each imagepadding
can be found in the Examples sectionMixed
- Options to pass through to engine for export
gmsmith
supports quality
via {exportOpts: {quality: 75}}
String
- Optional algorithm to pack images with
binary-tree
which packs images as efficiently as possiblealgorithm
can be found in the Examples sectionObject
- Optional algorithm options to pass through to algorithm for layout
top-down
supports ignoring sorting via {algorithmOpts: {sort: false}}
Returns:
Object
- Container for result information
ReadableStream
- Readable stream outputting generated image contentsObject
- Map from filepath to coordinate information between original sprite and spritesheet
filepath
will be the same as provided in params.src
Object
- Container for coordinate information
result.coordinates[filepath]
Number
- Horizontal position of top-left corner of original sprite on spritesheetNumber
- Vertical position of top-left corner of original sprite on spritesheetNumber
- Width of original spriteNumber
- Height of original spriteObject
- Container for information about spritesheet
Number
- Width of the spritesheetNumber
- Height of the spritesheetImages 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
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
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
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
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
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.
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:
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:
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:
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
.
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.
Copyright (c) 2012 Todd Wolfson
Licensed under the MIT license.
© 2010 - cnpmjs.org x YWFE | Home | YWFE