TUFLOW Viewer

TUFLOW Viewer replaces Crayfish and TUPLOT as the TUFLOW result viewer for QGIS for version 3.6 onwards. It uses the Mesh Data Abstraction Library (MDAL) available in QGIS to display and interact with TUFLOW map output results, and the TUFLOW results python library (the same library used by TUPLOT in earlier versions of QGIS) for viewing TUFLOW time series results.

Getting Started

Installation

TUFLOW Viewer is a free tool that comes as part of the TUFLOW plugin in QGIS. For instructions on how to install the plugin, read the following wiki page:

How to install the TUFLOW plugin

There are also instructions on installing plugins in the QGIS documentation - if you choose to follow the QGIS documentation, the plugin is called "TUFLOW" in the repository:

Link to QGIS Documentation - Installing and Managing Plugins

Opening TUFLOW Viewer

Once the TUFLOW plugin is installed, the TUFLOW Viewer tool can be opened by clicking the following icon in the plugin toolbar:

Upgrading The Plugin

It's recommended to upgrade the plugin whenever a new version is released. The upgrade process is typically done via the Plugin Manager.

Error While Upgrading the Plugin

Error_While_Upgrading_Plugin

Getting a Python Error

Occasionally the TUFLOW plugin will throw an exception and this will produce a Python Error which is displayed either as a yellow banner at the top of the map window or a window may appear stating than an 'Error has occurred while executing Python code'.

What Does This Mean?

This means that the TUFLOW plugin has encountered something unusual or a situation that it does not know how to handle i.e. it has reached a line in the code that has failed to execute and as a consequence Python has bailed out. This means that all the code below this point that was meant to be executed has not. This can have knock on consequences as variables may not exist or be set to incorrect values and signal handling (e.g. what happens when a menu item is clicked) may be broken. So a python error can lead to further python errors that would normally not have occurred, so the first python error is usually the most important.

What To Do

1. Email the Stack Trace to support@tuflow.com with a description of the steps that produced the python error (as best you can describe it). This is to help us identify bugs and fix the plugin so that it catches this exception in the future.
2. If you find that you are now experiencing further python errors (probably caused by the initial error) you can try the following in order of severity:
   1. On the TUFLOW Viewer menu bar File >> Reload TUFLOW Viewer - this will reload TUFLOW Viewer, resetting all variables and signals. You will be required to load in any time series results again and other settings may also be reset. Map output results will remain in the workspace and be reloaded into TUFLOW Viewer.
   2. Save the workspace (.qgz) and restart QGIS
   3. Restart QGIS - you can save the workspace (.qgz), however you should first select on the TUFLOW Viewer menu bar File >> Close TUFLOW Viewer Completely - this will close the viewer and also remove all settings associated with it from the workspace so that the problematic variable is not accidentally reloaded with the workspace
   4. The nuclear option - Restart QGIS and load a new workspace from scratch (do not load a saved workspace)

Loading Results

Results can be loaded several ways:

Option 1

File >> Load Results

Option 2

Right Click in Open Results >> Load Results

The following options are available for loading into TUFLOW Viewer:

1. Load Results --> This is done via a TCF, TLF, or FVC (TUFLOW FV) file and will load in all results (Map Outputs and ESTRY Time Series)
2. Load Results - Map Outputs --> Select map output mesh results file (*.xmdf, *.dat, *.2dm, *.xmdf.sup, *.dat.sup, *.nc (supports netCDF format from TUFLOW FV output only))
3. Load Results - Time Series --> Select ESTRY time series output results (*.tpc)
4. Load Results - Time Series FM --> Load Flood Modeller results. This requires a .gxy and result .csv file to be exported from Flood Modeller.
5. Load Results - Particles --> Select output from particle module (*.nc) which will typically be suffixed with _ptm
6. Import 1D Hydraulic Tables --> Select a _1d_ta_tables_check.csv check file
7. Import 1D ESTRY Cross-Sections --> This will automatically happen if an appropriate TUFLOW input is opened in QGIS while TUFLOW Viewer is open (e.g. 1d_xs)

File:LoadResults Eg img.PNG

If I Receive an Error?
If you receive an error similar to that below when trying to load results from a TCF:

UnicodeDecodeError: 'utf-8' codec can't decode byte 0x92 in position 626: invalid start byte

This usually results from inconsistent encoding of the TUFLOW control files. You can fix this by changing the encoding of all your control files to a single type - typically UTF-8. You can do this using Notepad++, please see below link for how to do this (refer last image).
TUFLOW_Message_0060

Map Outputs

Map outputs are the 2D result outputs from TUFLOW (or 3D outputs from TUFLOW FV). Basic interaction with the map output results in TUFLOW Viewer are described below:

1. Change Results --> changing between different simulation results is done by selecting the result name(s) in the 'Open Results' widget
2. Change Result Type --> changing between different result types is done using the 'Result Type' widget
3. Display Maximum --> if available, maximums can be toggled on/off for the different result types
4. Display Vectors --> vector results can be displayed in combination with any of the scalar result types e.g. velocity vectors can be displayed with depth
5. Style Scalar Map Outputs --> styling scalar map output results is similar to styling raster layers in QGIS and can be done via QGIS properties (right click >> properties) or pressing F7 to open the properties docking window.
6. Style Vector Map Outputs --> similar to the styling the scalar map outputs, there are a range of options for styling the vector layers.
7. Save Default Styles --> users can save default styles for result types so that they are automatically applied each time results are imported using TUFLOW Viewer.
8. Display The Mesh --> the quickest way to toggle the mesh is to click the grid box in TUFLOW Viewer.
9. 3D to 2D Depth Averaging --> For 3D map output results, the 3D to 2D depth averaging method can be changed in the propertes.

Time Series Outputs

Time series outputs are typically 1D result outputs from TUFLOW but can also include 2D time series results (plot outputs or reporting locations) if any exist. Time series results consist of a GIS layer that the user can interact with to plot the results in TUFLOW Viewer, and of course the results themselves.

1. ESTRY Time Series Results
2. ESTRY Time Series Results - 2013 TUFLOW Release
3. Flood Modeller Time Series Results And Cross-Sections

Particle Outputs

Outputs from the particles module can be loaded into TUFLOW Viewer and viewed along side hydrodynamic the results. The below lists the basic interaction with particle outputs:

1. Particle Outputs

Plotting Results

TUFLOW Viewer supports numerous plotting options (listed below) to help users interrogate results.

1. Map Output - Plotting Time Series
2. Map Output - Plotting Cross-Sections and Longitudinal Profiles
3. Map Output - Plotting Flow
4. Map Output - Curtain Plot
5. Map Output - Vertical Profile
6. Map Output - Plotting 3D to 2D Depth Averaged Time Series
7. Map Output - Plotting Multiple Locations
8. Map Output - Plotting From Vector Layer (e.g. shp file)
9. Time Series Ouput - Plotting Time Series
10. Time Series Ouput - Plotting Longitundinal Profiles
11. Plotting 1D Cross-Secion Inputs (with / without results)
12. Plotting 1D Hydraulic Table Check Files
13. Importing a User Defined Time Series To Display On The Plot
14. Using a Secondary Axis
15. Plotting 1D Flow Regime
16. Exporting and Copying The Plot
17. Exporting The Drawn GIS Plot Points / Lines
18. Changing The Legend Location
19. Customising The Plotting Styles
20. Customising The Plot Axes
21. Toggling Plot Grid Lines
22. Importing a Custom Colour Ramp For The Curtain Plot
23. Navigating And Querying The Plot Window
24. Batch Exporting Plots
25. Extracting Median and Mean Time Series - Australian Rainfall and Runoff

Plotting From Map Outputs

Time Series

You can plot one or multiple temporal map output results as a time series.

1. Choose which map outputs to plot --> click on the time series graph down arrow under Map Output Plotting >> Check on desired result types
2. Click off the menu
3. Click the time series graph again (not the down arrow)
4. Click somewhere on your results

File:MapOutputPlotting TS.gif

2D Cross Sections and Long Sections

You can plot one or multiple map output results as a cross section for the current time step.

1. Choose which map outputs to plot --> click on the cross-section graph down arrow under Map Output Plotting >> Check on desired result types
2. Click off the menu
3. Click the cross-section graph again (not the down arrow)
4. Left click somewhere on your results to start the cross-section
5. Left click to add vertices to your cross-section polyline
6. Right click to finish

File:MapOutputPlotting CS.gif

Follow the steps above in the direction of flow to plot long sections.

Plotting Flow

You can post calculate flow from the map output results. Note that this approach should be used for approximation only. The preferred method is to use a PO line in TUFLOW.

1. Click on the Plot Flux button down arrow under Map Output Plotting
2. Left click somewhere on your results to start the flux line
3. Left click to add vertices to your flux line
4. Right click to finish

The direction convention is the same as PO lines in TUFLOW - the positive direction of flow is from left bank to right bank looking downstream
File:MapOutputPlotting Q.gif

Plotting Long Section From Shape File

It's possible to plot time series, flow, cross sections, and long plots using an existing shape file (or other vector formats supported by QGIS). Example below using a shape file to plot a long section:

1. Select polyline used for plotting (time series will use point object)
2. Choose Layer Selection under Map Output Plotting
3. Choose which map outputs to plot --> click on the cross-section graph down arrow under Map Output Plotting >> Check on desired result types
4. Click the cross-section graph again (not the down arrow)

File:2D long plot from selection.gif

Plotting From Time Series Outputs

If time series results are loaded in (e.g. 1D results) you can plot from the outputted types.

1. Select result type e.g Flow under the Time Series section in the Result Types
2. Use QGIS Select Tool and select one of the PLOT GIS features

File:TimeSeriesPlotting Q.gif

Plotting 1D Long Sections

If time series results are loaded in (e.g. 1D results) you can plot long sections from the results. Example below plotting a long section from stormwater pipes:

1. Select single channel (pipe) from the PLOT_L GIS layer
2. Select a long section result type e.g Water Level and/or Culverts and Pipes (Long section result types have the icon with a light blue line)
3. Selecting a second channel downstream of the first will plot the long section between the selected channels (if no second channel is selected, the long section will plot until the outlet)

File:1D long plot from selection.gif

Using a Secondary Axis

If you are plotting multiple result types at once, you may want to plot one or more of the lines on a secondary axis. This can be done 2 ways:
Option 1

Click the Secondary Axis icon on the appropriate result type in the Result Types Panel

Option 2

Right Click on the appropriate result type in the Result Types Panel and check on Secondary Axis

File:ToggleSecondaryAxis.gif

Changing Plot Properties

Plot properties can be changed via
Option 1

TUFLOW Viewer Settings >> Customise

Option 2

Customise tool icon in the plot toolbar

Using this, properties such as the plot axis, item name in legend, and line / point styling can be modified. The styling is saved in the session and will be used the next time the same plot type (e.g. depth time series) is plotted.

Changing the default colours

The default colours are randomly generated when TUFLOW Viewer is opened and can be re-generated by selecting Settings >> Reset Plotting Colours. This will also reset any custom line properties the user may have set.

Changing the axis limits and names

The same process can be used to set the axis limits and axis names. The axis names will be saved in the session and can be reset to default by selecting Settings >> Reset Plot Axis Names. Changing the axis limits will cause the plot axis to become frozen (depending on which axis limits was changed). The axis limits can be unfrozen by unchecking the relevant axis icon in the plot toolbar.
File:Axis limits frozen.png

File:PlotProperties 1.gif

File:PlotProperties 2.gif

File:PlotProperties 3.gif

File:PlotProperties 4.gif