# 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

```bash
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:

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

---

### **Check Geometry and Channels**

Validate mesh geometry and check for channel edges:

```bash
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:

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

---

### **Refine Large Connections**

Refine all connections larger than 1000 meters:

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

---

### **Improve Triangle Aspect Ratios**

Optimize the mesh to favor 120° angles in triangles:

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

---

### **Limit Node Connections**

Disconnect nodes with more than 5 connections:

```bash
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:

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

---

### **Comprehensive Mesh Correction**

Combine multiple checks and corrections:

```bash
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:

```bash
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

1. **Input File Requirements:**
  - The input mesh file **must** be in `.nei` format.
  - If using a boundary file (`-b`), it must be in `.bel` format.
2. **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`).
3. **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.
4. **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.
5. **Performance:**
  - For large meshes, consider running the tool on a **machine with sufficient memory** and processing power.

---

## See Also

- [FE Mesh Formats](https://www.example.com/fe-mesh-formats) (for `.nei` and `.bel` file specifications)
- [Delaunay Triangulation](https://en.wikipedia.org/wiki/Delaunay_triangulation) (for understanding the `--delaunay` method)
- [Mesh Quality Metrics](https://www.example.com/mesh-quality) (for aspect ratio and angle criteria)