Convert TUFLOW Model GIS Format

From Tuflow
Revision as of 22:49, 22 September 2022 by Ellis Symons (talk | contribs)
Jump to navigation Jump to search

This tool will convert a TUFLOW model's GIS format (vector and raster layers) into a user specified, TUFLOW Supported, format. It works very similarly to the package model functionality that exists in TUFLOW and will try and package files from all scenarios/events. The difference between the package model functionality and this tool is that this tool will perform additional format conversion steps and update relevant control files to reflect these conversions.

Available since TUFLOW Plugin v3.3

Running the Tool

This tool can be found in the QGIS processing toolbox panel under 'TUFLOW'. To open the Processing Toolbox Panel, navigate to 'View' in the menubar and select Panels >> Processing Toolbox Panel.
Processing toolbox panel toggle.PNG

Convert gis format in panel.PNG

Parameters
TCF
Location of an existing TUFLOW model TCF file. This is the TCF of the model that will be converted.

Output Vector Format
Output vector format of the converted model. Supported formats are GPKG, SHP, MIF.

Output Raster Format
Output raster format of the converted model. Supported formats are GTIFF, GPKG, ASC, FLT.

Output Profile
This parameter is only used for GPKG format outputs. GPKG is a database and can store multiple layers inside one file. This option determines how the output GPKG layers will be grouped into databases.

Options:

  • SEPARATE

This option will write each GPKG layer into its own database. Where the tool encounters commands that have multiple geometry types read in on the same line (using the vertical line delimiter "|"), the layers will be combined into a single database.

  • GROUP BY CONTROL FILE 1

This option will group layers into databases defined by the control file they were specified in. In this option, TRD and TEF files are not considered separate control files.

  • GROUP BY CONTROL FILE 2

Similar to "GROUP BY CONTROL FILE 1" except will treat TRD and TEF as separate control files.

  • ALL IN ONE

Groups all layers together into one database.

Output Folder
Optional parameter specifying the output location of the converted model. By default the output location will a new folder with the same name as the input TCF located in the same folder as the input TCF.

Root Folder
By default the tool will try and find the 'root' folder containing the model files (commonly this folder is named 'TUFLOW'). The tool will try and guess the root folder based on the location of the TCF and the directory structure. If it can't find the root folder, or it picks the wrong folder then this parameter can be used to override this location within the tool.

Scenarios
Available since v3.6
The conversion can be restricted by specifying scenario and event names. Using this option will stop the conversion of layers that are within an 'IF Scenario/IF Event' logic blocks if the scenario name is not provided by the user. This option will also clean the control files and remove unused scenario names. Event names can also be used, however are only applied to logic blocks in the control files and does not filter event sources provided in the TUFLOW Event File (.tef).

To use this option:

  1. Ensure 'Restrict Conversion by Scenario' is checked on
  2. List scenario and event names in the text edit. This should be done in the same manner as TUFLOW batch files e.g. -s <scenario-name> -e <event-name>. The order does not matter and numbering scenarios is not required, although is accepted (e.g. -s1 -s2).

Checking the Output

The first thing to check is the output log that is written in the dialog window. At the bottom, the log should specify whether any errors occured during conversion. If errors did occur, the tool should skip the problematic files/commands and continue with the conversion process. The tool will bail only if a more serious error occurs, for instance the tool was unable to determine the 'root' folder. Or alternatively if an unexpected error occurs then this can also cause the tool to finish early.

If errors did occur, then they should be reported in the log with more context. Users can copy the log (or save it) using the tool icons in the bottom right of the log window. Copying this text into a text editor (e.g. Notepad++) can be useful for searching for the keyword "ERROR" to track down these locations.

Checking the model
The tool will produce a "ready to run" model in TUFLOW most of the time. There may be situations where the user will be required to make small adjustments to the output to get the model to run. If you encounter a situation where this happens, feel free to contact support@tuflow.com and let us know what the issue was.

A known conversion issue could occur if the tool is converting both MIF and SHP files into a single format (e.g. GPKG) as the projection of these files may be interpreted slightly differently by GDAL (even though they are the same). Users may therefore be required to manually update the projection of the affected files, or add the TUFLOW command "GIS Projeciton Check == WARNING" to the TCF. Be careful to ensure they are in fact the same projection before using this command.

Python and the Soure Code

It's possible to run the tool outside of QGIS in Python. The tool uses GDAL to read and write the GIS files and does not rely on any QGIS libraries. The source code and instructions on how to run the tool in Python can be found at the following location on the TUFLOW Community GitLab page.

Errors

Python version error
If you receive a Python version error, this means that you are running a version of Python older than the required version of Python 3.9. To fix this, you will need to update your Python interpreter version. If you are running this tool in QGIS, then you will be required to update your QGIS installation to the latest version, or the latest long term release version.

Other errors
If you receive any other errors, please send through a copy of the output log to support@tuflow.com.



Up
Go-up.png Back to TUFLOW QGIS Plugin Main Page