refactor identify and getters commands

identify getters now only use -verbose when necessary. -verbose is quite
slow when run on large (3MB) images. The -format option is a good
replacement for most cases.

This change causes a slight behavior change since previously all
getters used -verbose. The impacted getters are:

  format()
  depth()
  size()
  color()
  filesize()

These getters now use the -format option which is much faster but
may produce different results than previous releases. If you need
the old (slow) behavior for these properties, first use the full
`identify()` method and read the value afterward.

  var image = gm(img);
  image.identify(function (err) {
    console.log(image.data.format);
  })

closes #83

Author: aheckmann

lib/getters.js

@@ -8,88 +8,129 @@ module.exports = function (gm) {
 
   var proto = gm.prototype;
 
+  /**
+   * `identify` states
+   */
+
+  const IDENTIFYING = 1;
+  const IDENTIFIED = 2;
+
+  /**
+   * Map getter functions to output names.
+   *
+   * - format: specifying the -format argument (see man gm)
+   * - verbose: use -verbose instead of -format (only if necessary b/c its slow)
+   * - helper: use the conversion helper
+   */
+
   var map = {
-      'size': 'size'
-    , 'format': 'format'
-    , 'depth': 'depth'
-    , 'color': 'color'
-    , 'orientation': 'Orientation'
-    , 'res': 'Resolution'
-    , 'filesize': 'Filesize'
+      'format': { key: 'format', format: '%m' }
+    , 'depth':  { key: 'depth',  format: '%q' }
+    , 'filesize': { key: 'Filesize', format: '%b' }
+    , 'size':  { key: 'size', format: '%wx%h', helper: 'Geometry' }
+    , 'color': { key: 'color', format: '%k',  helper: 'Colors' }
+    , 'orientation': { key: 'Orientation', verbose: true }
+    , 'res':   { key: 'Resolution', verbose: true }
   }
 
+  /**
+   * Getter functions
+   */
+
   Object.keys(map).forEach(function (getter) {
     proto[getter] = function (opts, callback) {
       if (!callback) callback = opts, opts = {};
+      if (!callback) return this;
 
-      var key = map[getter]
+      var val = map[getter]
+        , key = val.key
         , self = this;
 
       if (self.data[key]) {
         callback.call(self, null, self.data[key]);
         return self;
       }
 
-      self.identify(opts, function (err, stdout, stderr, cmd) {
-        if (err) {
-          return callback.call(self, err, stdout, stderr, cmd);
+      self.bufferStream = !! opts.bufferStream;
+
+      self.on(getter, createListener(callback));
+
+      if (val.verbose) {
+        self.identify(opts, function (err, stdout, stderr, cmd) {
+          self.emit(getter, err, self.data[key], stdout, stderr, cmd);
+        });
+        return self;
+      }
+
+      var args = makeArgs(self, val);
+      self._exec(args, function (err, stdout, stderr, cmd) {
+        var result = (stdout||'').trim();
+
+        if (val.helper in helper) {
+          helper[val.helper](self.data, result);
+        } else {
+          self.data[key] = result;
         }
 
-        callback.call(self, null, self.data[key]);
+        self.emit(getter, err, self.data[key], stdout, stderr, cmd);
       });
 
       return self;
     }
   });
 
+  /**
+   * identify command
+   *
+   * Overwrites all internal data with the parsed output
+   * which is more accurate than the fast shortcut
+   * getters.
+   */
+
   proto.identify = function identify (opts, callback) {
     if (!callback) callback = opts, opts = {};
     if (!callback) return this;
 
     var self = this;
-    self.bufferStream = !! opts.bufferStream;
 
-    if (self._identifying) {
-      self._queue.push(callback);
+    if (IDENTIFIED === self._identifyState) {
+      callback.call(self, null, self.data);
       return self;
     }
 
-    if (Object.keys(self.data).length) {
-      callback.call(self, null, self.data);
+    self.on('identify', createListener(callback));
+
+    if (IDENTIFYING === self._identifyState) {
       return self;
     }
 
-    self._queue = [callback];
-    self._identifying = true;
+    self._identifyState = IDENTIFYING;
+    self.bufferStream = !! opts.bufferStream;
 
-    var args = [
-        'identify'
-      , '-ping'
-      , '-verbose'
-      , self.sourceStream ? '-' : self.source
-    ];
+    var args = makeArgs(self, { verbose: true });
 
     self._exec(args, function (err, stdout, stderr, cmd) {
       if (err) {
-        return callback.call(self, err, self.data, stdout, stderr, cmd);
+        self.emit('identify', err, self.data, stdout, stderr, cmd);
+        return;
       }
 
-      // parse response
-      var err = parse(stdout, self);
+      err = parse(stdout, self);
 
-      var i = self._queue.length;
-      while (i--) {
-        self._queue[i].call(self, err, self.data);
+      if (err) {
+        self.emit('identify', err, self.data, stdout, stderr, cmd);
+        return;
       }
 
-      self._identifying = false;
+      self.emit('identify', null, self.data);
+      self._identifyState = IDENTIFIED;
     });
 
     return self;
   }
 
   /**
-   * Parse Identify response frames
+   * Parses `identify` responses.
    *
    * @param {String} stdout
    * @param {Gm} self
@@ -162,7 +203,47 @@ module.exports = function (gm) {
   }
 
   /**
-   * helpers.
+   * Create an argument array for the identify command.
+   *
+   * @param {gm} self
+   * @param {Object} val
+   * @return {Array}
+   */
+
+  function makeArgs (self, val) {
+    var args = [
+        'identify'
+      , '-ping'
+    ];
+
+    if (val.format) {
+      args.push('-format', val.format);
+    }
+
+    if (val.verbose) {
+      args.push('-verbose');
+    }
+
+    args.push(self.sourceStream ? '-' : self.source);
+    return args;
+  }
+
+  /**
+   * Creates a listener function which calls `callback`
+   * with proper scope and arguments.
+   *
+   * @param {Function} callback
+   * @return {Function}
+   */
+
+  function createListener (callback) {
+    return function (err, data, stdout, stderr, cmd) {
+      return callback.call(this, err, data, stdout, stderr, cmd);
+    }
+  }
+
+  /**
+   * identify -verbose helpers
    */
 
   var helper = gm.identifyHelpers = {};

test/getterColor.js

@@ -8,20 +8,9 @@ module.exports = function (_, dir, finish, gm) {
   gm(dir + '/blue.gif').color(function (err, color) {
     if (err) return finish(err);
 
-    assert.equal(2, color)
+    assert.equal(1, color)
     assert.equal(this.data.color, color)
 
-    var blueWorks = this.data.Colors['0'] == '(  0,  0,255)\t  blue';
-    var blackWorks = this.data.Colors['1'] == '(  0,  0,  0)\t  black';
-
-    if (!blueWorks) {
-      blueWorks = this.data.Colors['1'] == '(  0,  0,255)\t  blue';
-      blackWorks = this.data.Colors['0'] == '(  0,  0,  0)\t  black';
-    }
-
-    assert.ok(blueWorks);
-    assert.ok(blackWorks);
-
     finish();
 
   });

test/getterDepth.js

@@ -8,13 +8,13 @@ module.exports = function (gm, dir, finish) {
   gm
   .depth(function getterdepth (err, depth) {
     if (err) return finish(err);
-    assert.equal(8, depth);
-    assert.equal(8, this.data.depth);
-
-    if (gm._options.imageMagick)
-      assert.equal('8-bit', this.data.Depth);
-    else
-      assert.equal('8 bits-per-pixel component', this.data.Depth);
+    if (this._options.imageMagick) {
+      assert.equal(16, depth);
+      assert.equal(16, this.data.depth);
+    } else {
+      assert.equal(8, depth);
+      assert.equal(8, this.data.depth);
+    }
     finish();
   });
 }

test/getterFilesize.js

@@ -10,7 +10,7 @@ module.exports = function (gm, dir, finish) {
     if (err) return finish(err);
 
     if (this._options.imageMagick) {
-      assert.ok(/7.79KB/.test(size));
+      assert.equal('7792B', size, size);
     } else {
       assert.equal(size, '7.6K');
     }
@@ -27,7 +27,7 @@ module.exports = function (gm, dir, finish) {
       if (err) return finish(err);
 
       if (this._options.imageMagick) {
-        assert.ok(/7.79KB/.test(size));
+        assert.equal('7792B', size, size);
       } else {
         assert.equal(size, '7.6K');
       }

test/getterFormat.js

@@ -9,7 +9,7 @@ module.exports = function (gm, dir, finish) {
     if (err) return finish(err);
 
     assert.equal(format, 'JPEG');
-    assert.equal(this.data.Format, 'JPEG (Joint Photographic Experts Group JFIF format)');
+    assert.equal(gm.data.format, 'JPEG');
 
     finish();
   });

test/getterIdentify.js

@@ -26,6 +26,7 @@ module.exports = function (_, dir, finish, gm) {
       assert.equal(d['Rendering intent'], 'Perceptual');
       assert.equal(d.Properties['date:create'], '2012-09-15T17:33:20-07:00');
       assert.equal(d.Properties['exif:DateTimeDigitized'], '2011:07:01 11:23:16');
+      assert.equal(d.Format, 'JPEG (Joint Photographic Experts Group JFIF format)');
 
     } else {
       assert.equal(d.Orientation, 'TopLeft');
@@ -38,8 +39,43 @@ module.exports = function (_, dir, finish, gm) {
       assert.equal(ex['GPS Info'], 558);
       assert.equal(ex['GPS Longitude'], '80/1,4970/100,0/1');
       assert.equal(ex['GPS Time Stamp'], '15/1,23/1,945/1');
+      assert.equal(d.Format, 'JPEG (Joint Photographic Experts Group JFIF format)');
+      assert.equal(d['Geometry'], '430x488');
     }
 
-    finish();
+    gif();
   });
+
+  function gif () {
+    var test = gm(dir + '/blue.gif');
+    if (im) test.options({ imageMagick: true });
+    test.identify(function (err) {
+      if (err) return finish(err);
+
+      if (im) {
+        assert.equal(1, this.data.color);
+
+        var blueWorks = this.data.Colormap['0'] == '(  0,  0,255) #0000FF blue';
+        var blackWorks = this.data.Colormap['1'] == '(  0,  0,  0) #000000 black';
+        assert.ok(blueWorks);
+        assert.ok(blackWorks);
+
+      } else {
+        assert.equal(2, this.data.color);
+
+        var blueWorks = this.data.Colors['0'] == '(  0,  0,255)\t  blue';
+        var blackWorks = this.data.Colors['1'] == '(  0,  0,  0)\t  black';
+
+        if (!blueWorks) {
+          blueWorks = this.data.Colors['1'] == '(  0,  0,255)\t  blue';
+          blackWorks = this.data.Colors['0'] == '(  0,  0,  0)\t  black';
+        }
+
+        assert.ok(blueWorks);
+        assert.ok(blackWorks);
+      }
+
+      finish();
+    });
+  }
 }

test/getterRes.js

@@ -8,6 +8,11 @@ module.exports = function (gm, dir, finish) {
   gm
   .res(function getterres (err, res) {
     if (err) return finish(err);
+    if (gm._options.imageMagick) {
+      assert.equal('72x72', res);
+    } else {
+      assert.equal('72x72 pixels/inch', res);
+    }
     assert.equal(res, this.data.Resolution)
     finish();
   });

test/getterSize.js

@@ -12,12 +12,6 @@ module.exports = function (gm, dir, finish, GM) {
     assert.equal(size.width, 460);
     assert.equal(size.height, 155);
 
-    if (gm._options.imageMagick) {
-      assert.equal(this.data.Geometry, '460x155+0+0');
-    } else {
-      assert.equal(this.data.Geometry, '460x155');
-    }
-
     GM(dir + '/identifyParseErr.jpg').size(function (err) {
       if (err) return finish(err);
       finish();