perceptualdiff

node-perceptualdiff

A node port of the perceptualdiff image comparison (http://pdiff.sourceforge.net) with some additional features

Usage:

The package can be used in two different ways:

• per command line; just as the original project
• through a class in your code

Command-Line usage:

The command-line tool can be found in the bin directory. You can run the application with

node ./bin/perceptualdiff.js <image1>.png <image2>.png

Use image1 and image2 as the images you want to compare.

Note: This port only supports PNGs!

The command-line tool exposes a couple of flags and parameters for the comparison:

--verbose           Turn on verbose mode"
--fov deg           Field of view in degrees [0.1, 89.9] (default: 45.0)
--threshold p       Number of pixels/percent p below which differences are ignored
--threshold-image p Number of pixels/percent p below which differences are not generated (see --output)
--threshold-type p  'pixel' and 'percent' as type of threshold. (default: pixel)
--pyramid-levels p  Number of levels of Laplacian pyramids. (default: 3)
--gamma g           Value to convert rgb into linear space (default: 2.2)
--luminance l       White luminance (default: 100.0 cdm^-2)
--luminance-only    Only consider luminance; ignore chroma (color) in the comparison
--color-factor      How much of color to use [0.0, 1.0] (default: 1.0)
--scale             Scale images to match each others dimensions
--sum-errors        Print a sum of the luminance and color differences
--output o          Write difference to the file o
--version           Print version
--help              This help

Most of the parameters were exposed as the original project does. However, I changed a couple of parameter signatures to make the interface a little bit more consistent.

• --luminanceonly was renamed to luminance-only
• --colorfactor was renamed to color-factor

Since the PNG library, I use, does not support resampling, I needed to remove this feature for now. So, there is no --resample. Please resample the images through other means before using this diff-tool.

I also added a couple additional features and some were exposed to the command-line tool:

• --threshold-image p makes it possible to skip some of the comparison, reducing the time spent analysing the images as node is a LOT slower than C is. This feature will also skip the creation of output images if this threshold is not reached; it simply stops caring if the difference is below the threshold.
• --threshold-type p changes the threshold by considering absolute pixels or percentage of total pixels. The values are pixel and percent respectively.
• --pyramid-levels p specifies the detail of the comparison - the higher the number is, the higher the comparison resolution but also the longer it will take. 2 is the lowest number possible. The original perceptualdiff tool used internally 8 as default. Again, node is just too slow.

Class usage:

The package can also be used directly in code, without going through the command-line.

Example:

var PerceptualDiff = require('perceptualdiff');
 
var diff = new PerceptualDiff({
    imageAPath: '...',
    imageBPath: '...',
 
    scale: true,
    verbose: true,
    pyramidLevels: 5,
 
    thresholdType: PerceptualDiff.THRESHOLD_PERCENT,
    threshold: 0.01,
    imageThreshold: 0.005,
 
    outputPath: '...'
});
 
diff.run(function (passed) {
    console.log(passed ? 'Passed' : 'Failed');
});

All the parameters that were available in the command-line tool are also available through the class constructor - they use camelCasing instead of snake-casing. The class exposes additional parameters that are not available from the command-line.

• imageAPath Defines the path to the first image that should be compared (required)
• imageBPath Defines the path to the second image that should be compared (required)
• imageOutputPath Defines the path to the output-file. If you leaves this one off, then this feature is turned-off.
• verbose Verbose output (default: false)
• luminanceOnly Only consider luminance; ignore chroma (color) in the comparison (default: false)
• sumErrors Print a sum of the luminance and color differences (default: false)
• fieldOfView Field of view in degrees 0.1, 89.9
• gamma Value to convert rgb into linear space (default: 2.2)
• luminance White luminance (default: 100.0 cdm^-2)
• thresholdType Type of threshold check. This can be PerceptualDiff.THRESHOLD_PIXEL and PerceptualDiff.THRESHOLD_PERCENT (default: THRESHOLD_PIXEL)
• threshold Number of pixels/percent p below which differences are ignored (default: 100)
• imageThreshold Number of pixels/percent p below which differences are not generated (default: 50)
• colorFactor How much of color to use 0.0, 1.0
• pyramidLevels Number of levels of Laplacian pyramids. (default: 3)
• scale Scale images to match each others dimensions (default: false)
• outputMaskRed Red intensity for the difference highlighting in the output file (default: 255 - full red)
• outputMaskGreen Green intensity for the difference highlighting in the output file (default: 0)
• outputMaskBlue Blue intensity for the difference highlighting in the output file (default: 0)
• outputMaskAlpha Alpha intensity for the difference highlighting in the output file (default: 255)
• outputMaskOpacity Opacity of the pixel for the difference highlighting in the output file (default: 0.7 - slightly transparent)
• outputBackgroundRed Red intensity for the background in the output file (default: 0)
• outputBackgroundGreen Green intensity for the background in the output file (default: 0)
• outputBackgroundBlue Blue intensity for the background in the output file (default: 0)
• outputBackgroundAlpha Alpha intensity for the background in the output file (default: 0 - transparent)
• copyImageAToOutput Copies the first image to the output image before the comparison begins. This will make sure that the output image will highlight the differences on the first image.
• copyImageBToOutput Copies the second image to the output image before the comparison begins. This will make sure that the output image will highlight the differences on the second image.

Logging:

By default, the logger doesn't log events anywhere, but you can overwrite this behavior by overwriting PerceptualDiff.log:

var diff = new PerceptualDiff({
    ...
});
 
diff.log = function (text) {
    // Do whatever you want to do
};
 
...

Example:

There are some examples in the examples folder, where I used screenshots of Wikipedia to check for visual regressions. You can find examples for:

• Missing DOM elements in hidden_regression
• Disrupted sorting in sorting_regression
• Color changes in style_regression
• Text capitalization in text_regression

All screenshots were compared to wikipedia_approved.png, a previously approved screenshot without a regression. Each of the regression has the screenshot and the output result, highlighting the differences.

TODO:

• Code documentation

LICENSE

The original project was release with the GPL v2 license.