### Install node-gyp

Source: https://github.com/twolfson/spritesmith/blob/master/README.md

Install node-gyp globally using npm. This is a requirement for the canvassmith engine.

```bash
npm install -g node-gyp
```

--------------------------------

### Spritesmith Streaming Output Usage

Source: https://github.com/twolfson/spritesmith/blob/master/README.md

This example shows how to use spritesmith with streaming output. It involves creating a `Spritesmith` instance, processing images to get individual image streams, and then processing those streams to generate the final spritesheet stream and coordinate map.

```js
// 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}
});
```

--------------------------------

### Use canvassmith Engine with Spritesmith

Source: https://context7.com/twolfson/spritesmith/llms.txt

Install canvassmith and pass its constructor to the engine option. This engine is fastest for large sprite sets.

```javascript
// npm install canvassmith --save-dev
var fs = require('fs');
var Spritesmith = require('spritesmith');
var canvassmith = require('canvassmith');

Spritesmith.run({
  src: ['/icons/a.png', '/icons/b.png'],
  engine: canvassmith             // pass the constructor directly
}, function (err, result) {
  if (err) { throw err; }
  fs.writeFileSync('/out/canvas-spritesheet.png', result.image);
});
```

--------------------------------

### Install Custom Engine with npm

Source: https://github.com/twolfson/spritesmith/blob/master/README.md

When upgrading to spritesmith v2.0.0 or later, custom engines may need to be reinstalled to ensure compatibility with the new spritesmith-engine-spec. Use npm to install the latest version of your engine.

```bash
npm install my-engine-smith@latest --save-dev
```

--------------------------------

### Use gmsmith Engine with Spritesmith

Source: https://context7.com/twolfson/spritesmith/llms.txt

Install gmsmith and pass its name to the engine option. This engine supports most image formats and requires GraphicsMagick or ImageMagick to be installed on the system's PATH. engineOpts can be used to specify ImageMagick.

```javascript
// npm install gmsmith --save-dev
// Requires GraphicsMagick or ImageMagick installed on PATH
Spritesmith.run({
  src: ['/icons/a.png', '/icons/b.png'],
  engine: 'gmsmith',
  engineOpts: { imagemagick: true },   // explicitly use ImageMagick binary
  exportOpts: { quality: 85 }          // gmsmith supports quality for JPEG
}, function (err, result) {
  if (err) { throw err; }
  fs.writeFileSync('/out/gm-spritesheet.png', result.image);
});
```

--------------------------------

### Generate Spritesheet with Canvassmith Engine

Source: https://github.com/twolfson/spritesmith/blob/master/README.md

Generate a spritesheet using the 'canvassmith' engine. Ensure 'canvassmith' is installed as a dependency. Requires loading dependencies like fs and Spritesmith, and specifying source image paths.

```js
// 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
});
```

--------------------------------

### Process Images into a Stream

Source: https://context7.com/twolfson/spritesmith/llms.txt

Use `processImages` to pack sprites and get a ReadableStream for the generated image. This is ideal for piping output directly to a file. Ensure images are created first using `createImages`.

```javascript
var fs = require('fs');
var Spritesmith = require('spritesmith');

var sprites = ['/icons/a.png', '/icons/b.png', '/icons/c.png'];
var smith = new Spritesmith();

smith.createImages(sprites, function handleImages(err, images) {
  if (err) { throw err; }

  var result = smith.processImages(images, {
    algorithm: 'binary-tree',   // default; most space-efficient
    padding: 4,                 // 4px gap between each sprite
    exportOpts: {}
  });

  // result.image is a Readable stream — pipe it to a file
  result.image.pipe(fs.createWriteStream('/output/sprite.png'));

  result.image.on('error', function (err) {
    console.error('Image generation error:', err);
  });

  result.image.on('end', function () {
    console.log('Spritesheet written.');
    console.log('Coordinates:', result.coordinates);
    // { '/icons/a.png': { x: 0, y: 0, width: 16, height: 16 }, ... }
    console.log('Properties:', result.properties);
    // { width: 48, height: 16 }
  });
});
```

--------------------------------

### Spritesmith.run() with Layout Algorithms

Source: https://context7.com/twolfson/spritesmith/llms.txt

Demonstrates how to use different layout algorithms with Spritesmith.run to control sprite packing.

