RiverWare Animated Tea Cup and Flow Elements: Requirements Analysis
Phil Weinstein, CADSWES, 7-30-2014

Overview

This document explores some initial ideas for a new animated data visualization tool in RiverWare to depict reservoir levels and relative flows. This new display will incorporate two dynamic graphical elements depicting various quantities at one moment in time:

1. Reservoir Tea Cup
2. Flow Element

A timestep slider with animation controls will allow the user to move these graphical elements to a new timestep within a designated time range, and optionally automatically step that timestep forward at a settable rate (as an animation or slide show).

Tea Cup Reference Example A visual tool on the California Department of Water Resources website provides a good example of the sort of Reservoir Tea Cup graphical element we would like to create.
Source: http://cdec.water.ca.gov/cdecapp/resapp/getResGraphsMain.action

This visually depicts these quantities:

• The capacity of the reservoir
• The current storage (volume) of the reservoir.
• The historical average storage for the reservoir (for the reference date).

The Tea Cup element also includes these text / numeric items:

• The name of the reservoir
• The current storage as a percentage of capacity
• The current storage as a percentage of historical average (for date).
• Several value points along the vertical (volume) scale.

The full map image depicts "callouts" -- lines connecting the tea cup image to a particular point within the map. (We will not be implementing this feature).

In the CDWR graphic, most reservoirs seem to share a common vertical (volume) scale. But some smaller-capacity reservoirs have a larger scale (e.g. see Pyramid Lake at the bottom of the graphic).

RiverWare Tea Cup Elements

One Tea Cup element can be shown for each reservoir in the model, optionally shown or hidden. Tea Cup elements can be dragged by the user to a new location within a Tea Cup View (see below).

Note: This proposal is for support of these three specific reservoir volume quantities: capacity, current storage, and historical average storage. A more generic approach is also possible -- allowing the user to provide labels and data sources for: (1) full value, (2) current value, (3) marker value. It's not clear that that level of generality would be preferable. A compromise would be to treat only the marker value generically, e.g. for a guide-curve value instead of historical average -- this possibility is not explored further in this document.

General Reservoir Tea Cup configuration settings for all tea cup elements in the model include:

1. Color selections for each graphical feature:
   1. Background bounding-rectangle color and opacity (0% to 100%).
   2. Background bounding-rectangle border color, and "show" option.
   3. Capacity color (rectangle background) ... default: Yellow
   4. Current storage color (rectangle background and font) ... default: Blue
   5. Historical average storage color (line and font) ... default: Red
   6. Axis lines and ticks color ... default: Gray
2. Font selections:
   1. Reservoir Label
   2. Percentage Text
   3. Volume Scale Legend

Reservoir Tea Cup instance configuration settings include identification of the data source for these features:

In addition to those instance configuration settings, tea cup instances support the following persistent state information:

1. Location within the Tea Cup View in which the tea cup element is contained.

Other RiverWare Tea Cup element provisions:

1. The width of tea cup elements will be the same for all instances, based on a hard-coded function of the selected Reservoir Label font.
2. The height of a tea cup element will be a function of both the selected Reservoir Label font (as above) and the capacity of the reservoir.
   
3. Only a single uniform vertical (volume) scale will be supported.
4. The vertical (volume) axis tick-marks will be placed automatically based on the Volume Scale Legend font. There will be tick marks at 0 (bottom) and the capacity (top), and usually a few at nice volume values in between. (See the reference example above).
5. Callouts will not be supported.
6. Independent tooltips, showing slot names and value (as appropriate) will be provided for these features:
   1. Capacity rectangle
   2. Current storage rectangle
   3. Historical average storage line
7. A context menu will be supported with these operations:
   1. Plot...
   2. Show slots in New SCT...
   3. Add slots to the open SCT...
   4. Open Object...
   5. Open Storage Slot...
   6. Open Historical Average Slot...
   7. Configure...
   8. Hide (note: the Tea Cup View will have provisions for showing hidden tea cups, see below).

