Add tolerance to gm.compare options object. Change the gm.compare logic to always run the mse comparison as expected.

README.md

@@ -484,7 +484,7 @@ Graphicsmagicks `compare` command is exposed through `gm.compare()`. This allows
 
 Currently `gm.compare` only accepts file paths.
 
-    gm.compare(path1, path2 [, tolerance], callback)
+    gm.compare(path1, path2 [, options], callback)
 
 ```js
 gm.compare('/path/to/image1.jpg', '/path/to/another.png', function (err, isEqual, equality, raw) {
@@ -510,6 +510,20 @@ gm.compare('/path/to/image1.jpg', '/path/to/another.png', 1.2, function (err, is
 })
 ```
 
+To output a diff image, pass a configuration object to define the diff options and tolerance.
+
+
+```js
+var options = {
+  file: '/path/to/diff.png',
+  highlightColor: 'yellow',
+  tolerance: 0.02
+}
+gm.compare('/path/to/image1.jpg', '/path/to/another.png', options, function (err, isEqual, equality, raw) {
+  ...
+})
+```
+
 ## Contributors
 [https://github.com/aheckmann/gm/contributors](https://github.com/aheckmann/gm/contributors)
 

lib/compare.js

@@ -14,54 +14,53 @@ var utils = require('./utils');
  *
  * @param {String} orig Path to an image.
  * @param {String} compareTo Path to another image to compare to `orig`.
- * @param {Number} [tolerance] Amount of difference to tolerate before failing - defaults to 0.4
+ * @param {Number|Object} [options] Options object or the amount of difference to tolerate before failing - defaults to 0.4
  * @param {Function} cb(err, Boolean, equality, rawOutput)
  */
 
 module.exports = exports = function (proto) {
-  function compare(orig, compareTo, tolerance, cb) {
+  function compare(orig, compareTo, options, cb) {
     orig = utils.escape(orig);
     compareTo = utils.escape(compareTo);
 
     var isImageMagick = this._options && this._options.imageMagick;
     // compare binary for IM is `compare`, for GM it's `gm compare`
     var bin = isImageMagick ? '' : 'gm ';
-
+    var execCmd = bin + 'compare -metric mse ' + orig + ' ' + compareTo;
+    var tolerance = 0.4
     // outputting the diff image
-    if (typeof tolerance === 'object') {
-      var diffOptions = tolerance;
-      if (typeof diffOptions.file !== 'string') {
-        throw new TypeError('The path for the diff output is invalid');
+    if (typeof options === 'object') {
+      if (options.file) {
+        if (typeof options.file !== 'string') {
+          throw new TypeError('The path for the diff output is invalid');
+        }
+         // graphicsmagick defaults to red
+        var highlightColorOption = options.highlightColor
+          ? ' -highlight-color ' + options.highlightColor + ' '
+          : ' ';
+        var diffFilename = utils.escape(options.file);
+        // For IM, filename is the last argument. For GM it's `-file <filename>`
+        var diffOpt = isImageMagick ? diffFilename : ('-file ' + diffFilename);
+        execCmd += highlightColorOption + ' ' + diffOpt;
       }
-      // graphicsmagick defaults to red
-      var highlightColorOption = diffOptions.highlightColor
-        ? ' -highlight-color ' + diffOptions.highlightColor + ' '
-        : ' ';
-      var diffFilename = utils.escape(diffOptions.file);
-      // For IM, filename is the last argument. For GM it's `-file <filename>`
-      var diffOpt = isImageMagick ? diffFilename : ('-file ' + diffFilename);
-      var cmd = bin + 'compare' + highlightColorOption + orig + ' ' + compareTo +
-        ' ' + diffOpt;
-
-      return exec(cmd, function (err, stdout, stderr) {
-        // ImageMagick returns err code 2 if err, 0 if similar, 1 if dissimilar
-        if (isImageMagick && err && err.code === 1) {
-          err = null;
+      
+      if (options.tolerance) {
+        if (typeof options.tolerance !== 'number') {
+          throw new TypeError('The tolerance value should be a number');
         }
-        return cb(err, stdout, stderr);
-      });
-    }
+        tolerance = options.tolerance;
+      } 
+    } else {
+      // For ImageMagick diff file is required but we don't care about it, so null it out
+      isImageMagick && (execCmd += ' null:');
 
-    // else, output the mean square error (mse)
-    if ('function' == typeof tolerance) {
-      cb = tolerance;
-      tolerance = 0.4;
+      if (typeof options == 'function') {
+        cb = options; // tolerance value not provided, flip the cb place
+      } else {
+        tolerance = options
+      }
     }
 
-    var execCmd = bin + 'compare -metric mse ' + orig + ' ' + compareTo;
-    // For ImageMagick diff file is required but we don't care about it, so null it out
-    isImageMagick && (execCmd += ' null:');
-
     exec(execCmd, function (err, stdout, stderr) {
       // ImageMagick returns err code 2 if err, 0 if similar, 1 if dissimilar
       if (isImageMagick) {

test/compare.js

@@ -13,12 +13,14 @@ module.exports = function (gm, dir, finish, GM) {
 
       var options = {
         highlightColor: 'yellow',
-        file: dir + '/diff.png'
+        file: dir + '/diff.png',
+        tolerance: 0.001
       };
 
-      // Compare these images and write to a file.
-      GM.compare(dir + '/original.jpg', dir + '/noise3.png', options, function(err) {
+      // Compare these images and write diff to a file.
+      GM.compare(dir + '/original.jpg', dir + '/noise3.png', options, function(err, same) {
         if (err) return finish(err);
+        if (!same) return finish(new Error('Compare should be the same!'));
 
         fs.exists(options.file, function(exists) {
           if (exists) finish();