```APIDOC
## Layout algorithms — Controlling sprite packing

Spritesmith delegates layout to the [`layout`](https://github.com/twolfson/layout) package, offering five algorithms. Pass the algorithm name as `algorithm` in `Spritesmith.run` or `processImages`. Use `algorithmOpts` to pass algorithm-specific settings (e.g., disabling sort).

### Algorithms

- **binary-tree** (default): Most compact packing.
- **left-right**: Sprites arranged in a single horizontal row.
- **top-down**: Sprites arranged in a single vertical column.
- **diagonal**: Sprites placed along the diagonal.
- **alt-diagonal**: Alternate diagonal placement.

### Example Usage with `Spritesmith.run`

```js
var Spritesmith = require('spritesmith');
var fs = require('fs');

var sprites = ['a.png', 'b.png', 'c.png', 'd.png'].map(function (f) {
  return '/icons/' + f;
});

// binary-tree (default)
Spritesmith.run({ src: sprites, algorithm: 'binary-tree' }, function (err, result) {
  fs.writeFileSync('/out/binary-tree.png', result.image);
});

// left-right
Spritesmith.run({ src: sprites, algorithm: 'left-right' }, function (err, result) {
  fs.writeFileSync('/out/left-right.png', result.image);
});

// top-down with sort disabled
Spritesmith.run({
  src: sprites,
  algorithm: 'top-down',
  algorithmOpts: { sort: false }   // preserves original array order
}, function (err, result) {
  fs.writeFileSync('/out/top-down-unsorted.png', result.image);
});

// diagonal
Spritesmith.run({ src: sprites, algorithm: 'diagonal' }, function (err, result) {
  fs.writeFileSync('/out/diagonal.png', result.image);
});

// alt-diagonal
Spritesmith.run({ src: sprites, algorithm: 'alt-diagonal' }, function (err, result) {
  fs.writeFileSync('/out/alt-diagonal.png', result.image);
});
```
```

--------------------------------

### Spritesmith.run(params, callback)

Source: https://context7.com/twolfson/spritesmith/llms.txt

The static helper method `Spritesmith.run` is the simplest way to use the library. It instantiates a `Spritesmith` instance, creates engine image objects from the source files, lays them out, and returns the final spritesheet as a `Buffer` along with coordinate and property metadata via an error-first callback.

```APIDOC
## Spritesmith.run(params, callback)

### Description
Generates a spritesheet in one call by processing source images, laying them out, and returning the final spritesheet as a Buffer along with coordinate and property metadata.

### Method
`static`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **params** (object) - Required - An object containing parameters for the run.
  - **src** (array) - Required - An array of image file paths or Vinyl file objects.

### Callback
- **callback** (function) - An error-first callback function.
  - **err** (Error) - An error object if an error occurred, otherwise null.
  - **result** (object) - An object containing the spritesheet data.
    - **image** (Buffer) - The combined spritesheet image data.
    - **coordinates** (object) - A map where keys are source filepaths and values are objects containing `x`, `y`, `width`, and `height` of each sprite.
    - **properties** (object) - An object containing the overall `width` and `height` of the spritesheet.

### Request Example
```js
var fs = require('fs');
var Spritesmith = require('spritesmith');

var sprites = [
  '/path/to/icons/home.png',
  '/path/to/icons/user.png',
  '/path/to/icons/settings.png'
];

Spritesmith.run({ src: sprites }, function handleResult(err, result) {
  if (err) {
    throw err;
  }

  fs.writeFileSync('/path/to/output/spritesheet.png', result.image);
  console.log(result.coordinates);
  console.log(result.properties);
});
```

### Response
#### Success Response (Callback)
- **result.image** (Buffer) - The generated spritesheet image.
- **result.coordinates** (object) - Mapping of source filepaths to sprite coordinates and dimensions.
- **result.properties** (object) - Object containing the total width and height of the spritesheet.
```

--------------------------------

### new Spritesmith(params)

Source: https://context7.com/twolfson/spritesmith/llms.txt

Creates a new `Spritesmith` instance with an optional custom engine and engine options. The default engine is `pixelsmith`. Pass the engine as a string (npm package name) or as a pre-required constructor. Engine options are forwarded to the engine's constructor.

```APIDOC
## new Spritesmith(params)

### Description
Constructor for creating a new `Spritesmith` instance. Allows for configuration of the image processing engine and its options.

### Method
`constructor`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **params** (object) - Optional - Configuration options for the Spritesmith instance.
  - **engine** (string|function) - Optional - The engine to use. Can be an npm package name (string) or a pre-required constructor function. Defaults to 'pixelsmith'.
  - **engineOpts** (object) - Optional - Options to be passed to the engine's constructor.

### Request Example
```js
var Spritesmith = require('spritesmith');

