RiverWare Output Canvas: Teacup Storage and Flow Animation: Design 3
Phil Weinstein, David Neumann, Patrick Lynn, Edie Zagona, CADSWES, 8-25-2014 (e) -- 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 timestep-animated components:

1. Images
2. Text Items
3. Teacups
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

• 8-26-2014: Added detail about manipulating the ends of a Flow Line; see Section 2.5.
• 8-25-2014: Design 3, initially reviewed by David; review changes applied.
• 8-25-2014: David's Review of Design 3:
      R:\doc\Output\OutputCanvas\2014\ReviewNotes\Design3-Review-2014-08-25.docx / .pdf
• 8-22-2014: Outline of Design 2 to 3 Changes:
      R:\doc\Output\OutputCanvas\2014\ReviewNotes\ Design2-Review-2014-08-22.docx / .pdf
• Note [8-2014]: The Output Canvas support dialogs and graphics presented here are design mockups.

(0.2) Prior Design Versions

• 8-21-2014: Design 2: Initial Property Editor-based GUI design:
       R:\doc\Output\OutputCanvas\2014\OutputCanvDesign2-2014-08-21.docx / .pdf
• 8-07-2014: Design 1: Dialog-based GUI design:
       R:\doc\Output\OutputCanvas\2014\OutputCanvFuncDesign-2014-08-07.docx / .pdf

(0.3) Contents

1. Teacup Reference Examples
   1. California Dept. of Water Resources
   2. Bureau of Reclamation, Pacific Northwest Region Hydromet Program
2. Supported Graphics Objects
   1. Graphics Objects: Images
   2. Graphics Objects: Text Items
   3. Graphics Objects: Teacups
   4. Graphics Objects: Teacup Legends
   5. Graphics Objects: Flow Lines
3. Data Source Slot References
4. Output Canvas Configuration
   1. Output Canvas Object Tree
   2. Output Canvas "Add Item" Action Menu
   3. Output Canvas Preview Panel
   4. Settings: (General) Canvas Configuration
   5. Settings: Image Group
   6. Settings: Image
   7. Settings: Text Group
   8. Settings: Text Item
   9. Settings: Teacup Group
   10. Settings: Teacup Legend
   11. Settings: Bounding Box
   12. Settings: Marker Specification
   13. Settings: Teacup
   14. Settings: Flow Line Group
   15. Settings: Flow Interval Declaration
   16. Settings: Flow Line
   17. Settings: Flow Interval Threshold
5. Special Graphics Object Provisions
   1. Create Teacups Operation (Wizard)
   2. Create Flow Lines Operation (Wizard)
   3. Other Teacup Provisions
   4. Output Provisions
   5. Output Canvas in RiverWare Model Reports
6. Output Canvas Viewer

(1) Teacup Reference Examples

Two examples of water resource Teacup graphics are provided here to help devise a design for RiverWare Teacup items.

(1.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 Teacup 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 Teacup 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 Teacup 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).

