@syngrisi/node-resemble.js/README.md

Image analysis and comparison for nodejs

# @syngrisi/node-resemble.js

<p align="center">
<a href="https://nodejs.org/docs/latest-v22.x/api/index.html"><img src="https://img.shields.io/badge/node-22+-brightgreen.svg"></a>
<a href="https://www.npmjs.com/package/@syngrisi/node-resemble.js"><img src="https://img.shields.io/npm/v/@syngrisi/node-resemble.js.svg"></a>
</p>

Image analysis and comparison library for Node.js. This is a supported fork of [node-resemble.js](https://github.com/burnpiro/node-resemble.js), which is a modification of [Resemble.js](https://github.com/Huddle/Resemble.js).

This project does not need canvas or any other binary dependencies (uses [sharp](https://github.com/lovell/sharp) for image processing).

## Installation

```bash
npm install @syngrisi/node-resemble.js
```

or

```bash
yarn add @syngrisi/node-resemble.js
```

### Example

##### Retrieve basic analysis on image.

```javascript
var api = resemble(fileData).onComplete(function(data){
	console.log(data);
	/*
	{
	  red: 255,
	  green: 255,
	  blue: 255,
	  brightness: 255
	}
	*/
});
```

##### Use resemble to compare two images.

```javascript
var diff = resemble(file).compareTo(file2).ignoreColors().onComplete(function(data){
	console.log(data);
	/*
	{
	  misMatchPercentage : 100, // %
	  isSameDimensions: true, // or false
	  dimensionDifference: { width: 0, height: -1 }, // defined if dimensions are not the same
	  getDiffImage: function(){}, // returns the diff image (PNG object)
	  getDiffImageAsJPEG: function(quality){} // returns the diff image as a JPEG buffer
	}
	*/
});
```

##### You can also change the comparison method after the first analysis.

```javascript
// diff.exact();          // true pixel-to-pixel, zero tolerance
// diff.ignoreNothing();  // tolerant (±16 per channel)
// diff.ignoreColors();
diff.ignoreAntialiasing();
```

##### Specify matching Box for image comparsion

```javascript
diff.ignoreRectangles([[325,170,100,40], [10,10,200,200]]);
```
- Ignores matched rectangles
- <[Array<Array[x, y, width, height]>]>
```javascript
diff.includeRectangles([[325,170,100,40], [10,10,200,200]]);
```
- Compares only within given rectangles
- <[Array<Array[x, y, width, height]>]>

##### Change the output display style.

```javascript
resemble.outputSettings({
  errorColor: {
    red: 255,
    green: 0,
    blue: 255
  },
  errorType: 'movement',
  transparency: 0.3
});
// resembleControl.repaint();
```

--------------------------------------
## Example usuage (in cucumber step definition)


     this.Then(/^Screenshot should match image "(.*)"$/, function (image, callback) {
        browser.takeScreenshot().then(function(pngString) {
          var screenshot = new Buffer(pngString, 'base64');
     
          resemble(image)
            .compareTo(screenshot)
            .onComplete(function(data){
     
              if (Number(data.misMatchPercentage) <= 0.01) {
                callback();
              } else {
                data.getDiffImage().pack().pipe(fs.createWriteStream(image + 'diff.png'));
                callback.fail(new Error("Screenshot '" + image+  "' differ " + data.misMatchPercentage + "%"));
              }
            });
        });
      })

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

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

## Why this package ships raw `resemble.js`

`resemble.js` is a maintained fork kept intentionally close to upstream
[Resemble.js](https://github.com/Huddle/Resemble.js) — the file itself notes
this ("keeping wrong indentation and '_this' for better diff with origin
resemble.js") to keep future upstream diffs small and easy to review. Unlike
the other packages in this monorepo, it is **not** compiled with `tsc`: the
comparison/diff algorithm it implements is baseline-affecting (changing it
would invalidate visual baselines across every consumer of this repo), so it
is deliberately frozen and shipped as-is.

Type declarations are instead provided via a small, hand-written
`resemble.d.ts` covering the API surface consumers actually use (the
`resemble(...).compareTo(...).ignore*().onComplete(...)` chain and
`resemble.outputSettings(...)`), rather than being generated by compiling the
source. The `build` script is an intentional no-op that documents this choice
so monorepo-wide build loops don't break.

Credits:
 * Created by [James Cryer](http://github.com/jamescryer) and the Huddle development team.
 * [Lukas Svoboda](http://github.com/lksv) - modification for node.js
 * [Kemal Erdem](https://github.com/burnpiro) - modification
 * [Viktar Silakou](https://github.com/viktor-silakov) - modification