mesh-doctor v3.2.3¶

Mercurial revision 5786:5c8b45563631 | 2026-08-04

Description¶

mesh-doctor is a tool designed to check the validity of finite element (FE) input meshes based on multiple diagnostics and produce a valid, corrected mesh as output. It ensures the mesh meets quality criteria for numerical simulations, such as:

Geometry consistency.
Absence of crossing connections.
Optimal triangle aspect ratios.
Proper boundary definitions.

Usage¶

mesh-doctor [OPTIONS] -m input.nei

Note: The -m option is mandatory and must specify the input mesh file (.nei format).

Options¶

Input/Output Options¶

Option	Description
`-h`, `--help`	Display help and exit.
`-m <file>`	Required. Input mesh file (`.nei` format).
`-b <file>`	Boundary file (`.bel` format).
`-o <name>`	Root name for the final grid output. If not specified, defaults to `mesh-doctor.nei`.

Mesh Validation Options¶

Option	Description
`-c`	Check for channel edges (e.g., narrow connections between water bodies).
`-g`	Check the geometry of the mesh (e.g., angles, aspect ratios).
`-s`	Safety check: Look for crossing connections in the mesh.
`-p <file>`	If `-s` is used, specify a polygon file to limit the working area of the safety check.

Mesh Correction Options¶

Option	Description
`-d <float>`	Maximum resolution: refine all connections larger than the specified value (in meters).
`--no-renum`	Do not check or optimize the index numbering of nodes.
`--reshape-only`	Only reshape triangles with bad angles (e.g., too sharp or too flat). Otherwise, all triangles are checked.
`--no-reshape`	Do not reshape triangles at all.
`--aspect`	Activate triangle aspect ratio improvement to favor 120° angles.
`--nghmax <int>`	Maximum number of connections allowed at a node. If exceeded, disconnect the node. Default: 7.

Delaunay Method Options¶

Option	Description
`--delaunay`	Activate the Delaunay method to improve angles at the exterior boundary.
`--maxsize <float>`	If `--delaunay` is used, specify the maximum distance (in meters) tolerated for boundary connections. Default: 5000.
`--minsharp <float>`	If `--delaunay` is used, specify the minimum angle (in degrees) tolerated for boundary triangles. Default: 10.

Debugging Options¶

Option	Description
`--debug`	Activate debug verbose mode for detailed output.

Deprecated Options¶

Option	Description
`-z`	Deprecated. Pre-set zone to limit the working area. Use `-p` with a polygon file instead.

Examples¶

Basic Mesh Validation¶

Check the validity of a mesh file and save the corrected version:

mesh-doctor -m input.nei -o corrected_mesh.nei

Check Geometry and Channels¶

Validate mesh geometry and check for channel edges:

mesh-doctor -m input.nei -g -c -o validated_mesh.nei

Safety Check with Polygon Limitation¶

Perform a safety check (crossing connections) limited to a specific polygon area:

mesh-doctor -m input.nei -s -p polygon.bel -o safe_mesh.nei

Refine Large Connections¶

Refine all connections larger than 1000 meters:

mesh-doctor -m input.nei -d 1000 -o refined_mesh.nei

Improve Triangle Aspect Ratios¶

Optimize the mesh to favor 120° angles in triangles:

mesh-doctor -m input.nei --aspect -o optimized_mesh.nei

Limit Node Connections¶

Disconnect nodes with more than 5 connections:

mesh-doctor -m input.nei --nghmax 5 -o limited_mesh.nei

Delaunay Method for Boundary Improvement¶

Use the Delaunay method to improve boundary angles with custom thresholds:

mesh-doctor -m input.nei \
  --delaunay \
  --maxsize 3000 \
  --minsharp 15 \
  -o delaunay_mesh.nei

Comprehensive Mesh Correction¶

Combine multiple checks and corrections:

mesh-doctor -m input.nei \
  -g -c -s \
  -d 500 \
  --aspect \
  --nghmax 6 \
  -o final_mesh.nei

Debug Mode¶

Run with debug output to diagnose issues:

mesh-doctor -m input.nei --debug -o debug_mesh.nei

Environment Variables¶

mesh-doctor does not rely on external environment variables for its core functionality. However, it may inherit system-level settings (e.g., for file paths or parallel processing if integrated with other tools).

Notes¶

Input File Requirements:

The input mesh file must be in .nei format.
If using a boundary file (-b), it must be in .bel format.

Output:

If no output name is specified (-o), the corrected mesh is saved as mesh-doctor.nei.
Intermediate files (e.g., mesh-doctor.00.nei, mesh-doctor.01.nei) may be generated in debug mode (--debug).

Mesh Quality:

The tool automatically checks for:
- Crossing connections (with -s).
- Bad angles (with -g or --aspect).
- Over-connected nodes (with --nghmax).
Use --reshape-only to focus on problematic triangles only.

Delaunay Method:

The --delaunay option is computationally intensive and should be used for boundary improvements only.
Adjust --maxsize and --minsharp to control the tolerance for boundary connections and angles.

Performance:

For large meshes, consider running the tool on a machine with sufficient memory and processing power.