Blink-Diff

A lightweight image comparison tool










Table of Contents

• Installation
• Usage
  • Command-Line Usage
  • Object Usage
  • Cropping
  • Perceptual Comparison
  • Logging
  • Block-Out
• Examples
• API-Documentation
• Tests
• Project Focus
• Project Naming
• Contributions
• Contributors
• Third-party libraries
• License

##Image Comparison and Result

##Installation
Install this module with the following command:

npm install blink-diff

Add the module to your package.json dependencies:

npm install --save blink-diff

Add the module to your package.json dev-dependencies:

npm install --save-dev blink-diff

##Usage
The package can be used in two different ways:

• per command line
• through an object

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

blink-diff --output <output>.png <image1>.png <image2>.png

Use image1 and image2 as the images you want to compare.
Only PNGs are supported at this point.
The command-line tool exposes a couple of flags and parameters for the comparison:

--verbose           Turn on verbose mode
--debug             Turn on debug mode - leaving all filters and modifications on the result
--threshold p       Number of pixels/percent 'p' below which differences are ignored
--threshold-type t  'pixel' and 'percent' as type of threshold. (default: pixel)
--delta p           Max. distance colors in the 4 dimensional color-space without triggering a difference. (default: 20)
--copyImageA        Copies first image to output as base. (default: true)
--copyImageB        Copies second image to output as base.
--no-copy           Doesn't copy anything to output as base.
--output o          Write difference to the file 'o'
--filter f          Filters f (separated with comma) that will be applied before the comparison.
--no-composition    Turns the composition feature off
--compose-ltr       Compose output image from left to right
--compose-ttb       Compose output image from top to bottom
--hide-shift        Hides shift highlighting (default: false)
--h-shift           Acceptable horizontal shift of pixel. (default: 0)
--v-shift           Acceptable vertical shift of pixel. (default: 0)
--block-out x,y,w,h Block-out area. Can be repeated multiple times.
--version           Print version
--help              This help

###Object usage
The package can also be used directly in code, without going through the command-line.
Example:

var diff = new BlinkDiff({
    imageAPath: 'path/to/first/image', // Use file-path
    imageBPath: 'path/to/second/image',

    thresholdType: BlinkDiff.THRESHOLD_PERCENT,
    threshold: 0.01, // 1% threshold

    imageOutputPath: 'path/to/output/image'
});

diff.run(function (error, result) {
   if (error) {
      throw error;
   } else {
      console.log(diff.hasPassed(result.code) ? 'Passed' : 'Failed');
      console.log('Found ' + result.differences + ' differences.');
   }
});

All the parameters that were available in the command-line tool are also available through the class constructor, however they might use slightly different wording. 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; imageAPath or imageA is required – see example below)
• imageA Supplies first image that should be compared (required; imageAPath or imageA is required – see example below) – This can be a PNGImage instance or a Buffer instance with PNG data
• imageBPath Defines the path to the second image that should be compared (required; imageBPath or imageB is required – see example below)
• imageB Supplies second image that should be compared (required; imageBPath or imageB is required – see example below) – This can be a PNGImage instance or a Buffer instance with PNG data
• imageOutputPath Defines the path to the output-file. If you leaves this one off, then this feature is turned-off.
• imageOutputLimit Defines when an image output should be created. This can be for different images, similar or different images, or all comparisons. (default: BlinkDiff.OUTPUT_ALL)
• verbose Verbose output (default: false)
• thresholdType Type of threshold check. This can be BlinkDiff.THRESHOLD_PIXEL and BlinkDiff.THRESHOLD_PERCENT (default: BlinkDiff.THRESHOLD_PIXEL)
• threshold Number of pixels/percent p below which differences are ignored (default: 500) – For percentage thresholds: 1 = 100%, 0.2 = 20%
• delta Distance between the color coordinates in the 4 dimensional color-space that will not trigger a difference. (default: 20)
• outputMaskRed Red intensity for the difference highlighting in the output file (default: 255)
• 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)
• outputShiftRed Red intensity for the shift highlighting in the output file (default: 255)
• outputShiftGreen Green intensity for the shift highlighting in the output file (default: 165)
• outputShiftBlue Blue intensity for the shift highlighting in the output file (default: 0)
• outputShiftAlpha Alpha intensity for the shift highlighting in the output file (default: 255)
• outputShiftOpacity Opacity of the pixel for the shift 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: undefined)
• outputBackgroundOpacity Opacity of the pixel for the background in the output file (default: 0.6 – transparent)
• blockOut Object or list of objects with coordinates that should be blocked before testing.
• blockOutRed Red intensity for the block-out in the output file (default: 0) This color will only be visible in the result when debug-mode is turned on.
• blockOutGreen Green intensity for the block-out in the output file (default: 0) This color will only be visible in the result when debug-mode is turned on.
• blockOutBlue Blue intensity for the block-out in the output file (default: 0) This color will only be visible in the result when debug-mode is turned on.
• blockOutAlpha Alpha intensity for the block-out in the output file (default: 255)
• blockOutOpacity Opacity of the pixel for the block-out in the output file (default: 1.0)
• 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. (default)
• 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.
• filter Filters that will be applied before the comparison. Available filters are: blur, grayScale, lightness, luma, luminosity, sepia
• debug When set, then the applied filters will be shown on the output image. (default: false)
• composition Creates as output a composition of all three images (approved, highlight, and build) (default: true)
• composeLeftToRight Creates comparison-composition from left to right, otherwise it lets decide the app on what is best
• composeTopToBottom Creates comparison-composition from top to bottom, otherwise it lets decide the app on what is best
• hShift Horizontal shift for possible antialiasing (default: 2) Set to 0 to turn this off.
• vShift Vertical shift for possible antialiasing (default: 2) Set to 0 to turn this off.
• hideShift Uses the background color for “highlighting” shifts. (default: false)
• cropImageA Cropping for first image (default: no cropping) – Format: { x:, y:, width:, height: }
• cropImageB Cropping for second image (default: no cropping) – Format: { x:, y:, width:, height: }
• perceptual Turn the perceptual comparison mode on. See below for more information.
• gamma Gamma correction for all colors (will be used as base) (default: none) – Any value here will turn the perceptual comparison mode on
• gammaR Gamma correction for red – Any value here will turn the perceptual comparison mode on
• gammaG Gamma correction for green – Any value here will turn the perceptual comparison mode on
• gammaB Gamma correction for blue – Any value here will turn the perceptual comparison mode on

Example:

var firstImage = PNGImage.readImage('path/to/first/image', function (err) {

  if (err) {
    throw err;
  }

  var diff = new BlinkDiff({
      imageA: srcImage, // Use already loaded image for first image
      imageBPath: 'path/to/second/image', // Use file-path to select image

      delta: 50, // Make comparison more tolerant
      
      outputMaskRed: 0,
      outputMaskBlue: 255, // Use blue for highlighting differences
      
      hideShift: true, // Hide anti-aliasing differences - will still determine but not showing it

      imageOutputPath: 'path/to/output/image'
  });

  diff.run(function (error, result) {
    if (error) {
      throw error;
    } else {
      console.log(diff.hasPassed(result.code) ? 'Passed' : 'Failed');
      console.log('Found ' + result.differences + ' differences.');
    }
  });
});

####Cropping
Images can be cropped before they are compared by using the cropImageA or cropImageB parameters. Single values can be left off, and the system will calculate the correct dimensions. However, x/y coordinates have priority over width/height as the position are usually more important than the dimensions – image will also be clipped by the system when needed.
####Perceptual Comparison
The perceptual comparison mode considers the perception of…