RiverWare Output Canvas: Teacup Storage and Flow Animation: Development Plan
Phil Weinstein, David Neumann, Patrick Lynn, Edie Zagona, CADSWES, 8-27-2014 (a) -- See Project Index

(0) Overview

This document presents a development plan for the RiverWare "Output Canvas" output device described in this design document:

Note [8-27-2014]: We may want to consider overlaying a full-blown Wizard feature for Teacup creation -- including setup of markers and integrated text items within the Teacup Group. The "Create Multiple Operation (Wizard)" feature described in section 5.1 would be just one part of that. Development of the currently designed feature is being put off (moved from Phase 2 to Phase 4) until we more broadly consider what the high-level features should be.

(0.1) Document Status

(0.2) Contents

  1. Development Phases
    1. Basic Teacups, without integrated text items.
    2. Text Items in Teacups and on canvas
    3. Canvas images
    4. Create Multiple Teacups Operation
    5. Flow Lines
  2. Advanced Features
    1. Inclusion of Output Canvases in Model Reports
    2. Animated File Generation
    3. Customized rwSetting ValueType support for timestep date/times.

(1.0) Development Phases

This feature may be developed in the following phases, initially for RiverWare 6.6:

  1. Basic Teacups, without integrated text items.
  2. Text Items in Teacups and on canvas
  3. Canvas images
  4. Multiple Teacups Operation
  5. Flow Lines

Advanced Features (can individually be done as part of prior phases).

  1. Inclusion of Output Canvases in Model Reports
  2. Animated File Generation
  3. Customized rwSetting ValueType support for timestep date/times.

(1.1) Phase I: Basic Teacups, without integrated text items.

     

This phase provides a usable Output Canvas output device type with simplified "Basic Teacup" graphics (lacking integrated text items). The user will be able to create multiple Output Canvas output device instances and add Teacups for individual simulation objects (and related data objects) and a basic Teacup Legend.

This includes these Teacup graphical features:

*The Bounding Box is included among the basic features because it is a graphical depiction of a fundamental property Qt graphics items used to implement the Teacup graphics. This will be useful in development diagnostics.

The Output Canvas "Add Item" Action Menu will support these actions:

  1. Add Teacup Group
  2. Add Teacup Legend ... to Teacup Group
  3. Add Bounding Box ... to Teacup Group
  4. Add Teacup Marker ... to Teacup Group
  5. Add Teacup ... to Teacup Group

Phase I Tasks:

Note: Enhancements to rwSettings ValueTypes -- for property types not currently supported -- e.g. timestep date/time can be put off until later. Support for such types can initially be provided using plain text or enumerated types.

  (A) Basic Data Model and Configuration GUI Support

  1. Define rwSettings Identifiers for each of the "Phase I" Output Canvas Config classes.
  2. Data Model: class definitions for (a) Output Canvas Output Device (b) Output Canvas Config, containing ... (c) Teacup Group, (e) Teacup, (e) Bounding Box, and (f) Teacup Marker, (g) Teacup Legend. This includes rwSetting list definitions for most of these classes.
  3. Mostly stubbed Output Canvas Configuration Dialog.
  4. Management of Output Canvas output devices, including device data persistence.
  5. Object Tree (QTreeView), including Qt Abstract Item Model implementation based on an Output Canvas Config instance.
  6. Deployment and integration of an rwSettingsTree in the Settings property editor panel.
  7. Application of rwSettingsTree changes to the Output Canvas Config instance data.
  8. "Add Item" Action Menu with the five operations enumerated above.

  (B) Basic Canvas / Graphics View Implementation

  1. Basic Qt Graphics View subclasses (of RwGraphicsScene and RwGraphicsView) to implement the canvas, deployed within the Output Canvas Config Dialog as the "preview" panel.
  2. Stubbed development of the Teacup and Teacup Legend Graphics Items, with just dummy (icon) display.
  3. Basic canvas operations: Teacup item selection, moving (by dragging).
  4. Reference Timestep GUI support: Deploy Date/time spinner / animation controls.
  5. Heuristic initial Teacup placement algorithm, based on relative SimObj positions within the simulation view.

  (C) Teacup Graphics Items

  1. Data source slot reference support, resolution of data source slots for the various graphic entities.
  2. Geometry computations and vertical scale composition.
  3. Graphics rendering for each of the graphical features listed above.
  4. Teacup context menu, operations.

  (D) Teacup Legend Graphics Items -- possibly postponed to a 2nd iteration.

  1. Geometry computations: vertical positions determined by label text rows.
  2. Graphics rendering modifications for legend-specific geometries

  (E) Maintenance Features

  1. Handling of item positions when reducing canvas dimensions.
  2. Responding to SimObj name changes.
  3. ...

  (F) Output Canvas Viewer Dialog

  1. Deployment of simplified version of canvas in viewer dialog.
  2. Functions:
    1. Export as Image File ...
    2. Plot... (all entities of selected Teacups)
    3. Show slots in New SCT ...
    4. Show slots in Open SCT ...
    5. Open <object> ...
    6. Open <data object> ...
    7. Open Current Value Slot
    8. Open Marker Slot >> ...

(1.2) Phase II: Text Items in Teacups and on canvas

This phase provides addition of Text Items to the canvas (in Text Groups) and to Teacups (as integrated text items). The Output Canvas "Add Item" Action Menu will support these additional actions:

  1. Add Text Group
  2. Add Text Item: Plain ... to Text Group
  3. Add Text Item: Timestep ... to Text Group
  4. Add Text Item: One Slot Value ... to Text or Teacup Group
  5. Add Text Item: Two Slot Values ... to Text or Teacup Group
  6. Add Text Item: Computed Fraction ... to Text or Teacup Group

