Merge branch 'master' of github.com:szym/display

README.md

@@ -1,5 +1,9 @@
 # display: a browser-based graphics server
 
+A very lightweight display server for [Torch](http://torch.ch). Best used as a remote desktop paired with a terminal of your choice.
+
+Use a Torch REPL (e.g., [trepl](https://github.com/torch/trepl)) via SSH to control Torch and tell it to display stuff (images, plots, audio) to the server. The server then forwards the display data to (one or more) web clients.
+
 ## Installation
 
 Install for Torch via:
@@ -21,15 +25,33 @@ By default, the server listens on localhost. Pass `0.0.0.0` to allow external co
 
     th -ldisplay.start 8000 0.0.0.0
 
-See `example.lua` or `example.py` for sample usage.
+Then open `http://(hostname):(port)/` in your browser to load the remote desktop.
 
-    disp = require 'display'
-    disp.image(image.lena())
-    disp.plot(torch.cat(torch.linspace(0, 10, 10), torch.randn(10), 2))
+To actually display stuff on the server, use the `display` package in a Torch script or REPL:
 
-![](https://raw.github.com/szym/display/master/example.png)
+    -- Generic stuff you'll need to make images anyway.
+    torch = require 'torch'
+    image = require 'image'
+
+    -- Load the display package
+    display = require 'display'
+
+    -- Tell the library, if you used a custom port or a remote server (default is 127.0.0.1).
+    display.configure({hostname='myremoteserver.com', port=1234})
+
+    -- Display a torch tensor as an image. The image is automatically normalized to be renderable.
+    lena = image.lena()
+    display.image(lena)
+
+    -- Display a torch tensor as a graph. The first column is always the X dimension.
+    -- The other columns can be multiple series.
+    display.plot(torch.cat(torch.linspace(0, 10, 10), torch.randn(10), 2))
 
-> TODO: fill me in
+Each command creates a new window on the desktop that can be independently positioned, resized, maximized.
+If you want to reuse a window, pass the window id returned by each `image` or `plot` command as the `win` option.
+See `example.lua` or `example.py` for a bigger example.
+
+![](https://raw.github.com/szym/display/master/example.png)
 
 ## Development
 
@@ -57,7 +79,6 @@ See `example.lua` or `example.py` for sample usage.
 
 `audio` places raw audio content in an `<audio>` element
 
-
 ## Technical overview
 
 The server is a trivial message forwarder:

init.lua

@@ -52,6 +52,12 @@ local function normalize(img, opts)
   return img
 end
 
+-- Set the URL of the listening server
+function M.configure(config)
+  local port = config.port or 8000
+  local hostname = config.hostname or '127.0.0.1'
+  M.url = 'http://' .. hostname .. ':' .. port ..'/events'
+end
 
 function M.image(img, opts)
   -- options: