RiverWare Output Canvas / Teacup Development Report -- Sept. 2014
 Phil Weinstein, David Neumann, Patrick Lynn, Edie Zagona, CADSWES, 9-20-2014

A design and two weeks of initial development for an "Output Canvas" Output Device supporting Teacup graphical items were completed in August and September 2014 for RiverWare 6.6. This document describes the completed development work and summarizes the remaining tasks.

See also these documents:

Actual Development Screenshot:

Completed Output Canvas / Teacup Development Work

The Output Canvas Configuration Dialog currently provides:

  1. A configuration Object Tree and accompanying Property Editor for creating and configuring Output Canvas objects (currently just Teacups and supporting configuration objects). These are similar to the configuration controls for RiverWare Model Reports.
  2. An "Output Canvas Preview" panel where prototype Teacups for simulation objects are drawn, dragged (single item only) and animated.
  3. A "Log" panel (tab) which reports the validity of teacup slot configurations. This report is refreshed each time the user modifies the configuration.
  4. Functions:
    1. "Export Image" (to file) and "Copy Image" (to the system clipboard) -- for the current canvas image.
    2. "Export Configuration" as an Output Canvas Output Device file. Such exported files can be imported from the Output Manager dialog.
    3. "Fit Teacups using Simulation View positions." (See discussion below).
    4. "Delete All Teacups," with confirmation.
    5. "OK" and "Apply" buttons save the current configuration state for the Output Canvas Output Device instance. Such devices persist within the model file.

The Object Tree and Property Editor support:

  1. Creation of a single Teacup Group, multiple Teacups, multiple Markers, and a Bounding Box configuration.
  2. Single tree item selection. The selected tree item's properties (settings) are shown in the Property Editor below the Object Tree.
  3. Item deletion, with confirmation. (See also the "Delete All Teacups" operation under the Edit menu).
  4. Move Up and Down operations (arrow icon buttons) for: (a) teacups within a list of teacups, and (b) markers within a list of markers.
  5. A vertical splitter (invisible on Windows, but draggable by the user) between the Object Tree and Property Editor.
  6. NOTE: The Property Editor has text-only, or otherwise incomplete support for three new "rwSettings" value types: Colors, Local Slot Names and Timestep Date/Times. We will want to implement custom editors for those new value types. See discussion below.

