# @itk-wasm/compare-images

> Compare images with a tolerance for regression testing.

Latest version **5.4.2** (published 2026-08-18) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @itk-wasm/compare-images
pnpm add @itk-wasm/compare-images
yarn add @itk-wasm/compare-images
bun add @itk-wasm/compare-images
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 5.4.2 |
| Published | 2026-08-18 |
| First published | 2023-08-22 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 1 |
| Unpacked size | 1.9 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 236 |
| Maintainers | paulhax, thewtex |
| Keywords | itk, wasm, webassembly, wasi |

## Links

- npm: https://www.npmjs.com/package/@itk-wasm/compare-images
- Repository: https://github.com/InsightSoftwareConsortium/ITK-Wasm
- npm.io page: https://npm.io/package/@itk-wasm/compare-images

## Dependencies (1)

- [itk-wasm](https://npm.io/package/itk-wasm.md) ^1.0.0-b.201

## Recent versions

- 5.4.2 (latest) — 2026-08-18
- 5.4.1 — 2025-11-09
- 5.4.0 — 2025-02-24
- 5.3.1 — 2025-01-05
- 5.3.0 — 2025-01-05
- 5.2.3 — 2024-10-23
- 5.2.2 — 2024-10-23
- 5.2.1 — 2024-10-23
- 5.2.0 — 2024-08-11
- 5.1.1 — 2024-05-19
- 5.1.0 — 2024-05-18
- 5.0.2 — 2024-03-11
- 5.0.1 — 2024-01-23
- 5.0.0 — 2024-01-09
- 4.0.2 — 2023-12-19
- … 6 more at https://npm.io/package/@itk-wasm/compare-images/versions

## README

# @itk-wasm/compare-images

[![npm version](https://badge.fury.io/js/@itk-wasm%2Fcompare-images.svg)](https://www.npmjs.com/package/@itk-wasm/compare-images)

> Compare images with a tolerance for regression testing.

[👨‍💻 **Live API Demo** ✨](https://insightsoftwareconsortium.github.io/ITK-Wasm/compare-images/ts/app/ ':include :type=iframe width=100% height=800px')

[🕮 **Documentation** 📚](https://insightsoftwareconsortium.github.io/ITK-Wasm/compare-images/ts/docs/)


## Installation

```sh
npm install @itk-wasm/compare-images
```

## Usage

### Browser interface

Import:

```js
import {
  compareImages,
  setPipelinesBaseUrl,
  getPipelinesBaseUrl,
} from "@itk-wasm/compare-images"
```

#### compareImages

*Compare images with a tolerance for regression testing.*

```ts
async function compareImages(
  testImage: Image,
  options: CompareImagesOptions = { baselineImages: [] as Image[], }
) : Promise<CompareImagesResult>
```

|  Parameter  |   Type  | Description          |
| :---------: | :-----: | :------------------- |
| `testImage` | *Image* | The input test image |

**`CompareImagesOptions` interface:**

|          Property         |             Type            | Description                                                                                                                                           |
| :-----------------------: | :-------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
|      `baselineImages`     |          *Image[]*          | Baseline images compare against                                                                                                                       |
|   `differenceThreshold`   |           *number*          | Intensity difference for pixels to be considered different.                                                                                           |
|     `radiusTolerance`     |           *number*          | Radius of the neighborhood around a pixel to search for similar intensity values.                                                                     |
| `numberOfPixelsTolerance` |           *number*          | Number of pixels that can be different before the test fails.                                                                                         |
|   `ignoreBoundaryPixels`  |          *boolean*          | Ignore boundary pixels. Useful when resampling may have introduced difference pixel values along the image edge.                                      |
|        `webWorker`        | *null or Worker or boolean* | WebWorker for computation. Set to null to create a new worker. Or, pass an existing worker. Or, set to `false` to run in the current thread / worker. |
|          `noCopy`         |          *boolean*          | When SharedArrayBuffer's are not available, do not copy inputs.                                                                                       |

**`CompareImagesResult` interface:**

|         Property         |       Type       | Description                                                                       |
| :----------------------: | :--------------: | :-------------------------------------------------------------------------------- |
|         `metrics`        | *JsonCompatible* | Metrics for the baseline with the fewest number of pixels outside the tolerances. |
|     `differenceImage`    |      *Image*     | Absolute difference image                                                         |
| `differenceUchar2dImage` |      *Image*     | Unsigned char, 2D difference image for rendering                                  |
|        `webWorker`       |     *Worker*     | WebWorker used for computation.                                                   |

#### setPipelinesBaseUrl

*Set base URL for WebAssembly assets when vendored.*

```ts
function setPipelinesBaseUrl(
  baseUrl: string | URL
) : void
```

#### getPipelinesBaseUrl

*Get base URL for WebAssembly assets when vendored.*

```ts
function getPipelinesBaseUrl() : string | URL
```


### Node interface

Import:

```js
import {
  compareImagesNode,
} from "@itk-wasm/compare-images"
```

#### compareImagesNode

*Compare images with a tolerance for regression testing.*

```ts
async function compareImagesNode(
  testImage: Image,
  options: CompareImagesOptions = { baselineImages: [] as Image[], }
) : Promise<CompareImagesNodeResult>
```

|  Parameter  |   Type  | Description          |
| :---------: | :-----: | :------------------- |
| `testImage` | *Image* | The input test image |

**`CompareImagesNodeOptions` interface:**

|          Property         |    Type   | Description                                                                                                      |
| :-----------------------: | :-------: | :--------------------------------------------------------------------------------------------------------------- |
|      `baselineImages`     | *Image[]* | Baseline images compare against                                                                                  |
|   `differenceThreshold`   |  *number* | Intensity difference for pixels to be considered different.                                                      |
|     `radiusTolerance`     |  *number* | Radius of the neighborhood around a pixel to search for similar intensity values.                                |
| `numberOfPixelsTolerance` |  *number* | Number of pixels that can be different before the test fails.                                                    |
|   `ignoreBoundaryPixels`  | *boolean* | Ignore boundary pixels. Useful when resampling may have introduced difference pixel values along the image edge. |

**`CompareImagesNodeResult` interface:**

|         Property         |       Type       | Description                                                                       |
| :----------------------: | :--------------: | :-------------------------------------------------------------------------------- |
|         `metrics`        | *JsonCompatible* | Metrics for the baseline with the fewest number of pixels outside the tolerances. |
|     `differenceImage`    |      *Image*     | Absolute difference image                                                         |
| `differenceUchar2dImage` |      *Image*     | Unsigned char, 2D difference image for rendering                                  |

---
_Source: https://npm.io/package/@itk-wasm/compare-images · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._