RiverWare Presentation Canvas: Tea Cup and Flow Animations: Functional Design
Phil Weinstein, David Neumann, CADSWES, 8-03-2014 (a) -- Initial Draft -- See Project Index

(0) Overview

This document presents a design for a new RiverWare "Presentation Canvas" output device which can be used to illustrate water storage levels and water flows over a period of time. The initial implementation supports the following graphical elements, including two animated components:

1. Images
2. Text Items
3. Tea Cups
4. Flow Lines

Subsequent development of the Presentation Canvas output device may provide additional graphical features, such as incorporation of RiverWare Plot Page and Pie Chart output devices. Presentation Canvases may eventually be deployable on the web. Those features are beyond the scope of this project.

(0.1) Document Status

• 7-31-2014: This initial draft is being submitted for review to confirm its scope and essential provisions. It does not yet present an actual user interface design to support the proposed functionality.
• 8-01-2014: "Flow Items" are now called "Flow Lines". They don't have to have "Flow" units, but all Flow Lines within a particular Presentation Canvas will have the same unit type.
• 8-01-2014 (b): Better writing for the Flow Line section (4), and mention of displayed text for Flow Lines.
• 8-02-2014 (a): Canvas navigation operations: zoom, hand drag, etc.
• 8-03-2014 (a): Minor edits, no substantive changes.

(0.2) Contents

1. Presentation Canvas
   1. Image Items
   2. Text Items
   3. Additional Presentation Canvas Provisions
2. Tea Cup Reference Examples
   1. California Dept. of Water Resources
   2. Bureau of Reclamation, Pacific Northwest Region Hydromet Program
3. Tea Cup Items
   1. Presentation Canvas Configuration for Tea Cups
   2. Tea Cup Instance Configuration
   3. Other RiverWare Tea Cup Item Provisions
4. Flow Lines
   1. Presentation Canvas Configuration for Flow Lines
   2. Flow Line Instance Configuration
   3. Other RiverWare Flow Line Provisions
5. Supporting Dialogs

(1) Presentation Canvas

The Presentation Canvas is a new RiverWare graphical output device. Existing graphical output devices include the Plot Page and Pie Chart. Similar to the Pie Chart device, the Presentation Canvas provides a timestep slider with animation controls to allow the user to move timestep-animatable items to different timesteps within a model data time range -- and to automatically step that timestep forward at a settable rate to present an animation or slide show.

The Presentation Canvas output device is "workspace-like" in that it contains graphic objects which are selectable and draggable on top of an optional background image. (Note that, as described below, image items -- of which there may be several -- all function as background images. There is no particular designated "background image."). In addition to the Tea Cup and Flow Line items described in detail in subsequent sections, the Presentation Canvas supports these graphical components and properties, similar to the existing support for these in the RiverWare Simulation Workspace View:

1. Image Items (usable as background images).
2. Text Items
3. Background Color (property).

The locations of all graphical elements within the Presentation View will generally be locked, but when unlocked, can be dragged to a different location.

(1.1) Image Items

Image Items can be created from basic image files (JPEG, PNG, GIF) and are saved (serialized) within the Presentation Canvas output device. They can be exported as PNG or JPEG files.

Image items support an adjustable opacity (0% to 100%). There is not explicit support for a particular "background image" (as there is with the Simulation View); all image items are drawn "under" the other three types of items described in this document. Partially transparent image items (less than 100% opacity) are effectively blended with the Presentation Canvas' configured background color.

(1.2) Text Items

Text Items can contain multiple lines of text with a single selectable color and font. Instead of picking a potentially unique font specification for each Text Item instance, the user defines a limited set of fonts within the Presentation Canvas from which one can be selected for a Text Item.

Text Items support several magic text strings which can be dropped in to the user supplied text in the Text Item Editor with push buttons or an action menu. These strings include:

• <timestep> -- the Presentation Canvas' reference timestep from the timestep slider/animation control.*
• <model> -- the RiverWare model name.
• <device> -- the Output Device name
• <date> -- the current date (wall calendar)
• <version> -- the RiverWare version

*In a sense, this provision makes the Text Item an "animated" component which needs to be updated each time a new "reference timestep date/time" is set.

(1.3) Additional Presentation Canvas Provisions

The Presentation Canvas supports:

1. Multiple element selection (including extended-selection "shift" and "control" clicking and rubber-band selection), for operations on multiple items including:
   1. moving (by dragging, as a group),
   2. hiding
   3. plotting
2. A "File" menu including:
   1. Import Configuration...
   2. Export Configuration...
   3. Export Image...
   4. Duplicate...
   5. Print...
3. An "Edit" menu including:
   1. Add Text...
   2. Add Image...
   3. Add Tea Cup...
   4. Add Flow Line...
   5. Configure... (show the Presentation Canvas configuration dialog).
