Difference between revisions of "HEC-RAS to TUFLOW"

From Tuflow
Jump to navigation Jump to search
 
(175 intermediate revisions by 6 users not shown)
Line 1: Line 1:
 
=Introduction=
 
=Introduction=
This page contains a brief introduction to the methods of converting HEC-RAS model inputs into a format which compatible with TUFLOW. If you have any suggestions to be included in these pages, please email <font color="blue"><u>support@tuflow.com</u></font>.<br>
+
This page outlines some utilities that may be used to convert HEC-RAS model files into a format which is compatible with TUFLOW. <br>If you have any suggestions to be included in these pages, please contact <u>[mailto:support@tuflow.com support@tuflow.com]</u>.<br>
  
=Geometric Conversion (SDF_to_GIS.exe)=
+
= Geometry Conversion (sdf_to_gis.exe) =
The SDF_to_GIS.exe utility converts HEC-RAS geometric data data into TUFLOW compatible GIS and csv input format. The utility outputs include:
+
The HECRAS_to_TUFLOW.exe utility is available for download from the TUFLOW <u>[https://www.tuflow.com/downloads/#utilities website]</u>, it
 +
converts HEC-RAS geometric data into a TUFLOW compatible GIS (mif and shp) and csv input format. The utility outputs include:
 
<ol>
 
<ol>
<li> 1D centerline GIS information
+
<li> Centerline location data in GIS format
<li> Cross section GIS locations
+
<li> Cross-section locations in GIS format
 
<li> Cross-section data in csv format
 
<li> Cross-section data in csv format
 
</ol>
 
</ol>
  
The HEC-RAS model inputs need to be in SDF format, and must be geo-referenced using a real world projection. SDF format is an HEC-RAS export format.
+
[[File:HECRAS_SDF_Output_002.JPG|600px]]
  
== Input Processing (HEC-RAS)==
 
  
== Example Utility Syntax ==
+
The steps required to use this utility are:
 +
<ol>
 +
<li> Export the HEC-RAS geometry data into sdf format
 +
<li> Create a GIS projection file for the conversion
 +
<li> Create a batch file to run the utility
 +
<li> Double click the batch file in windows explorer to execute the model conversion
 +
</ol>
 +
 
 +
== Input Data Processing ==
 +
 
 +
The HEC-RAS model inputs need to be in SDF format (HEC-RAS export format), and must be geo-referenced using a real world projection.
 +
 
 +
Export the HEC-RAS sdf file using:  File >> Export GIS Data...
 +
 
 +
[[File:HECRAS_SDF_Export.JPG|600px]]
 +
 
 +
<br>
 +
Select the following items within the GIS Export window:
 +
*River (Stream) Centerlines
 +
*User Defined Cross Sections
 +
*Entire Cross Section
 +
*Reach Lengths
 +
*Bank Stations
 +
*Levees
 +
*Ineffective Areas
 +
*Blocked Obstructions
 +
*Manning's n
 +
 
 +
[[File:HECRAS_SDF_Selection.JPG|600px]]
 +
<br>
 +
 
 +
== Utility Execution ==
 +
The utility requires GIS projection information to correctly translate the spatial dataset from SDF format to *mif or *.shp format. This is done by including either a projection or header file in the same folder directory as the SDF file. The utility will use the projection information from this file for the data conversion.
 +
<ol>
 +
<li> mif format input requirement:  Projection.mif or Header.mif
 +
<li> shp format input requirement:  Projection.prj or Header.prj
 +
</ol>
 +
The following error message will be produced if projection information is not available:
 +
ERROR - A Header.prj or Projection.prj file does not exist in folder
 +
 
 +
The utility is currently limited to being run using a batch file. To create a batch file:
 +
<ol>
 +
<li> Create a new text file in the same location as the sdf file. The name is arbitrary but the file must have the extension ".bat". For example, "run_sdf_to_GIS.bat".
 +
<li> Enter the relevant command syntax to the batch file (refer to the 'Input Flags' table and examples provided below).
 +
<li>Double click the batch file in windows explore to execute the model conversion.<br>
 +
</ol>
 +
 
 +
=== Input Flags ===
 +
A list of the input switches is provided below:
 +
{| align="left" class="wikitable"
 +
! Switch
 +
! width=90% | Description
 +
|-
 +
|"-mif"|| The output format will be the MapInfo Interchange format (.mif/.mid) recognised by most GIS software
 +
|-
 +
|"-shp"|| The output format will be the ArcGIS Shapefile format. This can be opened directly in ArcMap OR QGIS (and most GIS software)
 +
|-
 +
|"-notrim|| This command will prevent the utility from trimming cross-section data at levee markers. This is a non-default option due to most users converting HEC-RAS creek cross-section data into a TUFLOW 1D compatible format, whilst the surrounding floodplain in 2D areas are modeled in 2D (not requiring HEC-RAS inputs)
 +
|}
 +
 
 +
=== Example Syntax ===
 +
<u>Description:</u> Convert HEC-RAS sdf data to mif format, trimming cross-section at levee markers (default trim option):<br>
 +
<li><tt>sdf_to_gis.exe -mif hecras_example.sdf</tt></li>
 +
 
 +
<u>Description:</u> Convert HEC-RAS sdf data to shp format, trimming cross-section at levee markers (default trim option):<br>
 +
<li><tt>sdf_to_gis.exe -shp hecras_example.sdf</tt></li>
 +
 
 +
<u>Description:</u> Convert HEC-RAS sdf data to mif format, not trimming cross-section at levee markers:<br>
 +
<li><tt>sdf_to_gis.exe -mif  -notrim  hecras_example.sdf</tt></li>
 +
 
 +
<u>Description:</u> Convert HEC-RAS sdf data to shp format, not trimming cross-section at levee markers:<br>
 +
<li><tt>sdf_to_gis.exe -shp  -notrim  hecras_example.sdf</tt></li>
 +
 
 +
<u>Note</u>  The above listed syntax assumes that the sdf_to_gis.exe, hecras_example.sdf file and associated batch file are located within the same directory. If not the case, absolute file path referencing will be required. For example:
 +
<li><tt>C:\TUFLOW\Utilities\HECRAS\sdf_to_gis.exe -mif  -notrim  hecras_example.sdf</tt></li>
  
 
== Utility Output ==
 
== Utility Output ==
 +
sdf_to_gis.exe will output five GIS files and a series of csv files, one for each cross-section.
 +
 +
<u>TUFLOW Input</u>
 +
<ol>
 +
<li> ''1d_xs_<sdf_filename>_surf_line'': <br>
 +
This dataset defines the location of the cross-sections. The file uses a format that is compatible with TUFLOW. The field attributes for "Source", "Type" and "Flags" have been pre-filled.
 +
<li> ''Cross-section csv files'':<br> 
 +
This dataset defines the cross-section properties. Across channel distance, channel elevation and manning's roughness have been pre-filled with the csv datasets.
 +
</ol>
 +
 +
<br>
 +
<u>Check Files</u>
 +
<ol>
 +
<li> ''<sdf_filename>_streams'': <br>
 +
This file defines the centerline of the channel. This centerline data can be split using the cross-section data to define the 1D channel (1d_nwk) in a TUFLOW model. The following field attributes should be used if this check file is converted into a TUFLOW input:
 +
<ol>
 +
<li>"Len_or_ANA"= 0 (the length of the line/polyline is used).
 +
<li>"n_or_n_F" = 1 (materials are being defined in the cross-section csv files. n_or_n_F is a multiplication factor of the cross-section manning’s n value).
 +
<li>"US_Invert"= -99999 (the bed of the channel cross-section is used).
 +
<li>"DS_Invert"= -99999 (the bed of the channel cross-section is used).
 +
</ol>
 +
<li> ''<sdf_filename>_cut_line'': <br>
 +
Echo of the cross-section line (non-trimmed).
 +
<li> ''<sdf_filename>_levee_pts'': <br>
 +
Points defining the intersection of the cross-section line with the levee used to trim the cross-section dataset.
 +
<li> ''<sdf_filename>_surf_line'': <br>
 +
Point dataset reporting the location of each elevation values within the csv cross-section dataset.
 +
</ol><br>
 +
 +
= Geometry Conversion (miTools) =
 +
MiTools is a MapInfo add-on that is available for download from the TUFLOW <u>[https://www.tuflow.com/Tuflow%20Utilities.aspx website]</u>.
 +
MiTools can be used to convert HEC-RAS geometry cross-section data into mif/mid spatial and csv tabular format for direct input into TUFLOW.<br><br>
 +
The tool provides various user options, such as:
 +
*Inclusion of manning n within the cross-section csv dataset.
 +
*Various overbank trim options (no trimming, deactivate or trim).
 +
 +
[[File:miTools_HECRAS.JPG|800px]]<br>
 +
 +
Refer to the <u>[[miTools_Tips | miTools Tips and Tricks]]</u> section for more information about miTools.
 +
<br><br>
 +
 +
= Boundary Conditions (HEC-DSS) =
 +
The 2023 TUFLOW Release introduced support for time-series data from HEC-DSS files within a TUFLOW boundary condition database.
 +
 +
HEC-DSS is a database system for time series, curve, gridded data and more, developed by the U.S. Army Corps of Engineers Hydrologic Engineering Center (HEC).  See their website at https://www.hec.usace.army.mil/software/hec-dss/ for more information. The format is used for HEC developed software for data input and output.  Rather than convert HEC-DSS time-series curves for use in TUFLOW, DSS data used by a HEC-RAS model can now also be used directly in TUFLOW.<br>
 +
 +
HEC-DSS files organise data into paths with six parts (Part A – Part F) that resemble how files are organised on disk. The image below shows an example DSS file with a single path, with the curve plotted below.<br>
 +
 +
[[File:HEC_DSSVue.png]]
 +
 +
To use a HEC-DSS time-series curve within a TUFLOW model, save a copy of the HEC-DSS input file to the TUFLOW bc_dbase folder and enter the following information into the TUFLOW boundary condition database:
 +
<ol>
 +
<li> Enter the TUFLOW boundary condition location ID in the "Name" column.
 +
<li> Provide the HEC-DSS filename in the “Source” column.
 +
<li> Leave “Column 1”, which is used for time, blank (DSS files store the time with the curve values).
 +
<li> Identify the pathname in “Column 2”.  Event placeholders such as __event__ can be used as part of the pathname.  Wilcards (*) can be used for parts of the path, however, ensure the wildcards will not select more than one path within the file.
 +
<li> The “Add” and “Mult” columns can be used to offset or scale the time-series values, the same as non-DSS time-series curves.
 +
</ol>
 +
The image below shows how the time-series curve above could be included in a boundary condition database.  A wildcard is used for “Column 2” of the pathname (date range).  Note that the pathname must start with a forward slash (/).
 +
<tt>Name, Source, Column 1, Column 2, Add Col 1, Mult Col 2, Add Col 2, Column 3, Column 4
 +
FC01, EG.dss, , /Example/EG01/FLOW/*/5Minute/BC/, , , , , </tt>
 +
By default, TUFLOW uses the first point in the time-series curve as TUFLOW time-zero.  This can be changed using the TCF command “HEC-DSS Start Date” to identify the date/time that should be used for time-zero.  The date should be in the isodate format: yyyy-mm-dd hh:mm:ss, where the time portions are optional.<br>
 +
:<font color="blue"><tt>HEC-DSS Start Date </tt></font> <font color="red"><tt>== </tt></font> <tt>2022-01-01</tt> <br>
 +
Note: Non-time series data such as gridded data from a HEC-DSS file is not supported at this time.  Contact support@tuflow.com to request other features that would be beneficial to your workflows.
 +
 +
<br>
 +
 +
=Frequently Asked Questions (FAQ)=
 +
==Is there a way to transfer a complete HEC-RAS 2D model directly to TUFLOW?==
 +
For 2D HEC-RAS models, we recommend requesting the raw input datasets used in the HEC-RAS model, if possible, and then reconstructing a TUFLOW model from scratch. We have found that this method is easier and results in higher quality data input for TUFLOW, as opposed to using data that has been downscaled to the HEC-RAS grid resolution. Additionally, HEC-RAS and TUFLOW use different grid mesh formations, which makes a direct automated conversion impractical.
 +
<br>
  
= Boundary Condition Data Conversion (coming soon)=
+
{{Tips Navigation
 +
|uplink=[[Main_Page| Back to Main Page]]
 +
}}

Latest revision as of 09:54, 21 December 2023

Introduction

This page outlines some utilities that may be used to convert HEC-RAS model files into a format which is compatible with TUFLOW.
If you have any suggestions to be included in these pages, please contact support@tuflow.com.

Geometry Conversion (sdf_to_gis.exe)

The HECRAS_to_TUFLOW.exe utility is available for download from the TUFLOW website, it converts HEC-RAS geometric data into a TUFLOW compatible GIS (mif and shp) and csv input format. The utility outputs include:

  1. Centerline location data in GIS format
  2. Cross-section locations in GIS format
  3. Cross-section data in csv format

HECRAS SDF Output 002.JPG


The steps required to use this utility are:

  1. Export the HEC-RAS geometry data into sdf format
  2. Create a GIS projection file for the conversion
  3. Create a batch file to run the utility
  4. Double click the batch file in windows explorer to execute the model conversion

Input Data Processing

The HEC-RAS model inputs need to be in SDF format (HEC-RAS export format), and must be geo-referenced using a real world projection.

Export the HEC-RAS sdf file using: File >> Export GIS Data...

HECRAS SDF Export.JPG


Select the following items within the GIS Export window:

  • River (Stream) Centerlines
  • User Defined Cross Sections
  • Entire Cross Section
  • Reach Lengths
  • Bank Stations
  • Levees
  • Ineffective Areas
  • Blocked Obstructions
  • Manning's n

HECRAS SDF Selection.JPG

Utility Execution

The utility requires GIS projection information to correctly translate the spatial dataset from SDF format to *mif or *.shp format. This is done by including either a projection or header file in the same folder directory as the SDF file. The utility will use the projection information from this file for the data conversion.

  1. mif format input requirement: Projection.mif or Header.mif
  2. shp format input requirement: Projection.prj or Header.prj

The following error message will be produced if projection information is not available:

ERROR - A Header.prj or Projection.prj file does not exist in folder

The utility is currently limited to being run using a batch file. To create a batch file:

  1. Create a new text file in the same location as the sdf file. The name is arbitrary but the file must have the extension ".bat". For example, "run_sdf_to_GIS.bat".
  2. Enter the relevant command syntax to the batch file (refer to the 'Input Flags' table and examples provided below).
  3. Double click the batch file in windows explore to execute the model conversion.

Input Flags

A list of the input switches is provided below:

Switch Description
"-mif" The output format will be the MapInfo Interchange format (.mif/.mid) recognised by most GIS software
"-shp" The output format will be the ArcGIS Shapefile format. This can be opened directly in ArcMap OR QGIS (and most GIS software)
"-notrim This command will prevent the utility from trimming cross-section data at levee markers. This is a non-default option due to most users converting HEC-RAS creek cross-section data into a TUFLOW 1D compatible format, whilst the surrounding floodplain in 2D areas are modeled in 2D (not requiring HEC-RAS inputs)

Example Syntax

Description: Convert HEC-RAS sdf data to mif format, trimming cross-section at levee markers (default trim option):

  • sdf_to_gis.exe -mif hecras_example.sdf
  • Description: Convert HEC-RAS sdf data to shp format, trimming cross-section at levee markers (default trim option):

  • sdf_to_gis.exe -shp hecras_example.sdf
  • Description: Convert HEC-RAS sdf data to mif format, not trimming cross-section at levee markers:

  • sdf_to_gis.exe -mif -notrim hecras_example.sdf
  • Description: Convert HEC-RAS sdf data to shp format, not trimming cross-section at levee markers:

  • sdf_to_gis.exe -shp -notrim hecras_example.sdf
  • Note The above listed syntax assumes that the sdf_to_gis.exe, hecras_example.sdf file and associated batch file are located within the same directory. If not the case, absolute file path referencing will be required. For example:

  • C:\TUFLOW\Utilities\HECRAS\sdf_to_gis.exe -mif -notrim hecras_example.sdf
  • Utility Output

    sdf_to_gis.exe will output five GIS files and a series of csv files, one for each cross-section.

    TUFLOW Input

    1. 1d_xs_<sdf_filename>_surf_line:
      This dataset defines the location of the cross-sections. The file uses a format that is compatible with TUFLOW. The field attributes for "Source", "Type" and "Flags" have been pre-filled.
    2. Cross-section csv files:
      This dataset defines the cross-section properties. Across channel distance, channel elevation and manning's roughness have been pre-filled with the csv datasets.


    Check Files

    1. <sdf_filename>_streams:
      This file defines the centerline of the channel. This centerline data can be split using the cross-section data to define the 1D channel (1d_nwk) in a TUFLOW model. The following field attributes should be used if this check file is converted into a TUFLOW input:
      1. "Len_or_ANA"= 0 (the length of the line/polyline is used).
      2. "n_or_n_F" = 1 (materials are being defined in the cross-section csv files. n_or_n_F is a multiplication factor of the cross-section manning’s n value).
      3. "US_Invert"= -99999 (the bed of the channel cross-section is used).
      4. "DS_Invert"= -99999 (the bed of the channel cross-section is used).
    2. <sdf_filename>_cut_line:
      Echo of the cross-section line (non-trimmed).
    3. <sdf_filename>_levee_pts:
      Points defining the intersection of the cross-section line with the levee used to trim the cross-section dataset.
    4. <sdf_filename>_surf_line:
      Point dataset reporting the location of each elevation values within the csv cross-section dataset.


    Geometry Conversion (miTools)

    MiTools is a MapInfo add-on that is available for download from the TUFLOW website. MiTools can be used to convert HEC-RAS geometry cross-section data into mif/mid spatial and csv tabular format for direct input into TUFLOW.

    The tool provides various user options, such as:

    • Inclusion of manning n within the cross-section csv dataset.
    • Various overbank trim options (no trimming, deactivate or trim).

    MiTools HECRAS.JPG

    Refer to the miTools Tips and Tricks section for more information about miTools.

    Boundary Conditions (HEC-DSS)

    The 2023 TUFLOW Release introduced support for time-series data from HEC-DSS files within a TUFLOW boundary condition database.

    HEC-DSS is a database system for time series, curve, gridded data and more, developed by the U.S. Army Corps of Engineers Hydrologic Engineering Center (HEC). See their website at https://www.hec.usace.army.mil/software/hec-dss/ for more information. The format is used for HEC developed software for data input and output. Rather than convert HEC-DSS time-series curves for use in TUFLOW, DSS data used by a HEC-RAS model can now also be used directly in TUFLOW.

    HEC-DSS files organise data into paths with six parts (Part A – Part F) that resemble how files are organised on disk. The image below shows an example DSS file with a single path, with the curve plotted below.

    HEC DSSVue.png

    To use a HEC-DSS time-series curve within a TUFLOW model, save a copy of the HEC-DSS input file to the TUFLOW bc_dbase folder and enter the following information into the TUFLOW boundary condition database:

    1. Enter the TUFLOW boundary condition location ID in the "Name" column.
    2. Provide the HEC-DSS filename in the “Source” column.
    3. Leave “Column 1”, which is used for time, blank (DSS files store the time with the curve values).
    4. Identify the pathname in “Column 2”. Event placeholders such as __event__ can be used as part of the pathname. Wilcards (*) can be used for parts of the path, however, ensure the wildcards will not select more than one path within the file.
    5. The “Add” and “Mult” columns can be used to offset or scale the time-series values, the same as non-DSS time-series curves.

    The image below shows how the time-series curve above could be included in a boundary condition database. A wildcard is used for “Column 2” of the pathname (date range). Note that the pathname must start with a forward slash (/).

    Name, Source, Column 1, Column 2, Add Col 1, Mult Col 2, Add Col 2, Column 3, Column 4
    FC01, EG.dss, , /Example/EG01/FLOW/*/5Minute/BC/, , , , , 
    

    By default, TUFLOW uses the first point in the time-series curve as TUFLOW time-zero. This can be changed using the TCF command “HEC-DSS Start Date” to identify the date/time that should be used for time-zero. The date should be in the isodate format: yyyy-mm-dd hh:mm:ss, where the time portions are optional.

    HEC-DSS Start Date == 2022-01-01

    Note: Non-time series data such as gridded data from a HEC-DSS file is not supported at this time. Contact support@tuflow.com to request other features that would be beneficial to your workflows.


    Frequently Asked Questions (FAQ)

    Is there a way to transfer a complete HEC-RAS 2D model directly to TUFLOW?

    For 2D HEC-RAS models, we recommend requesting the raw input datasets used in the HEC-RAS model, if possible, and then reconstructing a TUFLOW model from scratch. We have found that this method is easier and results in higher quality data input for TUFLOW, as opposed to using data that has been downscaled to the HEC-RAS grid resolution. Additionally, HEC-RAS and TUFLOW use different grid mesh formations, which makes a direct automated conversion impractical.

    Up
    Go-up.png Back to Main Page