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.

The Simulation View displays a schematic of the basin; objects are represented by icons and are linked together to form a network.

The canvas properties dialog is accessed as follows:

This dialog allows you to change the following attributes of the canvas:

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.15 illustrates.

Configurable background image properties include the following:

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.

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.

See Accounting Network in Accounting for details on the Workspace Accounting 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.

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.

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.

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:

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.

Figure 1.17 illustrates the possible movement of coordinate data within RiverWare.

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.18 shows the workspace Simulation View for the model we will be using to illustrate this process.

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:

We will discuss each of the Geospatial Canvas Configuration Dialog tabs in turn.

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).

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 RiverWare¹, 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:

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:

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:

This panel displays information about the projected and geographic coordinate systems associated with the Geospatial View.

You can either set these fields interactively or, if the appropriate image projection metadata is present, RiverWare will set them automatically.

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.

This panels displays information about the locations of the background image and canvas in the projected coordinate system.

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.24, you perform the following steps.

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.

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.

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.

In this tab, you can specify additional display settings for the geospatial workspace, as follows:

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.

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.