# mesh-format v3.2.3 **Mercurial revision 5770:c90c3015e72d | 2026-05-22** --- ## Description `mesh-format` is a command-line tool designed to **convert between different mesh formats**. It supports a wide range of input and output formats, making it versatile for various applications in computational modeling and oceanography. --- ## Usage ```bash mesh-format -i input_filename -o output_filename [OPTIONS] ``` --- ## Options ### **Input/Output Options** | Option | Description | | -------------- | --------------------------------------- | | `-i ` | Path to the **input mesh file**. | | `-o ` | Path to the **output mesh file**. | | `-iF ` | Specify the **input format** manually. | | `-oF ` | Specify the **output format** manually. | --- ### **Mesh Processing Options** | Option | Description | | ------ | -------------------------------------------------------------------------------------- | | `-r` | Run `fe_reducebw(mesh, 100)` to reduce the bandwidth of the mesh. | | `-c` | **Create mode** (default): Generate a new output file. | | `-u` | **Update mode**: Update `(lon, lat)` variables in the output file from the input file. | --- ### **Boundary and Bathymetry Options** | Option | Description | | ----------- | ---------------------------------------------------------------------------------------------------------------- | | `-b ` | Path to the **boundary elements file** (`.bel`). | | `-d ` | Path to the **bathymetry file** (`.s2r`). Only relevant if the output format supports bathymetry. | | `--inv` | Invert bathymetry convention: **positive downward** (default is negative downward). Only affects boundary codes. | | `--dry=no` | Disallow dry nodes in boundary processing. | | `--dry=yes` | Allow dry nodes in boundary processing (default). | --- ### **Projection and Scaling Options** | Option | Description | | ------------------- | ------------------------------------------------------- | | `--iproj=` | Input projection (e.g., `--iproj=+proj=latlong`). | | `--oproj=` | Output projection (e.g., `--oproj=+proj=utm +zone=10`). | | `--wproj=` | Working projection for intermediate calculations. | | `--h_scale ` | Scale factor for bathymetry depth values. | --- ### **Grid Options** | Option | Description | | -------------- | ----------------------------------------------------------------------------------- | | `-g ` | Grid options for structured mesh generation (e.g., `-g "gridfile.nc,maskfile.nc"`). | --- ### **Miscellaneous Options** | Option | Description | | -------------- | ------------------------------------------------------------------- | | `-h`, `--help` | Display help and exit. | | `--quadrangle` | Force the mesh to use **quadrangle elements** (default: triangles). | --- ## Supported Formats The tool supports the following mesh formats: | Format Name | Description | | ----------------- | ----------------------------------------------------- | | `nei` | Neighbour format (`.nei`). | | `nc` | NetCDF 2D format (`.nc`). | | `nc2d` | NetCDF 2D format (default for `.nc` files). | | `nc3d` | NetCDF 3D format. | | `gmsh` | [Gmsh](https://gmsh.info/) mesh format. | | `gmsh_ww` | Gmsh format for WaveWatch III. | | `fvcom` | [FVCOM](https://fvcom.smast.umassd.edu/) mesh format. | | `schism` | [SCHISM](https://schism.wiki/) mesh format. | | `schism-netcdf` | SCHISM NetCDF format. | | `kml` | Keyhole Markup Language (for Google Earth). | | `quadrangle` | Quadrangle ASCII format. | | `telemac_ascii` | [TELEMAC](https://www.opentelemac.org/) ASCII format. | | `telemac_binary` | TELEMAC binary format. | | `telemac_swapped` | TELEMAC swapped binary format. | | `quoddy` | Quoddy mesh format. | | `netcdf` | Structured NetCDF format. | | `LGP2` | LGP2 NetCDF format. | > **Notes:** > > - Default input format: `nei` for `.nei` files, `nc2d` for `.nc` files. > - Default output format: Same as input format unless specified otherwise. --- ## Examples ### **Basic Conversion** Convert a mesh from `.nei` to NetCDF format: ```bash mesh-format -i input.nei -o output.nc ``` ### **Specify Input/Output Formats** Convert a Gmsh mesh to TELEMAC ASCII format: ```bash mesh-format -i input.msh -o output.dat -iF gmsh -oF telemac_ascii ``` ### **Add Bathymetry** Convert a mesh and add bathymetry from a `.s2r` file: ```bash mesh-format -i input.nei -o output.nc -d bathymetry.s2r ``` ### **Invert Bathymetry Convention** Convert a mesh with bathymetry values **positive downward**: ```bash mesh-format -i input.nei -o output.nc --inv ``` ### **Update Coordinates** Update `(lon, lat)` coordinates in an existing NetCDF mesh: ```bash mesh-format -i input.nc -o output.nc -u ``` ### **Reduce Bandwidth** Optimize mesh bandwidth for better performance: ```bash mesh-format -i input.nei -o output.nei -r ``` ### **Use Projections** Convert a mesh with input and output projections: ```bash mesh-format -i input.nei -o output.nc \ --iproj="+proj=latlong" \ --oproj="+proj=utm +zone=10" ``` ### **Scale Bathymetry** Apply a scaling factor to bathymetry values: ```bash mesh-format -i input.nei -o output.nc --h_scale 1.5 ``` ### **Process Boundary Elements** Convert a mesh and include boundary elements from a `.bel` file: ```bash mesh-format -i input.nei -o output.nc -b boundaries.bel ``` ### **Generate Structured Mesh** Create a structured mesh from grid and mask files: ```bash mesh-format -o output.nei -g "gridfile.nc,maskfile.nc" ``` ### **Force Quadrangle Elements** Convert a mesh to use quadrangle elements: ```bash mesh-format -i input.nei -o output.nc --quadrangle ``` --- ## Environment Variables `mesh-format` does not rely on specific environment variables. However, it uses standard system libraries (e.g., NetCDF, PROJ) that may require environment configurations: - **PROJ**: Ensure `PROJ_LIB` is set if using custom projections. - **NetCDF**: Ensure `NETCDF_PATH` is configured if NetCDF libraries are not in the default path. --- ## Notes 1. **Input/Output Requirements**: - Both `-i` (input file) and `-o` (output file) are **mandatory**. - If the input or output format is not specified, the tool attempts to infer it from the file extension. 2. **Bathymetry Handling**: - Bathymetry data (from `-d`) is only applied if the output format supports it. - Use `--inv` to switch between **positive downward** and **negative downward** conventions. 3. **Boundary Codes**: - Boundary elements (from `-b`) are processed and assigned codes based on depth values. - Use `--dry=no` to exclude dry nodes from boundary processing. 4. **Mesh Optimization**: - The `-r` option reduces the bandwidth of the mesh, which can improve performance in some numerical models. 5. **Projection Support**: - Projections (`--iproj`, `--oproj`, `--wproj`) are optional and require the PROJ library. 6. **Structured Meshes**: - The `-g` option is used for generating structured meshes from grid and mask files. --- ## See Also - [Gmsh Documentation](https://gmsh.info/doc/texinfo/gmsh.html) - [FVCOM Official Website](https://fvcom.smast.umassd.edu/) - [SCHISM Wiki](https://schism.wiki/) - [TELEMAC Official Website](https://www.opentelemac.org/) - [NetCDF Documentation](https://www.unidata.ucar.edu/software/netcdf/docs/) - [PROJ Library](https://proj.org/)