RiverWare Output Canvas: Teacup and Flow Animations: Design 2 to 3 Changes
Phil Weinstein, David Neumann, Patrick Lynn, CADSWES, 8-22-2014 -- See Project Index

Revisions:

The prior design document has been put aside as "Design 2". It is available in these forms:

David, Patrick and Phil met today (Thursday, 8-21-2014) to review the above design. This document outlines the decisions we have made. I think.

(1) Add to document higher level overview of Object Tree and related settings and controls.

The "Design 3" document will provide a higher-level overview, via examples, of the Object Tree and the related Settings (property editor) and the "Add Item" action menu (similar to that shown in the Model Report configuration dialog).

Related: Some item type settings will be changed to a set of related creation functions (e.g. of different types of Text Items). That is, those "type" properties will not be editable, but rather will be set when the item is created. Similarly, the Teacup Group's "Marker Count" setting will be eliminated; Markers will just be added through an "Add Item" action. Also, the top level Group items will not be automatically, initially present, but will be individually added. THE POINT HERE IS THAT the revised document will enumerate all of the "Add Item" actions -- and there may be many. (I'm thinking, about 15).

(2) Data source identification refactoring.

We are going back to an original idea that Teacup and Flow Line instances are associated with a particular primary simulation object (plus, optionally, a related secondary simulation object -- generally a data object). Instead of associating each of the Teacups' and Flow Lines' graphical entities (rectangle heights, marker line positions, line display attributes) with an unrestricted slot reference -- to any slot in the model -- those graphical entities are associated with slots whose complete names are derived -- in some way -- from the Teacups' or Flow Lines' associated objects and some uniform identifying information (initially just a local slot name) defined at the Teacup Group or Flow Line Group level.

This applies to the following graphical entities:

The design will document these initially supported Data Source Types:

  1. <primary object> (from Teacup or Flow Line Instance) . <local slot name> (configured at the "group" level).
  2. <secondary object> (from Teacup or Flow Line Instance) . <local slot name> (configured at the "group" level).

Other ideas for future Data Source Types -- not necessarily to be documented in the design -- (this should be based on actual future requirements):

  1. <data object table slot> (defined at the "group" level) . <primary object name used as column label>
  2. <data object for entity, e.g. current value> (defined at the "group" level) . <primary object name used as local slot name>

Potential support for multiple Teacup Groups and Flow Line Groups mitigates the limitations imposed by defining certain data source identification components at a central (e.g. Teacup Group) level.

(3) Distinct Output Canvas Configuration and View dialogs.

In a way that is analogous to various other advanced output devices (this applies differently to the various examples), we will provide distinct dialogs for configuring and viewing an Output Canvas output device.

  1. The Output Canvas Configuration Dialog is similar to the Model Report output device supporting an object tree and (rwSetting-) property editor with a preview panel. Only in this dialog can Teacups and other graphical features be configured and moved (dragged) to a different location on the canvas. This dialog presents OK, Apply and Cancel buttons for applying changes (or not) to the output device configuration saved within the model. A "View" button brings up the Output Canvas View dialog.
  2. The Output Canvas View Dialog presents the canvas in a relatively static form. The only dynamic control is the timestep date/time spinner / animation controls (similar to those shown in the Pie Chart output device).

(4) Our own Teacup Legend Design (rather than closely modeling the legend on the CDWR example).

The close adaptation of the CDWR Teacup Legend in the "Design 2" Output Canvas required some pretty crazy provisions -- like requiring the user to provide not only color selections, but also color name text. "Design 3" will more precisely define the Teacup Legend graphic in such a way that special configuration settings will not be needed.

(5) Simplification of Teacup Text Item Formats

See section 5.3 in the "Design 2" document.

  1. Numeric values will not be defined in terms of graphical entity values (e.g. Teacup Maximum, Current, or Marker values), but rather in terms of the sorts of hybrid slot references on which those entity values are based -- See Item 2, above.
  2. We will still support all three of the following Text Item Types, but their configurability will be limited as indicated here:
    1. One Value Ref  (e.g. "ALPY 6435 cfs") ... no change
    2. Two Value Ref  (e.g. "97346 / 95190") ... only a "/" character will be supported; there will be no "middle text" setting. Also, as mentioned below, units are always included (this is no longer configurable). So the example would be: "97345 ft3 / 95190 ft3".
    3. Fraction (e.g. "67% Full"). Only percent will be supported -- not decimal fraction -- and this text item type will be called Percent.
  3. A Teacup Text Item's Type will not be a setting, but rather will be a fixed property of the item established at creation time. That is, the Object Tree's "Creation Action Menu" will include three distinct creation functions:
    1. Create Teacup Text Item: One Value
    2. Create Teacup Text Item: Two Values
    3. Create Teacup Text Item: Percent

Accordingly, the following Teacup Numeric Text Item Settings are being REMOVED:

rwSetting ID Label Type Shown for text item types
TCUP_TXT_TYPE Type enum (see above) all
TCUP_TEXT_LEGEND Legend Text string all
TCUP_TXT_ENT1_TYPE Entity 1 Teacup Entity Enum one value ref, two value ref, fraction
TCUP_TXT_ENT1_SHU Entity 1, Show Units? bool one value ref, two value ref
TCUP_TXT_MIDTEXT Middle Text string two value ref
TCUP_TXT_ENT2_TYPE Entity 2 Teacup Entity Enum two value ref, fraction
TCUP_TXT_ENT2_SHU Entity 2, Show Units? bool two value ref
TCUP_TXT_FRACT_FMT Fraction Format decimal or percent, enum fraction
TCUP_TXT_FRACT_PREC Fraction Precision integer: 0, 1, 2, ... fraction

The following Teacup Numeric Text Item Settings are being RETAINED:

rwSetting ID Label Type Shown for text item types
TCUP_TXT_PREFIX Prefix Text string all
TCUP_TXT_SUFFIX Suffix Text string all
TCUP_TXT_COLOR Text Color color all

The following Teacup Numeric Text Item Settings are being ADDED:

rwSetting ID Label Type Shown for text item types
TCUP_TXT_VAL1_DATSRC_TYPE Value 1 Data Source Type Data Source Type enum* all
TCUP_TXT_VAL1_SRC_LSLOT Value 1 Slot Name local slot name all
TCUP_TXT_VAL2_DATSRC_TYPE Value 2 Data Source Type Data Source Type enum* two value ref, percent
TCUP_TXT_VAL2_SRC_LSLOT Value 2 Slot Name local slot name two value ref, percent

*Data Source Type enumeration has these display values:

While we didn't fully address this in the review meeting, similar simplifications will be applied to (non-Teacup) Text Items. See section (4) in the "Design 2" document. Those will still need some of the additional text item types -- at least "Plain" and "Ref Timestep" (for display of the Output Canvas' reference timestep). The provision that slot references in those text items are complete slot names remains unchanged.

(6) Culling many other configuration settings.

While we intend for the design document to have somewhat broader scope than the initial implementation, we're deciding to hold off on some of the provisional configuration features I had specified in the "Design 2" document. In some cases, it makes more sense to wait until specific requirements arise from actual use of initially provided basic features.

"Design 2" configuration settings will be simplified in these ways:

  1. Only a single general purpose text label for each graphical entity (e.g. Teacup Maximum, Current, and markers) rather than distinct "short" and "long" labels).
  2. Teacups will support only a single column of Teacup Text Items. (We won't attempt to support the two-column use case demonstrated in the CDWR example).
  3. When numeric values are displayed, we will unconditionally show units. (There won't be distinct "Show Units" options).
  4. We won't support numeric precision specifications. Both the unit type's current unit and precision within the currently selected Unit Scheme will be used on all displayed numeric values. (My sense had been that users will almost always want to use lower precisions in this context, as Output Canvases are inherently suited for "ball park" summary presentations, whereas virtually all other uses of numeric values in RiverWare generally require higher precision).
  5. We won't need "color name settings" (for support of the Teacup Legend, see above).
  6. We won't make use of a Teacup Group "Marker Count" setting. Marker (specifications) will individually be added to Teacup Groups.

(7) For Flow Lines, change of the incorrect use of the word "Stage" to "Flow Interval".

While not actually discussed at this review meeting, based on my earlier e-mail (copied below) and a brief discussion with David, I will provisionally change use of the word "Stage" to "Flow Interval".

In the current draft of the Output Canvas output device (for Tea Cups and Flow Lines) my use of "Stage" is not correct for the concept of a range of values (among a set of range values) for flows RELATIVE TO the particular channel's capacity.  This is sort of like the "Operating Level" concept for reservoirs.

As of this moment, the design document above refers to "Stage Count" (number of identified flow ranges defined within a Flow Line Group) and "stage tree items" (at two different levels) with these properties:

(1) Defined at the Flow Line Group level for each of the "Stage Count" stages:
  • Stage Label (string)
  • Stage Color
  • Stage Line Style
(2) Defined at the Flow Line Instance level for each of the "Stage Count" stages:
  • Stage Threshold Type ("Value" or "Slot"):
    • Stage Threshold Value (the bottom of a "stage")
    • Stage Threshold Slot (basically a "guide curve" for the bottom of the "stage")
(The "Flow" paradigm is used for Flow Lines even though other entities, of other unit types, could be represented with these lines).

SOME IDEAS -- in place of "stage":
  • "Flow Interval"
  • "Flow Range"
  • ...
Any thoughts?

Patrick's Initial Design 2 Review Comments

Subject:     Re: Status: Output Canvas / Tea Cups: Property Editor-based GUI Design
Date:   Thu, 21 Aug 2014 11:45:19 -0600
From:   Patrick Lynn

I have read Phil's Functional Design document, though I skimmed the Flow Lines section. I thought I'd put some comments in writing before we talk this afternoon, partly because Edie won't be in that discussion. I won't try to organize these thoughts too much though since we'll be discussing this shortly.

I am feeling the lack of something less detailed and more concerned with the requirements, something between the two diagrams and the Function Design document. For example, what types of labels are we planning to support initially, regardless of rwSettings details.

Also, we should make explicit how this output device fits in with the others. The proposal is to combine the configuration of the device with the device itself. usually these are two separate dialogs, two separate activities: configure the device, generate it. I think the plan is fine, but there are a few more details to mention. maybe generating the device presents the dialog locked, with the config panels hidden.

I would vote for a minimal set of settings initially and add them as necessary, using a reasonable default. For example, you could skip fonts initially, just go with some reasonable defaults. Also I think some settings can be eliminated for good, such as precision, because that is what the unit schemes are for. if they want different precisions they can easily create a different unit scheme.

I think that in each of the 3 or 4 times you say something like "our property editor implementation doesn't easily support variable number of items ...", there is not in fact a need for such a thing if the object tree design is crafted differently. The big example is the the teacup set and the relationship to objects. I think we can safely define a tea cup set as a set of teacups that each display the same quantities on different SimObjs. Given this definition, the user could add the following items to a tea cup set:
  Teacup Label (Text Item)
  Teacup Marker
  Legend
  Teacup

Each Teacup would have the following properties:
  SimObj
  DataObj
  Location

The Teacup Labels and Markers references to slot names would also include an indication of whether it was on the SimObj or DataObj. And so on. Wouldn't something like this work? It's could be thought of as taking the knowledge incorporated into wizard and incorporating it into the object hierarchy.

Patrick

--- (end) ---