The application uses layers and objects to define the topography of models. These layers are accessed from the Layer Control Panel. The following layers are used to support 1D, 2D and, 1D/2D models.


DTM layers

Elevation data may be integrated into any XPSWMM 1D, 2D or 1D/2D model with a Digital Terrain Model (DTM) in the form of Triangular Irregular Network (TIN).  In addition an ASCII grid may also be referenced.  In that case only the bounding rectangle and the maximum and minimum elevations are reported.  This Grid may be referenced for 2D modeling by the 2D engine if the option is selected in the 2D Job Control.

A variety of tools are available to import, export and manage the display of DTM layers. To access these tools, move the mouse over DTM Layers in the Layer Control Panel and right click to load the contextual popup menu.

To add a DTM, select one of the options:

After the DTM layer has been added, select an option:

Reference a Grid File for XP2D

The Reference a Grid File for XP2D option allows you to load an existing grid file (*.asc, *.flt, *.txt) into the software, which will be used as the surface data. For large models, loading a Grid file from an external source may be more beneficial than building the DTM surface (*.xptin).

Once the grid file is loaded, it becomes available in the Layer Control Panel. You can then right-click and modify the DTM Properties

Load XPTIN File

The Load XPTIN File option allows the you to load an existing TIN file (*.xptin and .tin.0) that was created by xp or the 12D model software packages. When a TIN file is selected xp will report the number of triangles, points, and also indicates the real world extents.

Create XPTIN From XYZ File

The Create XPTIN From XYZ  File option allows an XYZ or and XYZS file delimited file to be triangulated and loaded into you project. The file can be delimited by space or comma and should follow the form: 

XYZ File: 

X1, Y2, Z1

X2, Y2, Z2

Example: 

100.2, 347.2, 213.2

2001., 347.4, 199.4


XYZS File

X1, Y2, Z1, S1

X2, Y2, Z2, S2

Example:

100.2, 347.2, 213.2, 610

2001., 347.4, 199.4, 610

Where:

S1 and S2 indicate points on a breakline

Choosing the Create XPTIN From XYZ File command from the right-click menu will launch a Windows Explorer dialog. Navigate to the location of the XYZ or XYZS file to load, and click Open the data file. The dialog will close and triangulation will begin. The progress bar monitors the triangulation.

A series of files will be created named aaaaa.tin.X where:

aaaaa = name of source XYZ or XYZS file

X = a number indicating one of several files created to make the TIN. The file ending in 0 is the principal file.

The color coded TIN will appear in the network window and the path to the TIN file will be indicated in a new line in the layer control panel.

Create XPTIN From Grid File

The Create XPTIN From Grid File option allows you to create a DTM from an ESRI Grid file. Launch the tool by right clicking on the DTM Layers row in the  Layer Control Panel.

In the Windows Explorer dialog, navigate to the source file. Click Open to load the file.

Create XPTIN From 12D ASCII File

The Create XPTIN From 12D ASCII File option allows the importing of a 12D ASCII DTM file in order to create an *.xptin. It should be noted that in order to properly be converted the 12D ASCII file must be a complete TIN file and include triangulation points.

DTM Builder

The DTM builder allows a spreadsheet view of the data points to be triangulated to create the TIN. This spreadsheet view can be directly edited or copied and pasted into to generate and modify the points. Selecting the Create DTM button will triangulate the points and display and add the TIN to the Layer Control Panel.

There are several data formats which can be imported to populate the DTM Creator spreadsheet. These format types are described below and can be selected from the right side of the DTM Builder dialog.

Read XYZ File

Load a file of easting, northing, elevation, and string name. Similar to the previous option of creating a TIN from XYZ file but the data will be able to be edited in the spreadsheet view before triangulation. This option will allow the import of *.xyz, *.xyzs, *.txt and *.csv format files.

Read GIS File

Reads the elevation points from a MapInfo MIF file (*.mif) or ESRI Shape file (*.shp).

Read Grid File

This import option allows the import of ESRI format files (*.asc, *flt, and *.txt) into the DTM Builder.

The Check for Duplicate Points option will check for duplicate x,y points already read. If duplicates are found, only the first one read will be used. This option will slow the DTM Creator; if there are no duplicates in the input data file, this option should be disabled.

If more than one duplicate of X, Y, Z values of 0, 0, 0 are added similar to the image below, the application will not proceed and the following error message will be displayed:

Cannot create TIN file, no triangle generated.


DTM Properties

The DTM Properties dialog is used to manage the DTM layers.

The top window lists active DTM layers. Select a layer to perform any of the options:

Load. Load a new DTM file

Create. Launches the DTM Builder dialog. 

Color Range. Adjust the color display

Up/Down. Adjust the order of display for the DTM layers

Delete Remove the DTM from the model

Show. Toggle the display of the layer (same effect as the visible check box on the Layer Control Panel)

Display Legend. Toggle the display of the DTM legend in the Network View.

Edit Legend. Edit the display of the DTM legend in the Network View.

Information Tab

The Information tab of DTM Properties displays the following field groups:

General Attributes:

Number of Triangles – Lists the number of triangles in the DTM

Number of Points – Number of individual data points contained within the DTM

Elevation (Min/Max) – Displays the minimum and maximum elevations contained within the DTM

Real World Extents:

Top – Location of the top of the DTM extents

Bottom – Location of the Bottom of the DTM extents

Left – Location of the Left of the DTM extents

Right – Location of the Right of the DTM extents

Display Properties Tab

The Display tab of DTM Properties displays the following field groups:

Draw Parameters:

Fill Color on Height Range [Flag] – Enables the color filling of the DTM based upon the height range

Contours and Style – Allows the toggling of major and minor contours and the selection of contour styles

NOTE:

If both color shading and contours are desired it is important to increase the transparency of the colors in order to visualize the contours.

Contour Labels Tab

The Contour Labels tab of DTM Properties displays the following field groups:

Contour Labels:

Contour labels can be turned on or off with the Show check box. The user can select the label interval such as every 100m.

Font:

The font and color can be selected for the contour label.

Align:

Select the desired contour alignment using the radio button.

DTM Gradient Colors

The DTM Gradient Colors dialogue is used to adjust the elevation gradient colors of the DTM layers. To open this dialog, click on the Color button in the DTM Properties dialog.

DTM Legend

To access DTM Legend dialog:

  1. Highlight the Topography -> Legends line in the Layer Control Panel and right click 
  2. Select Properties from the pop-up menu

DTM Grid Layer

The Grid Layer accepts indented layer(s) of polygon(s). These polygons will expose the underlying triangulation if they overlay a triangulated XPTIN.

To add a Grid Layer:

  1. Right-lick the Grid Layers in the Layer Control Panel and then select Add Layer.
  2. Enter the name for the new layer and then click OK.

To view the properties of a Grid Layer, right-click the specific Grid Layer in the Layer Control Panel and then select Properties.  If multiple DTM are present they will be listed in this dialog.  Toggle the Show tick box in order to specify the layer for viewing.

To rename a Grid Layer, right-click the specific Grid Layer that you want to rename in the Layer Control Panel and then select Rename This Layer. Enter the new name in the dialog.

To delete a Grid Layer, right-click the specific Grid Layer that you want to delete in the Layer Control Panel and then select Delete This Layer.

To view or modify the color, right-click the specific Grid Layer in the Layer Control Panel and then select Colour.

To delete the content of a layer, right-click the specific Grid Layer in the Layer Control Panel and then select Delete Contents Of This Layer. Click OK to confirm deletion.


Export DTM Data

Use this tool to export all or a single TIN file to a txt file. Launch the tool by right clicking on the DTM Layers row in the Layer Control Panel.

 

Breaklines (Gullies and Ridges)

Gullies and ridges are breaklines that cause discontinuities in the surface of 2D active areas. They are represented as polylines. Effectively the elevations of the cells lying below the polyline are raised or lowered to correspond to the polyline. Within the modeling environment the minimum thickness of breakline is 1 cell.

2D Breaklines are defined as a gully (or ridge) polyline with a fixed elevation throughout. 3D breaklines are specified as a Gully or Ridge polyline with a specified elevation at each vertex.

When the elevation (z value) derived from the DTM and the user defined elevation differs, XPSWMM defines the breaklines using:

Gully: minimum value

Ridge maximum value

For a Gully, z values are modified only if the user defined z values are lower than the current DTM value.

For a Ridge, z values are modified only if the user defined z values are higher than the current DTM value.

To add a gully or ridge polyline using the graphical interface:

  1. Highlight the Topography layer in the Layer Control Panel, and right-click to launch a pop-up menu
  2. Select Add New Layer -> Gully Breaklines or Ridge Breaklines


  3. Highlight the newly-created layer, and select the Polyline Tool  from the Object Creation Tools.
  4. On the network window, left-click where the first vertex will be placed.
  5. Continue left-clicking to create the breakline, and double click on the last vertex to end the drawing process and launch the Breaklines data dialog.


  6. Elevations along the polyline extracted from the DTM are shown in the table as a reference. Use the radio buttons to define the gully (or breakline) as either 2D (at a specified contour) or 3D using the elevations derived from the DTM. New elevations may be added or copied and pasted into the Elevation column
  7. Click OK to apply the changes and close the dialog
     

To import gullies or ridgelines from a GIS file:

  1. Highlight the Topography layer in the Layer Control Panel, and right-click to launch a pop-up menu
  2. Select Add New Layer -> Gully Breaklines or Ridge Breaklines 
  3. Right-click the newly-created layer, and select Import from GIS file on the pop-up menu
  4. In the next dialog, navigate to the source GIS/CAD file. 
  5. To import only selected data, check the box next to Import Selected Data. Select a property (or attribute) from the drop menu, and specify the value for selected records. The ‘Weld Vertices’ option can be selected in this dialog. When this option is turned on, each vertex added during import is first checked against existing vertices, and welded if any vertex exists in the same location. When the Weld Vertices option it is turned off, this welding does not occur – a new vertex is added for every point imported – but the import process may be faster.
     
     
  6. In the next dialog, click the radio button corresponding to the desired elevation option. To read the elevation from the Attribute Data, use the drop list to select the appropriate attribute in the source file.
     
     

  7. A report of the import operation is displayed. Click on OK.


To modify the layout of a gully or ridge polyline:

  1. Check the Gullies Layer on the Layer Control Panel to ensure that it's unlocked. A locked layer will have a small padlock icon beside the layer name. 
     

    If the layer is locked, right-click the layer name, and select "Unlock Layer" from the pop-up menu. 
  2. Select the Pointer Tool from the Object Creation Tools.
  3. Move the mouse to the object and left click, the mouse will change to the four-arrowed cross when it is moved over a vertex .
  4. Hold the left button down and drag to move a vertex.
  5. Select a gully/ridge vertex or polyline, and right click. Choose the appropriate command from the popup menu.
     

To modify the display properties of the gully or ridge polylines:

  1. Make sure the gully or ridge is unlocked on the Layer Control Panel.
  2. To view and modify the display properties, either: 
    1. move the mouse over a gully or ridge and right-click. Select Properties from the popup menu, or
    2. move the mouse over the Gully or Ridge line in the Layer Control Panel and right click. Select Properties from the popup menu.


To edit the elevation data of a gully ridge:

  1. Make sure the gully or ridge is unlocked on the Layer Control Panel.
  2. Double click on a polyline. Alternatively, or left-click on a polyline to select it, right-click and select Edit Data from the popup menu.
  3. Enter the data to be modified in the Breaklines Data dialog.
     

The Ridge and Gully breaklines can be displayed as shown above, or along with the existing surface elevations in the Edit dialog. 

Fill Areas

An entire region of the 2D model can be raised or lowered by using fill areas. These polygons can be used to simulate levees, buildings, ponds and other features missing in the DTM.

Each fill area polygon is assigned a constant elevation. Effectively all of the grid cells within the fill area 2D model will be raised or lowered. The entire cell must be within the fill area to be affected. If the fill area elevation is higher, the area will not be flooded until the water level is above its elevation. If the fill area elevation is lower (representing a pond), the area will fill with water until the surface reaches the elevation the surrounding cells.

Where fill areas overlap the DTM, xp assigns the elevation of the fill area to the model cell. Users can manually add Fill Areas or import these shapes as shown in the 2D Object Creation section. 

The Data Dialog is used to edit the elevation of the fill area

The display properties dialog is used to modify the perimeter and fill pattern of the fill area polygon

In version 2013 and later, Fill Areas have a global adjustment method (i.e. double click on the object to open the dialog and make revisions). The changes can then be applied to the selected object, all selected objects, or all object of this type.

Note

All fill area polygons exist in a single data layer and have the same display properties. Editing the display properties of a single polygon will modify the display properties of all fill area polygons.

Elevation Shapes

Elevation Shapes are used to modify Grid cell elevations based on the given user input, similar to Dynamic Elevation Shapes. Elevation Shapes can be either polygons or polylines.

There are different menu dialogs for each type of Elevation Shape, polygons or polylines, which contain different input fields. These dialogs are outlined below:

 

You can manually add Elevation Shape polygons or polylines or import these shapes as shown in the 2D Object Creation section

Elevation Shape (Polyline)

Breakline Type:

TIN Breakline

Designates the Elevation Shape polyline as a TIN breakline, which is used when the Elevation Shape polyline is located within a 2D elevation Shape Polygon.

Breakline

Designates the Elevation Shape polyline as a normal breakline.

Line Type:

Thin

Denotes that the Elevation Shape polyline will have no width.

Thick (width)

Input the width of the Elevation Shape polyline.

Note

When applying an Elevation Shape polyline along 1D/2D interface lines (in order to force exact top of bank or other ridge information to the adjacent 2D cells) the Thick line option should be selected to ensure that the whole cell is raised to the correct height. This is needed as 1D/2D interface (HX) cells are inactive on one side so the whole cell needs to be raised – a thin line will only raise the nearest cell side which could be the inactive side of the cells draped by the 1D/2D interface line. 


Elevation Modification:

Lower where Current Elevations are Higher:

This option will LOWER the current cell levels by given amounts only if current elevations are higher.

Raise where Current Elevations are Lower:

This option will RAISE the current cell levels by given amounts only if current elevations are lower.

