RiverWare 6.7 Development -- Output Canvas Flow Lines / Dec. 2014
Phil Weinstein, David Neumann, Edie Zagona, CADSWES -- edit 12-31-2014

1. Overview
2. Flow Line Group Creation and Configuration
3. Flow Line Creation and Configuration
4. Flow Line Display Features
5. Flow Line Operations
6. Setting the Flow Line Group's Maximum Value
7. Some Possible Flow Line and Output Canvas Enhancements

(1) Overview

This document describes the Output Canvas' Flow Line capabilities developed through December 2014. This is beyond the Output Canvas capabilities delivered with RiverWare 6.6 which includes Teacups and Teacup Legend, Text Items and Images.

This Flow Line development represents a subset of Flow Line features described in this design document:

RiverWare Output Canvas: Tea Cup and Flow Animations: Design 3 [31 pp.]
R:\doc\Output\OutputCanvas\2014\OutputCanvDesign3-2014-08-25.docx

Basic flow line features include:

1. Creation of multiple flow line groups and flow lines.
   • A set of new flow lines can be added to a flow line group in a single operation using a GUS object selection.
   • Flow lines are initially placed within the canvas at a location based on the flow line's simulation object within the simulation view.
2. A flow line is a single line segment drawn on the output canvas.
   • Draggable "anchor point" icons are shown at each end when the flow line is selected.
   • The flow line itself is also draggable.
   • Flow lines are currently always black.
3. Each flow line has a single slot references defined with:
   1. a simulation object name defined within each flow line.
   2. a local slot name defined within the flow line group, default: "Outflow".
4. Flow line thickness depicts the absolute magnitude of the slot -- at the output canvas' reference timestep -- relative to all flow lines within the group. The thickness is interpolated using these flow line group settings:
   • Minimum Thickness
   • Maximum Thickness
   • Minimum Value. Values at or below this value are drawn with the minimum thickness.
   • Maximum Value. Values at or above this value are drawn with the maximum thickness.
5. In the Output Canvas configuration dialog, flow line tree items support these context menu operations: Copy/Cut/Paste/Delete, Move Up/Down, Open Object.
6. In the canvas (both the configuration preview and in the output canvas viewer), flow lines support these context menu operations: Open Object, Open Slot, Plot Slot, Configure -- PLUS the following operations on the all flow lines within the containing flow line group: Show Slots in New SCT, Plot Slots, and Configure Group.

"Design 3" flow line features which were NOT implemented include:

1. Flow line color and line style depicting magnitudes relative to each flow line's channel's "capacity" or associated guide curves. The current design calls for user specification of lists of "flow intervals" with display attributes defined within the flow line group and "thresholds" defined within each flow line.
2. Attachment behaviors of flow line anchor points; snapping.

(2) Flow Line Group Creation and Configuration

In an Output Canvas (output device) created from the RiverWare Output Manager dialog, a flow line group can be created in these two ways in the Output Canvas Configuration dialog:

1. With the "Flow Line Group" item selected in the "Add Item" option menu, and the "General Settings" (top-most) tree item selected within the Output Canvas Content tree, click the green plus ("+") button, or:
2. With the context menu on the General Settings (top-most) tree item: Add Item >> Flow Line Group.

Either of the operations above create a new Flow Line Group item. With that new item selected within the Output Canvas Content list, the group's default settings are shown in the settings panel; see image to the right.

The slots associated with the flow lines within a flow line group must have the same unit type and local slot name (e.g. "Outflow"). These slots can be on different object types (e.g. Reservoirs and Reaches), as long as each of those object types have a slot with the specified local slot name.

Double clicking on the Unit Type value shows a unit type combo box for the selection of the desired unit type; generally "Flow" will be appropriate (the default).

Double clicking on the Slot Name value allows direct entry of a slot name. Also, an ellipsis button is shown which brings up a slot name selector with slot names represented within the existing slots of the model. Notice that the currently configured slot name is shown in parenthesis after the flow line group's name in the Output Canvas Content tree.

Instead of basing a group's flow line's slot references on the main simulation object associated with the flow line, slots on associated data objects can instead be used. This is done by changing the Flow Line Group's Slot Reference Type from "Object / Slot Name" to "Data Object / Slot Name", as illustrated below.

As mentioned in the overview, each flow line's thickness is computed as an interpolation based on minimum and maximum values and thicknesses. The maximum value should be devised in relationship to the maximum values (generally, flows) among all flow lines in the group.

• Note that there is no expectation that all encountered series values will be within the "Minimum / Maximum Value" range. It's just that flow line thickness for values outside that range will be "clipped" at the respective configured Minimum or Maximum Thickness.
• See also the subsequent section on Setting the Flow Line Group's Maximum Value.

(3) Flow Line Creation and Configuration

Multiple flow lines can be created within any flow line group in these two ways in the Output Canvas Configuration dialog:

1. With the "Flow Line" item selected in the "Add Item" option menu, and a flow line group selected within the Output Canvas Content tree, click the green plus ("+") button, or:
2. With the context menu on a Flow Line Group tree item: Add Item >> Flow Line.

