RiverWare Output Canvas: Tea Cup and Flow Animations: Functional Design
Phil Weinstein, David Neumann, CADSWES, 8-06-2014 -- Ready for Review -- See Project Index

(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

(0.2) Contents

  1. Output Canvas
    1. Image Items
    2. Text Items
    3. General Output Canvas Configuration
    4. Output Provisions
    5. 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 locations of all graphical elements within the Output Canvas will generally be locked, but when unlocked, they can be dragged to a different location. This is supported with a "Lock item positions" checkbox.

(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, generally contained within a RiverWare model file.

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:

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

The user can also add a slot reference to a text item. The slot's value (at the Output Canvas' reference timestep) and display units can be included within the Text Item using these magic text strings:

(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 general configuration settings for both Image Items and Text Items:

  1. Output Device Name
  2. Canvas Size (width and height, in screen pixels).
  3. Background Color
  4. Three (3) Text Item Fonts
  5. Flow Line Label Font

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

  1. Reference timestep date/time (most recently used value).

(1.4) Output Provisions

The Output Canvas can be exported as an image file (at a single reference timestep) or as an animated-image file. Supported still-image formats include PNG and JPEG. Image output dialog support is modeled on existing image export functions, for example, this dialog for exporting the workspace image:

      

The configured dimensions of the Output Canvas can be used, or can be overridden.

Note: Animated-image file export will be supported with the MPEG, AVI, MNG or MOV file format, or something similar. None of the utility libraries we are currently using (including Qt) support any sort of movie-file generation, so we will need to investigate the available software tools. We may be able to make use of the FFmpeg, Libav, MEncoder, or GStreamer tools, but this will require some integration work.

Output Canvas still images can be included in RiverWare model reports. The model report contains a reference to a particular Output Canvas (output device) instance saved in the model file. The reference timestep date/time, image width, and image height of the Output Canvas can either be used, or overridden in the model report configuration. The following detail shows a Pie Chart model report item's configuration within a model report.

      

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

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 Tea Cup Item also includes these text / numeric items:

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. Up to three (3) horizontal marker definitions:
    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).
  6. 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.
  7. Font selections:
    1. Tea Cup Label
    2. Numeric Fraction (Percentage) Text
    3. Scale Axis Value Text (at tick marks).
  8. 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 (up to 3) configured for Tea Cups at the Output Canvas:

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 open its configuration dialog box.
  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 currently 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. 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 two ways:

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
    3. a line style (solid, dashed, dotted)
  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 open its configuration dialog box.
  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. 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) ---