# mesh-split v3.2.3

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

---

## Description

`mesh-split` is a tool designed to **refine and split meshes** based on input polygons or predefined zones. It supports various mesh formats and provides options for customizing the splitting process, such as discretization, line modes, and exact node placement.

---

## Usage

```bash
mesh-split [OPTIONS] -m input
```

---

## Options


| Option                          | Description                                                                                                                           |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `-h`, `--help`                  | Show this help and exit.                                                                                                              |
| `-m <file>`                     | **Required.** Path to the input mesh file.                                                                                            |
| `-iF <format>`                  | Input mesh format. See [Mesh Formats](#mesh-formats) for supported formats.                                                           |
| `-p <file>`                     | Path to the polygon input file to split the mesh.                                                                                     |
| `-r <name>`                     | Root name for intermediate files. Default: `mesh-split`.                                                                              |
| `-o <file>`                     | Output file for the final result (used with `--with-discretisation`).                                                                 |
| `-z <zone>`                     | Pre-set zone to limit the working area. Supported zones: `korea`, `north-china`, `central-china`, `south-china`, `taiwan`, `lofoten`. |
| `--with-discretisation <types>` | Discretization element pairs (e.g., `LGP0xLGP1`, `DGP1xLGP2`, `DNP1xLGP2`, `Q1xQ0`). Default: `LGP0xLGP1`.                            |
| `--line-mode <mode>`            | Type of coordinates: `LOXODROMIC`, `ORTHODROMIC`, or `CARTESIAN`. Default: `LOXODROMIC`.                                              |
| `--exact`                       | Move original nodes to exactly split on polygon limits.                                                                               |
| `--quadrangle`                  | Enable quadrangle grid support.                                                                                                       |
| `--polar`                       | Enable polar grid support.                                                                                                            |
| `--debug`                       | Enable debug verbose mode.                                                                                                            |


---

(mesh-formats)=
## Mesh Formats

The following mesh formats are supported:


| Format ID | Format Name       |
| --------- | ----------------- |
| 4         | `nc2d`            |
| 4         | `nc`              |
| 5         | `nc3d`            |
| 0         | `nei`             |
| 10        | `gmsh`            |
| 11        | `gmsh_ww`         |
| 15        | `fvcom`           |
| 12        | `schism`          |
| 13        | `schism-netcdf`   |
| 14        | `kml`             |
| 40        | `quadrangle`      |
| 31        | `telemac_ascii`   |
| 30        | `telemac_binary`  |
| 32        | `telemac_swapped` |
| 2         | `quoddy`          |
| 42        | `netcdf`          |
| 43        | `LGP2`            |


---

## Examples

### **Basic Mesh Splitting**

Split a mesh using a polygon file:

```bash
mesh-split -m input_mesh.nc -p polygon.plg
```

### **Split Mesh with Custom Root Name**

Split a mesh and specify a custom root name for intermediate files:

```bash
mesh-split -m input_mesh.nc -p polygon.plg -r my_mesh_split
```

### **Split Mesh with Discretization**

Split a mesh and apply discretization to the output:

```bash
mesh-split -m input_mesh.nc -p polygon.plg --with-discretisation "LGP0xLGP1 DGP1xLGP2" -o output_mesh.nc
```

### **Split Mesh in a Predefined Zone**

Split a mesh limited to the `korea` zone:

```bash
mesh-split -m input_mesh.nc -z korea
```

### **Split Mesh with Exact Node Placement**

Split a mesh and ensure nodes are exactly placed on polygon limits:

```bash
mesh-split -m input_mesh.nc -p polygon.plg --exact
```

### **Split Mesh with Quadrangle Support**

Split a mesh with quadrangle grid support:

```bash
mesh-split -m input_mesh.nc -p polygon.plg --quadrangle
```

### **Split Mesh with Orthodromic Line Mode**

Split a mesh using orthodromic coordinates:

```bash
mesh-split -m input_mesh.nc -p polygon.plg --line-mode ORTHODROMIC
```

### **Split Mesh with Debug Mode**

Enable debug mode to generate intermediate files for troubleshooting:

```bash
mesh-split -m input_mesh.nc -p polygon.plg --debug
```

---

## Environment Variables

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

---

## Notes

1. **Input Mesh File:**
  - The `-m` option is **required** and must point to a valid mesh file in one of the [supported formats](#mesh-formats).
2. **Polygon File:**
  - The `-p` option specifies the polygon file used to split the mesh. If not provided, the mesh will not be split.
3. **Discretization:**
  - Use `--with-discretisation` to specify element pairs for discretization. The default is `LGP0xLGP1`.
  - Example pairs: `LGP0xLGP1`, `DGP1xLGP2`, `DNP1xLGP2`, `Q1xQ0`.
4. **Line Modes:**
  - `LOXODROMIC` (default): Rhumb line (constant bearing).
  - `ORTHODROMIC`: Great circle (shortest path on a sphere).
  - `CARTESIAN`: Straight line in Cartesian coordinates.
5. **Zones:**
  - Predefined zones (`korea`, `north-china`, etc.) limit the working area to a specific geographic region.
6. **Exact Node Placement:**
  - The `--exact` option ensures that nodes are moved to exactly fit the polygon limits, which can be useful for precise splitting.
7. **Debug Mode:**
  - The `--debug` option generates intermediate files (`dump-01.plg`, `dump-02.plg`, etc.) for troubleshooting.

---

## See Also

- [CF Conventions](http://cfconventions.org/) (for NetCDF-based mesh formats)
- [GMSH](https://gmsh.info/) (for `gmsh` and `gmsh_ww` formats)
- [FVCOM](https://fvcom.smast.umassd.edu/) (for `fvcom` format)
- [SCHISM](https://schism.water.tamu.edu/) (for `schism` and `schism-netcdf` formats)
- [TELEMAC](https://www.opentelemac.org/) (for `telemac_ascii`, `telemac_binary`, and `telemac_swapped` formats)