// Using default pixelsmith engine
var smith = new Spritesmith();

// Using canvassmith engine
var smithCanvas = new Spritesmith({ engine: require('canvassmith') });

// Using gmsmith with explicit ImageMagick preference
var smithGM = new Spritesmith({
  engine: 'gmsmith',
  engineOpts: { imagemagick: true }
});

// Using phantomjssmith with a custom timeout
var smithPhantom = new Spritesmith({
  engine: 'phantomjssmith',
  engineOpts: { timeout: 10000 }
});
```

### Response
- **instance** (Spritesmith) - A new Spritesmith instance configured with the provided parameters.
```

--------------------------------

### Spritesmith Constructor and Streaming Output

Source: https://github.com/twolfson/spritesmith/blob/master/README.md

This section details the modern, streaming API for spritesmith. It involves creating a `Spritesmith` instance, processing images into a streamable format, and then processing those images to generate the spritesheet.

```APIDOC
## Spritesmith Constructor and Streaming Output

### Description
Provides a streaming API for generating spritesheets, allowing for more flexibility and better handling of large image sets. This involves instantiating `Spritesmith`, creating image objects, and then processing them.

### Method
1. **Constructor**: `new Spritesmith(options)`
2. **createImages**: `spritesmith.createImages(src, callback)`
3. **processImages**: `spritesmith.processImages(images, callback)`

### Parameters
#### Constructor Options (`options`)
- **engine** (string) - Optional - The spritesmith engine to use.
- **algorithm** (string) - Optional - The algorithm to use for image layout.
- **algorithmOpts** (object) - Optional - Options for the chosen layout algorithm.

#### `createImages` Parameters
- **src** (Array<string> | Array<object>) - Required - An array of image file paths or image data. If objects are provided, they should conform to the Vinyl file specification.
- **callback** (function) - Required - A callback function that receives an error and an array of image objects.
  - **err** (Error) - An error object if an error occurred.
  - **images** (Array<object>) - An array of image objects, each containing image properties like `width` and `height`.

#### `processImages` Parameters
- **images** (Array<object>) - Required - An array of image objects, typically generated by `createImages`.
- **callback** (function) - Required - A callback function that receives an error and the processed result.
  - **err** (Error) - An error object if an error occurred.
  - **result** (object) - An object containing the spritesheet information:
    - **image** (ReadableStream) - A readable stream of the spritesheet image data.
    - **coordinates** (object) - Mapping of image filenames to their position and dimensions.
    - **properties** (object) - Metadata about the spritesheet (width, height).

### Request Example
```js
// Load in dependencies
var Spritesmith = require('spritesmith');

// Create a new spritesmith instance
var spritesmith = new Spritesmith();

// Define source images
var sprites = ['fork.png', 'github.png', 'twitter.png'];

// Create image objects from source
spritesmith.createImages(sprites, function handleImages (err, images) {
  if (err) {
    console.error(err);
    return;
  }

  // Process the images to create the spritesheet
  var result = spritesmith.processImages(images);
  result.image.pipe(require('fs').createWriteStream('spritesheet.png')); // Example: pipe to a file
  console.log(result.coordinates); // Object mapping filename to {x, y, width, height} of image
  console.log(result.properties); // Object with metadata about spritesheet {width, height}
});
```

### Response
#### Success Response (Callback with result)
- **result.image** (ReadableStream) - A stream of the generated spritesheet image.
- **result.coordinates** (object) - Mapping of image filenames to their position and dimensions.
- **result.properties** (object) - Metadata about the spritesheet (width, height).

#### Error Response (Callback with err)
- **err** (Error) - Details of the error encountered during processing.
```

--------------------------------

### Generate Spritesheet with Spritesmith.run

Source: https://context7.com/twolfson/spritesmith/llms.txt

Use this method for a simple, all-in-one spritesheet generation. It returns the image buffer, coordinates, and properties via a callback. Ensure error handling for the callback.

