# mesh-refine v3.2.3

**Mercurial revision 5803:7164e00e8f3d | 2026-08-18**

---

## Description

`mesh-refine` is a tool designed to **refine a mesh** by adjusting its resolution based on specified criteria. It allows for controlled refinement of mesh elements to improve accuracy in specific areas while maintaining computational efficiency.

---

## Usage

```bash
mesh-refine [OPTIONS]
```

---

## Options


| Option         | Description                                                            |
| -------------- | ---------------------------------------------------------------------- |
| `-h`, `--help` | Display this help message and exit.                                    |
| `--debug`      | Enable debug mode for detailed output.                                 |
| `-m <file>`    | Specify the input **mesh file** (required).                            |
| `-d <value>`   | Maximum distance (`dmax`) for edge selection during refinement.        |
| `-e <value>`   | Maximum criterion (`cmax`) for edge selection during refinement.       |
| `-c`           | Enable **channels** mode for specialized refinement.                   |
| `-o <file>`    | Specify the output file. Default: `refined-reshaped.nei`.              |
| `-p <file>`    | Specify a **polygon file** to guide refinement in specific regions.    |
| `--quadrangle` | Use **quadrangle elements** instead of triangles (default: triangles). |


---

## Examples

### **Basic Mesh Refinement**

Refine a mesh with default settings:

```bash
mesh-refine -m input_mesh.nei
```

### **Refine with Maximum Distance**

Refine edges longer than `10.0` units:

```bash
mesh-refine -m input_mesh.nei -d 10.0
```

### **Refine with Maximum Criterion**

Refine edges based on a criterion value of `5.0`:

```bash
mesh-refine -m input_mesh.nei -e 5.0
```

### **Refine with Channels Mode**

Enable channels mode for specialized refinement:

```bash
mesh-refine -m input_mesh.nei -c
```

### **Refine with Polygon Guidance**

Refine the mesh within a specific polygon region:

```bash
mesh-refine -m input_mesh.nei -p polygon_file.poly
```

### **Refine with Custom Output**

Save the refined mesh to a custom output file:

```bash
mesh-refine -m input_mesh.nei -o refined_output.nei
```

### **Refine with Quadrangle Elements**

Use quadrangle elements instead of triangles:

```bash
mesh-refine -m input_mesh.nei --quadrangle
```

### **Refine with Debug Mode**

Enable debug mode for detailed output:

```bash
mesh-refine -m input_mesh.nei --debug
```

### **Combined Refinement**

Refine a mesh with a maximum distance of `15.0`, a criterion of `3.0`, and save to a custom output:

```bash
mesh-refine -m input_mesh.nei -d 15.0 -e 3.0 -o custom_refined.nei
```

---

## Environment Variables

`mesh-refine` does not rely on specific environment variables. However, ensure your system has sufficient resources (memory, CPU) for large mesh refinements.

---

## Notes

1. **Input Mesh:**
  - The input mesh file must be in a **supported format** (e.g., `.nei`).
  - If no input mesh is specified (`-m`), the tool will display an error and exit.
2. **Output:**
  - By default, the refined mesh is saved as `refined-reshaped.nei`.
  - Use `-o` to specify a custom output filename.
3. **Refinement Criteria:**
  - `-d` (`dmax`) and `-e` (`cmax`) are used to select edges for refinement.
  - If neither `-d` nor `-e` is specified, the tool will perform a **basic doubling** of the mesh elements.
4. **Channels Mode:**
  - Enabling `-c` activates specialized refinement for channels, which may be necessary for certain hydraulic or coastal applications.
5. **Polygon Guidance:**
  - The `-p` option allows refinement to be focused on specific regions defined by a polygon file.
6. **Element Type:**
  - By default, the tool uses **triangle elements** (`FE_TRIANGLE`).
  - Use `--quadrangle` to switch to quadrangle elements (`FE_QUADRANGLE`).
7. **Debug Mode:**
  - Use `--debug` to enable detailed output for troubleshooting or analysis.

---

## See Also

- [FE Mesh Formats](https://example.com/fe-mesh-formats) (for supported mesh file formats)
- [Polygon File Formats](https://example.com/polygon-formats) (for polygon guidance files)