User:Jcreer/Toolbox Unstructured Grids Tools

This article describes tools from the SMS toolbox that are used to edit, create, and otherwise modify Ugrids.

UGrids Tools

Export Curvilinear Grid

The Export Curvilinear Grid tool is used to create a curvilinear (boundary fitted) grid file (or files) for a curvilinear compatible mesh, scatter set or UGrid that is loaded into SMS. This can make use of user provided I,J index data sets if they exist. It also supports the option to compute I,J data indices. In this case, the orientation of the first cell in the surface will define the orientation of the I,J axes of the grid.

For EFDC grid files it may also use provided cell based datasets to populate the additional properties of the grid. These can include:

• Depth
• Z Roughness
• Vegetation type
• Wind shelter

Input Parameters

The format of the data file will be in either CH3D (also referred to as GSMB) or EFDC (also referred to as LTFATE). The input parameters include:

• Generate cell i-j datasets toggle.
• Cell i-coordinate dataset (optional) – Select the cell based dataset that defines the I index of each cell. This is required if the toggle to generate I-J is not selected.
• Cell j-coordinate dataset (optional) – Select the cell based dataset that defines the J index of each cell. This is required if the toggle to generate I-J is not selected.

Datasets that are available if the format is EFDC:

• Depth dataset (optional) – Select the cell based dataset to define the depth of each cell.
• Z Roughness dataset (optional) – Select the cell based to define the roughness of each cell.
• Vegetation type dataset (optional) – Select the cell based to define the vegetation type of each cell.
• Wind shelter dataset (optional) – Select the cell based to define the wind shelter value of each cell.

Output Parameters

The path to where files will be saved defaults to the project directory if one is defined in the instance of SMS. The path can be cut/paste from a file browser in windows to this edit field.

• CH3D grid file name defaults to "grid.inp".
• EFDC dxdy file name defaults to "dxdy.inp".
• EFDC lxly file name defaults to "lxly.inp".
• EFDC cell file name defaults to "cell.inp".

Current location in toolbox

This tool is currently located in Unstructured Grids/Export Curvilinear Grid.

Notes

The file formats for the CH3D and EFDC grids are defined in the Import Curvilinear Tool documentation. The cell.inp file for EFDC is not used for importing since it does not include any unique information for the definition of the grid. This file includes an ASCII map of the cell types in the grid.

Import Curvilinear Grid

The Import Curvilinear Grid tool is used to load an existing curvilinear (boundary fitted) grid into SMS as a UGrid object. This will also create cell based datasets defining the I, J index of each cell in the UGrid. Depending on the selected format and the specific data file(s).

For EFDC grid files it may also create additional cell based datasets for the UGrid that is loaded. These can include:

• Depth
• Z Roughness
• Vegetation type
• Wind shelter

Input parameters

• Format of the data file – Select the file format for the UGrid that will be imported.
  • "CH3D" – Will import a CH3D file.
  • "EFDC" – Will import a EFDC file.
• CH3D formatted grid file – Clicking the Select File button will open a Select File dialog where the CH3D file can be selected.
• EFDC formatted dxdy.inp file – Clicking the Select File button will open a Select File dialog where the dxyy.inp EFDC file can be selected.
• EFDC formatted lxly.inp file – Clicking the Select File button will open a Select File dialog where the lxly.inp EFDC file can be selected.

Output parameters

• Output UGrid name – Enter the name of the imported UGrid.

Current location in the toolbox

Unstructured Grids/Import Curvilinear Grid

CH3D Format

Format of the CH3D file (grid.inp). This file includes a 2 line header and a line for every corner point in a rectangular grid This includes inactive regions. The locations are ordered in a row major order. SMS will export 5 columns of data including (X, Y, Z, I, J). The (I, J) columns are not used in the import process. They are implied. The first line is a name to assign to the grid.

The second line defines the size of the grid based on cell corners. The number of cells in each direction is a maximum of the number of corners minus 1. Cell corners that do not correspond to an active cell in the grid is assigned a coordinate location of (9.0x10¹⁸, 9.0x10¹⁸, 9.0x10¹⁸).

Because this file format does not include cell based information, a single row or column of inactive cells is not supported. The corners of these cells are defined by the active neighbor, so the cell is assumed to exist. File organization:

    Grid_name
    num_rows_of_pts  num_cols_of_pts
    x y z 1 1
    x y z 2 1
    .
    .
    .
    x y z num_rows 1
    x y z 1 2
    x y z 2 2
    .
    .
    .
    x y z num_rows 2
    .
    .
    .
    x y z 1 num