```javascript
var fs = require('fs');
var Spritesmith = require('spritesmith');

var sprites = [
  '/path/to/icons/home.png',
  '/path/to/icons/user.png',
  '/path/to/icons/settings.png'
];

Spritesmith.run({ src: sprites }, function handleResult(err, result) {
  if (err) {
    throw err;
  }

  // Save the combined spritesheet image to disk
  fs.writeFileSync('/path/to/output/spritesheet.png', result.image);
  // result.image => <Buffer 89 50 4e 47 ...>  (PNG Buffer)

  // result.coordinates maps each source filepath to its position
  console.log(result.coordinates);
  // {
  //   '/path/to/icons/home.png':     { x: 0,  y: 0,  width: 32, height: 32 },
  //   '/path/to/icons/user.png':     { x: 32, y: 0,  width: 32, height: 32 },
  //   '/path/to/icons/settings.png': { x: 64, y: 0,  width: 32, height: 32 }
  // }

  // result.properties describes the total spritesheet dimensions
  console.log(result.properties);
  // { width: 96, height: 32 }
});
```

--------------------------------

### Spritesmith.run (Legacy)

Source: https://github.com/twolfson/spritesmith/blob/master/README.md

This method provides a legacy API for generating spritesheets. It takes an options object and a callback function. The callback receives an error object (if any) and a result object containing the spritesheet image, coordinates, and properties.

```APIDOC
## Spritesmith.run (Legacy)

### Description
Generates a spritesheet and coordinate map from a list of source images using a callback.

### Method
`Spritesmith.run(options, callback)`

### Parameters
#### Options
- **src** (Array<string>) - Required - An array of image file paths or image data.
- **engine** (string) - Optional - The spritesmith engine to use (e.g., 'gmsmith', 'canvassmith'). Defaults to the default engine.
- **algorithm** (string) - Optional - The algorithm to use for image layout (e.g., 'binary-tree'). Defaults to the default algorithm.
- **algorithmOpts** (object) - Optional - Options for the chosen layout algorithm.

#### Callback Function
- **err** (Error) - An error object if an error occurred during processing.
- **result** (object) - An object containing the spritesheet information:
  - **image** (Buffer) - The spritesheet image data.
  - **coordinates** (object) - An object mapping image filenames to their coordinates and dimensions within the spritesheet.
  - **properties** (object) - An object containing metadata about the spritesheet, such as its width and height.

### Request Example
```js
var Spritesmith = require('spritesmith');
var sprites = ['fork.png', 'github.png', 'twitter.png'];
Spritesmith.run({src: sprites}, function handleResult (err, result) {
  if (err) {
    console.error(err);
  } else {
    console.log(result.image); // Buffer representation of image
    console.log(result.coordinates); // Object mapping filename to {x, y, width, height} of image
    console.log(result.properties); // Object with metadata about spritesheet {width, height}
  }
});
```

### Response
#### Success Response (Callback with result)
- **result.image** (Buffer) - The generated spritesheet image.
- **result.coordinates** (object) - Mapping of image filenames to their position and dimensions.
- **result.properties** (object) - Metadata about the spritesheet (width, height).

#### Error Response (Callback with err)
- **err** (Error) - Details of the error encountered during processing.
```

--------------------------------

### new Spritesmith(params)

Source: https://github.com/twolfson/spritesmith/blob/master/README.md

Constructor for a new Spritesmith instance. Allows for optional engine overrides and engine-specific options.

```APIDOC
## new Spritesmith(params)

### Description
Constructor for a new `Spritesmith` instance.

### Parameters
#### 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](#engine).
    - For more engine options, see the [Engines section](#engines).
- **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.
```

--------------------------------

### Basic Spritesmith Usage with Node.js

Source: https://github.com/twolfson/spritesmith/blob/master/README.md

This is the primary way to use spritesmith. Load the module, define an array of image paths, and call `Spritesmith.run`. The callback receives an error or the result object containing the image buffer, coordinates, and properties.

```js
// 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}
});
```

--------------------------------

### Spritesmith Layout Algorithms

Source: https://context7.com/twolfson/spritesmith/llms.txt

Spritesmith supports multiple layout algorithms for packing sprites. Pass the desired algorithm name to `Spritesmith.run` or `processImages`. Algorithm-specific options can be provided via `algorithmOpts`.

