# DataTurbine Plot Utility

# rbnbPlot

# User Manual

## V2.51

## November 29, 2006

## Copyright 1999-2006, Creare Inc.

# Table of Contents

> ### Introduction

> > Overview
> > Setup and Startup

> ### Menu Bar

> > File

> > > Open RBNB
> > > Close RBNB
> > > Load Config
> > > Save Config
> > > Export to DataTurbine
> > > Exit

> > Mode

> > > Plot
> > > Table

> > Window

> > > Cascade
> > > Tile
> > > Manual

> > Help

> > > About

> ### Operation Controls

> > Playback Buttons
> > Position Slider
> > Duration Slider
> > Channel Selection
> > Display Groups

> ### Plot Configuration

> > Automatic Scaling
> > Manual Scaling
> > Zooming

> ### User Info Interpretation

# Introduction

## Overview

The rbnbPlot utility provides a graphical interface to numerical data in the DataTurbine. It functions much like a combination oscilloscope and strip chart recorder. It has both real-time monitoring and playback features. In fact, the transition between real-time and playback is completely seamless; simply "rewind" to review historical data while new information continues to stream into the DataTurbine. The following figure shows an example rbnbPlot display window.

Example rbnbPlot Display, Showing Text, StripChart, and Image Display Types

The rbnbPlot window is comprised of several functional areas:

> - Menu Bar for connecting, saving configuration, and setting operation mode
> - Operation Controls for selection of channels, data position and plot duration
> - Plot Configuration menus for plot axis scaling

## Setup and Startup

The rbnbPlot application needs to be run under a Java Virtual Machine (JVM). Different flavors of Java come by different names (e.g. java, jre, jview). See the Installation Guide which come with your software for how to setup a script or shortcut to execute rbnbPlot.

The rbnbPlot application has the following optional command-line arguments:

Option | Description
`-c` | Show channels with unknown point sizes (default is to hide them).
`-d duration` | Specify a startup time duration for the initial display of data (float).
-D max duration | Specify the maximum duration the slider will allow.
`-u time units` | Units for time (string). Default is 'Sec'.
`-r host:port` | Specifies DataTurbine to which to connect; defaults to none, use File/Open to connect.
`-k` | Attempts to kill DataTurbine when exiting rbnbPlot
`-p x,y` | Specify upper left corner of main window in pixels; default centers window on screen
`-s min,max,div` | Specifies manual scaling from min to max with div divisions
`-S` | "Start" mode, which forces rbnbPlot to start up in RT mode (versus paused mode)
`-w msec` | Specify number of extra milliseconds to sleep between real-time updates
`-n` | Allow RealTime Streaming
-g | Turn off gridline scrolling.
`-i` | Interpret 4 byte data values as integers (default is float)

Example:

> `java -jar plot.jar`

On startup or upon the initial opening of a connection to a DataTurbine, rbnbPlot attempts to:

> - Make a connection to the specified DataTurbine
> - Obtain a list of all available channels
> - Put 4 channels into each display group
> - Obtain a 'reasonable' amount of data for each channel in the first display group

The endpoints of the position slider reflect the earliest and latest available data. The default initial run mode is set to RT, so the plots automatically update as data becomes available.

# Menu Bar

The top Menu Bar has several pull-down menus, as described below.

## File

The File selection provides several functions, described below.

### Open RBNB

Opening a connection to the DataTurbine is required before data can be displayed. Provide the DataTurbine host name (or IP address) and port number. You should see confirmation of your connection in the rbnbPlot title bar, and the available channels will be listed in the channel selection panel.

### Close RBNB

This closes your current connection to the DataTurbine.

### Load Config

This function pops up a menu for loading previously-saved rbnbPlot configuration (see Save Config). Click OK and the display groups, channels, and scaling will be restored to the saved settings.

### Save Config

This function allows you to save your current rbnbPlot configuration. You need to give it a name by which it can be later recalled (see Load Config). Information regarding your channel selection, display groups and plot configuration is saved.

This information is saved as an DataTurbine channel. rbnbPlot recognizes configuration channels as special, and will not try to plot a configuration channel as data.

Saved configuration channels are not archived, and will be lost if the DataTurbine terminates.

### Export to DataTurbine

When rbnbPlot is connected to an RBNB Server, selecting "Export to DataTurbine" from the File menu pops up the Export to DataTurbine non-modal dialog box (shown above). In this dialog, specify the desired name of the exported source and whether the source should be archived. Hitting the Export button will copy the currently displayed channels to a new RBNB Source. What you see is what you get; i.e. the same data that is currently plotted is exported. Be warned that exporting a large amount of data can take a long time and use a large amount of system memory. After exporting, the new source is "detached", leaving it connected to the RBNB but not under rbnbPlot's control.

### Exit

This command exits the rbnbPlot program.

## Mode

Two display modes are provided, as described below.

### Plot

Plot mode is the default "strip chart" mode shown above. Each plot contains an annotated data trace.

### Table

Table mode displays numerical (versus graphical) information, as shown below.

Example rbnbPlot in Table Mode

Table mode displays the following columns of information, one row for each selected channel:

Name | Name of the selected channel
Units | Given units (if any) of the channel
First | Value of first data point for current interval
Last | Value of last data point for current interval
Min | Minimum data value for selected interval
Max | Maximum value in selected interval
Ave | Average of all values in selected interval
StdDev | Standard deviation of values in selected interval

## Window

The Window menu contains options that allows the user to specify the desired layout of the plot windows within the rbnbPlot viewing area. The user can select Cascade, Tile, or Manual.