Format of the EFDC files (dxdy.inp, lxly.inp). This format includes two files that work together to define the grid. The "dxdy.inp" files includes a 4 line comment header and a line for every active cell in the grid The header is metadata only and is not used in the import process. The last header line defines the values in each column for the data following. This includes:

• I J: the column and row index of the cell on this line.
• DX DY: the width and height of this cell.
• WATER DEPTH: the depth of the water in this cell.
• BOTTOM ELEV: the ground elevation value for this cell (cell based).
• ZROUGH: the roughness for this cell.
• VEG TYPE: the vegetation type for this cell.

The "lxly.inp" files also includes a 4 line comment header and a line for every active cell in the grid The header is metadata only and is not used in the import process. The last header line defines the values in each column for the data following. This includes:

• I J: the column and row index of the cell on this line.
• X Y: the location of the cell center of this cell.
• CUE CVE CUN CVN: the orientation of this cell (rotation values)
• WIND SHELTER: a wind shelter data value for this cell.

This format defines a nonconformal grid. Neighboring cells don't explicitly define the same corner points. When SMS loads this grid, the corner locations are merged to create a conformal grid. For this reason, when a grid is loaded and then rewritten, the detail definition may not be identical.

Import UGrid Points

The Import UGrid Points tool is used to import locations and datasets. The CSV file must contain coordinates for the points and, optionally, the file may contain datasets associated with the points.

The first line of the CSV file must be a header line with the coordinate columns of x, y, and z (optional). These columns must be named x, y, z. An error will be encountered if these columns do not exist.

Other columns may exist in the file for datasets. The dataset name is specified in the first line of the file. If the column does not have a name then the column will be skipped.

Transient data may also be imported using this tool. Transient datasets comprise multiple columns in the file with the same column name and with time specified on the second line of the file in the associated dataset column. There may not be any value specified on the second line of the file for the x, y coordinates. The time values may be relative times: 0.0, 2.5, 10.0, etc. Additionally, the time values may be specified as date times. The date format should be in the form of YEAR-MONTH-DAY HH:MM:SS.SS.

Multiple example files are shown below.

Input parameters

• CSV file with point coordinates and datasets – Shows the file name for the CSV file containing the coordinates and datasets. Clicking the Select File button will open a Select File browser dialog to select the CSV file.
• No data value – When the “No data value” is encountered in the csv file in one of the datasets XMS marks the value as “NULL” or “no data”. These values are not contoured or used in interpolation in XMS.
• Time unit – The time unit for transient datasets where the time is specified as a floating point number (in contrast to a date time).
• Coordinate system project file (*.prj) – Shows the file name for the projection associated with the coordinates of the points in the file. Clicking the Select File button will open a Select File browser dialog to select the PRJ file.

Current location in Toolbox

Unstructured Grids/Import UGrid Points

Example files

Example 1

id,y,x,c
1,15459458,2685809,6.4
2,15459506,2685824,9.7
3,15459524,2685850,8

This is a simple csv file. Notice the “x” and “y” columns; these are required. Note that “z” is not required. Also, notice that the order of x and y does not matter.

The other 2 columns: “id”, “c”. The will be imported as datasets.

Example 2

y	x	z	TDS	TDS	conc
			0	1	
-16	-75	8.5	59.04	9.24	1.9
32	-60	9.8	90.2	71	4.8
50	-34	0.7	67.2	98.4	9.5

This example shows a file with “x”, ”y”, and “z” columns. Notice that there are no values on the second line of the file for x, y, and z. This indicates that times are being specified for the datasets in the file.

The other 2 columns: “TDS” and “conc”. The will be imported as datasets. TDS will be a transient dataset with times of 0.0 and 1.0. The user will have to specify the units of the times in the tool. The conc dataset will be imported without multiple time steps.

Example 3

y	x	c2	c2	c2
		2011-02-01	2012-02-01	2013-02-01
-16	-75	59.04	43.64	9.24
32	-60	90.2	44.16	71
50	-34	67.2	0	98.4

This is a csv file with a transient dataset with the time specified as dates.

Example 4

y	X	c2	c2	c2 
		2011-02-01 15:30:22.1	2012-02-01	2013-02-01 6:45:15
-16	-75	59.04	43.64	9.24
32	-60	90.2	44.16	71
50	-34	67.2	0	98.4