```javascript
var Spritesmith = require('spritesmith');
var fs = require('fs');

var sprites = ['a.png', 'b.png', 'c.png', 'd.png'].map(function (f) {
  return '/icons/' + f;
});

// binary-tree (default): most compact packing
Spritesmith.run({ src: sprites, algorithm: 'binary-tree' }, function (err, result) {
  fs.writeFileSync('/out/binary-tree.png', result.image);
});

// left-right: sprites arranged in a single horizontal row
Spritesmith.run({ src: sprites, algorithm: 'left-right' }, function (err, result) {
  fs.writeFileSync('/out/left-right.png', result.image);
});

// top-down: sprites arranged in a single vertical column, sort disabled
Spritesmith.run({
  src: sprites,
  algorithm: 'top-down',
  algorithmOpts: { sort: false }   // preserves original array order
}, function (err, result) {
  fs.writeFileSync('/out/top-down-unsorted.png', result.image);
});

// diagonal: sprites placed along the diagonal
Spritesmith.run({ src: sprites, algorithm: 'diagonal' }, function (err, result) {
  fs.writeFileSync('/out/diagonal.png', result.image);
});

// alt-diagonal: alternate diagonal placement
Spritesmith.run({ src: sprites, algorithm: 'alt-diagonal' }, function (err, result) {
  fs.writeFileSync('/out/alt-diagonal.png', result.image);
});
```

--------------------------------

### Configure Spritesmith Instance with Custom Engines

Source: https://context7.com/twolfson/spritesmith/llms.txt

Instantiate Spritesmith with different image processing engines like 'canvassmith', 'gmsmith', or 'phantomjssmith'. Engine-specific options can be passed via 'engineOpts'.

```javascript
var Spritesmith = require('spritesmith');

// Using default pixelsmith engine (no options needed)
var smith = new Spritesmith();

// Using canvassmith engine (requires Cairo / node-canvas installed)
var smithCanvas = new Spritesmith({ engine: require('canvassmith') });

// Using gmsmith with explicit ImageMagick preference
var smithGM = new Spritesmith({
  engine: 'gmsmith',
  engineOpts: { imagemagick: true }
});

// Using phantomjssmith with a custom timeout
var smithPhantom = new Spritesmith({
  engine: 'phantomjssmith',
  engineOpts: { timeout: 10000 }
});
```

--------------------------------

### Generate Spritesheet with Alt-Diagonal Algorithm

Source: https://github.com/twolfson/spritesmith/blob/master/README.md

Use the 'alt-diagonal' algorithm to generate a spritesheet. Requires loading dependencies like fs and Spritesmith, and specifying source image paths.

```js
// 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
});
```

--------------------------------

### Configure gmsmith with ImageMagick

Source: https://github.com/twolfson/spritesmith/blob/master/README.md

Explicitly use ImageMagick with the gmsmith engine by setting the 'imagemagick' option within 'engineOpts'.

```js
{
  engineOpts: {
    imagemagick: true
  }
}
```

--------------------------------

### Spritesmith Legacy API Usage

Source: https://github.com/twolfson/spritesmith/blob/master/README.md

This code demonstrates the legacy API for spritesmith (versions prior to 3.0.0). It shows how to require the module and use the `spritesmith` function directly with a callback to handle the result.

```js
// 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.createImages(src, callback)

Source: https://context7.com/twolfson/spritesmith/llms.txt

Loads an array of file paths or Vinyl objects into engine-specific image objects that carry pixel dimensions (`width`, `height`). This is the first step of the two-step streaming API and is called internally by `Spritesmith.run`.

```APIDOC
## spritesmith.createImages(src, callback)

### Description
Loads source images (file paths or Vinyl objects) into engine-specific image objects, extracting their pixel dimensions. This is part of the lower-level API for more advanced usage or streaming.

### Method
`instance method`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **src** (array) - Required - An array of image file paths or Vinyl file objects.

### Callback
- **callback** (function) - An error-first callback function.
  - **err** (Error) - An error object if an error occurred, otherwise null.
  - **images** (array) - An array of engine-specific image objects, each containing `width` and `height` properties.

### Request Example
```js
var fs = require('fs');
var path = require('path');
var Vinyl = require('vinyl');
var Spritesmith = require('spritesmith');

var smith = new Spritesmith();

// Using plain file paths
var filePaths = ['/icons/star.png', '/icons/heart.png'];

smith.createImages(filePaths, function handleImages(err, images) {
  if (err) { throw err; }

  images.forEach(function (img, i) {
    console.log(filePaths[i], '=> width:', img.width, 'height:', img.height);
  });
});

// Using Vinyl objects
var vinylSprites = filePaths.map(function (fp) {
  return new Vinyl({ path: fp, contents: fs.readFileSync(fp) });
});

smith.createImages(vinylSprites, function handleImages(err, images) {
  if (err) { throw err; }
  // images[0].width, images[0].height available
});
```