Phase III Tasks:

  (A) Basic Data Model and Configuration GUI Support

  1. Define rwSettings Identifiers for Text Groups and Items
  2. Data Model: class definitions for (a) Text Group and Text Item, including rwSetting list definitions.
  3. Object Tree (QTreeView) and Settings support for Text Groups and Text Items.
  4. "Add Item" Action Menu: implement the six operations enumerated above.

  (B) Canvas Text Items (in Text Groups)

  1. Text composition (of the non-Plain text item types)
  2. Geometry computations
  3. Text Graphics Items / Text drawing
  4. Text Item context menu, operations: delete, configure.

  (C) Canvas Text Items in Teacups

  1. Text composition enhancements (using the Teacup's context)
  2. Geometry computations (including revisions to Teacup geometry)
  3. Text drawing (as part of the Teacup graphics)

  (D) Maintenance Features

  1. Handling of text item positions when reducing canvas dimensions.
  2. Responding to SimObj name changes.
  3. ...

(1.3) Phase 3: Canvas images

This phase provides addition of Images to the canvas. The Output Canvas "Add Item" Action Menu will support this additional action: Add Image.

Phase IV Tasks:

  (A) Basic Data Model and Configuration GUI Support

  1. Define rwSettings Identifiers for Text Groups and Items
  2. Data Model: class definitions for (a) Image Group and Image Item, including rwSetting list definitions.
  3. Object Tree (QTreeView) and Settings support for Image Groups (one instance) and Images.
  4. "Add Image" action implementation, including identification and loading of an image file.
  5. Image data serialization and persistence in the Image Item.

  (B) Image Graphics Item

  1. Creation, maintenance, and rendering
  2. Image context menu, operations: delete, configure.
  3. ...

(1.4) Phase IV: Create Teacups Operation (Wizard)

See section 5.1 in the design document.
Phase II Tasks:

  1. Basic dialog creation and layout.
  2. Object list composition (Add / Remove Objects)
  3. Associated Data Object identification (automatic initialization)
  4. Object and Data Object name editing
  5. Slot location algorithm; "Slots Found" indication
  6. Create Teacups operation

(1.5) Phase V: Flow Lines

This phase provides the addition of Flow Line Groups and Flow Lines to the canvas.
The Output Canvas "Add Item" Action Menu will support these additional actions:

  1. Add Flow Line Group
  2. Add Flow Line Interval Specification ... to Flow Line Group
  3. Add Flow Line ... to Flow Line Group

Phase V Tasks:

  (A) Basic Data Model and Configuration GUI Support

  1. Define rwSettings Identifiers for Flow Line Groups, Interval Specifications, Flow Lines and Threshold items.
  2. Data Model: class definitions for those four item types.
  3. Object Tree (QTreeView) and Settings support.
  4. "Add Item" Action Menu: implement the four operations enumerated above.
  5. Coordination of Threshold item lifecycle (on Flow Line instances) with the number of Interval Specifications (in Flow Line Groups).
  6. Flow Interval Threshold editing logic.

  (B) Flow Line Graphics Items

The position of a Flow Line graphics item is based on other graphics items. The end of a Flow Line which is not attached to a Teacup will be attached to an invisible Flow Line Anchor Point graphics item. This "anchor point" thing is used for both "free" (unattached) Flow Line ends and Flow Line ends attached to other Flow Line ends. Flow Lines (as such) will not themselves be movable by dragging. Rather, each of a Flow Lines end dynamically "tracks" either the Teacup or the Flow Line Anchor Point to which it is attached.

  1. Flow Line graphics item, basic implementation.
  2. Custom rendering, for line thickness, color and style (pattern).
  3. Flow Line Anchor Point (invisible graphics item) basic development.
  4. "Attach" action, initiated by dragging and dropping a "free" Flow Line Anchor Point onto something to which the end can be attached (see above).
  5. "Detach" action, initiated by a context menu operation on Teacups and Flow Line Anchor Points (having more than one Flow Line).

  (C) Maintenance Features

  1. Handling of Flow Line Anchor Point positions when reducing canvas dimensions.
  2. Responding to SimObj name changes.
  3. ...

(2.0) Advanced Features

The following advanced features can be completed as a final phase, or can be done as part of an earlier phase.

(2.1) Inclusion of Output Canvases in Model Reports

The integration of Output Canvases into Model Reports will be virtually identical to Model Report support for Pie Charts. See occurrences of "ChartItem" in the "ModelReportItem" class.

(2.2) Animated File Generation

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.

Here are a few relevant FFmpeg-related references:

I had also posted a question on the Qt Project Forum (8-5-2014). There was a response, but no direct Qt-based solution (for exactly what I was looking for) was suggested.

(2.3) Customized rwSetting ValueType support for timestep date/times.

The rwSettings property editor infrastructure currently supports about 25 "value types" assigned to individual settings. (See Sim/rwSettings.hpp). These determine the type of editing provided within -- and from -- property editor cells. Examples include: Multiline Text, Single Line Text, Filename, Simobj name, Font, Slot value -- to name just a few.

There is currently no support for timestep date/times. This is a minor setting in the Canvas Configuration (See section 4.4). The primary way of setting that value will actually be in a timestep spinner deployed within the canvas (both preview canvas and viewer canvas) along with the timestep animation controls. So initially, we will just use a text field for that property.

But it will be nice to explicitly support a timestep date/time ValueTime (either with a program-settable timestep size, OR perhaps in combination with a new Step Size ValueType, OR just supporting the run controller's timestep size) as its own ValueType. This needs more discussion.

--- (end) ---