2    DSM2 Schematic Viewing Program

2.1    Introduction

This chapter introduces the DSM2 Schematic Viewing Program (DSVP). This program is designed to serve as a graphical pre/post processor for DSM2 and its associated files. The DSVP is written in Java, an object-oriented, platform-independent language. For the purposes of this chapter, any words included between <> indicate the name of a button on the interface.

2.2    DSVP Input Files

2.2.1    DSM2 Input Files

The input files for DSM2 are in an ASCII column based structure. The current version of the DSVP uses the channels.inp file to gather information about the schematic channels. The program can also use the translations.inp file to assign data to a particular channel from a specified HEC-DSS file pathname. Future versions will use the data from all of the input files and allow manipulation of those files.

2.2.2    DSM2 Output

Both DSM2-HYDRO and QUAL output their results to either the HEC-DSS file format or as an unformatted binary tidefile. The current version of DSVP can read and display time series data from the HEC-DSS format. Future versions of the program will be able to read and display data from binary tidefiles as well.

2.2.3    Coordinate Data: .xy

The only data file that is required by the DSVP that is not an associated DSM2 file is a list of UTM coordinates for each node. This file is used to place each node in relation to the other nodes on the schematic.

2.3    Using the DSVP

2.3.1    General Description

The DSVP interface (Figure 2-1) consists of a control panel on the left side and a schematic display on the right.

Figure 2-1: DSVP Interface.
Figure 2-1: DSVP Interface.

The top of the control panel houses nine buttons with various functions (from left to right and top to bottom: Quit, Load, Save, Update, Reset, Channel Select, Remove Node, Merge Nodes, Merge Channels). The Load, Save, and Merge Channels buttons have no functional purpose at this time and serve only as placeholders. Below the buttons are two panels, one is the Quick Find panel and the other is the Zoom Control.

The bottom of the control panel houses a tabbed pane with five panels. These panels are: Load Data, Edit Data, Display, Legend, and Options.    The Load Data Panel

The Load Data Panel (Figure 2-2) consists of four panels to load each of four different types of files. These files are: the UTM xy position file, channels.inp file, DSS file, and translation file. The UTM xy file and channels.inp file are required to run the DSVP. The translations.inp file may be required only if a DSS file requires it. A DSS file is only required to view time series data. More than one file may be loaded for each type. The UTM, channels.inp and DSS files will overwrite existing values from previously loaded files. The translations file will append values. Each file loading panel contains two buttons, one for loading files, the other for removing files. The Load Data Panel also contains two buttons. The first is the <Load Files> button, which loads the data from the selected files. The second is the <Write Channels.inp> button, which will write out a specified channels.inp file for the loaded and updated channels.

Figure 2-2: Load Data Panel.
Figure 2-2: Load Data Panel.   The Edit Data Panel

The Edit Data Panel (Figure 2-3) contains the polygon selection tool. This tool allows the user to create a polygon and retrieve the channels and nodes contained within the polygon. It can then list those channels and/or nodes as well as highlight the selected channels. It allows for the selection and deletion of channels from the list. It allows for the user to edit data and visual properties for a large number of channels.

Figure 2-3: Edit Data Panel.
Figure 2-3: Edit Data Panel.   The Display Panel

The Display Panel (Figure 2-4) contains three combo boxes that allow for the choice of available data types. The value displayed by the channel color, channel arrow length and channel bar is determined from the combo boxes. The checkboxes adjacent to the combo box allow the user to decide whether or not to display values by the associated method.

The Display Panel has four buttons that can either highlight channels that have translations or DSS data loaded or create a list of those channels depending on which button is selected.

The bottom of the Display Panel contains a panel for the loading of selected data types. If time series data have been loaded, the time at which to start displaying the time series can be selected (through use of the slider). Starting, pausing, and resetting the display of the time series can be done by selecting the appropriate button. This panel displays the current time and number of DSS paths containing data at the current time being displayed. It displays the maximum time and minimum time available from the DSS file (if any are loaded). If there are multiple time intervals, the interval to be displayed can be changed through the combo box.

Figure 2-4: Display Panel.
Figure 2-4: Display Panel.   The Legend Panel

The Legend Panel (Figure 2-5) consists of a tabbed pane that has three panels (one for each data display type). The legend shows the range of values for the display type.

Figure 2-5: Legend Panel.
Figure 2-5: Legend Panel.    The Options Panel

The Options Panel (Figure 2-6) consists of five toggle buttons that turn display features on or off. These are: node labels, channel labels, channel arrows, channel bars and null values. Null values occur when there is no valid data present for a channel. A sixth button updates the display after options have been changed. Changes will not appear until the <Apply Changes> button is used or the schematic is redrawn by some other request.

Figure 2-6: Options Panel.
Figure 2-6: Options Panel.

2.3.2     Loading Files

To use DSVP, a UTM xy file and a channels.inp file must be loaded. A DSS file needs to be loaded if time series data are to be displayed. A translations.inp file needs to be loaded if required for a DSS file. Translations are treated as aliases for existing channels and cannot exist on their own.