### Response
#### Success Response (Callback)
- **images** (array) - An array of image objects, each with `width` and `height` properties.
```

--------------------------------

### spritesheet.processImages(images, options)

Source: https://github.com/twolfson/spritesmith/blob/master/README.md

Processes an array of images to generate a spritesheet. It places the images on a canvas and exports the spritesheet based on the provided options.

```APIDOC
## `spritesheet.processImages(images, options)`

### Description
Place interpretted images on a canvas and export spritesheet

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **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.
    - **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. For more algorithm options, see the [Algorithms section](#algorithms).
    - **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.

### Request Example
```json
{
  "images": [
    // ... image objects from createImages ...
  ],
  "options": {
    "padding": 2,
    "exportOpts": {
      "quality": 75
    },
    "algorithm": "binary-tree",
    "algorithmOpts": {
      "sort": true
    }
  }
}
```

### Response
#### Success Response (200)
- **image** (ReadableStream) - Readable stream outputting generated image contents
- **coordinates** (Object) - Map from filepath to coordinate information between original sprite and spritesheet
    - `filepath` (Object) - Container for coordinate information
        - **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

#### Response Example
```json
{
  "image": "<ReadableStream>",
  "coordinates": {
    "path/to/image1.png": {
      "x": 0,
      "y": 0,
      "width": 50,
      "height": 50
    },
    "path/to/image2.png": {
      "x": 50,
      "y": 0,
      "width": 50,
      "height": 50
    }
  },
  "properties": {
    "width": 100,
    "height": 50
  }
}
```
```

--------------------------------

### spritesmith.createImages(src, callback)

Source: https://github.com/twolfson/spritesmith/blob/master/README.md

Interprets images using the spritesmith engine. It takes an array of image sources and returns a callback with processed image data.

```APIDOC
## spritesmith.createImages(src, callback)

### Description
Interpret images via the `spritesmith` engine.

### Parameters
#### 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][spec-createImages].
            - **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.
```

--------------------------------

### `spritesmith.processImages(images, options)`

Source: https://context7.com/twolfson/spritesmith/llms.txt

Processes an array of images to generate a spritesheet. This method is suitable for streaming output, piping directly to a file write stream.

```APIDOC
## `spritesmith.processImages(images, options)` — Layout and export as a stream

Takes the array of engine images from `createImages`, packs them according to the chosen algorithm, and returns an object containing a `ReadableStream` for the generated image, the `coordinates` map, and the `properties` object. Use this method when you need streaming output (e.g., piping directly to a file write stream).

### Parameters

- **images**: Array of image objects (output from `createImages`).
- **options**: Object containing processing options.
  - **algorithm**: String - The layout algorithm to use (e.g., 'binary-tree').
  - **padding**: Number - Gap in pixels between each sprite.
  - **exportOpts**: Object - Engine-specific export options.

### Returns

An object with the following properties:
- **image**: ReadableStream - A stream for the generated spritesheet image.
- **coordinates**: Object - A map of image paths to their coordinates and dimensions.
- **properties**: Object - Properties of the generated spritesheet (e.g., width, height).

### Example
```js
var fs = require('fs');
var Spritesmith = require('spritesmith');

var sprites = ['/icons/a.png', '/icons/b.png', '/icons/c.png'];
var smith = new Spritesmith();

smith.createImages(sprites, function handleImages(err, images) {
  if (err) { throw err; }

  var result = smith.processImages(images, {
    algorithm: 'binary-tree',   // default; most space-efficient
    padding: 4,                 // 4px gap between each sprite
    exportOpts: {}              // engine-specific export options
  });

  // result.image is a Readable stream — pipe it to a file
  result.image.pipe(fs.createWriteStream('/output/sprite.png'));

  result.image.on('error', function (err) {
    console.error('Image generation error:', err);
  });

  result.image.on('end', function () {
    console.log('Spritesheet written.');
    console.log('Coordinates:', result.coordinates);
    // { '/icons/a.png': { x: 0, y: 0, width: 16, height: 16 }, ... }
    console.log('Properties:', result.properties);
    // { width: 48, height: 16 }
  });
});
```
```

--------------------------------

### Load Images with spritesmith.createImages

Source: https://context7.com/twolfson/spritesmith/llms.txt

This method is part of the streaming API and loads image files into engine-specific objects, providing their dimensions. It accepts either plain file paths or Vinyl objects, useful for Gulp pipelines.

```javascript
var fs = require('fs');
var path = require('path');
var Vinyl = require('vinyl');
var Spritesmith = require('spritesmith');

var smith = new Spritesmith();

// Using plain file paths
var filePaths = ['/icons/star.png', '/icons/heart.png'];

smith.createImages(filePaths, function handleImages(err, images) {
  if (err) { throw err; }

  images.forEach(function (img, i) {
    console.log(filePaths[i], '=> width:', img.width, 'height:', img.height);
  });
  // /icons/star.png  => width: 24 height: 24
  // /icons/heart.png => width: 24 height: 24
});

// Using Vinyl objects (e.g., from a Gulp pipeline)
var vinylSprites = filePaths.map(function (fp) {
  return new Vinyl({ path: fp, contents: fs.readFileSync(fp) });
});

smith.createImages(vinylSprites, function handleImages(err, images) {
  if (err) { throw err; }
  // images[0].width, images[0].height available
});
```

--------------------------------

### Add Padding Between Sprites

Source: https://github.com/twolfson/spritesmith/blob/master/README.md

Generate a spritesheet with added padding between images. The 'padding' option controls the spacing. Requires loading dependencies like fs and Spritesmith, and specifying source image paths.

```js
// 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
});
```

--------------------------------

### Padding between sprites

Source: https://context7.com/twolfson/spritesmith/llms.txt

Configures the padding (gap) between sprites on the generated spritesheet to prevent texture bleeding.

```APIDOC
## Padding between sprites