(1.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 Teacup "profiles" -- for different ranges of reservoir capacities. Each Teacup apparently has its own scale. The indicated flow ("cfs") text items are apparently independently placed (i.e. not implemented as part of the Teacup 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.

(2) Supported Graphics Objects

Various types of Graphics Objects can be displayed on an Output Canvas -- a new form of graphical RiverWare output device. These Graphics Objects include:

1. Images
2. Text Items
3. Teacups
4. Teacup Legends
5. Flow Lines

Several of these objects graphically depict -- or display as text -- numeric values from slots in the model. Series slot values are indexed with a reference timestep provided by the canvas.

The following sub-sections summarize the capabilities and display options for these Graphics Objects. See also the configuration "Settings" sections for these objects later in this document.

(2.1) Graphics Objects: Images

Images are added to an Output Canvas by loading individual image files and are retained (as data) within the Output Canvas. Images can be displayed in the canvas with partial opacity. Particular images can be designated as "background images" which forces them to be painted "under" non-background images and changes their configuration behaviors.

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. The "Add Image" operation starts by showing an image file selection dialog to allow the user to pick an image file to be loaded.

Image items support an adjustable opacity (0% to 100%). Individual items can be designated as "background images". Doing so has the following effects:

• Background images are drawn under all other items (including non-background images).
• Background images do not support a context menu. When right-clicking on a background image, the canvas' general context menu is shown (e.g. for adding other types of items).

In the Output Canvas Configuration dialog's canvas preview panel -- but not in the Output Canvas Viewer -- Images (and all Graphics Objects) are movable on the canvas, by dragging. The configuration preview panel presents checkboxes for locking the positions of: (a) All background images, and (b) All other graphics objects.

(2.2) Graphics Objects: Text Items

Text Items can be individually placed anywhere within the canvas. Several Text Item Types are supported as outlined in the table below. Text items support the following features:

• Text items can have a single line or multiple lines of text.
• Text items have an independently selectable color.
• Text items belong to a particular Text Item Group or Teacup Group.
• These Groups have an associated Font (for text items).
• All but the "Plain" text item type support optional Prefix and Suffix text.
• All but the "Plain" text item type support some sort of dynamic data (e.g. one or two slot values).
• When numeric slot values are shown they are always presented with units.
• When adding the "first" Text Item (outside of a Teacup context), an initial "Text Items" group, with a default font, is automatically created.

Five (5) Text Item Types are supported:

Text Item Type Example T Notes 1 Plain CURRENT RESERVOIR CONDITIONS   Static text. Prefix and Suffix are not supported. 2 Timestep Ending at Midnight - July 29, 2014   Shows the canvas' reference timestep. Several date/time formats are supported. 3 One Slot Value ALPY 6435 cfs   4 Two Slot Values 97346 ft3 / 95180 ft3 The two values are separated with " / ". 5 Computed Fraction Palisades 67% Full The presentation of fractions as either a percentage or a decimal number, and the number of fractional decimal digits displayed, are functions of the current Unit Scheme's configuration for the "Fraction" unit type. = Supported for Teacup Text Items.

(2.3) Graphics Objects: Teacups

RiverWare Teacups can be individually placed anywhere within the canvas. Teacups belong to a particular Teacup Group which defines the display properties for all teacup instances in the group. Teacup instances have an associated primary simulation object (typically a reservoir) and secondary simulation object (typically a data object) which are used to identify the data sources (slots) for the values illustrated by the teacup graphic.

Teacups graphically depict individual slot values relative to the canvas' "reference timestep" using the following graphical components:

1. A "Maximum Value" -- height of an outer rectangle.
2. A "Current Value" -- height of an inner rectangle, bottom aligned with the outer rectangle.
3. Zero or more "Marker Values" -- vertical position of horizontal marker line

Additionally, Teacups display the following components:

1. A vertical axis with automatically placed and labeled tick marks. The bottom value is always 0.
2. A Teacup Label (generally the name of a reservoir), with a configurable Font. (This label text always is black).
3. Zero or more Teacup Text Items, arranged vertically, horizontally centered, under the Text Label.
• Teacup Text Items support the "One Slot Value", "Two Slot Values" or "Computed Fraction" Text Item Types enumerated above.
• All of the Teacup Text Items share a single configurable Font (defined at the group level).
• Each Teacup Text Item instance has it's own configurable Text Color.
4. An optionally displayed bounding box with configurable background and border colors, and opacity. A neutral background color (e.g. white) with partial opacity helps set the teacup off from a background image.

(2.4) Graphics Objects: Teacup Legends

A Teacup Legend graphical image can be created for a Teacup Group and placed anywhere on the canvas. It is always drawn with a black border (bounding box) and a white background. It is similar to the teacup graphic, but with markers positioned vertically such that text labels can be placed to the right, evenly spaced. (See the accompanying image). In place of the vertical axis tick-marks with numeric values is the unit indication for those values. Only "legend text" for the Teacup Text Items is shown below the teacup bar -- no text is shown in place of the Teacup Label.

Each of the following graphical components are configured with a label or "legend text" used in the teacup legend.

• Maximum entity
• Current entity
• Each Marker
• Each Teacup Text Item

(2.5) Graphics Objects: Flow Lines

Flow Lines are line segments graphically depicting an individual slot's value at the canvas' "reference timestep" with the following graphical attributes:

1. Line Thickness -- absolute magnitude relative to all flow lines within the Flow Line Group.
2. Line Color and Line Style (pattern) -- relative magnitude, relative to the expected values for the particular series.

Each end of a RiverWare Flow Line can be placed anywhere within the canvas or "snapped to" any Teacup or Flow Line end. Flow Lines belong to a particular Flow Line Group which defines the display properties for all flow lines in the group. Flow Line instances have an associated primary simulation object (typically a reach) -- and optionally a secondary simulation object (typically a data object) -- which are used to identify the data source (slot) for the flow line's display properties -- and optionally to define thresholds using guide curve slots.

Flow Line Thickness is determined by a single function applied to all Flow Lines within a particular Flow Line Group. Specified minimum and maximum line thicknesses correspond to specified slot values. The graph to the right illustrates Flow Line Thicknesses (in pixels) as a function of slot values given this Flow Line Group configuration information:   Line Thickness Slot Value Min: 3 pixels 100 cfs Max: 12 pixels 400 cfs

Note that Flow Lines are drawn with anti-aliasing, so fractional line thicknesses (interpolated between the minimum and maximum thicknesses) are meaningful.

Flow Line Color and Line Style (pattern) reflect magnitudes relative to the slot's "capacity" (typically, water channel flow capacity). These display attributes are defined in a sequence of "Flow Intervals" at the Flow Line Group level. The thresholds for those intervals are defined independently for each Flow Line Instance. Thresholds can be expressed as constant values -- or -- as references to "guide curve" slots (any slot under the Flow Line's associated objects which can be resolved to a single value, with or without a reference timestep). See the following example.

Flow Interval Configuration EXAMPLE:

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

The locations of the two ends of a Flow Line graphics item are manipulated using other graphics items to which the Flow Line ends are attached. The end of a Flow Line which is not attached to a Teacup is implicitly attached to a Flow Line Anchor Point graphics item. Flow Line Anchor Points are used for both "free" (unattached) Flow Line ends and Flow Line ends attached to one or more other Flow Line ends. Flow Lines (as such) will not themselves be movable by dragging. Rather, each of a Flow Line's ends dynamically "track" either the Teacup or the Flow Line Anchor Point to which it is attached.

• In the configuration canvas, Flow Line Anchor Points (at the end of one or more Flow Lines) are draggable to other positions on the canvas.
• The "free end" of a Flow Line (implemented with a Flow Line Anchor Point) can be attached to a Teacup or other Flow Line end effectively by dragging and "snapping" that anchor point to a Teacup or other Flow Line end.
• A Flow Line end can be detached with a "Detach" context menu operation on the object to which that line end is attached -- either a Teacup OR a Flow Line Anchor Point shared by more than one Flow Line. The detach operation starts a mouse drag operation of the end being detached; the user can "snap" the end to a different Teacup or Flow Line end by clicking (near) that object, or can click anywhere on the canvas to place the end at that point. Hitting the Esc key aborts the detach operation.
• Flow Line Anchor Points (at the end of one or more Flow Lines) could be invisible. But we may instead decide to show them as a small hollow circle or filled disk. Their appearance could be made to change when the mouse hovers over them (in the configuration canvas).

(3) Data Source Slot References

The various types of Graphics Objects depict, or display as text, numeric values from slots in the RiverWare model. There are several ways in which various graphical features are related to particular "data source slots".

In the most general context, e.g. for Text Items within a Text Item Group, slots are identified using "complete" slot name -- any slot in the model which resolves to a scalar value given a reference timestep.

In the case of graphical features of a Teacup or Flow Line, each data source slot reference is constructed from two components:

1. Configuration information of the containing group (Teacup Group or Flow Line Group), AND
2. A primary or secondary simulation object reference associated with each Teacup or Flow Line instance.
   • The instance's primary simulation object is typically a reservoir or reach.
   • The instance's secondary simulation object is intended to be a data object related to the primary object.

The following Data Source Types are implemented:

An Entity Slot Name is a local slot name identified at the group level for particular graphical entities. These local slot names are applied to a reference simulation object supplied by each Teacup or Flow Line instance. Teacup Groups and Flow Line Groups provide an Entity Slot Name for each of these graphical entities:

• Teacup: Maximum Value -- outer rectangle height.
• Teacup: Current Value -- inner rectangle height.
• Teacup Markers: Value -- horizontal line vertical position.
• Teacup Text Item numeric fields -- one or two slot values displayed as text, possibly as a fraction (e.g. percent).
• Flow Line: Value -- line display attributes: thickness, color and pattern.
• Flow Line: Flow Interval Threshold ("guide curve") -- see section 2.5, above.
  

Note that the Teacup and Flow Line variants of the Data Source Types listed above implement the same data source slot reference algorithms. They are enumerated separately to more easily provide customized GUI representations for these two contexts (teacups and flow lines).

Additional Data Source Types for other data source topologies are possible. Below are a few examples. These make use of Data Objects designated at the group level to provide values for multiple Teacups or Flow Lines in the group.

(4) Output Canvas Configuration

An Output Canvas is configured with the Output Canvas Configuration Dialog. Its design is based on the RiverWare Model Report output device configuration dialog using an Object Tree / Property Editor GUI design.

The Output Canvas Configuration Dialog presents three main panels:

1. The canvas' hierarchy of Graphics Objects (and some configuration-detail objects) are presented and managed in the Object Tree panel. This tree supports single-item selection.
2. The Settings property editor panel presents the properties ("settings") for the selected object in the Object Tree.
3. The Output Canvas Preview panel presents an editable version of the Output Canvas. It reflects the configuration changes made in the Object Tree and Settings property editor. This view has workspace-like features, such as selecting and moving graphical features by dragging with the mouse.

The Output Canvas Configuration Dialog's GUI controls include:

1. A "File" menu:
   1. Export Configuration...
   2. Duplicate...
2. An "Edit" menu:
   1. Copy (selected graphics objects)
   2. Paste (copied graphics objects, possibly into a different Object Canvas)
3. A "View" menu:
   1. Generate -- (show in Output Canvas Viewer)
4. OK, Apply and Cancel buttons for applying changes (or not) to the output device configuration saved within the model.
5. A "Generate" button brings up the Output Canvas Viewer (see section 6).

Notes:

• Only an "Export Configuration..." function is provided. Importing an output device is done from the Output Manager.
• Exporting as Image and Movie files, and Printing are supported in the Output Canvas Viewer dialog.

(4.1) Output Canvas Object Tree

The output canvas Object Tree presents a hierarchical view of the canvas' Graphics Objects. The following outline illustrates the supported object structure. Multiple instances are supported except where noted. New Object Canvases have only a "Canvas Configuration" item, and that item cannot be deleted.

• Canvas Configuration (1) -- always present
• Image Group (1) -- "Images"
  • Image
• Text Group
  • Text Item
• Teacup Group
  • Teacup Legend (1)
  • Bounding Box (1)
  • Marker Specification
  • Teacup
  • Text Item
• Flow Line Group
  • Flow Interval Declaration
  • Flow Line
    • Flow Interval Threshold

The Settings (properties) supported for each of these object types are described in subsequent sections.

Multiple instances of the following types can be reordered (within their siblings) using up and down arrow buttons:

• Teacup Groups: Marker Specifications
• Teacup Groups: Text Items
• Flow Line Groups: Interval Declaration

(4.2) Output Canvas "Add Item" Action Menu

The Object Tree panel presents an "Add Item" action menu for each of the item types listed above (except for "Canvas Configuration" and Flow Interval Threshold item types). The "Add ... Group" actions are always enabled. Other actions are enabled only if the selected tree item indicates a supported context for the new item type. The "Add Item" action menu supports several variations of certain items. (Note: We could instead deploy these variations as a setting, but that requires dynamic manipulation of the accompanying dependent settings). The "Add Item" action menu has these items:

1. Add Image
2. Add Text Group
3. Add Text Item: Plain
4. Add Text Item: Timestep
5. Add Text Item: One Slot Value
6. Add Text Item: Two Slot Values
7. Add Text Item: Computed Fraction
8. Add Teacup Group
9. Add Teacup Legend
10. Add Bounding Box
11. Add Marker Specification
12. Add Teacup
13. Add Flow Line Group
14. Add Flow Interval Declaration
15. Add Flow Line

(4.3) Output Canvas Preview Panel

The Output Canvas Preview panel presents an editable version of the Output Canvas. It reflects the configuration changes made in the Object Tree and Settings property editor. This view has workspace-like features, such as selecting and moving graphical features by dragging with the mouse.

The Output Canvas Preview panel 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. deleting (with confirmation).
2. Checkboxes:
1. Lock Background Image Positions
2. Lock Other Item Positions
3. A context menu (shown when right-clicking on the canvas background) including:
   1. Add Text...
   2. Add Image...
   3. Add Teacup...
   4. Add Flow Line...

The "Add" actions in the context menu create a new tree item in the object tree, and select that item. This causes the Settings property editor to show the default settings for that new item. The various types of canvas items also support their own context menus. Generally, operations in those item context menus apply to the full selected set of items.

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

Double clicking any object in the canvas preview selects the corresponding item in the Object Tree. This shows the item's configuration settings in the Settings property editor.

Similar to the Pie Chart device, the Output Canvas Preview Panel (and also the Output Canvas Viewer) provide 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. This provides the canvas' reference timestep.

(4.4) Settings: (General) Canvas Configuration

The Settings property editor shows the Output Canvas' general settings when the "Canvas Configuration" item is selected in the object tree:

The reference timestep date/time is generally synchronized with the timestep slider shown with the canvas. Manual changes to the slider (including using the step buttons) change this value, but changes to that slider during an animation do not.

(4.5) Settings: Image Group

The initial implementation supports only a single Image Group which is implicitly created when the user adds an image. Its item label in the Object Tree is "Images". Image Groups support the following settings.

(4.6) Settings: Image

Image instances support the following settings.

*Although these values will be represented and serialized as rwSettings, they will not generally be visible in the Settings property editor. They will be visible only in a special debug mode, for development.

(4.7) Settings: Text Group

Text Groups encapsulate Text Items which are not part of a Teacup graphic. (Text Items can also be added to Teacup Groups for numeric text lines under the teacup label). Text Groups support the following settings.

(4.8) Settings: Text Item

Text Items can contain multiple lines of text with a single selectable color. Section 2.2 Graphics Objects: Text Items earlier in this document outlines Text Items' configuration features.

Five (5) Text Item Types are supported.

• Three types support Data Source Slot References -- (see Section 3) -- for use of scalar or time-series values in displayed text.
• All text items (except Plain text items) support user-specified ...
  • Prefix Text (before the dynamic value)
  • Suffix Text (after the dynamic value).

Text Item Type Example Slot Refs T Notes 1 Plain CURRENT RESERVOIR CONDITIONS 0   Static text. Prefix and Suffix are not supported. 2 Timestep Ending at Midnight - July 29, 2014 0   Shows the canvas' reference timestep. Several date/time formats are supported. 3 One Slot Value ALPY 6435 cfs 1   4 Two Slot Values 97346 ft3 / 95180 ft3 2 The two values are separated with " / ". 5 Computed Fraction Palisades 67% Full 2 The presentation of fractions as either a percentage or a decimal number, and the number of fractional decimal digits displayed, are functions of the current Unit Scheme's configuration for the "Fraction" unit type. = Supported for Teacup Text Items.

Text Items in Teacups support only the text item types having at least one slot reference, as indicated above. On Teacup Text Items, such slot references (Data Source Slot References) make use of configuration information provided both by the containing Teacup Group and the Teacup instance. Slot references on normal Text Items in Text Item Groups are "complete" slot names to any slot in the model (scalar, series, or periodic).

All Text Item Types use the following settings:

*Although these values will be represented and serialized as rwSettings, they will not generally be visible in the Settings property editor. They will be visible only in a special debug mode, for development. Also, these values will not be supported for Text Items in Teacups.

These user supplied text string settings are used on particular text item types or contexts, as noted.

The following special settings are also used particular Text Item Types, as noted.

(4.9) Settings: Teacup Group

Various Teacup composition and display properties are defined at the "Teacup Group" level. These properties are shared among all Teacups in the Teacup Group. The accompanying image is the result of the Teacup Group also containing these configuration-detail items: A Bounding Box item Three Marker Specification items Three Text Items Teacup Groups support the following settings.

(4.10) Settings: Teacup Legend

All information required for Teacup Legend appearance is available from the containing Teacup Group and certain configuration-detail objects within that group. The Teacup Legend supports the following settings.

*Although these values will be represented and serialized as rwSettings, they will not generally be visible in the Settings property editor. They will be visible only in a special debug mode, for development.

The Teacup Legend example illustrated below is a result of Teacup Group settings and settings within the following configuration-detail objects added to the group:

• A Bounding Box item
• Three Marker Specification items
• Three Text Items

(4.11) Settings: Bounding Box

When instantiated under a Group item, the Bounding Box is displayed on all items within that group. The initial Bounding Box implementation is limited to Teacup Groups.

Bounding Boxes support the following settings.

(4.12) Settings: Marker Specification

Marker Specifications are currently implemented only for Teacup Groups. Multiple Marker Specification items can be added to a group. Marker Specification support the following settings.

(4.13) Settings: Teacup

Most Teacup display attributes are defined within the containing Teacup Group. Teacup instances support the following settings.

*Although these values will be represented and serialized as rwSettings, they will not generally be visible in the Settings property editor. They will be visible only in a special debug mode, for development.

(4.14) Settings: Flow Line Group

Various Flow Line composition and display properties are defined at the "Flow Line Group" level. These properties are shared among all Flow Lines in the Flow Line Group.

A list of Flow Line Interval Declarations objects is also part of Flow Line Group display configuration. Flow Line Interval Declarations provide a Flow Interval label and associated line display properties: color and style (pattern). As the user adds and removes Flow Line Interval Declarations to/from a Flow Line Group, the same number of Flow Interval Threshold objects are set on all Flow Line instances in the group. Those provide specific Flow Interval threshold settings for the particular Flow Line instance.

Flow Line Groups support the following settings.

(4.15) Settings: Flow Interval Declaration

A list of Flow Line Interval Declaration objects is part of Flow Line Group display configuration.

As the user adds and removed Flow Line Interval Declarations to/from a Flow Line Group, the same number of Flow Interval Threshold objects are set on all Flow Line instances in the group. Those provide specific Flow Interval threshold settings for the particular Flow Line instance.

Flow Interval Declarations support the following settings.

(4.16) Settings: Flow Line

Flow Line items are added on demand by the user. When adding a Flow Line item, or any time thereafter, the user configures the item according to a line item configuration established for the containing Flow Line Group.

Flow Line instances support the following settings.

*Although these values will be represented and serialized as rwSettings, they will not generally be visible in the Settings property editor. They will be visible only in a special debug mode, for development.

(4.17) Settings: Flow Interval Threshold

The number of Flow Interval Threshold items under each Flow Line instance is dynamically updated when Flow Interval Declarations are added to, or removed from the Flow Line Group.

Flow Interval Threshold instances support the following settings.

The threshold values above represent the "bottom" of the entity's (typically, reach's) Flow Interval value for the particular Flow Interval. Values below the lowest threshold value are displayed with the Flow Line Group's Negligible Value Color and Line Style.