Either of the operations above shows the (GUS) Simulation Object selector. Multiple objects can be selected; a flow line item will be created for each selected object at a heuristically devised location (based on the location of the selected SimObj within the simulation view).

Selecting a flow line either in the Output Canvas Content tree or within the canvas preview causes that flow line's anchor points to become visible. The flow line may be repositioned by dragging the anchor points or the flow line itself.

A flow line's Label setting is initialized to the name of the Reference Object (from which the flow line was created). The label can be changed by the user, but it is currently used only within the configuration dialog's Output Canvas Content tree; the label text does not currently appear in the Output Canvas.

The "Reference Data Object" in the flow line configuration is used only if "Data Object / Slot Name" is selected in the containing flow line group's Slot Reference Type setting; see the previous section. If that is used, the configured slot name is expected to be on the Reference Data Object instead of the Reference Object. A flow line's Reference Data Object setting is initialized to the name of a data object whose name starts with the name of the picked Reference Object, if one is found. Otherwise it is set to the Reference Object's name with "Data" appended (preceded by a space character).

Flow line configuration errors are displayed in the configuration dialog's Log tab, for example:

(4) Flow Line Display Features

Flow lines are currently always drawn as solid black line segments. (Color and line style are being reserved for a future capability to convey a different value-quality than does line thickness). A flow line's thickness is computed from value and thickness interpolation settings defined within the containing flow line group, as described above.

A flow line's tooltip shows the name of the associated slot (generally a series slot, generally having "flow" units).

The single selected flow line has these ornaments:

1. A dotted bounding rectangle around the flow line.
2. (Only in the canvas preview, with item positions unlocked): donut dingbats with a transparent center around the flow line's two endpoints.

Flow lines are drawn under teacups, images and canvas text items, though teacups and images can be partially transparent, in which case the flow line will "show through" those items. Flow line anchor points are always drawn on top; see the accompanying image.

There is currently no direct support for showing RiverWare simulation object icons at the ends of flow lines, but user-supplied image icons (with the possibility of those being the the normal object icons) can be used for this purpose. (Note that each image is stored as image data within the output device, inside the RiverWare model. So this approach does increase the model size).

Flow lines don't currently display any text -- neither their label text nor their current value. But text items can be independently created and placed near flow lines. See two examples of this below.

(5) Flow Line Operations

Flow lines support a context menu with the following operations.

1. Open Object -- show the open object dialog for the flow line's reference object.
2. Open Slot -- show the flow line's associated slot (generally a series slot).
3. Plot Slot -- show a new plot page with a single plot showing the flow line's associated slot.

