Meshing M02 GIS Mesher

From TUFLOW FV Wiki
Jump to navigation Jump to search
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

Tutorial Description

In this tutorial we will be building a mesh for an inbank area of a riverine channel using the GIS Mesher. We will:

  • Create the project using the GIS Mesher GUI
  • Define the model domain (boundary polygon)
  • Define the mesh sizes
  • Specify the nodestring locations
  • Add the Elevation data
  • Add materials to the mesh
  • Build the mesh

(MADDY TODO:MB ADD add a decrip of model mesh)

Requirements And Downloads

Requirement Brief Description Download
GIS Mesher The GIS Mesher developed by Rising Water Software builds meshes for hydrodynamic models that use a combination of quadrilateral and triangular meshes. Spatial data is provided to the mesher as GIS layers, so that you can use your favorite GIS application to build quality meshes quickly and easily.

This tutorial was developed using GIS Mesher version 2023.01, it recommended to use this version or later versions of GIS Mesher. If using a different version of the GIS Mesher, some of the dialogue boxes and screen shots may change slightly, however the overall workflow should be similar.

GIS Mesher downloads and release notes can be found here GIS Mesher.
QGIS
The Geographic Information System (GIS) QGIS will be used in this tutorial in combination with GIS Mesher to help define inputs to the mesh builder. This tutorial was developed with QGIS 3.26.2, it is recommended to use this version or later versions. If using a different version of QGIS, some of the dialogue boxes and screen shots may change slightly.

We will also use the the QGIS TUFLOW Plugin which includes numerous tools to increase workflow efficiency.

QGIS can be download from Latest 64-bit version of QGIS.
Model Data The data provided for the completion of this tutorial includes:
  • The Module_Data folder which contains the bathymetry data as a raster (.tif) dataset, land-use areas provided as a shapefile (.shp), the model domain provided as a polygon shapefile (.shp) and a projection file (.prj)
  • The Complete_Mesh folder that contains the files for the completed tutorial in case you get stuck, and
  • A working folder is provided for the files you create and work within.
TUFLOW FV Tutorial Models.

Assumed Knowledge No prior knowledge is required for the completion of this tutorial. We have designed this tutorial to provide an introduction to meshing for all modelling levels. Not Applicable

Prepare Your Working Environment

(MADDY TODO: Create a simple chart that shows the workflow of how GIS Mesher and QGIS will be used together in the Tutorial).

Install GIS Mesher

Please head to GIS Mesher to download the latest version of software and access release notes. For additional help notes on the GIS Mesher Please use the Rising Water Documentation page. If you run into any issues during the installation process, please get in contact with the Rising Water help team via the Contact page.

Extract And Save The Data Package

Please ensure you have downloaded the Model Data. Copy and unzip the folder to your preferred working location, for example C:\TUFLOWFV\Meshing_M02_Tutorial_GIS_Mesher\. [(MADDY TODO: Tidy this up) REPLY we might need to update the file path depending on what we call the final m data package folder they download]

  • The Complete_Mesh folder contains a completed version of the tutorial and its supporting files. You can use this as a reference if you require.
  • The Module_Data folder that contains data files required to complete this tutorial.
  • The working folder is for the files you create and work within.
Mesh GISM 002.png

Creating The Project

The GIS Mesher GUI provides tools for building projects, creating GIS files, running the mesher, and running TUFLOW FV. Follow the below steps to create the project:

Firstly, start up the GIS Mesher GUI. It should like like the figure below.
Select File > New Project from the menu.
River chan Newproj 00.png

In the New Project dialog box, select the following:
1. Specify the parent folder as the working folder in your tutorial folder (likely different than specified below). (MADDY TODO: Have file paths consistent in your dialogue boxes with what you've suggested when you've prepared the working environment)
2. Set the project name as Riverine_Channel.
3. Click on the [...] for the working projection and select the _projection.prj file from the Module_Data folder. Note if you open the .prj file in a text editor you will notice that we have provided the projection system WGS 84 / UTM zone 60S
4. We will leave the GIS filetype as ESRI Shapefile.
5. For the Initial GIS files please check mesh_polylines, nodestrings, boundary and materials, then uncheck the remaining GIS filetypes.
6. Leave the filenames and other settings as default.

The dialog should look similar to the figure below Click OK.

River chan projSetup 00.png

When you click OK the GIS Mesher creates a set of folders and files that we will use as a starting point to build the mesh. The folder structure is shown in the figure below.

Trap chan folderstructure 01.png

  • The Riverine_Channel folder is the parent folder we set when creating the new project.
  • The .GISmesher folder stores the project settings for the GIS Mesher GUI.
  • The meshing folder will have the meshing control files and has subfolders for GIS and Tables.
  • The GIS folder has the template GIS files for the boundary, mesh polylines (used to define size information), and nodestrings which will be used in the meshing process.
  • The Tables folder is used for an advanced meshing technique called solution guided meshing which we will not be using.
  • The TUFLOWFV folder and sub-folders contain a TUFLOW FV simulation that can be used as a starting point to build models.

QGIS Workspace

In this tutorial you will create the mesh input files for the GIS Mesher in QGIS. Open a new QGIS project and save the project in your working folder. Select Project > Save As... Riverine_Channel.qgz

Mesh GISM 009.png

Defining The Model Domain

We will now use QGIS to populate the template GIS layers used to build our mesh.

Define The Mesh Boundary

1. To save time, the model boundary has been provided. Navigate to your Module_Data folder and copy all the files that start with boundary_001 as shown below:

Copy Boundary Files.png

2. Paste the files into the directory: working\Riverine_Channel\meshing\GIS and replace the empty boundary_001 template files we generated earlier when we created our project in the GIS Mesher GUI.

3. In QGIS, load the file working\Trap_Channel\meshing\GIS\boundary_001.shp by selecting Layer > Data Source Manager from the menu :

M01 GM 001 Image.png

(MADDY TODO: Update vector pic below to show source vector dataset as mesh_boundary_001.shp)

M02 GM 001.png

An alternative to step 3 above is to simply drag and drop the file working\Trap_Channel\meshing\GIS\boundary_001.shp into QGIS from the Windows File Explorer.

Define The Mesh Size Information

To define mesh size information we are going to use mesh polylines so we can elongate the cells in the direction of flow. Mesh polylines specify sizes as a size parallel to the polyline and a size perpendicular to the polyline. To create the polylines and set the cell sizes for mesh generation:
1. Load the empty template file meshing\GIS\mesh_polylines_001.shp using the same process we loaded in the boundary_001.shp in the previous section.

2. Select the mesh_polylines_001 layer in the layers panel and click the Toggle EditingTut 01 qgis editable 00.png button on the digitizing tab. (MADDY TODO: Need to show people where this button is, maybe a short section after saving the QGIS project where you say these are the key tools we are using today in QGIS may help? )
3. Select the Add a Line Feature Tut 01 digiLine 00.png button on the digitizing toolbar.
4. With Snapping Enabled Tut 01 EnableSnapping 00.png set the Enable Tracing offset to 10m (MADDY TODO: How to enable tracking to 10m?). Now trace the eastern bank of the boundary to generate mesh polylines along the side of the model boundary. (MADDY TODO: Need to show people where this button is, maybe a short section after saving the QGIS project where you say these are the key tools we are using today in QGIS may help? )
Tut 02 trace offset.png.

(MADDY TODO: Show the little offset line thing you showed me)

5. Set the feature attributes as the following: sizePara to 24 (m) and sizePerp to 8 (m). This will make cells 24m in the direction of the polylines and 8m perpendicular.

6. To trace the western bank of the boundary firstly change the Enable Tracing offset to -10m and now trace the west bank of the boundary. (MADDY TODO: -10m wasn't working for me (QGIS being buggy), to get around this I digitised the line in reverse. Can you check this pls)

7. Set the feature attributes as the following: sizePara to 24 (m) and sizePerp to 8 (m). This will make cells 24m in the direction of the polylines and 8m perpendicular.

8. Turn off Enable Tracing on the snapping toolbar.

9. Click the Save Layer Edits button and then Toggle Editing button on the digitizing toolbar.

Your project window should look similar to the below.
Tut 02 mesh polylines.png

Specify The Nodestring Locations

Next we will digitise nodestrings to define our open boundary condition locations. We need a nodestring on the upstream (outflow) and downstream (inflow) boundary of the model domain.
To specify the nodestring locations (QGIS instructions):
1. Add the file Working\Riverine_Channel\meshing\GIS\nodestrings_001.shp to QGIS using the Layer | Add Layer | Vector Layer Command.
2. Select the nodestrings_001 layer in the layers panel and click the Toggle EditingTut 01 qgis editable 00.png button on the digitizing tab.
3. With snapping enabled Tut 01 EnableSnapping 00.png (snapping toolbar), Add a Line Feature Tut 01 digiLine 00.png across the boundary_001.shp at the model inflow (See figure below). Set the ID to 1 and specify T for External which forces the nodestring to follow the mesh boundary.
4. Repeat step 3 at the model outflow (see figure below). Set the ID to 2 and External to T.
5. Click the Save button and then the Toggle Editing button on the digitizing toolbar.

The figure below shows the direction and ID of your newly created nodestrings:

River boundary NS polylines 00.png

Review The Elevation Data

(MADDY TODO: Bring the DEM into QGIS and Review.

Review The Materials Data

(MADDY TODO: copy material files over into gis directory, open up in qgis and review the contents)

Manning Roughness Coefficients are assigned to the mesh based upon a "material" type that is specified for each cell. The materials can be provided using a GIS polygon layer with IDs for each of the materials. A default material (generally the most prevalent) can be assigned in the GIS Mesher Control File to reduce the amount of digitizing required.

To reduce digitizing, the material polygons have been provided. From the Module_Data folder, copy materials_001 with the varied file extensions to Working\Riverine_Channel\meshing\GIS, and replace the existing materials file in GIS folder.

MADDY TODO: Load the materials data into your GIS application and colour by material ID, you should see something similar to the figure below. The Manning n values will be defined when setting up the TUFLOW FV model in Tutorial Module 02 with GIS Mesher.

Tut 02 mat ID .png

Update The Meshing Control File

Prior to building the mesh we need to make two changes to the meshing control file Working\Riverine_Channel\meshing\Riverine_Channel_000.mcf to read in our bathymetry and material information.

Update Elevations

To specify the bathymetry for elevations:
1. Open the file Working\Riverine_Channel\meshing\Riverine_Channel_000.mcf in a text editor (Notepad++ is a free editor that has a lot of useful features).
2. Find the line that has Read Grid Zpts. The line starts with an exclamation mark (!), which comments it out. Remove the exclamation mark and change it to Read Grid Zpts == ..\..\..\Module_Data\rb_dem.tif, as shown in the figure below.
Tut 02 MCF GRID COMMANDS 00.png

Update Materials

Within Riverine_Channel_000.mcf search for the line with the command Set Materials == 1 (MADDY TODO: any TUFLOW Syntax should be coloured and courier new font), and ensure that this is set to 1. This command sets the default material ID.

Tut 02 set mat.png

Build The Mesh

Now we need to build the mesh from the GIS Mesher GUI. To do this:
1. In the Run Mesher tab, verify that the control file is Riverine_Channel_000.mcf.
2. Click Run. The text in the output should provide feedback on the meshing process and after a few seconds include the line GIS Mesher Finished Successfully.
River chan GUISetup 00.png
3. Load the file meshing\output\Riverine_Channel_000_Cells.shp into your GIS Application to verify that the mesh appears correct.

This shapefile provides a representation of the mesh file. This should look something like the figure below if styled similarly based upon Z value and coloured using the Viridis color ramp. You can also symbolize the mesh based upon the MaterialID field to verify that these are set correctly.

Tut 02 cell mesher.png

(MADDY TODO: Can we add some more info here on the check files that come out etc. When we check the mesh are there particular things we want to be checking for?)


The Riverine_Channel_000.2dm file located in .\meshing\output\ is the meshing input file for TUFLOW FV. You can drag and drop the .2dm into your workspace. Congratulations on building your first mesh.

Refining the Mesh

The first mesh you build for a project is rarely your final one. Meshes are refined as model results are reviewed to better capture hydraulic controls, to add refinement as needed, or coarsen the mesh to improve run times. The GIS Mesher offers a wide range of refinement and mesh modification options, allowing you to:

  • Change the size parameters on existing points or polylines.
  • Add additional size points or polylines - This can be useful if you want to refine an area and there is sufficient space for a size transition.
  • Use the Size Multiplier command to scale the sizes for an entire mesh points or mesh polylines layer.
  • Add a Size Multiplier GIS layer to scale the sizes attached to mesh points or mesh polylines.

We will use the Size Multiplier GIS layer to create a mesh with an area of refinement.

To set up the refined mesh, we firstly need to create the Size Multiplier GIS layer. Please follow the below steps:
1. In the GIS Mesher GUI, switch to the Create GIS tab.
2. Choose size_multipliers for the Type.
3. Now set the filename to sm_refinement_001.shp and leave the layername field blank.
4. Click Create file. The file will be created in the Working\tut02\meshing\GIS folder.

Tut 02 create sizemulti shp.png

Now load the created Size Multiplier GIS layer, and if not already loaded add the boundary layer and DEM into QGIS:

  • .\Working\Riverine_Channel\meshing\GIS\sm_refinement_001.shp
  • .\Working\Riverine_Channel\meshing\GIS\boundary_001.shp
  • .\Module_Data\rb_dem.tif

We will now edit sm_refinement_001.shp and set the Size Multiplier values:

1. Select the sm_refinement_001 layer in the layers panel and click the Toggle EditingTut 01 qgis editable 00.pngbutton on the digitizing tab.
2. Create a polygon in approximately the same location shown in the figure below.
3. Set the MultiPri and MultiSec attributes both to 0.5. This will override the mesh sizing in the area to make the cells half as large in the primary (parallel to polyline) and secondary directions (perpendicular to the polylines).
4. Click the Save button and then Toggle Editing button on the digitizing toolbar.

Tut 02 mesh refinement parameters.png


We will now create the refined mesh:
1. Make a copy of the file Riverine_Channel_000.mcf in the Working\Riverine_Channel\meshing folder and name it Riverine_Channel_001.mcf
2. Open the new file Riverine_Channel_001.mcf in your text editor and add the line Read GIS Size Multipliers == GIS\sm_refinement_001.shp on the next line after the command Size Multiplier == 1 as follows:

Size Multiplier Snippet.png


3. In the GIS Mesher, change to the Run Mesher tab and select the file Riverine_Channel_001.mcf and click Run. This will regenerate the mesh with refined area.
You should now have a new mesh file \.meshing\output\Riverine_Channel_001.2dm

Tut 02 runGUI fvc02.png

Discussion:

Open the file meshing\output\Riverine_Channel_001_Cells.shp in QGIS. Can you see where you have refined your mesh? How does your first mesh Riverine_Channel_000.2dm compare to the new mesh Riverine_Channel_001.2dm compare? How does your first mesh Riverine_Channel_000 compare to the new mesh Riverine_Channel_001 compare?

(MADDY TODO: Add some pics of the refined area compared to the original to aid discussion. Also reword the above discussion, it's a bit confusing jumping from 2dm to shape etc. pick one of them.).

Conclusion

(MJS TODO: Conclusions need to be tightened up and linked to other tutorials once closer to publishing). Congratulations on completing meshing a riverine channel using the Rising Water Software GIS Mesher. We've covered a lot in this tutorial, including mesh generation, application of multiple materials, and refining your mesh. To build upon the skills you have gained from this tutorial please find more meshing tutorials here. If you feel ready to complete our modeling tutorials or learn more tips and tricks, please return to the TUFLOW FV Wiki Mainpage.

If you have any queries, feedback or requests for new functionality, please feel free to get in contact with support@tuflow.com.