annotations -> labels; update README

README.md

@@ -1,14 +1,19 @@
 # display: a browser-based graphics server
 
-Original forked from [gfx.js](https://github.com/clementfarabet/gfx.js/).
+Originally forked from [gfx.js](https://github.com/clementfarabet/gfx.js/).
 
-The original goal was to remain compatible with the torch/python API of gfx.js,
+The initial goal was to remain compatible with the torch/python API of `gfx.js`,
 but remove the term.js/tty.js/pty.js stuff which is served just fine by ssh.
 
-I also wanted charts to resize properly when their windows are resized.
+Compared to `gfx.js`:
 
-A secondary goal was to simplify session management and store window positions
-so that after reloading the window everything remains where it was left.
+  - no terminal windows (no term.js)
+  - dygraphs instead of nvd3 (have built in zoom and are perfect for time-series plots)
+  - plots resize when windows are resized
+  - images support zoom and pan
+  - image lists are rendered as one image to speed up loading
+  - windows remember their positions
+  - implementation not relying on the filesystem, supports multiple simultaneous clients (sources)
 
 ## Technical overview
 
@@ -21,6 +26,22 @@ interprets these commands, e.g.
 
     { command: 'image', src: 'data:image/png;base64,....', title: 'lena' }
 
+### Supported commands
+
+Common parameters:
+  - `id`: identifier of the window to be reused (pick a random one if you want a new window)
+  - `title`: title for the window title bar
+
+`image` creates a zoomable <img> element
+  - `src`: URL for the <img> element
+  - `width`: initial width in pixels
+  - `labels`: array of 3-element arrays `[ x, y, text ]`, where `x`, `y` are the coordinates
+    `(0, 0)` is top-left, `(1, 1)` is bottom-right; `text` is the label content
+
+`plot` creates a Dygraph, all [Dygraph options](http://dygraphs.com/options.html) are supported
+  - `file`: see [Dygraph data formats](http://dygraphs.com/data.html) for supported formats
+  - `labels`: list of strings, first element is the X label
+
 ## Installation and usage
 
 Install via:

example.sh

@@ -1 +1 @@
-curl -d '{ "command": "image", "id": "mypane", "src": "example.png", "width": 400, "title": "example", "annotations": [[0.1, 0.15, "lena"], [0.7, 0.6, "fabio"]] }' http://127.0.0.1:8000/events
+curl -d '{ "command": "image", "id": "mypane", "src": "example.png", "width": 400, "title": "example", "labels": [[0.1, 0.15, "lena"], [0.7, 0.6, "fabio"]] }' http://127.0.0.1:8000/events

init.lua

@@ -73,7 +73,7 @@ function M.image(img, opts)
   local imgdata = 'data:image/png;base64,' .. mime.b64(file:read('*all'))
   file:close()
 
-  send({ command='image', id=win, src=imgdata, annotations=opts._annotations, width=opts.width, title=opts.title })
+  send({ command='image', id=win, src=imgdata, labels=opts._labels, width=opts.width, title=opts.title })
   return win
 end
 
@@ -98,23 +98,23 @@ function M.images(images, opts)
   end
 
   -- merge all images onto one big canvas
-  local annotations = {}
+  local _labels = {}
   local numrows = math.ceil(#images / nperrow)
   local canvas = torch.FloatTensor(maxsize[1], maxsize[2] * numrows, maxsize[3] * nperrow):fill(0.5)
   local row = 0
   local col = 0
   for i, img in ipairs(images) do
     canvas:narrow(2, maxsize[2] * row + 1, img:size(2)):narrow(3, maxsize[3] * col + 1, img:size(3)):copy(img)
     if labels[i] then
-       table.insert(annotations, { col / nperrow, row / numrows, labels[i] })
+       table.insert(_labels, { col / nperrow, row / numrows, labels[i] })
     end
     col = col + 1
     if col == nperrow then
       col = 0
       row = row + 1
     end
   end
-  opts._annotations = annotations;
+  opts._labels = _labels;
 
   return M.image(canvas, opts)
 end

static/panes.js

@@ -334,12 +334,12 @@ function ImagePane(id) {
   image.className = 'content-image';
   content.appendChild(image);
 
-  var annotations = document.createElement('div');
-  annotations.className = 'annotations';
-  content.appendChild(annotations);
+  var labels = document.createElement('div');
+  labels.className = 'labels';
+  content.appendChild(labels);
 
   this.content = image;
-  this.annotations = annotations;
+  this.labels = labels;
   this.width = 0;
   this.height = 0;
 
@@ -369,12 +369,12 @@ function ImagePane(id) {
 }
 
 ImagePane.prototype = extend(Object.create(Pane.prototype), {
-  resizeAnnotations: function() {
+  resizeLabels: function() {
     // TODO: can we use CSS transforms instead?
-    this.annotations.style.left = this.content.offsetLeft + 'px';
-    this.annotations.style.top = this.content.offsetTop + 'px';
-    this.annotations.style.width = this.content.offsetWidth + 'px';
-    this.annotations.style.height = this.content.offsetHeight + 'px'
+    this.labels.style.left = this.content.offsetLeft + 'px';
+    this.labels.style.top = this.content.offsetTop + 'px';
+    this.labels.style.width = this.content.offsetWidth + 'px';
+    this.labels.style.height = this.content.offsetHeight + 'px'
   },
 
   reset: function() {
@@ -384,7 +384,7 @@ ImagePane.prototype = extend(Object.create(Pane.prototype), {
     c.style.top = '';
     c.style.width ='';
     c.style.height = '';
-    this.resizeAnnotations();
+    this.resizeLabels();
     this.width = this.content.width;
     this.height = this.content.height;
   },
@@ -404,7 +404,7 @@ ImagePane.prototype = extend(Object.create(Pane.prototype), {
                            Math.max(20 - content.offsetWidth, left)) + 'px';
     content.style.top = Math.min(el.offsetHeight - 18 - 20,
                           Math.max(20 - content.offsetHeight, top)) + 'px';
-    this.resizeAnnotations();
+    this.resizeLabels();
   },
 
   zoom: function(ev) {
@@ -431,15 +431,15 @@ ImagePane.prototype = extend(Object.create(Pane.prototype), {
     var self = this
       , content = this.content;
 
-    var drag = {
-      left: content.offsetLeft  - ev.pageX,
-      top: content.offsetTop - ev.pageY,
+    var anchor = {
+      x: ev.pageX - content.offsetLeft,
+      y: ev.pageY - content.offsetTop,
     };
 
     content.style.cursor = 'move';
 
     function move(ev) {
-      self.moveContent(drag.left + ev.pageX, drag.top + ev.pageY);
+      self.moveContent(ev.pageX - anchor.x, ev.pageY - anchor.y);
     }
 
     function up(ev) {
@@ -454,23 +454,23 @@ ImagePane.prototype = extend(Object.create(Pane.prototype), {
     on(document, 'mouseup', up);
   },
 
-  setContent: function(src, width, annotations) {
+  setContent: function(src, width, labels) {
     this.content.src = src;
     if (width) {
       this.content.width = width;
     } else {
       this.content.removeAttribute('width');
     }
-    this.annotations.innerHTML = '';
-    annotations = annotations || [];
-    for (var i = 0; i < annotations.length; ++i) {
-      var a = annotations[i];  // [x, y, text]
+    this.labels.innerHTML = '';
+    labels = labels || [];
+    for (var i = 0; i < labels.length; ++i) {
+      var a = labels[i];  // [x, y, text]
       var ae = document.createElement('div');
-      ae.className = 'annotation';
+      ae.className = 'label';
       ae.style.left = a[0] < 1 ? (a[0] * 100 + '%') : (a[0] + 'px');
       ae.style.top = a[1] < 1 ? (a[1] * 100 + '%') : (a[1] + 'px');
       ae.innerHTML = a[2];
-      this.annotations.appendChild(ae);
+      this.labels.appendChild(ae);
     }
   },
 });
@@ -527,7 +527,7 @@ var Commands = {
   image: function(cmd) {
     var pane = getPane(cmd.id, ImagePane);
     if (cmd.title) pane.setTitle(cmd.title);
-    pane.setContent(cmd.src, cmd.width, cmd.annotations);
+    pane.setContent(cmd.src, cmd.width, cmd.labels);
   },
 
   plot: function(cmd) {

static/style.css

@@ -101,11 +101,11 @@ button:hover {
   overflow: hidden;
 }
 
-.annotations {
+.labels {
   position: absolute;
 }
 
-.annotation {
+.label {
   position: absolute;
   background-color: rgba(0, 0, 0, 0.7);
   color: rgba(255, 255, 255, 0.7);