Flow Elements

The second type of graphical element shown in Tea Cup Views is the Flow Element. (This is not depicted in the Tea Cup Reference Example, above). These are drawn as lines having a width, color and pattern indicating the magnitude of a flow value at a particular point in time.

Either end of a Flow Element can be "snapped to" a Tea Cup Element, or can be independently placed anywhere within the Tea Cup View. We will need to devise mouse interaction techniques for disambiguating the action associated with clicking and dragging a Tea Cup element or a proximate Flow element. Flow elements will need two or three draggable "hot spots" for positioning -- one at either end, and possibly a third in the middle for geometric translation (moving) which could also "un-snap" the Flow Element from Tea Cup Elements.

A Flow Element will have a reference to any single Flow-units series slot in the model. The current magnitude of the element's flow series (at the reference timestep) will be depicted in three ways:

• Negligable (near-zero) flows will be shown as dotted lines.
• The element's line color will reflect the relative flow magnitude -- relative to the expected values for the particular flow series (loosely referred to as "stage", below).
• The element's line thickness will reflect the absolute flow magnitude relative to all flows within the model.

General Flow Element configuration for all flow elements in the model includes:

1. Negligable (near-zero) flow tolerance (e.g. 2 cfs). Flows below this value will be shown with dotted lines.
2. Minimum line width [pixels, in normal zoom mode, default: 1].
3. Maximum line width [pixels, in normal zoom mode]
4. Maximum line width flow value (e.g. 500 cfs). Any flows exceeding this value will be drawn with the maximum line width.
5. Number of supported flow "stages" (one or more).
6. For each stage:
   1. an optional text label
   2. a line color

Flow Element instance configuration settings include:

1. A reference to a particular flow series slot in the model.
2. For the 2nd and subsequent "stages" defined in the general Flow Element configuration (see above), either:
   1. a particular absolute flow value (e.g. 100 cfs), OR
   2. a reference to a "stage guide curve" (loosely speaking), typically a periodic slot.

In addition to the instance configuration settings, flow element instances support the following persistent state information:

1. For each of the flow element's two ends, either:
   1. a location within the Tea Cup View in which the flow element is contained, OR
   2. a reference to a particular Tea Cup Element to which the flow element end is "snapped".

Other RiverWare Flow Element provisions:

1. Tooltip showing the slot name and value.
2. A context menu with these operations:
   1. Plot...
   2. Add slot to the open SCT...
   3. Open Slot...
   4. Configure...
   5. Hide (note: the Tea Cup View will have provisions for showing hidden tea cups, see below).

Tea Cup Views

An obvious approach is to show Tea Cups either in their own new RiverWare Workspace View or as a special mode of the existing Simulation (or maybe Geospatial) Views. However, we have decided to present Tea Cup Views as a new kind of Output Device so that muliple instances could be defined within a single RiverWare model. This would be a graphical Output Device, similar to a Plot Page or Pie Chart, and would, in fact, present the same timestep slider / animation control as currently supported for Pie Charts:

Even if deployed as an Output Device, the Tea Cup View would be "workspace view-like" in that simulation objects (reservoirs) would be represented as selectable, draggable graphical objects shown on top of an optional background image.

The Tea Cup View supports:

1. Multiple element selection (including extended-selection "shift" clicking and rubber-band selection), for operations on multiple items including:
   1. moving (by dragging, as a group),
   2. hiding
   3. plotting (up to nine).
2. A context menu including the following operations:
   1. Show manager ... (including managing the show/hide states of all resevoir tea cup and flow elements in a list view).
   2. Show all hidden tea cups
   3. Show all hidden flow elements
   4. Background Image...
3. A timestep slider, animation control (see above).

Supporting Dialogs

1. Tea Cup System Settings Dialog (global)
2. Tea Cup View Manager Dialog
3. Tea Cup Element Configuration Dialog
4. Flow Element Configuration Dialog

--- (end) ---