Quick Links


Getting Started

Getting SigPlot · Instantiating a Plot · Adding Data · Overlay_href · Streaming/Real-Time 1D · Streaming/Real-Time 2D · Notes on Streaming Data · Plotting Audio Buffers · Appearance · Mouse Events · Menu · Mouse Selection · Highlighting · Colorbar

Getting Sigplot

SigPlot is compatible with the following:

  • Nodejs
  • Webpack (instructions available for ES5 and ES6)
  • Browserify
  • React

Detailed instructions can be found in the Readme.

Instantiating a Plot

To instantiate a plot, you will need a placeholder for the plot in HTML.

<div id="plot"></div>

Sigplot requires that the html placeholder has a non-zero size, which can be ensured using CSS:

#plot {height: 400px; width: 600px;}

In JavaScript, you can create the plot using this placeholder.

plot = new sigplot.Plot(document.getElementById('plot'), {});

Back to Top

Adding Data

To add data, a layer must be added. Every overlay function returns a layer. The following syntax can be used to plot an array called "data" on a plot called "plot":

plot.overlay_array(data);


SigPlot also supports the specialized BLUEFILE format.

plot.overlay_href('../../dat/sin.tmp');


Scrolling 2D data is typically implemented using overlay_pipe() then pushing data onto the plot in some sort of loop.

plot.overlay_pipe({
    type: 2000,
    subsize: 16384
});


plot.push(data_layer, data);

Overlay_href

The underlying HTTP request for overlay_href is handled asynchronously. If you want to take an action when the layer has been downloaded, use the onload callback.

plot.overlay_href('../../dat/sin.tmp', function(hdr, layer_n) {
    console.log("Finished overlay");
});


If you make two overlay_href() calls, the order is arbitrary. You can avoid this with the following:

//Use Immediately invoked function to create a closure
//so we can load files remotely, but keep the order
(function(p, files) {
    var do_next_overlay = function() {
        var f = files.shift();
        if (f) {
            p.overlay_href(f, do next_overlay);
        } else {
            p.rescale(); //we are done loading layers
       }
    }     do_next_overlay(); //kick things off
})(plot, ["../../dat/pulse.tmp", "../../dat/sin.tmp"]);


Back to Top

Streaming/Real-time
1D Plotting

For Layer1D, you can stream data to the plot by using the reload method.

plot_layer = plot.overlay_array(null, {
    xdelta: xdelta,
    xunits: 3,
    yunits: 26,
    size: fftsize / 2
});

//When new data comes in.
var data = [...];
plot.reload(plot_layer, data);


Streaming/Real-time
2D Plotting

For Layer2D, stream data to plot by using the overlay_pipe() method and push().

raster_layer = raster.ovrelay_pipe({
    type: 2000,
    subsize: fftsize / 2
    xdelta: xdelta,
    xunits: 3
});

//When new data comes in.
var data = [...];
raster.push(raster_layer, data);


Back to Top

Plotting Audio Buffers









  To plot audio, there are two options:

  • Convert the audio into a BLUEFILE on the server side and plot using overlay_href().
  • Convert the audio into an array using the new HTML5 AudioContext and plot using overlay_array().

The downside of the latter is that it only works with newer web-browsers. Users on Firefox and Safari will not see data in the plot on the right.



Back to Top

Appearance

Appearance for the plot above was set during instantiation:

plot = new sigplot.Plot(document.getElementById('plot'), {
  xi: true, //invert backrgound and foreground
  gridBackground: ["#fff", "#ddd"], //set a gradient background
  autohide_readout: true, //only show readout when mouse is over plot
  autohide_readout: true, //only show readout when mouse is over plot
  autohide_panbars: true //show panbars when necessary and mouse is over plot
});

Some appearance settings can be modified using the change_settings() method. For a complete list of settings that can be changed via the change_settings() method, refer to the functions documentation. For most settings, valid inputs are true, false, and null, which will toggle the setting. Other settings will allow other input, such as the the colors setting.

plot.change_settings( {invert: null}); //inverts colors
plot.change_settings( {show_x_axis: false}); //sets x-axis display
plot.change_settings( {cross: true}); //sets crosshairs
plot.change_settings( {colors: {fg: '#fff' } } ); //sets foreground

Mouse Events