This is a csv file with a transient dataset with the time specified as dates and times.

Merge UGrids (Geometry)

The Merge UGrids tool merges two 2D geometries. These can be 2D meshes, UGrids, or scatter sets. The geometries can overlap or not. In areas of overlap, the tool honors the primary grid, deletes all elements from the secondary grid that overlap part of the primary grid plus a buffer around the primary grid. This prevents the transition zone from becoming so small that poorly shaped cells result. The tool builds transition triangle cells to fill the gap created in this process. The new geometry is created as 2D Mesh in SMS.

Limitations:

• This tool only works on 2 geometries at a time. If multiple geometries are to be merged, they must be merged incrementally.
• The Primary grid argument for this tool must be a single contiguous geometry. (It can't be disjoint). If disjoint pieces exist, they must be merged into a background surface one at a time.

This tool is designed to replace the functionality to merge meshes and scatter sets in SMS. This operation is faster, more generic, and because it is in the toolbox, will be accessible outside of the standard SMS framework.

Input parameters

• Primary grid – Select the grid that will act as the primary grid. If there are conflicts during the merge, this grid will receive priority to resolve the conflict.
• Secondary grid – Select the grid that will act as the secondary grid during the merge.
• Duplicate point tolerance – When points are compared as duplicates the distance between the points is calculated. If the distance is less than this tolerance then the points are considered duplicates. This is used for comparing points on the outer boundary of the primary grid with points in the secondary grid and trying to preserve cells in the secondary grid that are adjacent to cells in the primary grid. The default value is usually sufficient but if you find cells in the secondary grid are being deleted and you want to preserve those then try increasing the tolerance.
• Buffer distance option – Option for buffering the outer boundary of the primary grid during the merge operation.
  • Default – The tool will use 0.01 times the minimum cell edge length as the buffer distance.
  • Specified – The tool will use the user specified buffer distance.
    • Buffer distance – specify the desired buffer distance. This is the width of the transition zone between the geomtries.
• Stitch non-overlapping grids with matching boundary points – Option for merging two grids that have matching boundary points and no overlapping features. This option should only be used if the user is positive that the grids satisfy this constraint. A grid with internal holes will result from using this option when the grids overlap. The tool will run significantly faster if this option is checked.

Output parameters

• Merged grid – Enter the name of the new merged UGrid.

Current Location in toolbox

Unstructured Grids/Merge Ugrids

It is recommended to use the Smooth Datasets tool instead of this tool.

Smooth UGrid

The Smooth UGrid tool is nearly identical to part of the Smooth Datasets tool. It can be applied to a 2D mesh, a scatter set, or a 2D Ugrid. The tool only supports the slope limited smoothing as described in Smooth Datasets with a user specified anchor type.

The difference between the tools is that this tool actually creates a new geometry with the elevation values smoothed rather than just creating a new dataset on the existing geometry.

Input parameters

• Input grid – Select the UGrid to use.
• Maximum slope – Set the maximum potential slope of the UGrid.
• Anchor type – Select which type of anchor for the smoothing process.
  • "Minimum value" – Sets the minimum elevation to be the anchor for the smoothing process.
  • "Maximum value" – Sets the maximum elevation to be the anchor for the smoothing process.

Output parameters

• Smoothed grid – Enter the name of the new smoothed UGrid.

Current Location in toolbox

Unstructured Grids/Smooth Ugrid

Related Tools

• Smooth Datasets

Extrude to 3D UGrid

The Extrude to 3D Ugrid tool converts a 2D UGrid into a 3D UGrid.

Input Parameters

• Input grid – Select a 2D UGrid to convert to a 3D UGrid.
• Number of layers – Enter the number of layers the new 3D UGrid will have.
• Layer n thickness – For each layer, enter the layer thickness. This value will be in the units set in the project projection.

Output Parameters

• Output grid – Name of the output grid.

Current Location in Toolbox

Unstructured Grids/Extrude to 3D UGrid

Map Activity to UGrid

This tool builds a dataset with values copied from one dataset and activity mapped from another. The tool has the following options:

Input Parameters

• Input grid– Select the geometry that will define the values for the new UGrid.
• Activity coverage – Select the coverage that will define the activity for the new UGrid.

Output Paramters

• Name of the output ugrid – Enter the name for the new activity UGrid.

Current Location in Toolbox

Unstructured Grids/Map Activity to UGrid