... plus a "Flow Line Group" submenu with the following operations. These operations apply to all flow lines in the same flow line group (i.e. the clicked flow line's sibling flow lines).

4. Show Slots in new SCT -- show a new SCT with one column (or row, depending on the default SCT configuration) for each flow line's series slot. See an example of this in the next section ("Setting the Flow Line Group's Maximum Value").
    
5. Plot Slots -- show a new plot page with a single plot with all of the flow lines' associated slots.
    
   • Note that, with the current RiverWare plot output device, there is limited support for a set of series slots having different units. Up to two different units can be represented, and those two units are mapped to the two vertical axis (left and right) -- even if those two units are of the same unit type (e.g. cfs and acre-feet/month -- both being "flow" units). So a plot generated from a set of flow lines will be misleading, and possibly incomplete, if the current unit scheme has different display units for the various flow line slots. A warning message will be shown if slots are dropped from the plot because more than two units are already represented.

(6) Setting the Flow Line Group's Maximum Value

As mentioned above, flow line thickness is computed using interpolation settings: minimum and maximum slot values which are mapped to minimum and maximum flow line thicknesses (in pixels). A reasonable minimum value is 0.0. The maximum value should be chosen which exceeds most slot values among all flow lines in the flow line group in the full time series. One way to come up with a good maximum value for a flow line group is illustrated below. This involves these steps:

1. From a context menu on any of the flow lines within the flow line group, pick "Flow Line Group >> Show Slots in new SCT...".
2. In the resulting SCT, select all cells. (This can be done with a single click in the top-left corner of the series data table).
3. In the selection statistics along the bottom of the SCT, notice the "Max" value.
4. Enter a number somewhat less than that maximum value in the Flow Line Group's "Maximum Value" settings.

Note: When an SCTs selection includes values with more than one unit (but only of a single unit type), the selection statistics are shown in the first encountered unit. This worked out well in the example illustrated below because the first slot had the desired units ("1,000 acre-ft/month"). The user may have to move a slot of the desired units to the first slot position (SCT row or column) in order to show selection statistics in those units. (It's easiest to change the order of series slots in an SCT by using the Edit Series Slot List tab).

(7) Some Possible Flow Line and Output Canvas Enhancements

Flow Lines

1. Flow lines should be poly-lines. Currently, flow lines have just two points. (They are line segments). Additional vertices could be managed graphically (e.g. through context menus on the canvas flow line and flow line anchor points). Vertex coordinate persistence should no longer be implemented through rwSettings since rwSettings don't currently support arrays (and the user doesn't need to numerically see or edit vertex coordinates anyway). Similarly, it should be possible to extend a flow line with a sequence of clicks (e.g. along a river bed on a map image).
    
2. Anchor point "attachment" behaviors / "snapping" are needed.
    
3. There seems to be a requirement for more flexibility in flow line slot reference composition. There are several ways of accomplishing this. (We should look at some representative realistic use cases).
    
4. We may want to devise a way of showing simulation object icons on the canvas -- in a way which is more convenient and efficient than using user-supplied image items.

Output Canvas

1. Remove explicit Slot Reference Type rwSettings -- i.e. "Object / Slot Name" vs. "Data Object / Slot Name". We could just automatically search both (when defined and valid) for the required slot name. (This is currently the most confusing setting type among the various output canvas configuration objects). This provision is slightly less expressive: it wouldn't be possible to use a slot on the associated Data Object which had the name of a physical slot on the reference object (e.g. "Outflow").
    
2. Multiple Item Selection, both in the configuration object tree and the canvas. (The selections should be at least partially synchronized, as is the current single item selection). The copy/paste buffer (for output canvas configuration objects) should be expanded to support a list of objects. There are many potential use cases for this enhancement, including managing multiple versions of large numbers of output canvas objects.
    
   • The simplest thing to do for the rwSetting panel would be to display a rwSetting list only when exactly one canvas configuration node is selected. This would be equivalent to the current level of rwSettingTree support.
   • A more advanced approach is presenting only those settings which are common to multiple selected nodes, displaying a value only if it is common to all nodes, and setting all values to a common value upon entry. This would require enhancements to rwSetting and rwSettingTree.
      
3. Available Animation Rates may be too limited -- especially for long time series. One possibility is adding an "animation frame timestep count" (which is currently, effectively, 1). That is, the number of timesteps to advance on each animation frame.

Teacups

1. It may be desirable to support the specification of a teacup's maximum value as a teacup setting.
    
   • The current default algorithm obtains the maximum volume value from the "storage" column in the last row of the object's Elevation Volume Table slot (if the object has such a slot, as do reservoirs). The problem with this is that, for numeric stability, that table is often significantly, arbitrarily extended.
   • The practical alternative is to provide the object's maximum value in a user scalar slot on a data object associated with the reservoir object. That's a lot of work for the user, and unless there are other potential uses for that Max Storage value, it would be simpler for the user to configure that right in the teacup.
   • Note that the maximum value is displayed in the teacup graphic, so its value can readily be confirmed by the user.
   • Technical: A direct way to support this would require an rwSetting enhancement outlined below ("rwSetting conditioning should be extended to a parent node's rwSetting list"). This is needed at least to make available the teacup group's configured unit type to the setting tree for each teacup.

Text Groups

1. Text Groups could have an option to force all slot values to be displayed with the current unit scheme's default display attributes (units and precision) for the value's unit type -- instead of the display attributes specifically configured for the particular slot.
    
   • The lack of that option (or only implemented behavior) shows up in Reservoir Outflow flow lines in the 24 Month Study regression test example. Notice that there are three different scale/units represented in the text items shown in this screenshot -- cfs, acre-feet/month and 1000 acre-feet/month -- http://cadswes2.colorado.edu/~philw/2014/TeaCup/Dec2014/2014-12-26/FlowLinesText-24MonthStudy.png

rwSettings

1. Usability issue: Generally, the Output Canvas Preview is immediately updated when changing a setting. But "Enumerated Type" settings (supported with an option menu or "combo box") don't take effect when the user chooses a new value item. The user must click away from the option menu for the change to be reflected in the preview.
    
   • Note: This enhancement was implemented as the solution to Gnats 5476 (1-22-2015).
    
2. rwSetting conditioning should be extended to a parent node's rwSetting list -- i.e. not just limited to the sibling settings within the same node. The rwSettingTree constructor could be passed a 2nd rwSetting list for rwSetting conditioning. It might be sufficient to pass just that 2nd list to rwSettingTree editor widget constructors, and to all rwSetting methods which take a "siblings" list.
    
   Such conditioning is currently used for:
   • conditionally showing an rwSetting, based on the value of a "sibling" rwSetting.
   • retrieving display attributes (units and precision), based on the value of a "sibling" rwSetting for either a slot instance or a unit type.

Plots

1. As mentioned in the description of the "Flow Line Group >> Plot Slots" context menu operation, if more than one unit is represented among the set of slots being plotted, the second unit is plotted along the right-side axis, and slots having neither of the two first units are dropped from the plot. This happens even if various represented units are of the same unit type! Note that when two units having the same unit type are represented, the vertical scales are unrelated, so the plot data is very misleading. This is exacerbated by the fact that you can't tell which curves (slots) correspond to which vertical axis (left and right). We should consider folding all slots having the same unit type into a single vertical axis using one of the represented units -- perhaps giving preference to the default unit for the particular unit type with respect to the currently active unit scheme.

--- (end) ---