4. A "View" menu including:
   1. Normal Zoom
   2. Zoom to Show All Items
   3. Zoom In [shortcut: Ctrl "+"]
   4. Zoom Out [shortcut: Ctrl "-"]
5. A context menu including:
   1. Add Text...
   2. Add Image...
   3. Add Tea Cup...
   4. Add Flow Line...
   5. Show all hidden Tea Cups
   6. Show all hidden Flow Lines
6. Navigation controls ... hand drag mode, rubber band zoom, etc.

Note: See also the context menus on Tea Cup and Flow Lines, described below. Generally, those operations apply to the full selected set of items.

(2) Tea Cup Reference Examples

Two examples of water resource tea cup graphics are provided here to help devise a design for RiverWare Tea Cup items.

(2.1) California Dept. of Water Resources 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 Item 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) axis.

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).

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).

(2.2) Bureau of Reclamation, Pacific Northwest Region Hydromet Program

Source: http://www.usbr.gov/pn/hydromet/burtea.html

In this particular map, there are three tea cup "profiles" -- for different ranges of reservoir capacities. But even within those that share the same profile, each tea cup apparently has its own scale.

The indicated flow ("cfs") text items are apparently independently placed (i.e. not implemented as part of the tea cup item).

Observation: this trapezoidal presentation is potentially ambiguous. Ostensibly storage volumes rather than pool elevations are depicted by the filled-in area. But it's not clear whether the height or the area of the filled-in area represents that volume. And certainly the height of that area doesn't accurately represent the pool elevation.

(3) Tea Cup Items

	CDWR Example

RiverWare Tea Cups are modeled primarily on the CDWR example presented above. They present:

1. Graphical representations of numeric values having a common unit (e.g. volume):
   1. A "maximum value" rectangular area
   2. A "current value" rectangular area
   3. Any number of "marker" horizontal lines (not just one)
2. Numeric labeled tick marks along the vertical axis
3. A tea cup item text label
4. Two optional fractions, presented as percentages below the text label.

Tea Cups are added to a Presentation Canvas on demand by the user. When adding a Tea Cup item, or any time thereafter, the user configures the item according to a tea cup configuration established for the Presentation Canvas. The following sections describe these configuration properties.

(3.1) Presentation Canvas Configuration for Tea Cups

All Tea Cups within a particular Presentation Canvas have a common configuration. This configuration includes:

1. A unit type (e.g. Volume).
2. Scale and unit specification, or an option to use the currently selected Unit Scheme scale and units for the selected unit type.
3. A Maximum Value Entity definition:
   1. Long Label text, e.g. "Total reservoir capacity"
   2. Short Label text, e.g. "capacity"
   3. A color selection
4. A Current Value Entity definition:
   1. Long Label text, e.g. "Current storage"
   2. Short Label text, e.g. "storage"
   3. A color selection
5. A number of horizontal marker definitions
6. For each horizontal marker definition:
   1. Long Label text, e.g. "Historic average level for date"
   2. Short Label text, e.g. "historic average"
   3. A color selection
   4. A line type (e.g. solid, dashed, dotted).
7. Left and Right Numeric Fraction (percent item), each having:
   1. Numerator Reference: choice of Current Value or one of the Markers.
   2. Denominator Reference: choice of Maximum Value, or Current Value.
   3. Tooltip Text.
   4. Note: the Color will be that corresponding to the Numerator Reference.
8. Font selections:
   1. Tea Cup Label
   2. Numeric Fraction (Percentage) Text
   3. Scale Axis Value Text (at tick marks).
9. Optional Tea Cup Bounding Box configuration:
   1. Background color and opacity (0% to 100%).
   2. Border color, and "show" option.

(3.2) Tea Cup Instance Configuration

Each Tea Cup item supports the following configurable properties. Note that all slot or slot column references must have the unit type specified at the Presentation Canvas level (see above):

1. The item label text (e.g. the name of a reservoir)
2. A "Total" value association: Either (a) an entered constant or (b) a reference to a Table slot and column reference. If the latter is selected, the value in the last row of that column used.
3. A "Current" value association: A slot or slot/column reference. (A column reference is used for multiple-column slots). Ordinary Table slots are excluded, but Periodic slots and TableSeries slots are allowed.
4. For each horizontal marker:
   • "Marker" value association: A slot or slot/column reference (with the same limitations as described above for the "Current" value association).

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

1. Location within the Presentation Canvas in which the Tea Cup Item is contained.

(3.3) Other RiverWare Tea Cup Item provisions:

1. The width of Tea Cup Items is the same for all instances, based on a hard-coded function of the selected Tea Cup Label font.
2. The height of a Tea Cup Item is a function of both the selected Tea Cup Label font (as above) and the item's "Total" value.
   
