# mesh-assembly v3.2.3

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

---

## Description

`mesh-assembly` is a tool designed to **assemble two meshes** into a single output mesh. For optimal performance, it is recommended to **place the smaller mesh first** in the command line.

---

## Usage

```bash
mesh-assembly small.nei big.nei [OPTIONS]
```

---

## Options


| Option          | Description                                                                                                                   |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `-h`, `--help`  | Display this help message and exit.                                                                                           |
| `--debug`       | Enable extra debugging output and save intermediate files (e.g., `merged.nei`).                                               |
| `--limited`     | Limit the merge to the **first boundary** in the first mesh.                                                                  |
| `-d <distance>` | Maximum merging distance in **kilometers** (default: `0.1`).                                                                  |
| `-o <path>`     | Path to the output assembled mesh file (default: `mesh-assembly.nei`).                                                        |
| `-p <path>`     | Path to the **separating polygon** file. Required when using `--overlapped`.                                                  |
| `--raw`         | Only **concatenate** the meshes without merging nodes.                                                                        |
| `--overlapped`  | Merge the **exterior of the first mesh** with the **interior of the second mesh**, respecting the polygon provided with `-p`. |
| `--no-reshape`  | Disable reshaping of the final mesh.                                                                                          |


---

## Examples

### **Basic Mesh Assembly**

Assemble two meshes with default settings:

```bash
mesh-assembly small.nei big.nei
```

### **Custom Output File**

Specify a custom output file:

```bash
mesh-assembly small.nei big.nei -o custom_output.nei
```

### **Limit Merge to First Boundary**

Limit the merge to the first boundary in the first mesh:

```bash
mesh-assembly small.nei big.nei --limited
```

### **Custom Merging Distance**

Set a custom merging distance of `0.5 km`:

```bash
mesh-assembly small.nei big.nei -d 0.5
```

### **Concatenate Meshes Without Merging**

Concatenate meshes without merging nodes:

```bash
mesh-assembly small.nei big.nei --raw
```

### **Overlapped Merge with Polygon**

Merge the exterior of the first mesh with the interior of the second mesh, using a separating polygon:

```bash
mesh-assembly small.nei big.nei --overlapped -p polygon.txt
```

### **Disable Reshaping**

Disable reshaping of the final mesh:

```bash
mesh-assembly small.nei big.nei --no-reshape
```

### **Debug Mode**

Enable debug mode to save intermediate files:

```bash
mesh-assembly small.nei big.nei --debug
```

### **Combining Options**

Combine multiple options for advanced use cases:

```bash
mesh-assembly small.nei big.nei --overlapped -p polygon.txt -d 0.2 -o merged_output.nei --debug
```

---

## Environment Variables

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

---

## Notes

1. **Input Meshes:**
  - Exactly **two meshes** must be provided as input.
  - The first mesh should ideally be the **smaller** one for better performance.
2. **Output:**
  - If no output file is specified (`-o`), the default name `mesh-assembly.nei` is used.
  - Intermediate files (e.g., `merged.nei`) are saved only in `--debug` mode.
3. **Merging Behavior:**
  - By default, nodes within `0.1 km` are merged. Adjust this with `-d`.
  - Use `--raw` to skip node merging entirely.
  - Use `--overlapped` for specialized merging based on a separating polygon.
4. **Reshaping:**
  - The final mesh is reshaped by default. Use `--no-reshape` to disable this step.
5. **Debugging:**
  - `--debug` provides additional output and saves intermediate files for troubleshooting.

---

## See Also

- [TRIGRID Mesh Format](https://www.comodo-ocean.fr/) (for mesh file specifications)
- Related tools: `fe_readmesh`, `fe_list`, `fe_edgetable`, `fe_merge`, `fe_reshapeall`