Skip to content
Node.js library for comparing images
Branch: master
Clone or download
Latest commit d7a4edd Mar 22, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
benchmark feat: add ability to make ignore antialiasing less strict Sep 11, 2018
lib fix: error maximum call stack size exceeded Mar 18, 2019
test chore(tests): fix unit tests Mar 22, 2019
.eslintrc.js chore: install and use eslint Aug 13, 2018
.travis.yml feat: ability to compare images by regions (#51) Feb 28, 2019
AUTHORS Update legal information Sep 19, 2016
LICENSE Update legal information Sep 19, 2016 feat: add diff clusters Mar 12, 2019
index.d.ts feat: add diff clusters Mar 12, 2019
index.js Merge pull request #28 from chrisdeely/default-highlight-color Mar 22, 2019
package.json 7.2.0 Mar 22, 2019


Build Status

Node.js library for comparing PNG-images, taking into account human color perception. It is created specially for the needs of visual regression testing for gemini utility, but can be used for other purposes.

Comparing images

var looksSame = require('looks-same');

looksSame('image1.png', 'image2.png', function(error, {equal}) {
    // equal will be true, if images looks the same

Parameters can be paths to files or buffer with compressed png image.

By default, it will detect only noticeable differences. If you wish to detect any difference, use strict options:

looksSame('image1.png', 'image2.png', {strict: true}, function(error, {equal}) {

You can also adjust the ΔE value that will be treated as error in non-strict mode:

looksSame('image1.png', 'image2.png', {tolerance: 5}, function(error, {equal}) {

Default tolerance in non-strict mode is 2.3 which is enough for the most cases. Setting tolerance to 0 will produce the same result as strict: true, but strict mode is faster. Attempt to set tolerance in strict mode will produce an error.

Some devices can have different proportion between physical and logical screen resolutions also known as pixel ratio. Default value for this proportion is 1. This param also affects the comparison result, so it can be set manually with pixelRatio option.

looksSame('image1.png', 'image2.png', {pixelRatio: 2}, function(error, {equal}) {

Comparing images with ignoring caret

Text caret in text input elements it is a pain for visual regression tasks, because it is always blinks. These diffs will be ignored by default. You can use ignoreCaret option with false value to disable ignoring such diffs. In that way text caret will be marked as diffs.

looksSame('image1.png', 'image2.png', {ignoreCaret: true}, function(error, {equal}) {

Both strict and ignoreCaret can be set independently of one another.

Comparing images with ignoring antialiasing

Some images has difference while comparing because of antialiasing. These diffs will be ignored by default. You can use ignoreAntialiasing option with false value to disable ignoring such diffs. In that way antialiased pixels will be marked as diffs. Read more about anti-aliasing algorithm.

looksSame('image1.png', 'image2.png', {ignoreAntialiasing: true}, function(error, {equal}) {

Sometimes the antialiasing algorithm can work incorrectly due to some features of the browser rendering engine. Use the option antialiasingTolerance to make the algorithm less strict. With this option you can specify the minimum difference in brightness (zero by default) between the darkest/lightest pixel (which is adjacent to the antialiasing pixel) and theirs adjacent pixels.

We recommend that you don't increase this value above 10. If you need to increase more than 10 then this is definitely not antialiasing.


looksSame('image1.png', 'image2.png', {ignoreAntialiasing: true, antialiasingTolerance: 3}, function(error, {equal}) {

Getting diff bounds

Looksame returns information about diff bounds. It returns only first pixel if you passed stopOnFirstFail option with true value. The whole diff area would be returned if stopOnFirstFail option is not passed or it's passed with false value.

Getting diff clusters

Looksame returns diff bounds divided into clusters. You can pass clusters size using clustersSize option.

looksSame('image1.png', 'image2.png', {stopOnFirstFail: false}, function(error, {equal, diffBounds, diffClusters}) {
    // {
    //     equal: false,
    //     diffBounds: {left: 10, top: 10, right: 20, bottom: 20}
    //     diffClusters: [
    //         {left: 10, top: 10, right: 14, bottom: 14},
    //         {left: 16, top: 16, right: 20, bottom: 20}
    //     ]
    // }

Building diff image

    reference: '/path/to/reference/image.png',
    current: '/path/to/current/image.png',
    diff: '/path/to/save/diff/to.png',
    highlightColor: '#ff00ff', // color to highlight the differences
    strict: false, // strict comparsion
    tolerance: 2.5,
    antialiasingTolerance: 0,
    ignoreAntialiasing: true, // ignore antialising by default
    ignoreCaret: true // ignore caret by default
}, function(error) {

Building diff image as a Buffer

If you don't want the diff image to be written on disk, then simply don't pass any diff: path to the createDiff method. The callback will then receive a Buffer containing the diff as the 2nd argument.

    // exactly same options as above, but without diff
}, function(error, buffer) {

Comparing colors

If you just need to compare two colors you can use colors function:

    {R: 255, G: 0, B: 0},
    {R: 254, G: 1, B: 1},
    {tolerance: 2.5}
You can’t perform that action at this time.