RiverWare Output Canvas: Tea Cup and Flow Animations: Functional Design
Phil Weinstein, David Neumann, CADSWES, 8-05-2014 (a) -- Initial Draft -- See Project Index
ORIGINAL REVIEW VERSION -- See Project Index for Latest Revision.

(0) Overview

This document presents a design for a new RiverWare "Output 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 Output Canvas output device may provide additional graphical features, such as incorporation of RiverWare Plot Page and Pie Chart output devices. Output 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-04-2014: Change from "Presentation Canvas" to "Output Canvas". Removal of canvas navigation / zooming features, and other simplifications.
• 8-05-2014: Minor: substantive typo fix: "Callouts ... are not currently supported". (But this decision is under review).

(0.2) Contents

1. Output Canvas
   1. Image Items
   2. Text Items
   3. General Output Canvas Configuration
   4. Additional Output 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. Output Canvas Configuration for Tea Cups
   2. Tea Cup Instance Configuration
   3. Other RiverWare Tea Cup Item Provisions
4. Flow Lines
   1. Output Canvas Configuration for Flow Lines
   2. Flow Line Instance Configuration
   3. Other RiverWare Flow Line Provisions
5. Supporting Dialogs

(1) Output Canvas

The Output 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 Output 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 Output Canvas output device is "workspace-like" in that it contains graphic objects which are selectable and draggable on top of an optional background image. In addition to the Tea Cup and Flow Line items described in detail in subsequent sections, the Output 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 Output Canvas has a configured size, in pixels. Zooming in or out is not supported. Scrollbars will be shown as needed (i.e. when the Output Canvas window is smaller than the configured size).

The Output Canvas supports "Edit" and "View" modes of operation which effects the available operations. For example, in "Edit" mode, double clicking on a Tea Cup opens its configuration dialog; in "View" mode, it opens the slot associated with its primary value entity. The locations of all graphical elements within the Output Canvas will generally be locked, but when unlocked, they 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 Output Canvas output device.

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 Output 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 three (3) Text Item Fonts within the Output Canvas from which one can be selected for any 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 Output 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) General Output Canvas Configuration Settings

Output Canvas configuration settings for the canvas' Tea Cups and Flow Lines are enumerated under the sections for those items (see below). Enumerated here are both general configuration settings for Image Items and Text Items:

1. Output Device Name
2. Canvas Size (width and height, in screen pixels).
3. Three (3) Text Item Fonts

(1.4) Additional Output Canvas Provisions

The Output 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 as Image...
   4. Duplicate...
   5. Print...
3. An "Edit" menu including:
   1. Configure... (show the Output Canvas configuration dialog).
4. 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

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 Output 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 Output Canvas. The following sections describe these configuration properties.

(3.1) Output Canvas Configuration for Tea Cups

All Tea Cups within a particular Output 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 Output 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 Output Canvas in which the Tea Cup Item is contained.

(3.3) Other RiverWare Tea Cup Item provisions:

1. Double clicking a Tea Cup item will either open its configuration dialog box or the Open Slot dialog for its "Current Value" slot, depending on the Edit/View mode of the Output Canvas.
2. 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.
3. 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.
   
4. Only a single uniform vertical scale is supported.
5. 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.
6. Callouts (illustrated in both examples above) are not currently supported.
7. Independent tooltips, showing slot names and value (as appropriate) are provided for these features:
   1. Maximum rectangle
   2. Current rectangle
   3. each horizontal marker
8. 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 Output Canvas has provisions for showing hidden tea cups).
   9. Delete (with confirmation).

(4) Flow Lines

"Flow Line" Output 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 illustrate 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 Output Canvas level. (All Flow Lines within a particular Output 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 Output Canvas.

The current Flow Line value is shown as numeric text along the drawn line using a font defined at the Output 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 Output 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 Output 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 Output Canvas. The following sections describe these configuration properties.

(4.1) Output Canvas Configuration for Flow Lines

General Flow Line configuration for all Flow Lines in a Output 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. The item label text (e.g. the name of a reach)
2. A reference to a particular series slot or AggSeries slot column in the model.
3. For the 2nd and subsequent "stages" defined in the Output 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:
   1. a location within the Output Canvas in which the Flow Line is contained,
   2. optionally, 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. Double clicking a Flow Line item will either open its configuration dialog box or the Open Slot dialog for its value slot, depending on the Edit/View mode of the Output Canvas.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 Output 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. Output Canvas Configuration Dialog
2. Tea Cup Item Configuration Dialog
3. Flow Line Item Configuration Dialog
4. Image Item Editor
5. Text Item Editor

--- (end) ---