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.
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.
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.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.
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.
220.127.116.11 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.
18.104.22.168 The Edit Data Panel
Figure 2-2: Load 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.
22.214.171.124 The Display Panel
Figure 2-3: Edit Data 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.
126.96.36.199 The Legend Panel
Figure 2-4: Display 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.
188.8.131.52 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
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
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
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
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
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.
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
Comments or Questions
Webmaster email to