|
|
This page outlines the 2D mesh formats supported by BASEMENT and BASEmesh.
|
|
|
|
|
|
All current 2D mesh formats used in BASEMENT v2.8 and v3.x are based on the format outlined in the [SMS 2DM specification](https://www.xmswiki.com/wiki/SMS:2D_Mesh_Files_*.2dm).
|
|
|
|
|
|
Please refer to the sections below for important deviations and supported tags.
|
|
|
|
|
|
[[_TOC_]]
|
|
|
|
|
|
## 2DM_v2 Format
|
|
|
|
|
|
| Tag | File Extension | BASEMENT v2 | BASEMENT v3 | Elevation |
|
|
|
|--------|----------------|-------------|-------------|----------------|
|
|
|
| 2dm_v2 | .2dm | Yes | Yes* | Node elevation |
|
|
|
|
|
|
\* *Using the 2DM_v2 format with BASMENT v3.x requires setting the `INTERPOLATION` key in the model setup. See [below](#using-2dm_v2-meshes-in-BASEMENT-v3.x) for instructions.*
|
|
|
|
|
|
The 2DM_v2 format is a strict subset of the original SMS 2DM mesh format, refer to the following table for a list of supported card identifiers.
|
|
|
|
|
|
### Card Identifiers
|
|
|
|
|
|
| Card | Description | Format |
|
|
|
|------------------------|---------------------------------------|-------------------------------------------------------|
|
|
|
| MESH2D | First line of the file, required | - |
|
|
|
| NUM_MATERIALS_PER_ELEM | The number of MATID columns to expect | `NUM_MATERIALS_PER_ELEM 1` |
|
|
|
| ND | Mesh node | `ND <node_id> <pos_x> <pos_y> <pos_z>` |
|
|
|
| E3T | Triangular mesh element | `E3T <element_id> <node_1> <node_2> <node_3> <matid>` |
|
|
|
|
|
|
### Implementation Details
|
|
|
|
|
|
The following list should not be considered part of the standard, but keeps track of some known issues encountered when generating these files for use with BASEMENT.
|
|
|
|
|
|
* While not explicitly allowed by the SMS version of the standard, most parsers will allow zero-indexed node or element IDs.
|
|
|
This is **not** permitted in meshes used with BASEMENT, all nodes and elements must be consecutive lists starting at 1.
|
|
|
* Trailing newline characters, which are often inserted by editors for POSIX compatibility, are **not** permitted.
|
|
|
|
|
|
### Using 2DM_v2 meshes in BASEMENT v3.x
|
|
|
|
|
|
BASEMENT v3.x stores its elevation data in the mesh elements, rather than in the nodes.
|
|
|
|
|
|
However, the older mesh format can still be used by having BASEMENT interpolate the mesh element interpolation data from the element's defining nodes.
|
|
|
|
|
|
Interpolation methods include: `mean`, `median`, `maximum`, `minimum`, and `weighted` and are specified in the `INTERPOLATION` key of the project's `model.json` setup file:
|
|
|
|
|
|
```json
|
|
|
"GEOMETRY": {
|
|
|
"mesh_file": "mesh_geometry.2dm",
|
|
|
"INTERPOLATION": {
|
|
|
"method": "weighted"
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
Next, the following line must be manually added to the beginning of the file:
|
|
|
|
|
|
```cs
|
|
|
MESH2DM
|
|
|
NUM_MATERIALS_PER_ELEM 1 // <- This line was inserted
|
|
|
ND 1 2.76 1.25 2.32
|
|
|
ND 2 2.78 1.25 2.36
|
|
|
...
|
|
|
```
|
|
|
|
|
|
Finally, the standalone string definition [sidecar file](#string-definitions) must be replaced with `NS` cards. Refer to the corresponding section in the [2DM_v3 specification](#2dm_v3-format) for details.
|
|
|
|
|
|
**Example sidecar file:**
|
|
|
|
|
|
```py
|
|
|
STRINGDEF {
|
|
|
name = Inflow
|
|
|
node_ids = (25, 23, 72, 3, 12)
|
|
|
upstream_direction = right
|
|
|
}
|
|
|
STRINGDEF {
|
|
|
name = Outflow
|
|
|
node_ids = (16, 55, 19, 2, 46, 63)
|
|
|
upstream_direction = left
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**Equivalent node strings:**
|
|
|
|
|
|
```cs
|
|
|
...
|
|
|
NS 25 23 72 3 -12 Inflow
|
|
|
NS 63 46 2 19 55 -16 Outflow
|
|
|
```
|
|
|
|
|
|
Keep in mind that `upstream_direction` is always `right` for the `NS`-card syntax. Note that the node ID order was flipped for the `Outflow` node string in the example to conform it to this convention.
|
|
|
|
|
|
Additional details on this compatibility mode can be found in the User Manual for BASEMENT, available on the [BASEMENT website](https://basement.ethz.ch/).
|
|
|
|
|
|
## 2DM_v3 Format
|
|
|
|
|
|
| Tag | File Extension | BASEMENT v2 | BASEMENT v3 | Elevation |
|
|
|
|--------|----------------|-------------|-------------|-------------------|
|
|
|
| 2dm_v3 | .2dm | Yes* | Yes | Element elevation |
|
|
|
|
|
|
\* *BASEmesh v2.0 allows the generation of 2DM_v3 meshes without node elevation data. This effectively halves interpolation time, but will result in a mesh that is no longer compatible with BASEMENT v2. Make sure to interpolate both nodes and elements if you want to re-use the same mesh for both environments.*
|
|
|
|
|
|
The 2DM_v3 format is a more radical deviation from the SMS 2DM standard in a number of ways.
|
|
|
|
|
|
### Element Elevations
|
|
|
|
|
|
The key difference between this format and its predecessor is that mesh elevation data is stored in the mesh elements, rather than in the nodes.
|
|
|
|
|
|
These element elevations take the form of the second material index for the mesh file, which necessitates allowing decimal values in the MATID columns. This may cause compatibility issues with other software, but it fully supported by MDAL/QGIS.
|
|
|
|
|
|
> **Compatibility note:** As of v3.0.2, BASEMENT does not use the node elevations at all. This makes interpolating the quality mesh nodes optional, leaving all node elevations at `0.0`. This is supported by BASEmesh v2 and higher.
|
|
|
>
|
|
|
> However, this does break compatibility with BASEMENT v2, be sure to interpolate both nodes and elements if you wish to use the same mesh in both BASEMENT environments.
|
|
|
|
|
|
### String Definitions
|
|
|
|
|
|
This format introduces the SMS `NS` ("node string") card identifier as the storage container for string definitions, rather than the sidecar file used in 2DM_v2.
|
|
|
|
|
|
A potential source of compatibility issues with other parsers is the inclusion of a name field after the final node string. This is not part of the SMS standard, but does not appear to cause any issues in most applications.
|
|
|
|
|
|
### Card Identifiers
|
|
|
|
|
|
| Card | Description | Format |
|
|
|
|------------------------|---------------------------------------|----------------------------------------------------------------------|
|
|
|
| MESH2D | First line of the file, required | - |
|
|
|
| NUM_MATERIALS_PER_ELEM | The number of MATID columns to expect | `NUM_MATERIALS_PER_ELEM 2` |
|
|
|
| ND | Mesh node | `ND <node_id> <pos_x> <pos_y> <pos_z>` |
|
|
|
| E3T | Triangular mesh element | `E3T <element_id> <node_1> <node_2> <node_3> <matid> <element_elev>` |
|
|
|
| NS | Node string / string definition | `<NS> <node_1> <node_2> ... -<node_n> <name>` |
|
|
|
|
|
|
Note that the last node index in a node string is negative to signal the end of the list when parsing.
|
|
|
|
|
|
### Implementation Details
|
|
|
|
|
|
The following list should not be considered part of the standard, but keeps track of some known issues encountered when generating these files for use with BASEMENT.
|
|
|
|
|
|
* While not explicitly allowed by the SMS version of the standard, most parsers will allow zero-indexed node or element IDs.
|
|
|
This is **not** permitted in meshes used with BASEMENT, all nodes and elements must be consecutive lists starting at 1.
|
|
|
* Trailing newline characters, which are often inserted by editors for POSIX compatibility, are **not** permitted.
|
|
|
* Node strings must be written into a single line. The implicit concatenation used by SMS is **not** supported. |