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¶

mesh-format -i input_filename -o output_filename [OPTIONS]

Options¶

Input/Output Options¶

Option	Description
`-i <file>`	Path to the input mesh file.
`-o <file>`	Path to the output mesh file.
`-iF <format>`	Specify the input format manually.
`-oF <format>`	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 <file>`	Path to the boundary elements file (`.bel`).
`-d <file>`	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=<proj>`	Input projection (e.g., `--iproj=+proj=latlong`).
`--oproj=<proj>`	Output projection (e.g., `--oproj=+proj=utm +zone=10`).
`--wproj=<proj>`	Working projection for intermediate calculations.
`--h_scale <value>`	Scale factor for bathymetry depth values.

Grid Options¶

Option	Description
`-g <options>`	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 mesh format.
`gmsh_ww`	Gmsh format for WaveWatch III.
`fvcom`	FVCOM mesh format.
`schism`	SCHISM mesh format.
`schism-netcdf`	SCHISM NetCDF format.
`kml`	Keyhole Markup Language (for Google Earth).
`quadrangle`	Quadrangle ASCII format.
`telemac_ascii`	TELEMAC 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:

mesh-format -i input.nei -o output.nc

Specify Input/Output Formats¶

Convert a Gmsh mesh to TELEMAC ASCII format:

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:

mesh-format -i input.nei -o output.nc -d bathymetry.s2r

Invert Bathymetry Convention¶

Convert a mesh with bathymetry values positive downward:

mesh-format -i input.nei -o output.nc --inv

Update Coordinates¶

Update (lon, lat) coordinates in an existing NetCDF mesh:

mesh-format -i input.nc -o output.nc -u

Reduce Bandwidth¶

Optimize mesh bandwidth for better performance:

mesh-format -i input.nei -o output.nei -r

Use Projections¶

Convert a mesh with input and output projections:

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:

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:

mesh-format -i input.nei -o output.nc -b boundaries.bel

Generate Structured Mesh¶

Create a structured mesh from grid and mask files:

mesh-format -o output.nei -g "gridfile.nc,maskfile.nc"

Force Quadrangle Elements¶

Convert a mesh to use quadrangle elements:

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¶

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.

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.

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.

Mesh Optimization:

The -r option reduces the bandwidth of the mesh, which can improve performance in some numerical models.

Projection Support:

Projections (--iproj, --oproj, --wproj) are optional and require the PROJ library.

Structured Meshes:

The -g option is used for generating structured meshes from grid and mask files.