Introduction to GIS Integration

USEFUL LINKS
Wiki Links	Help	Downloads
TUFLOW FV Wiki Main Page	Products Support/Contact	TUFLOW FV Downloads
TUFLOW FV Tutorials	Requesting a Licence	Tutorial Module Data
TUFLOW Classic/HPC Wiki	TUFLOW FV Glossary	Manuals

GIS Workflow using Tutorial Model 01 - Pre-Requisites

This tutorial assumes you have completed up to and including Step 6 of Tutorial Model 01.

For assistance with setting up QGIS for use with Tuflow FV, please refer to QGIS tips.

Set GIS Projection and Create Empty Files

When using GIS integration with TUFLOW FV it is required that all GIS inputs and the mesh are in the same spatial reference system. Both spherical geographic coordinate systems and cartesian projected systems are accepted. The need for a singular spatial reference system for all inputs and outputs to TUFLOW FV is required to ensure GIS objects align correctly with the mesh or ‘snap’ to each other allowing them to be correctly read by TUFLOW FV. The first step to ensure this is to create a ‘dummy’ GIS layer with the model’s GIS projection (i.e. the geographic coordinate system to be used for ALL the TUFLOW FV model inputs). For Tutorial 01 we are going to set the spatial reference system to the projected Mercator system WGS 84 / UTM zone 60S. This process is assisted by the QGIS TUFLOW Plugin as follows:

1. Using the TUFLOW Plugin through Plugins >>> TUFLOW >>> Editing >>> Configure / Create TUFLOW Project

2. In the following Dialog specify:

• The Projection – Select the projection WGS 84 / UTM zone 60S

• Project Folder – The folder where you will undertake your modelling. It is the folder that will contain the folder TUFLOWFV and all its supporting subfolders. For example: C:\TUFLOWFV\Training_Workshop\Tutorial_01\TUFLOWFV.
• TUFLOW (FV) exe – The location of your Windows 64bit TUFLOW FV executable, for example: C:\TUFLOWFV\2019.01.001\ noting that your save location of the TUFLOW FV executable may be different to this.

• Check TUFLOW Flexible Mesh radio button
• Check Save Default Settings Globally (for all projects)
• Check Create TUFLOW Folder Structure
• Check Run TUFLOW to create template files
• Check Tutorial Model

3. Follow all prompts to save the default settings, create the folder structure and empty template files. This will result in three main actions:

• Saving Default Setting Globally: The TUFLOW FV Plugin will be setup to allow you to run TUFLOW FV directly from QGIS. This will be saved for all QGIS projects. You will be setup to access tools on the QGIS plugin like ‘import empty layers’, ‘increment layer’ allowing for rapid model development.
• Create Model Folder Structure: This will create the default folder structure for TUFLOW FV as follows:

• Create Template Files: This will will create the projection file .\TUFLOWFV\model\gis\Projection.prj. For interest you can open this file in a text editor and view the long text string containing spatial reference information for our selected system UTM WGS 84 / Zone 60S. Please close this file without making any changes. The QGIS Plugin also creates the FVC file Create_Empties.fvc in the TUFLOWFV\runs folder, which will be run in TUFLOW FV to create empty files in TUFLOWFV\model\gis\empty.

Please review the folder and associated files that have been written to the ‘Empty’ template files folder: TUFLOWFV\model\gis\empty\. We will use these empty files as the basis for developing the materials, boundary locations, nodestrings and mesh topographic updates. Each empty file has been set with the projection UTM WGS / Zone 60S and has been populated with a series of attribute types that will allow us flexibility over how we assign components to our model.

Rerun Tutorial Model 01 to Create Check Files

Once ready, copy and save the Create_Empties.fvc file in the TUFLOWFV\runs folder as trap_steady_04.fvc and open this file in Notepad++. This file now only contains the command to define the GIS format and model projection. We will edit this file to create a new run file.

Update FVC File

1. Comment out the last command since we don’t need to generate empty files again.

GIS FORMAT  == SHP
SHP Projection  == ..\model\gis\projection.prj
Tutorial Model  == ON
!Write Empty GIS Files == ..\model\gis\empty

Note: If you have completed the first 6 sections of this tutorial and have succesfully created and run trap_steady_01.fvc from the TUFLOWFV\runs folder, skip to step 5.

