# image-diff

> Create image differential between two images

Latest version **2.0.0** (published 2017-08-22) · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install image-diff
pnpm add image-diff
yarn add image-diff
bun add image-diff
```

Provides the command `image-diff`.

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2017-08-22 |
| First published | 2013-11-18 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 0.8.0 |
| Dependencies | 6 |
| Known vulnerabilities | 0 (+2 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 2435 |
| Author | Todd Wolfson |
| Maintainers | twolfson, mlmorg, uber |
| Keywords | image, diff |

## Links

- npm: https://www.npmjs.com/package/image-diff
- Repository: https://github.com/uber/image-diff
- Issues: https://github.com/uber/image-diff/issues
- npm.io page: https://npm.io/package/image-diff

## Dependencies (6)

- [gm](https://npm.io/package/gm.md) ~1.21.1
- [tmp](https://npm.io/package/tmp.md) 0.0.23
- [async](https://npm.io/package/async.md) ~0.2.9
- [mkdirp](https://npm.io/package/mkdirp.md) ~0.3.5
- [commander](https://npm.io/package/commander.md) ~2.9.0
- [buffered-spawn](https://npm.io/package/buffered-spawn.md) ~1.1.1

## Alternatives

- [exif-parser](https://npm.io/package/exif-parser.md) — 3.8M weekly downloads
- [vite-plugin-compression](https://npm.io/package/vite-plugin-compression.md) — 569.5K weekly downloads
- [pica](https://npm.io/package/pica.md) — 442.4K weekly downloads
- [@reportportal/client-javascript](https://npm.io/package/@reportportal/client-javascript.md) — 408.8K weekly downloads
- [@tldraw/state](https://npm.io/package/@tldraw/state.md) — 316.0K weekly downloads

## Recent versions

- 2.0.0 (latest) — 2017-08-22
- 1.6.3 — 2016-08-01
- 1.6.2 — 2016-07-29
- 1.6.1 — 2016-07-19
- 1.6.0 — 2016-05-24
- 1.5.1 — 2016-03-24
- 1.5.0 — 2016-03-17
- 1.4.0 — 2016-03-17
- 1.3.0 — 2015-10-19
- 1.2.0 — 2015-06-28
- 1.1.0 — 2015-06-23
- 1.0.3 — 2015-04-25
- 1.0.2 — 2015-04-25
- 1.0.1 — 2014-02-22
- 1.0.0 — 2014-02-22
- … 7 more at https://npm.io/package/image-diff/versions

## README

# image-diff [![Build Status](https://travis-ci.org/uber/image-diff.svg?branch=master)](https://travis-ci.org/uber/image-diff)
# Project deprecated
We no longer have any active maintainers on this project and as a result have halted maintenance.

As a replacement, please see alternative projects like `looks-same` and `pixelmatch`:

https://github.com/gemini-testing/looks-same

https://github.com/mapbox/pixelmatch

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

Create image differential between two images

This was created as part of a [visual regression][] project.

[visual regression]: http://www.youtube.com/watch?v=1wHr-O6gEfc

![Example diff](docs/example.png)

## Getting Started
### Requirements
`image-diff` depends on [ImageMagick][].

Please install this before continuing.

[ImageMagick]: http://www.imagemagick.org/

### Setup
Install the module with: `npm install image-diff`

```javascript
var imageDiff = require('image-diff');
imageDiff({
  actualImage: 'checkerboard.png',
  expectedImage: 'white.png',
  diffImage: 'difference.png',
}, function (err, imagesAreSame) {
  // error will be any errors that occurred
  // imagesAreSame is a boolean whether the images were the same or not
  // diffImage will have an image which highlights differences
});
```

## Documentation
`image-diff` exposes the function `imageDiff` as its export.

### `imageDiff(options, cb)`
Create an differential image between multiple images

- options `Object`
    - options.actualImage `String` - Path to actual image file
        - options.actualImage **must** exist
    - options.expectedImage `String` - Path to expected image file
        - If options.expectedImage does not exist, a transparent image with the same height/width will be created.
    - options.diffImage `String` - Optional path to output differential image
    - options.shadow `Boolean` - Optional flag to indicate if we should draw a shadow of the unchanged parts of the images
        - For example, if an image is `+` and we diff with `-`, then the image will have `|` be red but also contain a faded `-`
        - By default, this options is `false` meaning a shadow will not be drawn
- cb `Function` - Error-first function to handle diff result
    - `cb` should have the signature `function (err, imagesAreSame)`
    - err `Error|null` - If there was an error in diffing, this will be it
    - imagesAreSame `Boolean` - Indicates that images are same or not

### `imageDiff.getFullResult(options, cb)`
Same as `imageDiff` but yields a fuller result

- options `Object` - See `imageDiff#options`
- cb `Function` - Error-first function to handle diff result
    - `cb` should have the signature `function (err, result)`
    - err `Error|null` - If there was an error in diffing, this will be it
    - result `Object`
        - total `Float` - Root mean square pixel difference across all pixels
          - Value can range from 0 (no difference) to 655535 (every pixel is different)
        - percentage `Float` - Normalized total difference
          - Value can range from 0.00 (no difference) to 1.00 (every pixel is different)
        - More info here: http://www.imagemagick.org/discourse-server/viewtopic.php?f=1&t=17284

**Example:**

```javascript
var imageDiff = require('image-diff');
imageDiff.getFullResult({
  actualImage: 'checkerboard.png',
  expectedImage: 'white.png',
  diffImage: 'difference.png',
}, function (err, result) {
  // result = {total: 46340.2, difference: 0.707107}
});
```

### `imageDiff.getRawResult(options, cb)`
Same as `imageDiff` but yields raw CLI result

- options `Object` - See `imageDiff#options`
- cb `Function` - Error-first function to handle diff result
    - `cb` should have the signature `function (err, result)`
    - err `Error|null` - If there was an error in diffing, this will be it
    - result `String` - Result from ImageMagick's `compare` command
        - Example output can be found here: http://www.imagemagick.org/discourse-server/viewtopic.php?f=1&t=17284

### CLI usage
We offer an `image-diff` executable to diff from the CLI. When images match, its exit code will be `0`. When they don't match, then it will be non-zero (e.g. `1`).

```
$ image-diff --help

  Usage: image-diff [options] <actual-image> <expected-image> [diff-image]

  Options:

    -h, --help     output usage information
    -V, --version  output the version number
    --shadow       Draw a shadow of unchanges parts on diff image

```

Example usage:

```bash
# Images don't match
image-diff checkerboard.png white.png diff.png
echo $?
# 1
# We can look at `diff.png` for the diff result

# Images do match
image-diff checkerboard.png white.png
echo $?
# 0
```

## 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](https://github.com/gruntjs/grunt) and test via `npm test`.

## Attribution
The font used for the example image is [Arial][] 30pt bold and [Courier New][] 38pt.

[Arial]: http://en.wikipedia.org/wiki/Arial
[Courier New]: http://en.wikipedia.org/wiki/Courier_%28typeface%29#Courier_New

## License
Copyright (c) 2013 Uber

Licensed under the MIT license.

---
_Source: https://npm.io/package/image-diff · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._