Change All Elevations:

This option will replace all cell elevations to the values denoted in the Perimeter Elevation section.

Note, in version 2013 and later, Elevation Shapes can be adjusted globally. After double clicking on the object and making a change in the dialog, the revision can be applied to the selected object, all selected objects, or all objects of this type.

Perimeter Elevations:

Constant elevation:

This option will set the cell levels at the given elevation.

Variable:

This option allows the independent modification of the elevations of each vertex. [Z column].

Adjustment to all Elevations:

Adjusts all existing cell elevations.

Elevation Shape Data (Polygon)

Elevation Modification:

Lower where Current Elevations are Higher:

This option will LOWER the current cell levels by given amounts only if current elevations are higher.

Raise where Current Elevations are Lower:

This option will RAISE the current cell levels by given amounts only if current elevations are lower.

Change All Elevations:

This option will replace all cell elevations to the values denoted in the Perimeter Elevation section.

Perimeter Elevations:

Merge With Existing Elevations:

This option will mix the existing cell elevations with the new elevation shape elevations.

Adjust All Existing Elevations:

This option will adjust all existing cell elvations.

Constant elevation:

This option will set the cell levels at the given elevation.

Variable:

This option allows the independent modification of the elevations of each vertex. [Z column].

Adjustment to all Elevations:

Adjusts all existing cell elevations.

Time to Reach Final Elevations:

The simulation time (in hours) until the Final Elevations are set, for example, the time until a fence or levee collapses.

Dynamic Elevation Shapes

Dynamic Elevation Shapes are used to modify changing Grid cell elevations based on the given user input. Dynamic Elevation Shapes can be either polygons or polylines and the attributes of which can be based on Time or Trigger Points. They can be used to simulate collapsing fences, levee or dam breaches, and other dynamic hydraulic situations where the grid cell definition changes throughout the simulation.

You can manually add Dynamic Elevation Shape polygons or polylines or import these shapes as shown in the 2D Object Creation section.

To modify or update a given Dynamic Elevation Shape select and right-click either the polyline or polygon and select Edit Data. The following description outlines the input options within the Dynamic Elevation Shape dialog.

Triggered By:

Start Time

Input the starting time in decimal hours , starting from midnight of the first day of the simulation.  For example, 2:30AM on the second day would be entered as 26.5 and this entry is irrespective of the model start time even if it does not start at midnight (hour 0).

Water Level at Trigger (at Value)

Input the water elevation value that triggers the Dynamic Elevation Shape change, for the connected Trigger Point.

Water Level Difference Between Triggers (at Value)

Input the water elevation difference that triggers the Dynamic Elevation Shape change, based on the connected Trigger Points.


Elevation Modification:

Lower where Current Elevations are Higher

This option will LOWER the current cell levels by given amounts only if current elevations are higher.

Raise where Current Elevations are Lower

This option will RAISE the current cell levels by given amounts only if current elevations are lower.

Change All Elevations

This option will replace all cell elevations to the values denoted in the Final Perimeter Elevation section.


Final Perimeter Elevations:

Merge With Existing Elevations

This option will mix the existing cell elevations with the new elevation shape elevations.

Constant elevation

This option will set the cell levels at the given elevation.

Variable

This option allows the independent modification of the elevations of each vertex. [Z column].

Adjustment to all Elevations

Adjusts all existing cell elevations.

Time to Reach Final Elevations

The duration time (in decimal hours) until the Final Elevations are set.  For example, the amount of time until a fence or levee collapses, if this would take 45 minutes then enter a value of 0.75.

Note

In version 2013 and later, Dynamic Elevation Shapes can be adjusted globally. After double clicking on the object and making revisions, the changes can be applied to the selected object, all objects, or all objects of this type.

Trigger Points

Trigger Points can be used as a reference point for adjusting Dynamic Elevation Shapes. Trigger Points are input into a 2D model using the Point option within the Object Creation toolbar and must be linked to a Dynamic elevation Shape before they can be referenced.

The linking of a dynamic shape to a trigger point is performed by selecting the Dynamic Elevation Shape with the Pointer tool. Then moving the cursor to the centroid of the shape the cursor will change to a polygon to node tool. Drag the cursor to the desired trigger point. When a trigger point is found the cursor will change to a crosshair. Release the mouse button to complete the connection.

Grids

For large models, it can be cumbersome to import the surface data. In these cases, it can be beneficial to read the grid file rather than actually building the DTM surface (*.xptin). This selection is available under the 2D Surface tab in the 2D Job Control dialog.

When you select to Read the DTM as opposed to Importing the DTM into the model, the grid extents for the surface can be displayed using one of these functions. If this function is not enabled, the extents of the surface data will be unknown. This is useful when building the model objects, navigating through the network, and reviewing results, and so on. Conversely, the grid display is not necessary when the surface data is imported into the model.