3. Only a single uniform vertical scale is supported.
4. The vertical axis tick-marks are placed automatically based on the Scale Axis font. There are tick marks at 0 (bottom) and the maximum (top), and usually a few at nice values in between.
5. Callouts are be supported (as are illustrated in the CDWR example).
6. Independent tooltips, showing slot names and value (as appropriate) are provided for these features:
   1. Maximum rectangle
   2. Current rectangle
   3. each horizontal marker
7. A context menu with the following operations. (Those which can reasonably be applied to multiple Tea Cups are applied to the multiple Tea Cup selection):
   1. Plot...
   2. Show slots in New SCT...
   3. Add slots to the open SCT...
   4. Open <object>... (shown only if the tea cup label is the name of a simulation object).
   5. Open Current Value Slot...
   6. Open <Marker> Slot... (one for each horizontal marker)
   7. Configure...
   8. Hide (note: the Presentation Canvas has provisions for showing hidden tea cups).
   9. Delete (with confirmation).

(4) Flow Lines

"Flow Line" Presentation Canvas items convey the magnitude of a series' value at the canvas' reference timestep using line width, color and pattern. (Neither of the two reference examples above illustate flow lines).

Generally, slots associated with Flow Lines have the flow unit type. But any single unit type can be used. This is configurable at the Presentation Canvas level. (All Flow Lines within a particular Presentation Canvas must have the same unit type).

A Flow Line has a reference to a single series slot (of the configured unit type) chosen by the user. The current magnitude of the element's series (at the reference timestep) will be depicted in three ways:

• Negligible (near-zero) flows are shown as dotted lines.
• The element's line color reflects the relative flow magnitude -- relative to the expected values for the particular series (loosely referred to as "stage", below).
• The element's line thickness reflects the absolute flow magnitude relative to all flows within the Presentation Canvas.

The current Flow Line value is shown as numeric text (somewhere) along the drawn line using a font defined at the Presentation Canvas for this purpose.

Either end of a Flow Line can be "snapped to" a Tea Cup Item or to the end of a different Flow Line or can be independently placed anywhere within the Presentation Canvas.

We will need to devise mouse interaction techniques for disambiguating the action associated with clicking and dragging a Tea Cup Item or a proximate Flow Line. Flow Lines 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 Line from other items.

Flow Line items are added to a Presentation Canvas on demand by the user. When adding a Line Item, or any time thereafter, the user configures the item according to a line item configuration established for the Presentation Canvas. The following sections describe these configuration properties.

(4.1) Presentation Canvas Configuration for Flow Lines

General Flow Line configuration for all Flow Lines in a Presentation Canvas includes:

1. A unit type (typically Flow).
2. Negligible (near-zero) tolerance (e.g. 2 cfs). Slot values below this value are shown with dotted lines.
3. Minimum line width [pixels, in normal zoom mode, default: 1].
4. Maximum line width [pixels, in normal zoom mode]
5. Maximum line width flow value (e.g. 500 cfs). Any flows exceeding this value will be drawn with the maximum line width.
6. Number of supported flow "stages" (one or more).
7. For each stage:
   1. an optional text label
   2. a line color
8. Flow text font (used for all Flow Lines in the canvas).

(4.2) Flow Line Instance Configuration

Flow Line instance configuration settings include:

1. A reference to a particular series slot or AggSeries slot column in the model.
2. For the 2nd and subsequent "stages" defined in the Presentation Canvas' Flow Line configuration (see above), either:
   1. a particular absolute value (e.g. 100 cfs), OR
   2. a reference to a "guide curve" sort of slot, typically a periodic slot.

In addition to the instance configuration settings, Flow Line instances support the following persistent state information:

1. For each of the Flow Line's two ends, either:
   1. a location within the Presentation Canvas in which the Flow Line is contained, OR
   2. a reference to a particular Tea Cup or other Flow Line to which the Flow Line end is "snapped".

(4.3) Other RiverWare Flow Line provisions:

1. Tooltip showing the slot name and value (when they are not shown as text on the canvas).
2. A context menu with the following operations. (Those which can reasonably be applied to multiple Flow Lines are applied to the multiple Flow Line selection):
   1. Plot...
   2. Add slot to the open SCT...
   3. Open Slot...
   4. Configure...
   5. Hide (note: the Presentation Canvas has provisions for showing hidden Flow Lines).
   6. Delete (with confirmation).

(5) Supporting Dialogs

These dialogs support the editing of configuration information described in the various sections above.

1. Presentation Canvas Configuration Dialog (global)
2. Tea Cup Item Configuration Dialog
3. Flow Line Item Configuration Dialog
4. Image Item Editor
5. Text Item Editor

--- (end) ---