skip to main content
User Interface : Workspace : Canvas or Workspace Views
Canvas or Workspace Views
The canvas is the region within the workspace in which models are built and displayed. These canvas is shown when in Full mode, but not shown in Compact mode, as described in Workspace Display Mode.
There are three versions of the canvas which display different Views of the objects and connection. The Simulation View displays a schematic of the basin; objects are linked together to form a network. The Accounting View (when accounting is enabled) shows a similar schematic, but each object is displayed as a rectangle which contains all the accounts on that object. The third view, the Geospatial View, displays objects at their actual locations on a georeferenced background map. Because of the differences in how the network is displayed in each view, there are different configuration options for each canvas. The following sections describe each canvas and the configuration options.
Note:  Each canvas is configured separately. Although the configuration dialogs are the same for the Simulation and Accounting Views, their settings are not shared. Thus, you can configure each independently.
Simulation View
The Simulation View displays a schematic of the basin; objects are represented by icons and are linked together to form a network.
Note:  The Simulation View was the original view in RiverWare. As such, most of the screenshots in the RiverWare documentation reference this view when describing models.
Canvas Properties
The canvas properties dialog is accessed as follows:
• From the menu, select Workspace, then Canvas Properties.
• Right-click the workspace and select Canvas Properties.
This dialog allows you to change the following attributes of the canvas:
• Canvas Width. Number of pixels
• Canvas Height. Number of pixels
• Set Background Color. The selected color is saved in the model file.
• Set Text Color
• Set Canvas Font including the style and size
Background Image
The Simulation Workspace supports the ability to show an image loaded from an image file (JPEG or PNG) as the background. The utility is accessed by right-selecting the workspace and choosing Background Image.
The path of the selected image is preserved in the model file (if the model file is saved after configuring the background image). When loading a model with a configured background image file, if the background image file does not actually exist at the recorded path, the model loads without a problem, and the currently-invalid image file path is retained.
If the selected image file does not represent a valid, supported image file format, the thumbnail (small image preview) will be blank, and the Tooltip on the thumbnail will indicate an error. Figure 1.16 illustrates.
Figure 1.16   
Configurable background image properties include the following:
• The image file path (to a JPG or PNG image file).
• The left offset of the image—number of pixels from the left side of the workspace.
• The bottom offset of the image—the number of pixels from the bottom of the workspace.
• The horizontal scale. (100% represents full image scale).
• An optionally independent vertical scale. (100% represents full image scale). If an independent vertical scale is not specified, the configured horizontal scale is used also for the vertical dimension.
• An opacity factor, as a percentage. Zero percent is completely transparent (invisible). 100% is complete opacity, which generally is too opaque unless the actual image is already faded.
• A toggle indicating whether the background image should actually be shown. This has the same state as the similar toggle in the workspace context menu.
A typical use of a background image is a map. This works well if you can reasonably position the icons at approximate positions and/or you do not have or wish to use geospatial coordinate data. But, georeferencing is available on the Geospatial View; see Geospatial View for details.
Figure 1.17   
Accounting View
If Accounting is enabled, the accounting network is displayed in the Accounting View, and can be selected by the option menu on the toolbar. The accounting view provides a representation of the physical objects, as well as the accounts on those objects where the network can be displayed without occluding or modifying the original physical network.
General configuration of the accounting view is identical to the Simulation View. See Canvas Properties for details.
Note:  The settings are independent, not shared.
See Accounting Network in Accounting for details on the Workspace Accounting View.
Geospatial View
The Geospatial View of the workspace provides a spatially coherent display of the modeled basin by associating a map projection and its Cartesian coordinate system with the view. Users locate objects and a background map image in this coordinate system, allowing RiverWare to display a schematic view of the modeled basin overlaid in registry with the map. That is, RiverWare objects are displayed at their location on the map. By providing an intuitive and information-rich view of a basin, the Geospatial view complements the Simulation and Accounting views of the workspace.
Following are key features of the Geospatial View.
• The Geospatial canvas has an associated map projection and location (rectangular extent) within the projection’s coordinate system.
• A map image with a known location in the coordinate system can be displayed in the background layer of the view.
• Images can be georeferenced interactively or automatically via metadata contained within the image file or an accompanying world file.
• The background image (map) can be changed to another with the same projection without requiring any change to the spatial locations (geospatial view coordinates) of the objects.
• Objects are georeferenced (given spatial coordinates) and displayed at that location.
• A distinction is made between an object’s display and actual spatial coordinates.
• Object coordinates can be shared between models and external GIS applications.
• Additional control over the schematic view is provided including sizing and labeling of the icons.
• The coordinates of the cursor in the map projection are continuously presented in the status bar. When available, geographic coordinates (lat/long) are displayed as well.
Introduction to GIS Concepts
Graphical information systems (GISs) support storage, analysis, and display of spatial data. This section introduces some basic GIS terminology and concepts which are relevant to the Geospatial View.
Locations on the spherical earth are most often represented as a pair of coordinates representing latitude and longitude. For some applications, a third coordinate representing an elevation relative to mean sea level is also used. To display a part of the curved surface of the earth on a flat surface necessarily requires a projection, and GIS systems typically represent flat display locations as Cartesian coordinates in a plane onto which the surface of the globe has been projected.
Several standards have been developed to provide agreed-upon coordinate systems for a given area. These standard coordinate systems define a set of map projections which together cover the target area. One common coordinate system which covers the globe is the Universal Transverse Mercator (UTM) coordinate system. This system defines a projection for the northern and southern areas of each of 60 longitudinal zones spanning the globe. For example, in the projection UTM Zone 11 North, the coordinates eastings = 397,800 m, northings = 4,922,900 m, corresponds to a location in central Oregon, USA.
Another standard coordinate system is the State Plane coordinate system which defines a set of projections for the United States. In this system, each state is divided into one or more zones, so a location is specified by a state, zone designation, and x, y coordinates.
Note:  A standard coordinate system defines a mathematical coordinate system corresponding to each projection of a set of projections; when these two uses of the term coordinate system would be confusing, we use the term to refer to the standard, and use the term projection or map projection for the component (mathematical) coordinate systems.
Coordinates, whether they be geographic (latitude and longitude) or correspond to a map projection, are specific to a datum. A datum is a reference surface and surveyed coordinates for a set of actual points and lines. Examples of common datums include the North American Datum of 1983 (NAD83) and the World Geodetic System of 1984 (WGS84).
The Geospatial View has a map projection associated with it, and everything displayed in that view (e.g., object icons, background image) needs to be displayed in that projection. Because RiverWare assumes that a single projection is shared between the Geospatial View, the object coordinates, and the map, RiverWare does not need to know the mathematical details of that projection. However, if these details are provided to RiverWare (typically by providing a background image which contains metadata describing the image’s projection), then RiverWare can translate projected coordinates to geographic coordinates, and display these coordinates where appropriate.
Object Coordinates
To support the Geospatial View of the workspace, RiverWare associates coordinates in the view’s projected coordinates system with each object on the workspace. To provide more flexibility for the user, RiverWare supports both Actual and Display spatial coordinates. Actual coordinates are the static coordinates of the object which may come from other sources. The display coordinates are the location where the object is shown on the geospatial view. Often the display coordinates differ from the actual coordinates because the object was moved slightly for less icon clustering or better display.
When an object is created, it is placed at the point of creation in the current view and given locations in the other two views based on its location in the current view. Objects can be moved in any view, and in the Geospatial View this will change the display spatial coordinates. This view also provides the following additional mechanisms to edit or specify spatial coordinates:
• The Object Coordinate Manager dialog displays spatial coordinates for all objects in a single dialog. This dialog supports editing of individual values as well as cut/paste/copy (see section below for more details). This also provide a mechanism to facilitate reconciliation of an object’s actual and display spatial coordinates.
• Import the Actual Coordinates from an ESRI shape file.
Following is a description of the Object Coordinate Manager Dialog which is used to edit/view object coordinates. The Object Coordinate Manager is non-modal and accessed by right-selecting the main workspace (in the Geospatial View) and then selecting Object Coordinates.
The Object Coordinate Manager dialog displays both the display and actual spatial coordinates for all workspace objects. This dialog supports editing of individual fields as well as cut/paste/copy. For each object, both the display and actual spatial coordinates are displayed.
Following are operations that you can perform through the dialog.
• Select Coordinate system. Coordinates are displayed for either the projected or geographic coordinate system. If the canvas has not been configured with full projection information, then RiverWare can not convert to geographic coordinates and this option is disabled.
• Sort. Objects in the table can be sorted using the Sort menu. There are options to sort by Object Type, Object Name, Display X or Y, Actual X or Y, Custom and Custom from Workspace. To use the Custom sort, highlight one or more objects and use the blue up and down arrows to sort the objects. The Custom from Workspace sort option is defined on the workspace Object List; see Simulation Object List.
• Editing. Values in the dialog are only editable when the appropriate Enable Editing toggle is selected. Then, double-click a value and type in a new number.
• Show Data Objects. The Show Data Objects toggle allows you to specify whether you wish to see data objects.
• Show on Workspace. Select one or more objects, then right-click and select Show on Workspace to highlight and select the objects on the workspace.
• Copy Display/Actual Coordinates to the other. The Operations menu has options to Copy Display Coordinates to Actual Coordinates and Copy Actual Coordinates to Display Coordinates. This allows you to move coordinates easily between the display and actual.
Note:  These operations copy all values in the column, not the selected ones. When you do this operation, it may overwrite data. Thus, a warning dialog is provided for you to confirm or cancel the operation.
• Export Copy/Import Paste Values. You can copy or paste any values to or from the system clipboard and then to or from external text or Excel files or back to this dialog. This gives you a lot of flexibility in how you move data.
Note:  When you copy and paste values, it is operating on the selected values in the sort order as it is displayed. There is also an Export Copy with the Object Names option to also export the RiverWare object name. These operations are available from the right-click context menu.
• Importing/Exporting Coordinates. Import and export spatial coordinates through the ESRI shape file format. In this context, the shape file format is a collection of three files with different suffixes:
– .shp - objects represented as points.
– .shx - indices into .shp file
– .dbf - object attributes (initially object name and object type)
RiverWare supports export of the spatial coordinates of all or selected objects. When coordinates are imported, the user will be warned that the existing coordinates will be overwritten and notified when coordinates for unknown objects are encountered.
Note:  Both export and import use the projected coordinate system.
Figure 1.18 illustrates the possible movement of coordinate data within RiverWare.
Note:  Any operation using the system clipboard involves a Copy, Cut, and Paste, which involves Export Copy and Import Paste within RiverWare.
Figure 1.18  Data operations in the Object Coordinate Manager dialog
Getting Started With the Geospatial View
This section describes how you might begin to use the Geospatial View with an existing model which to this point has made use of only the Simulation and/or Accounting Views. Figure 1.19 shows the workspace Simulation View for the model we will be using to illustrate this process.
Figure 1.19  Simulation view of example model
1. Acquire a map of the basin.
As discussed above, the Geospatial View is most useful when you have a basin map with projection information. Such maps can be exported from a GIS application or acquired from a map provider. For example, you can download maps for the United States in a variety of formats from the USGS National Map site:
2. Switch to the Geospatial View.
Initially the positions of the objects in this view will be based on their original placement in another view. Also, at this point, the canvas will have a default configuration and the object coordinates in the default coordinate system (which equates one unit of distance with one display pixel) will likely be orders of magnitude off of their true coordinates in any actual coordinate system. In our example, the southernmost reservoir (Salty Reservoir) is at the northernmost position, and object coordinates are in the range 100–400.
3. Load the map.
Continuing with our example, open the Geospatial Canvas Configuration dialog and select a GeoTIFF image.
Figure 1.20  Geospatial Canvas Configuration dialog for sample model
Note:  There are many supported formats but common ones include GeoTIFF, JPG2000, and MrSID.
As illustrated in Figure 1.21, this is a 514 x 515 pixel image with projection metadata. While the projected coordinate system is not named in the metadata, the geographic coordinate system (datum) on which the projection is based, is NAD27.
Figure 1.21  Geospatial Canvas Configuration dialog for sample model
4. Adjust the Canvas.
By selecting the Image & Canvas Locations tab, we see the location of the image in the projected coordinate system, and we can adjust the canvas size if necessary. By default the canvas is automatically sized to be slightly bigger than the image, which works well for this model.
5. Apply changes.
At this point you have established the basics of the configuration and can apply your changes by selecting OK. Since the default object coordinates are in the hundreds but the image rectangle y coordinates are in the 4000 km range, the objects are not on the canvas as we it is newly configured. Figure 1.22 illustrates the Geospatial View after applying our changes and letting RiverWare automatically place the objects on the canvas.
Note:  The status text in the lower left corner of the dialog now shows the location of the cursor coordinates in both the projected and geographic coordinate systems.
Figure 1.22  Geospatial Canvas after importing image
6. Position the objects.
All the objects are on the canvas, but they are not at their true locations. If you knew their coordinates in the projected coordinate system, you could use the Object Coordinate Manager to place them, but for most purposes, placing them by hand in the workspace is adequate. Figure 1.23 shows the workspace after placing the objects at their approximate locations on the map.
Figure 1.23  Geospatial Canvas after moving objects
7. Refine the Configuration.
For this small, low resolution image, the RiverWare icons tend to obscure the map. To improve the display, you can return to the canvas configuration dialog and adjust controls in the Additional Display Settings tab. Figure 1.24 shows the workspace after tinkering with the background color, font, and label orientation, and then adjusting the icon positions further.
Figure 1.24  Geospatial Canvas after adjusting settings
Geospatial Canvas Configuration Dialog
The Geospatial View is most useful when a basin map exists which can be located (georeferenced) in a known projection system. If this information is not available, consider using the Simulation View with a background image.
The Geospatial Canvas Configuration Dialog allows you to specify information about your georeferenced image and how it relates to the RiverWare workspace. It is accessed as follows:
• Right-click the geospatial workspace and select Canvas Properties.
• Select Workspace, then Canvas Properties when the Geospatial View is shown.
We will discuss each of the Geospatial Canvas Configuration Dialog tabs in turn.
Image & Coordinate System Tab
This portion of the dialog describes the background image and the projected and geographic coordinate systems associated with that image (and the Geospatial View in general).
Background Image
Image files are specified by full path names with environment variable expansion. Environment variables are specified using the $PATH syntax. If the image changes outside of RiverWare you may need to reload it using the Reload button.
Of the many image formats supported by RiverWare1, the most common are JPEG, PNG, JPEG 2000, GeoTIFF, and MrSID.When an image is loaded, RiverWare checks for the presence of two type of useful metadata:
• Georeference. Location of the image in its projection.
• Projection. Description of the projection in WKT (well known text) format.
If present, these data are used to set appropriate aspects of the configuration. Some image formats support the embedding of these metadata in the image file itself (e.g., GeoTIFF, JPEG 2000, and MrSID), but RiverWare also checks for a co-located file with a suffix indicating that it contains image metadata. For example, RiverWare will look for an associated file in the world file format, a plain text file format developed by ESRI for georeferencing raster map images.
A valid world file contains six lines, each containing a floating point value, denoted here by the letters A to F. These values define an affine transformation from pixel coordinates to projection coordinates in the form:
    
    
where:
– x1 = calculated x-coordinate of the projection location
– y1 = calculated y-coordinate of the projection location
– x = column number of a pixel in the image
– y = row number of a pixel in the image
– A = x-scale; dimension of a pixel in map units in x direction
– B, D = rotation terms
– C, F = translation terms; x, y map coordinates of the center of the upper left pixel
– E = negative of y-scale; dimension of a pixel in map units in y direction
For many GIS applications, creating an image with a world file is relatively straightforward. For example, to do this in ArcMap 10.0, select File, then Export Map, then select the Write World File checkbox in the dialog. On the other hand, when this is not possible, the world file format is simple enough that it can be created by hand with a text editor.
The Geospatial View currently supports only images with unrotated, square pixels, thus not all map images can be displayed as background images. If metadata indicate that these assumptions are violated, RiverWare will notify the user at image load time.
Following are additional controls and information contained in this section of the dialog:
• Checkbox indicating whether to Show Background Image in View.
• Integer indicating the percent Opacity with which to display the image
• Labels indicating the presence or absence of georeference and projection image metadata.
Coordinate System
This panel displays information about the projected and geographic coordinate systems associated with the Geospatial View.
• Description. Textual description of the coordinate system. This could include a technical description of the coordinate system such as “UTM NAD83 Zone 11N”, but RiverWare will not make any assumptions about the description contents.
• Units. Text describing the units of the coordinate system. These are not limited to the units supported for slot values because these are used for display purposes only.
• Precision. Number of digits to the right of the decimal point with which to display coordinates.
• Horiz. Axis. Label associated with the horizontal dimension of the coordinate system. For the projected coordinate system, this is usually “x” or “Easting” but you can also select <custom> and enter your own text. For geographic coordinate systems, this is usually “long” or “longitude”.
• Vert. Axis. Label associated with the vertical dimension of the coordinate system. It is usually “y” or “Nothing” but you can also select <custom> and enter your own text.
• Display Scale. Projection units per pixel used for displaying the canvas on the screen at a zoom factor of 100%. This setting relates the projection to the screen display of the canvas. When the Set Display Scale for Best Quality Display box is checked, RiverWare sets this automatically, usually using the display scale which leads one pixel in the background image to be displayed as one pixel on the screen.
Note:  RiverWare uses a single display scale for both vertical and horizontal dimensions.
• Well Known Text (WKT). Indicates whether full projection information is available in the WKT format and allows this text to be view and edited. Typically this description will be set automatically from image metadata, but if the image does not contain this information, it can be provided interactively.
You can either set these fields interactively or, if the appropriate image projection metadata is present, RiverWare will set them automatically.
Note:  If the fields are set automatically, it is possible to override the values set from metadata, but they will be reset if the image (and metadata) is reloaded. A preferable approach would be to correct the metadata to contain the desired information.
The geographic coordinate system portion of this panel is only relevant when full projection information is present, typically part of the projection metadata. When this information is not present, this portion of the panel is disabled.
Image & Canvas Locations Tab
This panels displays information about the locations of the background image and canvas in the projected coordinate system.
Background Image Rectangle Location
To display the background image at the proper location on the canvas, RiverWare needs to know its location in the projected coordinate system (i.e., the image must be georeferenced). There are two alternatives for providing this information if RiverWare did find it when the image was loaded. One is to select the Set from: World File button. RiverWare will then present a file chooser dialog for specifying the world file containing the image’s georeferencing information. This option is appropriate when an appropriate world file exists, but it is either not co-located with the image or has an unusual name that prevents RiverWare from discovering it.
If no metadata is available, then another option is to provide coordinates for two specific locations in the map, in which case RiverWare will use these reference point coordinates to compute projection coordinates for the full image. To provide this information to RiverWare, select the Set from: Reference Points button. This opens the Image Location Dialog which displays a view of your image. For this utility, a reference point is a location for which you know the coordinates and you can locate in the image. Only 2 reference points are needed to locate the image in the projection coordinate system.
As shown in Figure 1.25, you perform the following steps.
1. Locate a reference points in the image. Use the zooming tools to get as close as possible to the first reference location. Select the button and then select the image to locate the first reference point one. Zoom/Scroll to the second reference location. Select the second button and select the image to locate the second reference point.
2. For the first reference point corresponding to enter the coordinates in the dialog.
3. For the second reference point corresponding to enter either the x or y coordinate; the other coordinate will be computed by RiverWare.
4. Click OK to confirm the entry and close the dialog.
If you have set the background image rectangle location interactively, you can export the corresponding georeferencing information by selecting the Export World File button. RiverWare will allow you to select a file name and write the background image’s georeferencing information to that file in the world file format. This file can then be used to automatically register the image within other RiverWare models or with any application that can supports the world file format.
Figure 1.25  Geospatial view Image Location dialog
Canvas Rectangle Location
In the Canvas Rectangle Location area, you specify where the canvas rectangle lies in the projection’s coordinate system, by giving the coordinates of the lower left and upper right corners of that rectangle. Checking the Set from Background Image withe Margin checkbox will cause RiverWare to automatically compute the canvas location to be that of the Background Image with an optional margin added to each side. Clearing this box allows you to interactively enter three coordinates of the canvas location (the remaining coordinate will be computed by RiverWare based on the other three). Care should be taken here to enter a canvas location that includes that of the image.
Canvas and Image Rectangles
This panel provides a high-level view of the canvas and image rectangles, drawn as rectangles whose size and relationship to each other matches that defined in the Background Image Rectangle Location and Canvas Rectangle Location panels. The locations of each coordinate (A, B, C, and D) are shown in the thumbnail.
Additional Display Settings Tab
In this tab, you can specify additional display settings for the geospatial workspace, as follows:
• Canvas Background Color. Select the button to bring up a color chooser.
• Icon Size. Enter a new value for the RiverWare icon size at 100% zoom factor.
Note:  The standard size is 40 pixels. Currently, this setting is global for the geospatial canvas. In the future, this may be changed to a per-object setting.
• Icon Label Location. Select the location of the label: below, above, left, right of the object.
Note:  No Label is an option. Currently, this setting is global for the geospatial canvas. In the future, this may be changed to a per-object setting.
• Icon Label Font. Provide a font and size for the label text.
• Icon Label Font Color. Select a color for the object label text.
All selections in this frame are applied to the sample reservoir icon immediately, but are applied to your workspace when the OK or Apply button is selected.
Applying Configuration Changes
When you are satisfied with the configuration and would like to apply it to the Geospatial View, select OK or Apply at the bottom of the dialog. This will apply changes from all tabs of the dialog (OK will also close the dialog). If the current spatial coordinates of one or more object do not fall within the configured canvas boundaries, you will be prompted with the warning dialog shown. A detailed explanation can be shown, basically explaining that RiverWare expects all objects to be displayed on the canvas, and that continuing the apply operation will cause RiverWare to automatically reposition those objects so that they are on the canvas. This is a reasonable thing to do if this is the first time an image and coordinate system information has been configured for this view. Once the new configuration has been applied the Geospatial View, you can then refine the positions of the object (by direct manipulation with the workspace or using the Object Coordinate Manager, described below). On the other hand, the objects could have correct coordinates for the coordinates system but are off of the canvas due to unintended changes to the canvas location, in which case you should cancel the apply operation and correct any problems.
Following are some strategies for dealing with overlapping icons which is sometimes called icon clustering.
• Use smaller icons and place labels to one side or the other.
• Give clustered objects display spatial coordinates that allow for a clear display, deviating somewhat from their actual coordinates as necessary.

1 RiverWare uses the GDAL open source library to read image files. This library supports over 100 raster data formats, though many of these formats are not suitable for background images because they do not contain color rendering information.

Revised: 08/02/2021