TUFLOW Viewer

TUFLOW Viewer replaces Crayfish and TUPLOT as the TUFLOW result viewer for QGIS (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

QGIS Version

A few notes on the recommended QGIS version:

It is recommended to use the latest version of QGIS. The reasons for this are:

• TUFLOW Viewer is developed using the latest version, and although backwards compatibility is maintained as best as possible, TUFLOW Viewer is tested more frequently on the latest QGIS version.
• The mesh data provider (MDAL) and the temporal controller (which now underpins the mesh datasets in QGIS) are both relatively new in comparison to other libraries (e.g. GDAL) and are therefore more regularly updated with new features, enhancements, and bug fixes by the QGIS developers. TUFLOW Viewer takes advantage of these updates.
  

Although TUFLOW Viewer has been developed to be consistent across QGIS versions, it is not always possible. Some QGIS developments and behaviour changes have led to TUFLOW Viewer behaviour also changing either through necessity or to keep in-line with the QGIS development direction. The below is a current list of known behaviour changes due to QGIS version:

1. Date-time format within TUFLOW Viewer - QGIS 3.14 introduced the temporal controller
   
   • Prior to QGIS 3.14, TUFLOW Viewer stored all results internally as relative time. The user could display as date-time and the reference time by changing Zero Date in Settings >> Options.
   • QGIS 3.14, TUFLOW Viewer tried to mimic the behaviour of previous versions but the reference time could also be altered natively in the mesh layer Properties. Note on this version, this is the first QGIS release with the temporal controller and as a consequence some of the functionality matured and changed in subsequent versions. Users may experience strange behaviour when using TUFLOW Viewer with the QGIS 3.14 if using date-time format. It is recommended to upgrade to later versions of QGIS if date-time format is required.
   • Post QGIS 3.14 TUFLOW Viewer stores all results internally as absolute time and the user must change the reference time in the native properties of the mesh layer to alter the dates being displayed. Zero Date now only changes how the relative time is displayed in TUFLOW Viewer and doesn't change the mesh layer reference time.
   • Please follow the link below on how to use isodate (date-time) format in TUFLOW Viewer in QGIS 3.16+ (recommended minimum version if using date-time format): Working With Isodate (Date-Time) format.

Installation or Version Upgrade

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, please follow these steps: Installation of 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

Plugin Upgrades

It's recommended to upgrade the plugin whenever a new version is released. The upgrade process is typically done via the Plugin Manager (QGIS Drop Menu: Plugins >> Manage and Install Plugins...)


If you encounter an error while upgrading the plugin please follow these steps: Error_While_Upgrading_Plugin

Using TUFLOW Viewer

Opening the TUFLOW Viewer

After installing the QGIS TUFLOW plugin the TUFLOW Viewer tool can be opened by clicking the following icon in the plugin toolbar:

Loading Results

TUFLOW simulation results can be loaded several ways:

1. Select File >> Load Results from the TUFLOW Viewer drop menu.
2. Right Click in the Open Results panel and select Load Results.
   File:LoadResults Eg img.PNG
   

Using either of the above methods, the following result load options are available:

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 - Particle Tracking Module --> 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).

Troubleshooting
If you receive an error similar to below when attempting to load results from a TCF you will need to fix the encoding of your TUFLOW control files:

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

This error is caused by incompatible encoding of the TUFLOW control files. You resolve this issue by changing the encoding of all your TUFLOW control files to a single type (typically UTF-8). You can do this using Notepad++. Please see the following link for instructions how to do this (refer last image): TUFLOW_Message_0060.

Map Output Display and Styling

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 Result Selection --> 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 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 layer propertes.
10. Locking Plot Output Timesteps to the Map Output Interval

Time Series Output Display and Styling

Time series outputs are typically 1D result outputs or 2D time series results (plot outputs or reporting locations). Time series results consist of two elements, the result datasets and GIS layers that the user can interact with to customise the plot selection in TUFLOW Viewer.

1. ESTRY Time Series Results
2. ESTRY Time Series Results - 2013 TUFLOW Release
3. Flood Modeller Time Series Results And Cross-Sections
4. Viewing All Available Output Timesteps

Particle Tracking Output Display and Styling

Outputs from the Particle Tracking (PT) Module can be loaded into TUFLOW Viewer and viewed alongside the hydrodynamic results. The below links list the basic particle tracking view options:

1. Particle Tracking Outputs
2. Viewing All Available Output Timesteps

Plotting Results

TUFLOW Viewer supports numerous plotting options to help users display and interrogate results.

1. Summary of Plotting Toolbar Options
   

Map Outputs

1. Map Output - Plotting Time Series
2. Map Output - Plotting Time Series for Multiple Locations
3. Map Output - Plotting Cross-Sections and Longitudinal Profiles
4. Map Output - Plotting Flow
5. Map Output - 3D Curtain Plot
6. Map Output - 3D Vertical Profile
7. Map Output - Plotting 3D to 2D Depth Averaged Time Series
8. Map Output - Plotting 3D to 2D Depth Averaged Cross-Sections
9. Map Output - Plotting From Vector a Layer (e.g. shp file)

Time Series Outputs

1. Time Series Output - Plotting Time Series
2. Time Series Output - Plotting Longitudinal Profiles
3. Showing Selected Elements and Selecting Sub-Sets
4. Plotting 1D Cross-Section Inputs (with / without results)
5. Plotting 1D Hydraulic Table Check Files
6. Extracting Median and Mean Time Series - Australian Rainfall and Runoff

Plot Display Outputs

1. Using a Secondary Axis
2. Using a Date Axis
3. Displaying the Current Time
4. Plotting 1D Flow Regime
5. Exporting and Copying A Plot
6. Exporting The Drawn GIS Plot Points / Lines
7. Customising The Legend
8. Customising The Plotting Styles
9. Customising The Plot Axes
10. Plot Grid Line Display
11. Importing a Custom Colour Ramp For The Curtain Plot
12. Navigating And Querying The Plot
13. Auto Update Plot From Cursor Location
14. 3D Mesh Vertical Layer Display

Other

1. Importing a User Defined Time Series Dataset To Display On The Plot
2. Batch Exporting Plots

Working With Isodate (Date-Time) format

1. Working With Date-Time - Map Outputs
2. Working With Date-Time - Time Series Outputs
3. Working With Date-Time - Particle Outputs
4. Working With Date-Time - User Defined Time Series

300px

Customising the TUFLOW Viewer Dock Appearance

1. Hiding the Plot Window
2. Customising the Plot Background Colour
3. Setting the Default Font Size For the Plot
4. Toggling Output Timesteps

650px

Summary of TUFLOW Viewer Setting Options

Use the link below to see a list and description of the available settings in the Settings >> Options TUFLOW Viewer drop menu. Older versions of the plugin may look slightly different, however most options will still be available.

1. Summary of Options

350px

Creating an Animation

Animations can be exported from TUFLOW Viewer for all accepted result types (map outputs, time series, long sections etc). The process for animation creation is the same regardless of the result type. The tool will export an image for each output timestep in a given range and then use ffmpeg to convert the images into a video. TUFLOW Viewer offers the additional functionality of adding dynamic plots and dynamic time text. It also offers convenience functionality for adding items such as a legend and images (such as a company logo).

1. Exporting An Animation

Batch Exporting Maps

TUFLOW Viewer offers the ability to batch export maps using mesh layers. This tool does not seek to replace other similar tools that may be inherently built in to QGIS, however does offer the ability to:

• Automatically add plots from the mesh layer to the maps.
• Automatically load mesh results, plot, and export maps.

It also offers convenience functionality for adding map items (such as a legend, images and scales), however these can also be added manually in the print layout.

1. Batch Exporting Maps

Python Error Troubleshooting

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

When this occurs it 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 all the code below this point that was meant to execute 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. As such, a python error can lead to further python errors that would normally not have occurred. Because of this flow-on effect the first python error is usually the most important.

If you encounter a python error please:

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 alternative in order of severity (least to worst):
   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 QGIS 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 last resort option is to restart QGIS and load and create a new workspace from scratch (do not load a saved workspace).