### Cascade

Selecting the Cascade menu item cascades all plot windows, where plot windows are added in a stack with the title bars showing. When the user selects a new channel to display, a new plot window containing the data for this channel will be added to the cascade. Resizing the rbnbPlot window will not re-layout the individual plot windows. While in Cascade mode, the user may move and resize the individual plot windows as desired.

### Tile

Selecting the Tile menu item tiles all plot windows, where each plot window is fully exposed and all available space within the rbnbPlot viewing area is fully utilized. When the user selects a new channel to display, a new plot window containing the data for this channel will be added to the viewing area and all existing plot windows will be re-tiled to accomodate the new plot window. Resizing the rbnbPlot window automatically re-tiles the viewing area such that all plot windows will still be fully exposed in the new view. While in Tile mode, the user may move and resize the individual plot windows as desired, however as soon as the rbnbPlot window is resized, the plot windows will be automatically re-tiled.

### Manual

Selecting the Manual menu item specifies that no automatic layout should be performed on the plot windows when the rbnbPlot window is resized. When the user selects a new channel to display, a new plot window containing the data for this channel will be added in cascading fashion to the viewing area.

## Help

### About

Pops up an identification and version information window.

#

# Operation Controls

The top part of the rbnbPlot window contains a variety of operation controls. Refer to the example rbnbPlot screen above for reference.

## Playback Buttons

The top row of control buttons provide tapedeck-like position control:

`|<` | Go to beginning (oldest) of data.
`<` | Play continuously backwards. Press multiple times to go faster.
`<|` | Single-step one interval backwards.
`||` | Pause (stop) playback.
`|>` | Single-step one interval forwards.
`>` | Play continuously forwards. Press multiple times to go faster.
`>|` | Go to end (newest) of data.
`RT` | Real-time (continuous) update.

## Position Slider

The top of the two slider bars is an alternate way to set the data position (time). Pull it left or right until the desired time-stamp is displayed above the slider.

The Position information (above the Position slider) shows the time-stamp for either the oldest or newest displayed data, depending upon the condition. For real-time tracking (`RT`) and end-of-data (`>|`), the newest time-stamp (right edge of plotted data) is shown. For all other cases, the oldest time-stamp (left edge of the plotted data) is shown. A position may be typed or pasted into the textbox, and that data will be fetched and displayed when the return key is pressed.

## Duration Slider

The bottom of the two slider bars sets the length, or duration of the displayed data interval. Slide it left or right until the desired duration interval is displayed above the slider. The Duration information is displayed above the slider, and a new duration may be typed or pasted into the textbox. When the return key is pressed, that data will be fetched and displayed.

Note: Be careful when selecting long durations; it is possible under some circumstances to request very large amounts of data, which can take a long time to fetch and plot, or worse yet, cause an application to run out of memory.

## Channel Selection

The panel in the upper right of the rbnbPlot window is the channel selection box. Click it to pop up an independent, resizable channel selection window. Click n a channel to select or deselect it. Click Reset to deselect all channels. The following figure shows channels, three of which are selected for display.

Channel Selection Menu

In Tile mode, channels are displayed first in a single column of plot boxes, then in multiple columns, according to a built-in heuristic.

Even though all selected channels will be requested, rbnbPlot can only display data for three types of channels: image, text, and stripchart. Channels are displayed as images if the channel name ends with ".jpg" or ".jpeg". Channels are displayed as text if the channel name ends with ".txt" or ".text", or if the channel's MIME type begins with "text". All other channels are displayed as Stripchart channels, though data is displayed only for word lengths given in the table below.

Data Word Length | Presumed Data Format
2 Bytes | short integer
4 Bytes | single precision floating point
8 Bytes | double precision floating point

## Display Groups

The numbered buttons below the other operation controls (and above the display area) are Display Group selection buttons. Each display group has an associated selection of channels. You can pre-configure groups of channels in different display groups, then switch between them quickly at run-time.

Note: Some data source applications pre-configure display group information, and provide labels which automatically appear on the display group selection buttons.

# Plot Configuration

Mouse click on any of the display plots to bring up the following plot configuration window:

Example Plot Configuration Pop-Up Menu

## Automatic Scaling

You can select to either automatically or manually scale the data. The top AutoScale (increasing/decreasing) selection will update the Y-axis limits (up or down) every time new data is plotted.

The second AutoScale (increasing only) selection only updates the Y-axis limits when the plot scale increases. This latter choice is advantageous when rapidly changing plot scales would otherwise be distracting. You can also specify the initial plot limits and number of Y-axis divisions for this mode.

Autoscale (increasing only) is the default plot mode.

## Manual Scaling

The Manual Scaling option lets you set the number of divisions in the Y-axis, as well as the minimum and maximum Y-axis limits.

## Zoom

Dragging the mouse in a display plot will highlight the region selected. When the mouse is released, rbnbPlot will zoom in to that start and duration for all displayed channels, and update the position and duration information accordingly.
.

Dragging a Region to Specify Zooming

The Resulting Zoomed Display

# User Info Interpretation

When a data source has supplied User Info specifying units, scale, and/or offset, rbnbPlot applies this EU conversion prior to plotting the data, and the units are shown at the top of the ordinate axis. User Info must be in the form of key-value pairs, separated by commas. An example setting of user info for the ChannelMap cm and channel index 0 is
cm.PutUserInfo(0,"units=feet,scale=3.281,offset=0");
For the data shown above in the Zoom section, this User Info results in the display:
Data Converted from Meters to Feet via User Info