spritesmith

spritesmith converts a collection of images into a single spritesheet and a coordinate map.

• Spritesheet: A single image containing all input images.
• Coordinate Map: A JSON object mapping each input filename to its position and dimensions within the spritesheet:

{
  "/path/to/image.png": {
    "x": 0,
    "y": 0,
    "width": 32,
    "height": 32
  }
}

You can control how images are packed using the algorithm option. Spritesmith uses the layout library to provide several packing strategies:

• binary-tree: (Default) Packs images as efficiently as possible.
• top-down: Packs images in a top-down fashion.
• left-right: Packs images from left to right.
• diagonal: Packs images diagonally.
• alt-diagonal: An alternative diagonal packing.

Use algorithmOpts to pass specific settings to these algorithms (e.g., disabling sorting in top-down).

In version 3.0.0, the API was updated to support streaming outputs. This involved moving to a class-based constructor and separating the image creation phase from the processing phase.

To maintain compatibility with older codebases, Spritesmith.run was introduced as a static method that provides the same behavior as the pre-3.0.0 function.

Engines determine how images are interpreted and exported. You can specify an engine via params.engine and its settings via params.engineOpts.

You can install spritesmith using npm to convert multiple images into a single spritesheet and a coordinate map.

npm install spritesmith

You can specify a custom layout algorithm by passing the algorithm key in the options object to Spritesmith.run(). This allows you to control how images are arranged within the spritesheet (e.g., using 'alt-diagonal').

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 (err) {
    throw err;
  }

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

The gmsmith engine uses either Graphics Magick or Image Magick. You can explicitly force the use of Image Magick via engineOpts:

{
  engineOpts: {
    imagemagick: true
  }
}

Spritesmith allows you to swap the underlying engine used for image processing. To use a custom engine, install the engine package (e.g., canvassmith) and pass the required module to the engine key in the Spritesmith.run() options object.

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

// In our script
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 (err) {
    throw err;
  }

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

To prevent images from touching in the generated spritesheet, use the padding option in Spritesmith.run(). This value specifies the number of pixels of space to add between each image.

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
}, function handleResult (err, result) {
  if (err) {
    throw err;
  }

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

You can manually manage the spritesmith lifecycle by using the Spritesmith constructor.

Parameters (params):

• engine: (Optional) A String or Object to override the default engine (pixelsmith).
• engineOpts: (Optional) An Object containing options to pass through to the chosen engine (e.g., { engineOpts: { timeout: 10000 } } for phantomjssmith).

const Spritesmith = require('spritesmith');
const spritesmith = new Spritesmith({
  engine: 'canvassmith',
  engineOpts: { /* engine specific options */ }
});

The spritesmith.createImages(src, callback) method interprets source images via the configured engine without yet placing them on a canvas.

Parameters:

• src: An array of filepaths (String[]) or Vinyl objects (Object[]).
• callback: An error-first function function (err, images).
  • err: Error|null.
  • images: An array of processed image objects. Each object contains metadata about the input image: height and width.