(5) Special Graphics Object Provisions

(5.1) Create Teacups Operation (Wizard)

Multiple Teacups for a set of simulation objects (typically, reservoirs) can be created with a single operation using the Create Teacups dialog. This operation is available once at least one Teacup Group has been defined -- this provides the data source slot definitions which can be applied to a set of objects, with a set of associated data objects.

See the accompanying dialog mockup image. The user selects a Teacup group and adds simulation objects to an object list -- either from a selection on the workspace or using the object selector. The dialog attempts to locate associated Data Objects for all simulation objects added to the list by searching for data objects whose names start with the added simulation objects' names. If no such data object is found, the Data Object column cell is left blank.

Given the particular simulation objects, and the local slot names defined in the Teacup Group's configured Data Source Slot References for the particular graphical components (Maximum, Current, and each of the Markers), the dialog attempts to identify particular slots. The "Slots Found" column indicates the success of that slot lookup: A Green-Check icon is shown if all slots are found for the particular simulation object / data object pair. Otherwise a Red-X icon is shown.

When all object items are valid (i.e. with slots found for all Teacup graphical comontents), the "Create Teacups" button becomes enabled. Clicking the "Create Teacups" button creates the new Teacups and shows a message box confirming the completion of the operation and reporting its status. The operation will fail if the "Replace existing Teacups having the same label text (object name)" checkbox is not checked and such conflicts exist.

