This is a planning page for the in-development Spectral Workbench API.

##Purpose##

The API (starting with the macro system, below) will make it possible for anyone to develop new functions, like:

* displaying a set of wavelengths (and their intensities) for, say, a contaminant you're looking for
* displaying a ratio of wavelength x to wavelength y -- say, for normalized differential vegetation index (NDVI)
* display intensity at 600nm and indicate intensity at 600nm for the last 10 measurements
* calling up, averaging, and displaying the average of all spectra [tagged with "oliveoil"](https://spectralworkbench.org/tag/oliveoil) or whatever
* graph intensity at wavelength X over time, for the past Y weeks
* save spectra periodically
* develop a better spectrum matching function (find nearest match)
* make a function which can auto-recognize a CFL spectrum and offer to auto-calibrate

##Macros##

We're going to start with a simple macro language, probably initially in a sandbox so people can try things out. We'll build out this language for a bit, let it stabilize, and then tackle the problems of publishing macros and sharing them amongst users. You can try the API out now (but not yet save macros) at https://spectralworkbench.org/capture

<a href="https://www.flickr.com/photos/jeffreywarren/8086861454/" title="Initial (very rough) interface for Spectral Workbench macros by jeferonix, on Flickr"><img src="https://farm9.staticflickr.com/8329/8086861454_9c18f2cdb7.jpg" width="500" height="257" alt="Initial (very rough) interface for Spectral Workbench macros"></a>

###Getting started###

To create a macro we'll have a simple editor you can enter JavaScript code into. At first you won't be able to save, and it'll just be a console "sandbox". The basic template will look something like this:

    setup: function() {
        // code to run on startup
        $W.add_button("My Button",function(){ do_something() })
      },
      draw: function() {
        // code to run every frame
      }

A very simple command to run in the macro console (works as of Oct 14 2012) would be:

    setup: function() { window.open($W.canvas.toDataURL(),'_newtab').focus()}

Which opens a new tab with the current image data as a PNG. For now, you can use any of the below variables and methods in a Javascript console such as found in Chrome, Safari, or Firebug on Firefox.

###Variables and methods###

A range of variables and methods will be available to use in your macros. To start with, you can read through the existing framework here: 

https://github.com/jywarren/spectral-workbench/blob/master/webserver/public/javascripts/capture.js

* **$W.data** - returns a nested array of wavelength/intensity pairs, as floats and integers between 0-255, respectively. Example to come; intensities are separated by R, G, and B channels.
* **$W.mode** - "rgb" or "average", i.e. whether we're currently looking at color channel data or the averaged "monochrome" data
* **$W.markers** - an array of markers at certain wavelengths, as input by the user. Later we'll make it easy to add new markers (see _upcoming_ section below)
* **$W.notify(string msg,string type,boolean expire)** - alert the user with a message (msg) of type "notify", "warning" or "error" shown in green, yellow, or red respectively. Defaults to expire = true, which means it disappears after 2 seconds.
* **$W.getIntensity(obj data,int x)** - Get the intensity from 0-255 for a given x-position in the video frame. Use as follows:

    $W.getIntensity($W.data[0].data,200) // fetches intensity for x-position of 200 px

* **$W.calibrate(id,x1,w1,x2,w2)** - calibrates the spectrum with id *id*, using wavelength/pixel pairs. Integer x1 is a position in the x-axis of the spectrum image (origin left) with a known wavelength position of (decimal) w1. x2 and w2 follow the same convention and the two positions are used to linearly interpolate the calibration. __Note that this occurs only on the server side, and if you have loaded a spectrum, it will not reflect the new calibration until you re-load it from the server.__
* **$W.saveSpectrum()** - saves the current spectrum of data and brings up the Save dialog.
* **$W.getWavelength(int col)** - returns wavelength as a decimal for the x-axis position given in "col"
* **$W.toggle_mode()** - switch from "rgb" to "average" mode or back
* **$W.show_rgb()** - switch from "average" to "rgb" mode
* **$W.show_average()** - switch from "rgb" to "average" mode
* **$W.add_spectrum(int id)** - fetches data from a spectrum with the given ID, and displays it in the graph for comparison
* **$W.excerptCanvas()** - returns a PNG (data url) of the current waterfall display image

###Upcoming variables and methods###

* **$W.add_button(string label,function action)** - adds a new button to the interface which has the given label and triggers the given action
* **$W.add_marker(string name,int wavelength)** - _not yet implemented_ - add a new marker to monitor the intensity at this wavelength. 

###Examples###

Please add your own if you like:

**Saving image data offline**

<script src="https://gist.github.com/3889063.js"> </script>