2. Go to the folder Complete_Model\TUFLOWFV\runs, copy the original tutorial FVC file trap_steady_01.fvc across to our working folder the TUFLOWFV\runs folder.

3. Copy across the input boundary data steadyQ_01.csv and steadyWL_01.csv from Complete_Model\TUFLOWFV\bc_dbase to our working folders of the model .\TUFLOWFV\bc_dbase\

4. Copy the mesh file trap_steady_01.2dm from Complete_Model\TUFLOWFV\model\geo over to our working mesh folder .\TUFLOWFV\model\geo

5. Copy across ALL commands from trap_steady_01.fvc to the newly created trap_steady_04.fvc file, below the existing lines of code.

6. Change the output type to xmdf for easier viewing in using the TUFLOW Viewer in QGIS:

 output   == xmdf

7. Additionally at the end of the file add:

Write Check Files  == ..\check

8. We are now ready to re-run our simulation with GIS check files enabled. We will run TUFLOW FV Using a Windows Batch File as detailed in the following section.

Running from a Batch File.

The preferred method to run TUFLOW FV is via a Windows batch file. We are going to create a batch file in the .\TUFLOWFV\runs folder called _run.bat. To do this, right click inside the runs folder, creating a new text file as follows:

Rename the newly created text file to _run.bat and open in Notepad++ (or your preferred text editor).

1. Once in a text editor add this command to set the path to FV executable:

set exe="Add your folder path to TUFLOW FV here\TUFLOWFV.exe"

where path is the path to your TUFLOW FV executable.

2. Set the number of CPU threads used in the simulation based on your PC spec:

set OMP_NUM_THREADS=2

3. Add the following command to run the FVC file using the above FV executable:

%exe% trap_steady_04.fvc

4. Run the model by double clicking the batch file. If you want to know more about running TUFLOW FV from a batch check out our Running TUFLOW FV from a batch file Wiki Page.

Inspect the Check Files

With GIS enabled and using the Write Check Files == ..\check command the TUFLOW FV 2019 release can export GIS files that assist you in reviewing what TUFLOW FV has used for input. We will start by investigating the three check files generated for trap_stready_04.fvc shown below.

1. Go to the TUFLOWFV\run\log folder, open trap_steady_04.qgs file by dragging this file into QGIS or simply double clicking it.

Now all the check files are opened in the “Output Layers”. (This model doesn’t have any input GIS layer, so the “Input Layers” group is empty).

2. Use the Apply TUFLOW Style to Open Layers button to check the styles of the check layers.

Note: If you cannot see the mesh at this point, select the ‘trap_steady_04_mesh_check (R)’ layer, go to view > ‘zoom to layer’.

3. Right click on the _mesh_check_R layer and open Attribute Table.

The following information can be check from the attributes:

• IDX2: 2D cell ID,
• IDX3: 3D cell ID (If the mode is 2D the IDX2 will equal IDX3),
• CTRDX: Cell center X coordinate,
• CTRDY: Cell center Y coordinate,
• Mat: Cell material ID,
• ZB: Cell center bed elevation,
• BRough: Bed roughness.

4. Uncheck the _ns_check_L check file in the Layer Panel to show the mesh check file and the BC check file only. All the boundary cell faces are represented by a line segment. Select the _bc_check_L check file in the Layer Panel.

Use the Identify Feature tool and click on one of the cell faces to open a Feature Attributes Window.

The attributes include:

• ID: Nodestring ID associated with the boundary
• TYPE: Type of the boundary condition. In this model “Q” for flow boundary or “WL” for water level boundary.
• Subtype: Subtype of the boundary
• Source: Boundary source file linked with the boundary

5. Uncheck the _bc_check_L and check the _ns_check_L in the layers panel to review the location and the direction of nodestrings. If the nodestrings are set correctly, the arrows should be pointing in the direction of flow.

Viewing Modelling Results using TUFLOW Viewer

This section of the tutorial will show us how to use the TUFLOW Viewer in QGIS to view our XMDF results.

1. Click the TUFLOW Viewer (TuPlot) button to open the TUFLOW Viewer window. Go to File>>>Load Results - Map Outputs.

2. In the pop-up window navigate to TUFLOWFV\results and open trap_steady_04.xmdf.sup

3. In the TUFLOW Viewer, try:

• Click Toggle Mesh Rendering to show and hide model mesh
• Change the vector and scalar to plot on the Result Type panel
• Use the timestep slider/buttons to advance through the time

4. Right click on the result type and change the plot style in the Contour/Vector/Mesh tabs.

Set Nodestrings in QGIS

In the original tutorial model boundary nodestings were set in SMS each time the mesh was regenerated and saved to the 2dm file. With the GIS functionality now in TUFLOW FV 2019 Release, users can define nodestrings through GIS commands allowing nodestrings to be assigned somewhat independently to mesh generation and 2dm creation. We will now show you the steps involved to set nodestings in this way.

Update Input Files

1. Save a copy of TUFLOWFV\model\geo\trap_steady_01.2dm as trap_steady_05.2dm and open this 2dm file in your preferred text editor.

2. Navigate to the bottom of the 2dm file, delete the two lines that start with “NS” and save the file (note: do not leave blank lines).

3. In QGIS, use the Import Empty file to import a template 2d_ns layer.

Select the type 2d_ns

Give the Run ID as T01_Boundary_001

Check Lines as the geometry type and press OK

The plugin has made a copy of the empty template file from the model\gis\empty directory and saved it into the model\gis directory, the location where all our working gis files reside for our project. The Import Empty File tool has added our new layer to the QGIS map canvas available for further editing. Note the _L suffix added to the shp file indicating that it’s a polyline geometry type.

4. Zoom to the upstream boundary (east side) of the model and toggle editing for the layer 2d_ns_T01_Boundary_001_L.

Select the Add Feature and create a line right next to the east domain boundary shown below. The direction of the line should be “from right to left looking downstream in the direction of flow”, i.e. from bottom to top in this model. After drawing the final vertex, use the right mouse button to finish the line. Please note the offset of the polyline from the mesh. This is the recommended approach for assigning ‘BD’ type nodestrings. TUFLOW FV will use its boundary algorithms to project onto the mesh.

5. When you finish the line an attributes dialog will be displayed. Enter the following data:

• ID = 1
• Flags = BD

This designates the nodestring type with the ID “1”. The ‘BD’ indicates that the nodestring is to snap along the outside of the model domain. This flag is used to assign nodestrings associated with model open boundary inputs.

6. Apply TUFLOW Style to Current Layer to check the nodestring direction. 7. At the downstream boundary (west or right side), add another nodestring next to the model domain boundary.

8. When you finish the line, enter the following feature attributes:

• ID = 2
• Flags = BD

9. Also add another nodestring in the middle of the channel with the following attributes. This nodestring will be used to monitor flux over time through the channel:

• ID = 3
• Flags = NULL (no need to add anything here, the default in QGIS is NULL)

Note typically when recording fluxes you should aim to have the nodestring drawn perpendicular to the dominate flow velocity. 10. Finish the edit by toggle the editing and when prompted, save the file. Now the model should look like the one below:

Finish the edit by toggle the editing and when prompted, save the file.

Update the FVC File

We need to read the boundary condition GIS files into the TUFLOW FV model.

1. Save trap_steady_04.fvc as trap_steady_05.fvc and open this file in your preferred text editor.

2. Update the geometry file to the 2dm with no nodestring we saved earlier:

Geometry 2d == ..\model\geo\trap_steady_05.2dm

3. In the boundary condition block, add the following command to read the SHP file that defines the nodestring:

Read GIS Nodestring == ..\model\gis\2d_ns_T01_Boundary_001_L.shp

4. In the output command block add the following commands to output the fluxes through the 3 nodestrings. This will output a timeseries of flux outputs every 600 seconds or 10 minutes.

Output== Flux
    Output interval== 600
End Output

5. Update the batch file and run the model.

Discussion

1. How does the _ns_check file looks comparing to the previous model?

2. Open the TUFLOWFV\results\trap_steady_05_FLUX.csv file in Excel and plot the data. Does the flux through the nodestring look sensible?

Define Materials using GIS File

Bed materials can also be defined via GIS in the TUFLOW FV 2019 Release. To show this functionality we will assign a higher Manning’s ‘n’ value to the right-side slope of the trapezoidal channel.

Create 2d_mat File

1. In QGIS, use the Import Empty file to import a template 2d_mat layer.

Select the type 2d_mat

Give the Run ID as T01_Berm_001

Check Region as the geometry type and press OK

2. Toggle editing for the 2d_mat_T01_Berm_001_R layer and then select the Add Polygon Feature . Create a polygon to cover 2 rows of cells at the bottom of the model. As with the polylines once you are happy with your polygon, right click to finish the drawing. Enter the following data in the attributes dialog:

• Material = 2

Note that most of the cell will be assigned as “Material 1” using a global command and the polygon above will be used to override the material IDs for the selected cells. This means we don’t need to draw another polygon to select the rest of the cells.

3. Finish the edit by toggle the editing and when prompted, save the file.

Update FVC File

We need to set the material ID globally first, and then read the material GIS file into the TUFLOW FV model.

1. Save trap_steady_05.fvc as trap_steady_06.fvc and open this file in Notepad++.

2. In the material properties block, add:

Set Mat == 1
Read GIS Mat == ..\model\gis\2d_mat_T01_Berm_001_R.shp

The first command will set the cell material ID to 1 globally, and the second command will read the SHP file to override the cell material ID within the polygon.

3. At the end of the material properties block, also add the followings to define the Manning’s n value for material 2:

Material  == 2
    Bottom Roughness == 0.05
End Material 

Now the material properties block should look like this:

4. Update the batch file with trap_steady_06.fvc and run the model.

Discussions

1. Double click to open trap_steady_06.qgs workspace from the \runs\log directory and apply the default TUFLOW style to all layers.

2. Double click on the trap_steady_06_mesh_check_R layer and complete the following steps to “Categorize” the mesh colour based on “Mat”:

• In the “Symbology” tab, select “Categorized” from the first drag down list

• Select “Mat” attribute from the Column drag down list, and click “Change” button,

• Select “Simple fill” and change the “Fill style” to “Solid” if it hasn’t been selected

• “Classify” the mesh and press OK.

Is the material ID assigned properly to the cells?

3. Open TUFLOWFV\results\trap_steady_06.ALL.sup and compare the flow field with the previous models. Does the flow velocity become smaller where Manning’s ‘n’ is higher?

Simple Geometry Update using GIS File

In the TUFLOW FV 2019 Release it is now possible to update the topography/bathymetry directly from GIS using points, lines and polygon layers (and also GRIDS refer Tutorial Model 03). This was previously only available in TUFLOW FV using csv input which could be quite cumbersome. In this tutorial model we will create a small obstruction on both sides of the channel to highlight the use of topographic updates using GIS.

Create 2d_zline File

1. In QGIS, use the Import Empty file to import a template 2d_zln layer.

Select the type 2d_zln

Give the Run ID as T01_Obstruction_001

Check Lines as the geometry type and press OK

2. Toggle editing for the 2d_zln_T01_Obstruction_001_L layer and then select the Add Feature . Create two lines on both sides of the channel as shown below. When you finish the drawing enter the following data in the attributes dialog for both polylines:

• Elevation = 1

This will assign an absolute elevation of 1m to the cell centroids at cells intersected by each polyline.

3. Finish the edit by toggling the editing and when prompted, save the file.

Update FVC File

We will update the fvc file to read the Zline GIS file into the TUFLOW FV model.

1. Save trap_steady_05.fvc as trap_steady_07.fvc and open this file in your preferred text editor.

2. After reading the 2dm file, add:

 Read GIS Z Line  == ..\model\gis\2d_zln_T01_Obstruction_001_L.shp

3. Update the batch file and run the model.

Discussions

1. Double click to open trap_steady_07.qgs workspace from the \runs\log directory, and apply the default TUFLOW style to all layers.

2. The cells selected by the Z lines should have upward triangle signs to indicate the bed elevations have been modified. Check the attribute table and to see that the modification has been carried out correctly.

3. Open TUFLOWFV\results\trap_steady_07.xmdf.sup and compare the flow field with the previous models. Does the flow field near the obstruction look reasonable? You can see the areas were the topographic updates are assigned are dry. Also, there is an increase in velocity through the vicinity of the constriction which we would expect to see through this area.

Conclusion

Well done. You have now covered the basics of integrating TUFLOW FV with GIS.
Return to Tutorial Model 01 to complete the remainder of the tutorial, or if interested, please refer to Tutorial Model 03 for advanced GIS model build features.