New Teacup objects are heuristically placed on the Output Canvas based on the relative positions of the corresponding simulation objects in the Simulation View; the user will then be able to adjust their positions by dragging the Teacup canvas items.

(5.2) Create Flow Lines Operation (Wizard)

Multiple Flow Items for a set of simulation objects (typically, reaches) can be created with a single operation using the Create Flow Lines dialog. This operation is available once at least one Flow Item Group has been defined. It is analogous to the Create Teacups operation described above.

There are two main differences between the Create Teacups and Create Flow Lines operation.

1. An associated Data Object is less likely be to needed for the multiple Flow Line creation function -- at least for the Flow Line instance properties which can be initialized with this operation. But they may be needed -- either for the Flow Line's main value (data source slot) OR for "guide curve" slots used for Flow Lines' Flow Interval Thresholds (which may instead just be configured using constant values). The operation will not attempt to set up the new Flow Lines' threshold values (used only for line color and style -- not for line thickness), so the "Slots Found" indication is satisfied when the Flow Line's main value data source slot has been located.
2. If the selected objects -- or the simulation objects associated with already existing Teacups or Flow Lines ends -- have main channel links between them -- the newly created Flow Lines will be "snapped together" to reflect the select objects' topology. This algorithm requires more consideration.

(5.3) Other Teacup Provisions