A file can be loaded by choosing an appropriate file type panel and clicking on its <Load> button. This launches a dialog that allows the user to select a file. The dialog will load with a default filter appropriate for the file type, but "all files (*.*)" can be selected if the file desired does not match the default filter.

If a DSS file is being loaded, once the file has been selected, a second frame will open with a list of the available paths for that file. This frame is a standard VISTA group table and allows for the displaying of data for each path in either graphical plot or tabular format. It also allows for filtering of paths by path part or time window. Once all desired filtering has been done, the user selects which of the remaining paths are to be loaded and clicks on the <Load Paths> button at the bottom. If no paths are selected, all of the listed paths will be loaded.

Multiple files can be loaded for each file type. Each subsequently loaded file will appear in the view window of the combo box. Previously loaded files can be selected from the combo box. Files will be loaded in the order in which they are selected. Since conflicting values are overwritten, the last file selected will have all of its values present, but files selected earlier may have values overwritten.

To remove a file, select the file in the combo box so that it appears in the view window and then click the <Remove> button for that panel. Once all desired files have been selected, click on the <Load Files> button to load the data and create the schematic.

Once the necessary files have been loaded, the rest of the functions can be performed in any order.

2.3.3    Updating the Display

Anytime a change is made that affects the appearance of the schematic (display options, changing channel name or connecting nodes, etc.), the schematic display must be updated to show those changes on the screen. The program does not do this automatically (except when displaying data) to allow for multiple changes to be made by the user without taxing the system. As a result, when changes are made, the user must click on the <Update> button at the top right corner of the control panel, or on the <Update Display> button in the appropriate panel being accessed.

2.3.4    Channel Select

The Channel Select toggle button is located at the top of the control panel in the lower right corner of the series of six buttons. While the button is depressed, the user may click on a channel in the schematic and a Channel Info frame (Figure 2-7) for that channel will be displayed. Selecting is most effective near the middle of the channel where it will not be confused with node selection.

Figure 2-7: Channel Info Frame.
Figure 2-7: Channel Info Frame.

The Channel Info frame consists of a tabbed pane with three panels. These panels are: Channel Info, Edit Info and Options.

The Channel Info panel allows the user to see the values that are held by the channel. These include the channel's name, length, dispersion, Manning’s n, connecting nodes and any translations that are assigned to the channel.

The Edit Info panel allows the user to change the values contained by the channel. The values displayed in the Channel Info panel can be changed in this panel by overwriting the value in the text field and then clicking on <Apply Changes> to commit the changes to the channel. Translations can be added by entering a new name in the text field and clicking on <Add>. Translations can be removed by selecting the translation to be removed in the combo box and clicking on <Remove>. Be sure to click on <Apply Changes> when done.

The Options panel allows the user to change the display properties of an individual channel. The user can select whether or not to display data by channel color, channel arrow length, and/or channel bar. In addition, if the channel contains time series data, the user can select a type of data from the combo box and then graph that data by clicking the <Graph Data> button. The graph that is created is a direct extension of the VISTA graph.

The Update Display button can be used to apply the changes made on the visual appearance of the schematic.

The Channel Select works well in conjunction with either the Display Translations/Display Time Series buttons on the Display panel or with the Quick Find.

2.3.5    Quick Find

The Quick Find panel is found at the upper left side of the control panel. The Quick Find allows the user to quickly find the location of a channel or node. A channel may be located either by its name or by its translation. The method of searching (CHANNEL name, NODE name, or channel TRANSLATION) is selected from the combo box. The name to search for is entered into the text field. The user can click on <Find> and the schematic will be centered upon the location of the found object and the object will be highlighted red. The value entered must be an exact match for an existing name or no action will occur.

2.3.6    Zooming

The Zoom Controls panel is found at the upper right side of the control panel. The Zoom Controls panel allows for zooming into and out of the schematic by increment through the <+> and <-> buttons. It also allows for an absolute zooming between the increment range through the slider.

Zooming into a particular area can be accomplished by using the Zoom Select button. Once the button has been depressed, the user can click the mouse inside of the schematic to create the first corner of the zoom selection. With the mouse button still depressed, the user can drag the mouse to create the second corner of the selection rectangle. When the mouse button is released, the schematic will zoom into the selected area.

2.3.7    Polygon Selection and Editing

The Polygon Select tool is located in the Edit Data panel. When the <Polygon Select> button is depressed, the user can use a mouse to create a polygon in the schematic. Each time the mouse is clicked, a dot will appear at that point. If more than one dot is present, a line will appear between the newest dot and the one previously created. When all of the points have been created, click on <Done> to close the polygon. Once the polygon is closed, a list can be created. To create a new polygon, the user must first click on <Clear> to remove the previous points.

To create a list of nodes, simply click on <List Nodes> and an ordered list of all of the nodes contained within the polygon will be created and displayed below the button.

