Trapezoidal Teacups in RiverWare Output Canvases -- RiverWare 6.8
Phil Weinstein, David Neumann, Edie Zagona, CADSWES -- edit 12-11-2015 (b).
Document Home: R:\doc\Output\OutputCanvas\2015\TrapezoidalTeacups-RW68.doc

Overview

As introduced in RiverWare 6.6, Output Canvas Teacup graphics were limited to a vertical rectangular bar presentation. In RiverWare 6.8, two additional "teacup geometries" were introduced -- two forms of trapezoids. For any particular teacup group, the user can now choose between these three Teacup Geometry options:

1. Rectangular (as provided in RiverWare 6.6)
2. Trapezoidal, Congruent
3. Trapezoidal, Constant Top and Bottom Widths

Additionally, the following two features were added:

1. Configuration option to optionally show or hide the horizontal gap between the inner "Current" rectangle (or trapezoid) and the outer "Maximum" rectangle (or trapezoid).
    
2. For overflow of the "Current" area above the "Maximum" area, presentation of a distinct dotted pattern fill. (This became desirable especially with the ability to remove the gap between the current and maximum areas; that made the overflow area more difficult to discern).

Trapezoid Geometries

Trapezoid dimensions are configured with three values, in pixel units. These are configured at the teacup group level. (Note that an Output Canvas can have multiple teacup groups).

1. Maximum Teacup Height
2. Teacup Bottom Width
3. Teacup Top Width -- or -- Maximum Teacup Top Width

The Maximum Teacup Height applies to the teacup within the teacup group having the largest maximum value. All teacups within a teacup group have the same Teacup Bottom Width.

The two provided Teacup Geometries differ in how the teacup top widths are computed:

The "Trapezoidal, Congruent" geometry assigns the configured "Maximum Teacup Top Width" to the teacup within the teacup group having the largest maximum value. The top widths of all other teacups in the group are computed, based on where their maximum value falls within the geometry of largest teacup.

The "Trapezoidal, Constant Top and Bottom Widths" geometry assigns the configured "Teacup Top Width" to all teacups in the teacup group.

In both proposed trapezoidal geometries, teacup values -- typically reservoir volumes -- are linearly mapped to a graphical AREA within the teacup graphic, rather than a HEIGHT above the teacup baseline.

In the Rectangular geometry, all other teacup values are mapped to a vertical position above the teacup's base, proportional to the value-to-vertical-pixel ratio defined by the largest teacup.

For both Trapezoidal geometries, a value-to-area ratio is computed from the largest teacup. That computed value-to-area ratio is then used for computing geometries within all teacups within the teacup group.

The following diagrams depict these geometries, as applied to the largest teacup in the group, and another teacup in the same group.

Heights above the teacup base are computed using metrics associated with the largest teacup's geometry. This applies also to the top of the trapezoids for all other teacups in the group.

Each teacup effectively has its own function for mapping values to heights. The top width of the trapezoid is fixed. The top's vertical position is computed given the value-to-area ratio established by the largest teacup and the individual teacup's maximum value.

Teacup Geometry Configuration Settings

Arguments for the teacup geometry computations are configured at the teacup group level. They apply to all teacups contained in the teacup group. These arguments are specified in units of pixels.

As indicated above, a new "Show Gap" (Yes/No) configuration value was added -- this applies to all three supported teacup geometries (i.e. Rectangular too). All three geometries support a "Maximum Teacup Height" configuration value. The three geometries have distinct "teacup width" settings appropriate for the use of those configuration values.

--- (end) ---