# img-diff-js

> Library to compare 2 images

Latest version **0.5.4** (published 2024-03-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install img-diff-js
pnpm add img-diff-js
yarn add img-diff-js
bun add img-diff-js
```

## Health

**Score 40/100 (D)** — status: abandoned.

Positive: has types; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 0.5.4 |
| Published | 2024-03-04 |
| First published | 2017-07-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 228.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 120 |
| Author | Quramy |
| Maintainers | quramy |
| Keywords | diff, image, compare |

## Links

- npm: https://www.npmjs.com/package/img-diff-js
- Repository: https://github.com/reg-viz/img-diff-js
- Homepage: https://github.com/reg-viz/img-diff-js#readme
- Issues: https://github.com/reg-viz/img-diff-js/issues
- npm.io page: https://npm.io/package/img-diff-js

## Dependencies (5)

- [pngjs](https://npm.io/package/pngjs.md) ^7.0.0
- [mkdirp](https://npm.io/package/mkdirp.md) ^1.0.4
- [jpeg-js](https://npm.io/package/jpeg-js.md) ^0.4.2
- [pixelmatch](https://npm.io/package/pixelmatch.md) ^5.2.1
- [decode-tiff](https://npm.io/package/decode-tiff.md) ^0.2.0

## 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

- 0.5.4 (latest) — 2024-03-04
- 0.5.3 — 2024-03-04
- 0.5.2 — 2021-03-10
- 0.5.1 — 2020-12-04
- 0.5.0 — 2020-10-01
- 0.4.1 — 2018-02-07
- 0.4.0 — 2017-09-29
- 0.3.2 — 2017-07-19
- 0.3.1 — 2017-07-19
- 0.3.0 — 2017-07-18
- 0.2.0 — 2017-07-16
- 0.1.1 — 2017-07-15
- 0.1.0 — 2017-07-15
- 0.0.1 — 2017-07-15

## README

# img-diff-js

[![github actions](https://github.com/reg-viz/img-diff-js/workflows/build/badge.svg)](https://github.com/reg-viz/img-diff-js/actions)
[![npm version](https://badge.fury.io/js/img-diff-js.svg)](https://badge.fury.io/js/img-diff-js)
[![codecov](https://codecov.io/gh/reg-viz/img-diff-js/graph/badge.svg?token=6QopebRnI6)](https://codecov.io/gh/reg-viz/img-diff-js)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

:art: Node.js library to compare 2 images without native libs.

|            Actual             |             Expected              |        Difference         |
| :---------------------------: | :-------------------------------: | :-----------------------: |
| ![actual](example/actual.png) | ![expected](example/expected.png) | ![diff](example/diff.png) |

## Install

```sh
npm install img-diff-js
```

```js
const { imgDiff } = require("img-diff-js");

imgDiff({
  actualFilename: "example/actual.png",
  expectedFilename: "example/expected.png",
  diffFilename: "example/diff.png",
}).then(result => console.log(result));
```

## API Usage

### `imgDiff(opt: ImgDiffOptions): Promise<ImgDiffResult>`

Create image differential between two images.

#### `ImgDiffOptions`

```ts
{
  actualFilename: string;
  expectedFilename: string;
  diffFilename?: string;
  generateOnlyDiffFile?: boolean; // default false
  options?: {
    threshold?: number;   // default 0.1
    includeAA?: boolean;  // default false
  }
}
```

- `actualFilename` - _Required_ - Path to actual image file.
- `expectedFilename` - _Required_ - Path to expected image file.
- `diffFilename` - _Optional_ - Path to differential image file. If omitted, `imgDiff` does not output image file.
- `generateOnlyDiffFile` - _Optional_ - Generate only files with difference
- `options` - _Optional_ - An object to pass through [pixelmatch](https://github.com/mapbox/pixelmatch#api).

#### `ImgDiffResult`

```ts
{
  width: number;
  height: number;
  imagesAreSame: boolean;
  diffCount: number;
}
```

- `width` - Differential image's width.
- `height` - Differential image's height.
- `imagesAreSame` - It'll be true only if 2 images are same perfectly.
- `diffCount` - The number of differential pixels.

## Available format

The following codecs are available for input image files.

- [x] png
- [x] jpeg
- [x] tiff (limited. See https://github.com/Quramy/decode-tiff#compatibility )
- [ ] bmp

`imgDiff` detects the input image format from it's extension name. For example, if the input file name ends with ".jpeg", `imgDiff` attempts to decode in JPEG way regardless of the actual file format.

The output image format is PNG only.

## Contribute

PR or issue is welcome :)

### Setup

```sh
yarn
```

### Test

```sh
yarn test
```

### Run benchmark script

```sh
yarn run perf
```

## License

MIT License. See LICENSE under this repository.

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