Perceptualdiff NPM

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 (default: 45.0)
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 (default: 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 _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: