4.3 Input Layers
4.3.1 Input Formats
The main types of GIS Inputs are vectors, rasters and TINs. The following formats are supported as inputs in TUFLOW:
- GIS vector data layers: GeoPackage (.gpkg) (recommended), Shapefile (.shp) and MapInfo (.mif) (default) formats.
- GIS raster data layers: GeoTIFF (.tif) (recommended & default), GeoPackage (.gpkg), Float (.flt) and ASCII (.asc) formats. NetCDF formats are supported for some inputs such as time-varying rainfall grids.
- GIS TIN data layers: Land XML (.xml), 12d tin (.12da) formats (including super TINs) and SMS (.tin).
Most mainstream CAD/GIS platforms recognise these formats.
The format of input layers is solely controlled by the file extension. For example, for the vector formats, “.gpkg” for the GPKG format database (noting that no extension is used for a layer within a database), “.shp” for the SHP format and “.mif” for the MIF format. Prior to the 2023-03 release, if no file extension was specified TUFLOW assumed the input layer was in .mif format. To support the new GeoPackage format (the recommended vector format), TUFLOW will produce ERROR 0631 for inputs with no extension.
TUFLOW requires that all GIS layers imported or exported by TUFLOW must be in the same geographic projection. The model projection is initialised using the GPKG Projection, SHP Projection and MI Projection commands. Multiple input formats can be used (e.g. a mix of all format types within one model is allowed). If a model uses a mixture of format types as inputs, a projection command should be specified for each format.
The default output format for GIS check layers and GIS outputs depends on the Projection setting as mentioned above. If more than one Projection setting is specified, or to force the GIS output format, use the GIS Format command. The GeoPackage format is that recommended due to superior file/data management storage, data compression, and far greater viewing and querying speeds.
The default raster format is the GeoTIFF (.tif) format. Although a check is not done on the projection of .tif inputs, a projection can be assigned to .tif output rasters using the TIF Projection command.
4.3.2 GIS Commands
Commands containing “GIS” read and/or write a GIS vector layer. GIS commands read the geometry, attribute data, and projection data of the input layer. The available formats of input vector and raster layers are listed in Section 4.3.1. The geographic location of objects for GIS commands is important as the geographic position of the object controls the part of the TUFLOW model they affect.
When digitising objects, it is preferable that they do not snap to the 2D cell sides or corners as this may produce indeterminate effects.
4.3.2.1 GIS Attribute Interpretation
TUFLOW expects certain attributes, in a specific order for input layers. For example an initial water level layer (2d_iwl) layer only requires a single attribute (which is the initial water level value), whilst a 1d channel layer (1d_nwk) has a number of attributes including channel type, channel roughness, upstream and downstream elevation. The attributes required for each input layer are detailed in their respective sections throughout this manual. Any additional attributes appended to the layer will be ignored by TUFLOW (with the exception of the 1d_nwk layer as TUFLOW will treat it as a 1d_nwke layer).
The .tcf command Write Empty GIS Files can be used to automate the creation of template files with attribute structures that TUFLOW expects and with the recommended GIS data naming convention. They also can be automatically created using the TUFLOW Plugin Import Empty Tool.
A list of the TUFLOW template files is available on the TUFLOW Wiki TUFLOW Empty Files.
The names of GIS attributes as documented or produced by Write Empty GIS Files may change from previous TUFLOW releases to reflect new features and changes. The name of the attribute is irrelevant as far as TUFLOW is concerned as TUFLOW only requires that attributes are in the correct order and of the correct type (i.e. Character, Float, Integer, etc.). In all TUFLOW layers, the attributes can be named as the modeller wishes, so older layers that do not have the same attribute names as documented in this manual will still work correctly.
4.3.2.2 GIS Object Interpretation
Table 4.6 and Table 4.7 outline the compatible GIS objects and how they are interpreted by TUFLOW.
Object snapping is often used to relate point data with line and region data, for example with the Read GIS Z Shape or Read GIS BC command. TUFLOW supports point, end and vertex snapping. It does not support edge snapping. Objects that are linked (for example a 2d_bc “SX” type region and 2d_bc “CN” type line layer), must be snapped and also read in to TUFLOW on the same command line separated by a vertical bar “|”. For example:
| Object Type | TUFLOW Interpretation |
|---|---|
| Point | Refers to the 2D cell that the point falls within or a 1D object such as a node or boundary location. Points snapped to the sides or corners of a 2D cell may give uncertain outcomes as to which cell the point refers to. |
| Line (straight line) | Variety of uses including defining a continuous line of 2D cells, 1D channels, to connect objects, alignment of a 3D breakline, linking 1D and 2D elements. |
|
Pline (line with one or more segments) |
As for Line above. |
| Region (polygon) |
For 2D cells either:
1D nodes within the region are selected. If the 1D node falls exactly on the region perimeter uncertain outcomes may occur. |
| Multiple (Combined) Objects | In later versions of TUFLOW, multiple point, line and region objects are generally accepted (ERROR or WARNING messages are given if not the case). |
| Object Type | TUFLOW Interpretation |
|---|---|
| Arc | Ignored (do not use). |
| Collections | Not supported. Collections are groups of objects of differing type. |
| Ellipse | Ignored (do not use). |
| none | These objects are ignored and most commonly occur when a line of attribute data is added that is not associated with an object. In MapInfo, this occurs when a line of data is added directly to a Browser Window (i.e. no object was digitised). |
| Roundrect (Rounded Rectangle) | Ignored (do not use). |
| Rect (Rectangle) | Ignored (do not use). |
| Text | Ignored. |
4.3.3 GeoPackage Commands
GeoPackage is a widely supported, open format, built upon an SQLite database (this is stored as a single file with the extension .gpkg). The benefits of GeoPackage compared to the MapInfo (MIF/MID) and ESRI/QGIS Shapefile formats include:
- More than one layer can be stored in a single file. For example, all model inputs can be stored in a single GeoPackage database.
- It supports spatial indexing, making it much faster to work with in GIS packages.
- Significantly faster write speed from TUFLOW compared to the Shapefile format.
For tips on using GeoPackages, see the TUFLOW Wiki GeoPackage Tips page. Additionally, the TUFLOW Tutorial Modules are set up using the GeoPackage format and can be used as an introduction to using GeoPackages.
4.3.3.1 GPKG Input Commands
Since a GeoPackage database can have more than one layer, when reading data into TUFLOW, a GeoPackage file and table may both need to be specified. There are a variety of different options available. The following are possible:
To specify a table in a .gpkg directly use “>>”:
Read GIS Z Shape == gis\2d_zsh.gpkg >> 2d_zsh_L If a .gpkg file path is only specified, with no table reference, it will be assumed that the table name is the same as the .gpkg database name. For example, the following two commands are equivalent to one another:
Read GIS Z Shape == gis\2d_zsh_L.gpkg
Read GIS Z Shape == gis\2d_zsh_L.gpkg >> 2d_zsh_L To specify more than one table in a database in the same command line use “&&”. This is similar to “|” however there is no need to reference the database multiple times:
Read GIS Z Shape == gis\2d_zsh.gpkg >> 2d_zsh_L && 2d_zsh_P
“&&” can be used in conjunction with “|”:
Read GIS Z Shape == gis\2d_zsh_R.gpkg | gis\2d_zsh.gpkg >> 2d_zsh_L && 2d_zsh_P Use the command “USE ALL” with “>>” to tell TUFLOW to use all tables in the database:
Read GIS Z Shape == gis\2d_zsh.gpkg >> USE ALL Use the Spatial Database command to specify a database to use for subsequent table inputs. This command can be used multiple times in a control file to change the target .gpkg file. For example:
Spatial Database == gis\2d_EXG.gpkg
Read GIS Z Shape == 2d_zsh_R | 2d_zsh_L | 2d_zsh_P
Read GIS Mat == 2d_mat_R
Spatial Database == gis\2d_DEV.gpkg
Read GIS Mat == 2d_mat_R Spatial Database can be used in the .tcf, .ecf, .tbc, .tgc, .qcf, .tef. Commands are localised to their relevant control file with the exception of the .tcf which acts as a global command. If local spatial database are specified, they will take precedence over the global .tcf spatial database. The spatial database can be turned off or reverted to the .tcf database with the same command. Turning the spatial database off is a global command even when used in a control file other than the .tcf.
Spatial Database == OFF | TCF Prior to TUFLOW’s implementation of GeoPackage, if a file reference did not have an extension listed in the TUFLOW command syntax it was assumed the file was a MapInfo “mif” format. That rule no longer applies. If there is an open spatial database TUFLOW will not append “.mif” to the end of the table name.
4.3.3.2 GPKG Output Commands
The GIS outputs from TUFLOW can be set to GPKG by using the following command:
Outputs can be written into separate databases or grouped:
Grouped databases will group by output folder location. Separate databases will still group geometries together e.g., PLOT_P, PLOT_L, PLOT_R will be written to one database.
4.3.4 Grid Commands
Commands containing “Grid” read and/or write a GIS raster layer. The format is controlled by the file extension (e.g. .tif, .gpkg, .flt or .asc). The available formats of input raster layers are listed in Section 4.3.1.
For real (float) inputs the value is interpolated from the grid. For integer inputs (such as Code), the value applied is the integer value of the grid cell that the TUFLOW point falls within.
The Read Grid Zpts command permits a second argument to specify a GIS layer containing one or more polygons to clip the area of Zpts to be inspected. Elevations will only be assigned to Zpts lying inside polygons within the GIS layer. See Section 7.2.5.1 for more details.
4.3.5 TIN Commands
Commands containing “TIN” (triangulation file) read and/or write a TIN file. The format is controlled by the file extension (e.g. .tin, .xml or .12da). From the 2020-10-AB release, TUFLOW also supports super TINs in the .12da format. The same syntax is used for “TIN” layers as “GRID”.
TUFLOW can also be used to create a TIN (see Create TIN Zpts).
The Read TIN Zpts command permits a second argument, specifying a GIS layer containing one or more polygons to clip the area of Zpts to be inspected. Elevations will only be assigned to Zpts lying inside polygons within the GIS layer. See Section 7.2.5.1 for more details.
4.3.6 RowCol Commands (Legacy)
Commands containing “RowCol” or “MID” (e.g. Read RowCol Zpts) only read the attribute data file (i.e. .mid or .dbf file). This is a legacy feature and is not recommended for use. The row and column numbering in the TUFLOW model will change if the model cell size, orientation or origin change, this feature is not supported when using quadtree grids or the GeoPackage format.
For details on this legacy feature see Section 4.9.2 of the 2018 TUFLOW Manual.