To recieve "mtag" events, use theaddListener() method. The callback will be called whenever an "mtag" is emmitted; the event will always include an 'x' and 'y' value. Try clicking on the plot to see these values.

plot.addListener('mtag', function(event) {
  var elt1 = document.getElementById('mtagx');
  elt1.innerHTML = "X: " + event.x.toFixed(8);
  var elt2 = document.getElementById('mtagy');
  elt2.innerHTML = "Y: " + event.y.toFixed(8);
});


By default, clicking on the plot will trigger an "mtag". You can change the "mtag" mode via Cntrls... in the main menu or by using the change_settings() method.

plot.change_settings( {xcnt: "leftmouse"}); // mtag on left click
plot.change_settings( {xcnt: "continuous"}); // mtag on mouse movement
plot.change_settings( {xcnt: "disable"}); // disable the mtag (i.e. no events)


Back to Top

Menu

Custom Menu

By default, the main menu is accesible via middle-click. This can be disabled by setting the nomenu option to true.

plot = new sigplot.Plot(document.getElementById('plot'), {nomenu: true});

When the menu is disabled, a showmenu event will be emitted which can be used to provide a custom menu or take an alternate action. If you choose to display the custom menu where the main menu typically appears, you can use the 'x' and 'y' pixel locations emitted by the event. A hidemenu event will emit when the plot or a menu option is clicked that can be used to hide the menu.

Mouse Selection

In addition to zooming, the 'mouse-box' can be used to select an area on the plot by holding down CTRL while drawing a box. The "mtag" (see Mouse Events) emmited will include width and height. The default selection mode is "box", but this can be changed by modifying the rubberbox_mode variable.

plot.change_settings({rubberbox_mode: "vertical"}); //selects a y range
plot.change_settings({rubberbox_mode: "horizontal"}); //selects an x range
plot.change_settings({rubberbox_mode: "box"}); //default setting


Back to Top

Highlighting

SigPlot allows one or more x-ranges to be highlighted given a starting index, ending index, and alternate color. In the example above, highlighting is enabled with 'mouse-box' selection (hold down CTRL while selecting with mouse). Double-click to remove a highlight.

Basic higlighting can be added and removed with the following code:

plot.add_highlight(layer, {xstart: x1, xend: x2, color: "red"}); //add
//the following code clears all highlights
var highlights = hl_plot.get_layer(0).get_highlights();
for (var i = 0; i < highlights.length; i++) {
  var highlight = highlights[i];
  hl_plot.get_layer(0).remove_highlight(highlight)
}


Colorbar

By default, sigPlot has a small colorbar that is displayed with the readout along the bottom of the plot which shows the colormap used for the plot. When in 2D mode, (a raster is being displayed), an interactive large colorbar can be enabled.

The large colorbar can be displayed by either selecting "Large Colorbar" from the main menu under "Settings" or by using the change_settings method as shown below.

plot.change_settings({lg_colorbar: true});

By clicking the arrows above and below the colorbar, the colormap can be modified, updating the plot in real-time. This can be used to focus on certain characteristics of the plot.


Back to Top

PLUGINS

SigPlot's capabilities can be extended using the plugin mechanism. Plugins can draw on the plot, add to the menu, and interact with mouse events. SigPlot comes with some standard plugins in the sigplot.plugins.js file, but you may contribute others. To load the standard plugins, include the plugins file:

< script src="sigplot.plugins.js" > < /script >

A SigPlot plugin can be any JavaScript object. All methods are optional, but here is a common plugin:

MyPlugin = function(options) { /*Constructor*/ };

MyPlugin.prototype = {
  init: function(plot) { /*Called when the plugin is added to a plot*/ }
  dispose: function(plot) { /*Called when removed from a plot*/ }
  refresh: function(plot) { /*Called when the plugin needs to redraw*/ }
};
Back to Top

Slider

Sliders can be implemented individually or as pairs. These sliders are paired and the x-distance between them is shown when they are moved or clicked.

Back to Top

FUNCTIONS

An overview of the main functions used in SigPlot and their arguments.

sigplot.Plot · change_settings · overlay_href · overlay_array · overlay_pipe · overlay_websocket · push · get_layer · deoverlay · enable_listeners · disable_listeners · addListener · refresh · redraw
Back to Top