1. The width of Teacup Items is the same for all instances, based on a hard-coded function of the selected Teacup Label font.
2. The height of a Teacup Item is a function of both the selected Teacup Label font (as above) and the item's "Total" value.
   
3. Only a single uniform vertical scale is currently 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 (illustrated in both examples above) are not currently supported.
6. Tooltips showing slot names and/or values (as appropriate) are provided for these features:
   1. Maximum rectangle
   2. Current rectangle
   3. each horizontal marker
7. Double clicking on a Teacup object has the following effect, depending on the canvas context:
   1. Output Canvas Configuration Dialog, canvas preview: Select the object's item in the Object Tree; this causes the object's settings to be shown in the Settings property editor.
   2. Output Canvas Viewer: Show's the Open Object dialog for the object's primary reference simulation object.
8. As a convention of teacup diagrams in general, only non-negative values are depicted. It will be unusual for negative numbers to show up among the presented entities. Negative "current" values will result in no inner rectangle being drawn. Negative marker values (except those very close to zero) will result in such markers not being displayed.

(5.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. I believe that we will be able to make use of the FFmpeg, Libav, MEncoder, or GStreamer libraries, but this requires more investigation and some integration work.

Output Canvases saved within the model can be used in RiverWare Model Reports. See Section 6.

(5.5) Output Canvas in RiverWare Model Reports

Output Canvas still images (and maybe animated movie files of some format) 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 (for still images), 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.

(6) Output Canvas Viewer

The Output Canvas View Dialog presents the canvas in a relatively static form. The only dynamic controls are those to support a single "reference timestep":

Similar to the Pie Chart device, the Output Canvas Viewer (and also the Output Canvas Preview Panel) provide 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 View Dialog supports these menubar operations:

1. "File" menu
   1. Export as Image File...
   2. Export as Movie File...
   3. Print ...

Graphical Objects on the canvas support the following context menu operations:

1. Plot... (all entities of the selected Teacups and Flow Lines, up to nine objects for the nine plots in a plot page).
2. Show slots in New SCT...
3. Add slots to the open SCT...
4. Open <object>...
5. Open <data object>...

Teacups also support these additional context menu operations:

6. Open Current Value Slot...
7. Open <Marker> Slot... (one for each horizontal marker)

Double clicking on a Teacup or Flow Line object in the Output Canvas Viewer shows the Open Object dialog for the Teacup's or Flow Line's primary reference simulation object.

--- (end) ---