added; gm.compare support

README.md

@@ -375,6 +375,38 @@ or clone the repo:
     - **write** - writes the processed image data to the specified filename
     - **stream** - provides a ReadableStream with the processed image data
 
+##compare
+
+Graphicsmagicks `compare` command is exposed through `gm.compare()`. This allows us to determine if two images can be considered "equal".
+
+Currently `gm.compare` only accepts file paths.
+
+    gm.compare(path1, path2 [, tolerance], callback)
+
+```js
+gm.compare('/path/to/image1.jpg', '/path/to/another.png', function (err, isEqual, equality, raw) {
+  if (err) return handle(err);
+
+  // if the images were considered equal, `isEqual` will be true, otherwise, false.
+  console.log('The images were equal: %s', isEqual);
+
+  // to see the total equality returned by graphicsmagick we can inspect the `equality` argument.
+  console.log('Actual equality: %d', equality);
+
+  // inspect the raw output
+  console.log(raw)
+})
+```
+
+You may wish to pass a custom tolerance threshold to increase or decrease the default level of `0.4`.
+
+
+```js
+gm.compare('/path/to/image1.jpg', '/path/to/another.png', 1.2, function (err, isEqual) {
+  ...
+})
+```
+
 ## Contributors
 [https://github.com/aheckmann/gm/contributors](https://github.com/aheckmann/gm/contributors)
 

index.js

@@ -123,6 +123,7 @@ require("./lib/command")(gm.prototype);
 
 module.exports = exports = gm;
 module.exports.utils = require('./lib/utils');
+module.exports.compare = require('./lib/compare');
 module.exports.version = JSON.parse(
   require('fs').readFileSync(__dirname + '/package.json', 'utf8')
 ).version;

lib/compare.js

@@ -0,0 +1,42 @@
+// compare
+
+var exec = require('child_process').exec;
+var utils = require('./utils')
+
+/**
+ * Compare two images uses graphicsmagicks `compare` command.
+ *
+ * gm.compare(img1, img2, 0.4, function (err, equal, equality) {
+ *   if (err) return handle(err);
+ *   console.log('The images are equal: %s', equal);
+ *   console.log('There equality was %d', equality);
+ * });
+ *
+ * @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 {Function} cb(err, Boolean, equality, rawOutput)
+ */
+
+module.exports = exports = function compare (orig, compareTo, tolerance, cb) {
+  orig = utils.escape(orig);
+  compareTo = utils.escape(compareTo);
+
+  if ('function' == typeof tolerance) {
+    cb = tolerance;
+    tolerance = 0.4;
+  }
+
+  exec('gm compare -metric mse ' + orig + ' ' + compareTo, function (err, stdout, stderr) {
+    if (err) return cb(err);
+
+    var match = /Total: (\d+\.?\d*)/m.exec(stdout);
+    if (!match) {
+      err = new Error('Unable to parse output.\nGot ' + stdout);
+      return cb(err);
+    }
+
+    var equality = parseFloat(match[1]);
+    cb(null, equality <= tolerance, equality, stdout);
+  })
+}

test/fromBuffer.js

@@ -0,0 +1,31 @@
+var assert = require('assert')
+var fs = require('fs')
+
+module.exports = function (_, dir, finish, gm) {
+
+  var original = dir + '/original.jpg';
+  var result = dir + '/fromBuffer.png';
+
+  var buf = fs.readFileSync(original);
+
+  gm(buf)
+  .rotate('red', 30)
+  .write(result, function crop (err) {
+    if (err) return finish(err);
+
+    // tolerance defaults to 0.4
+    gm.compare(original, result, function (err, equal) {
+      if (err) return finish(err);
+      assert.ok(equal);
+
+      // accepts tolerance argument
+      gm.compare(original, result, 0.1, function (err, equal, equality, raw) {
+        if (err) return finish(err);
+        assert.ok(!equal);
+        assert.ok(equality > 0.1);
+        assert.ok(raw);
+        finish();
+      })
+    })
+  });
+}