Adding padding inserts a pixel gap to the right and bottom of every sprite on the sheet, preventing texture bleeding in CSS or WebGL contexts where sub-pixel rendering might bleed into adjacent sprites.

### Parameters

- **padding**: Number - The gap in pixels to add to the right and bottom of each sprite.

### Example Usage

```js
var fs = require('fs');
var Spritesmith = require('spritesmith');

Spritesmith.run({
  src: [
    '/icons/icon1.png',
    '/icons/icon2.png',
    '/icons/icon3.png'
  ],
  padding: 10  // 10px gap to the right and bottom of each sprite
}, function (err, result) {
  if (err) { throw err; }

  fs.writeFileSync('/out/padded-spritesheet.png', result.image);

  // With 32x32 sprites and padding: 10, coordinates will reflect actual
  // sprite dimensions (without padding), e.g.:
  // { '/icons/icon1.png': { x: 0,  y: 0, width: 32, height: 32 },
  //   '/icons/icon2.png': { x: 42, y: 0, width: 32, height: 32 }, ... }
  console.log(result.coordinates);
  console.log(result.properties);
  // { width: 116, height: 32 }  (3 * 32 + 2 * 10, trailing padding removed)
});
```
```

--------------------------------

### Generate Spritesheet Coordinate Map

Source: https://github.com/twolfson/spritesmith/blob/master/README.md

This JSON output represents the coordinate map generated by spritesmith, mapping image file paths to their position and dimensions within the spritesheet. It's useful for understanding the layout of the generated spritesheet.

```json
{
  "/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
  },
  // ...
}
```

--------------------------------

### Add Padding Between Sprites

Source: https://context7.com/twolfson/spritesmith/llms.txt

Adding padding inserts a pixel gap to the right and bottom of each sprite. This is useful for preventing texture bleeding in rendering contexts. The `padding` option specifies the gap size in pixels.

```javascript
var fs = require('fs');
var Spritesmith = require('spritesmith');

Spritesmith.run({
  src: [
    '/icons/icon1.png',
    '/icons/icon2.png',
    '/icons/icon3.png'
  ],
  padding: 10  // 10px gap to the right and bottom of each sprite
}, function (err, result) {
  if (err) { throw err; }

  fs.writeFileSync('/out/padded-spritesheet.png', result.image);

  // With 32x32 sprites and padding: 10, coordinates will reflect actual
  // sprite dimensions (without padding), e.g.:
  // { '/icons/icon1.png': { x: 0,  y: 0, width: 32, height: 32 },
  //   '/icons/icon2.png': { x: 42, y: 0, width: 32, height: 32 }, ... }
  console.log(result.coordinates);
  console.log(result.properties);
  // { width: 116, height: 32 }  (3 * 32 + 2 * 10, trailing padding removed)
});
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.