Teacups currently graphically support:

  1. A "Maximum" (outer rectangle) entity, with configurable color and special treatment of referenced slots:
  2. A "Current" (inner rectangle) entity with configurable color. Appropriate slots are Series and Periodic.
  3. Multiple optional Markers with configurable color.
  4. An optional Bounding Box configuration with various settings: opacity, fill color, optional frame with independent color. (This will be useful, in the future, for setting teacups off from a background image -- especially with a partial opacity).
  5. Teacup Labels are initialized to the name of the simulation object from which teacups are created, but they can be changed to any text. A configurable font for Teacup Labels is supported at the Teacup Group level. [See the related item under Property Editor ("rwSetting") improvements, below].
  6. Optionally shown vertical axis with numerically labeled tickmarks at the Maximum value and, if space permits, at the bottom (zero value). Numeric values are presented with the current Unit Scheme's numeric display attributes for the reference Unit Type. A configurable font for vertical axis tickmark values is supported at the Teacup Group level.
  7. Individual Teacups can be dragged on the canvas. Their canvas coordinates can also be edited in the Property Editor. (Numeric editing of coordinates can be used to precisely align several teacups; their coordinates correspond to the base (zero value) of the Maximum and Current rectangles, horizontally centered).
  8. Animation. The Current rectangle and the Marker lines are drawn for slot values at the canvas' reference timestep. The reference timestep is dynamically set by the date/time spinner, slider, and animation controller (to produce an animation or slide show).
  9. Context Menu Operations:
    1. "Open Object..." (show Open Object Dialog for the teacup's primary reference object).
    2. "Plot Slots..." (show Current slot and Marker slots in a new Plot Dialog).

Other implemented Teacup provisions:

  1. The default Teacup Group configuration is devised to support "single operation" teacup creation for ALL reservoirs in the workspace to provide "current storage" (volume) presentation with respect to the top of the Elevation Volume Table. The "Add Teacup" operation shows the GUS Object Selector with multiple object selection enabled.
  2. Newly created teacups are placed on the canvas at a position which is "proportional to" the objects' positions in the Workspace Simulation View -- with respect to ALL simulation objects (not just the set of teacups being created or previously created).
  3. The "Fit Teacups using Simulation View positions" operation (under the Edit menu) repositions all teacups using a similar algorithm. But instead of basing the new positions on all workspace objects, only the objects of the existing Teacups are used. This is more effective for actually "refitting" all teacups to the current canvas size.
  4. The largest Maximum-entity value among all defined teacups defines the vertical teacup scale for the whole canvas. That largest maximum value is currently hard-coded to be 100 pixels high.
  5. A teacup's Current-entity value is not expected to be larger than the teacup's Maximum-entity value. But if it ever is (at any particular timestep), the top of the Current (inner) rectangle can extend up to 10% of the canvas' largest Maximum height beyond the top of the Maximum (outer) rectangle. (That is, up to 10 pixels above; 10% of 100 pixels).

Other Canvas Preview provisions:

  1. The configured canvas size is intended to define the size of the exported (or copied, to the clipboard) canvas image. The bounding rectangle of the canvas is centered within the Canvas Preview panel, and is depicted with a darker color for the off-canvas region. This visual provision is new to canvas and workspace implementations in RiverWare; an actual QGraphicsItem (with a low "Z" value) implements this visual effect.

Property Editor ("rwSetting") improvements:

  1. The "Font" value type had previously been used to generate CSS font specification strings for use in HTML documents (for RiverWare Model Reports). That form of font specification is not directly usable for specifying fonts used in Qt-generated graphics (using the QGraphicsView architecture or in custom widget painting). Support for Font rwSettings was enhanced to create a form of CSS font specification which can be converted back into a Qt QFont, and that conversion was implemented. With this in place, it was possible to implement the following enhancement.

    Re-editing a Font rwSetting had previously initialized the Qt Font chooser dialog with the last edited font -- of any Font rwSetting instance -- rather than with the actual instance being edited. This made it difficult to make a minor change to an existing font setting (using the Qt Font chooser dialog) in applications where several distinct Font rwSetting instances are involved. Note that replicating a font specification from one Font rwSetting instance to another is still possible by copying and pasting the CSS font specification string; those strings are directly editable.

Remaining Output Canvas / Teacup / Flow Line Development Work

Incomplete Support for new "rwSettings" value types: Colors, Local Slot Names and Timestep Date/Times:

  1. Color settings are currently entered as text -- either with six hexadecimal digits ("#RRGGBB") -- (Red Green Blue -- from "00" to "FF") -- or any of the special (140) W3C color names, like AliceBlue, HoneyDew, PeachPuff, Coral. (These are not case sensitive, and spaces are ignored). See: http://www.w3schools.com/html/html_colornames.asp
  2. When using the GUS slot selector, Local Slot Name settings are currently assigned full slot instance names (including the containing object) rather than just the local slot name. So after picking a slot, the user must manually delete the simulation object-part of the name. (Otherwise, notice the resulting errors in the Log tab -- assuming at least one teacup exists).
  3. In the property editor, the Reference Timestep Date/Time setting (for the overall canvas configuration) is currently edited just as text. This is not really a problem because this property is also currently tied to a Timestep Date/Time spinner AND animation slider shown at the bottom of the preview panel.

Major Components and Features NOT YET Implemented:

  1. Teacup Legend
  2. Text Items on the Canvas and in Teacups (including dynamic numeric and timestep content).
  3. Image Items
  4. Full canvas "workspace" features: selection ornamentation, multiple teacup selection, teacup creation and deletion (from the canvas), and off-canvas item handling.
  5. A separate Output Canvas Viewer dialog.
  6. Animated (movie) File Generation (e.g. MPEG).
  7. Inclusion of Output Canvases in Model Reports.
  8. Flow Lines (this also needs serious design review).

Other Notable Open Issues:

  1. Teacups don't hold on to live SimObj or Slot pointers. Instead, only the names of the associated SimObj and optional DataObj are retained, and Slot references are resolved as needed. That's OK. But we need to respond to SimObj name changes by updating Teacups' object names. (This needs to be done at the Sim/OutputCanvasConfig data level -- not within a GUI component).
  2. The hard-coded maximum teacup Maximum rectangle height (of 100 pixels) should be made configurable, within a reasonable value range.
  3. The dotted and dashed pattern options for Markers don't look good. The current Marker line thickness is 3 pixels. (Reducing that to 2 pixels would probably improve -- tighten up -- those patterns).
  4. The design called for more numerically labeled tick marks on the vertical axis, as space allows (as is done for the California Dept. of Water Resources teacups). (Currently we're supporting only the top and zero -- but that might actually be sufficient).
  5. The range of currently supported animation rates is probably too limited -- not fast enough for large series.
  6. The Teacup's "Plot Slots..." context menu operation could support also the "Maximum" entity value as a Plot marker.
  7. When creating new Teacups (for a set of simulation objects) there is no option to remove already existing teacups for those objects, or refrain from creating redundant ones.
  8. While use of the Elevation Volume Table is convenient for creating a "current storage" presentation using readily available data, that is not always technically accurate. That reservoir table slot often contains extra rows beyond the actual capacity of the reservoir to accommodate certain computations. Users are free to create and use new scalar slots on associated data objects to provide the actual reservoir maximum capacities. (This is currently supported).

Property Editor ("rwSetting") Usability Issues:

  1. 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.
  2. The "Slot Selection" settings editor (the GUS slot selector) isn't automatically configured to limit the presented list of slots to those having the required Unit Type. Furthermore, each slot's unit type is presented within the selector only if the Unit Type filter is shown (regardless of whether the filter is actually turned on). (This takes four mouse clicks and a selection within a popup list each time the GUS slot selector is used). Ideally, the Unit Type filter would automatically be shown and set to the required Unit Type.

--- (end) ---