To create a list of channels, click on <List Channels> and an ordered list of the channels contained within the polygon will be created and displayed below the button. By selecting the <Partial Select> radio button option, the list of channels will contain all channels that have one or more nodes inside of the polygon. By selecting the <Complete Select> option, only those channels with both connecting nodes contained within the polygon will be selected. When the channels are selected, the channels in the list will be highlighted red in the schematic.

Once a list of channels has been created, additional channels can be added one at a time by using the <+> button. After this button is clicked, the first channel in the schematic that is clicked on is added to the list. To remove channels from the list, a channel or collection of channels is selected within the displayed list and then click on <->. By selecting one or more channels within the displayed list and clicking on <Edit> a new frame will open allowing for editing the values of the channels. If no channels are selected, <Edit> will open all channels within the list. This new frame allows the user to change the Manning’s n and dispersion values as well as the display properties for the selected channels. Make sure to click <Apply Changes> if any changes are made to the values. There is currently no equivalent functionality for nodes.

2.3.8    Loading and Selecting Data Types

There are three ways to display values on the schematic. The first is by channel color, the second is by the length of the channel arrow, and the third is by the level of a bar graph located next to the channel. Any combination of the three display types can be turned on or off by selecting or deselecting the appropriate checkbox next to the name. The data types to be displayed are chosen from the combo box next to each name. The list of data types is generated from any DSS files that are loaded. In addition, the static values from the channels.inp file are also loaded (dispersion, Manning's n and length).

Once the data types are selected and decisions on whether or not to use the display types are made, the data can be loaded by clicking <Load>. All static values will be loaded and displayed while time series data will be loaded into a buffer and the Load button will change to the Start button to indicate that the time series data are available for viewing.

2.3.9    Viewing Time Series Data

Once the data have been loaded by clicking on <Load> in the Display panel, the time series data can be viewed by clicking on <Start>. This starts the animation. The animation can be controlled by <Pause> and <Resume> (the Start button will change to these as appropriate). The absolute position in time can be selected through the slider. By clicking on the slider and dragging it to a position, the user can change the animation time period. While the slider is selected the number of paths containing time series data can be viewed at the bottom of the panel. Depending on the amount of data contained in the files, it may take a few seconds for the slider to update the values. When the user has decided on a time to continue with, the slider can be released and a new buffer will be created. The slider can also be used prior to starting the animation.

To load a new series of data types, first use <Clear> to reset the animation values. Then just repeat the earlier steps.

2.3.10   The Legend

The Legend panel simply shows what the data values are that correspond to a specific display type. The Legend panel consists of a tabbed pane containing three panels, one for each display type. By selecting a panel, the user can see the range of values attributed to that display type.

2.3.11   Changing Display Options

The Options panel allows the user to change display options for the schematic. There are five different choices that are selected by a corresponding toggle button. These choices are to display or not display the nodes, channel labels, channel arrows, channel bars and null values. The <Update Display> button can be clicked to update the visual appearance of the schematic after changes have been made.

When a channel value displayed by color has no value, it is displayed as black. By turning off the <Null Values> changes the color of those channels to the null color (light gray).

2.4    Current Directions

The DSVP is being rewritten to take advantage of the Java2D API. Java2D API is a more flexible architecture than the standard Java graphics package and is used for defining shapes, lines, and fonts. This allows for a wider range of graphics options. The DSVP has been split into modules to allow for development of functionality beyond the program itself and to ease future changes. Taking advantage of the reusable nature of object-oriented languages, the three main modules have split off from the DSVP. They are the Schematic, the DSM2 File Parser and the Tidefile Reader.

The Schematic is being initiated as a generic layout of nodes and arcs. This will allow for other programs such as CALSIM and DSM2-PTM to take advantage of the common graphic engine.

The DSM2 File Parser is designed to retrieve selected data from DSM2 input files and allow for easy graphical manipulation of the data contained in those files. The functions will include adding data, removing data, merging data and changing existing data. Additionally, the parser will allow checking the files.

The Tidefile Reader is being designed to function as a stand-alone application that will provide linkages for programs such as the DSVP or DSM2-PTM. The Tidefile Reader will use an XML (eXtensible Markup Language) based template structure (XTT - XML Tidefile Template) that will define the structure of the tidefile. The reader will also provide file exporting to either formatted ASCII or DSS format. Additionally, the reader will provide an animator to graphically view data over time.

The general layout of DSVP is being moved to a more menu driven layout. This allows for more space to be available for the schematic as well as increasing the logical structure of commands and operations.

In general, data is being moved to an XML structure. This format is flexible, allows for easy manipulation, is easy to discern its content and meaning outside of the program and has mechanisms for the self-checking of valid data.

Author: Tawnly Pranger
Back to Delta Modeling Section 2000 Annual Report Table of Contents

Last revised: 2000-10-23

About Us Hydrology & Operations Section Delta Modeling Section Computer Assistance Section
Home Page Available Studies Computer Models Reports Home Page Available Studies Computer Models Reports

Disclaimer, Comments or Questions
Webmaster email to htdelmod@water.ca.gov