# mesh2mesh v3.2.3

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

---

## Description

`mesh2mesh` performs **nearest-neighbor interpolation** of simulation outputs onto another **finite element (FE) grid**. It is designed to remap data from one mesh to another, preserving the structure and values of the original simulation.

---

## Usage

```bash
mesh2mesh [OPTIONS] file
```

---

## Options


| Option         | Description                                    |
| -------------- | ---------------------------------------------- |
| `-h`, `--help` | Display this help message and exit.            |
| `-i <file>`    | Input mesh grid file. **Required.**            |
| `-o <file>`    | Output mesh grid file. **Required.**           |
| `-s <value>`   | Value of the mask to apply (default: `999.9`). |


> **Note:** The `-f` option (format of the simulation file) is **deprecated**. The format is now **automatically inferred** from the file suffix (e.g., `.s2r`, `.s2c`, `.v2r`, `.v2c`).

---

## Examples

### **Basic Interpolation for Scalar Data (S2R Format)**

Interpolate scalar data from `input.s2r` to a new mesh:

```bash
mesh2mesh -i input_mesh.nc -o output_mesh.nc -s 999.9 input.s2r
```

### **Interpolate Vector Data (V2R Format)**

Interpolate vector data (e.g., velocity components) from `input.v2r`:

```bash
mesh2mesh -i input_mesh.nc -o output_mesh.nc input.v2r
```

### **Interpolate Complex Scalar Data (S2C Format)**

Interpolate complex scalar data (e.g., harmonic constants for tidal elevation):

```bash
mesh2mesh -i input_mesh.nc -o output_mesh.nc input.s2c
```

### **Interpolate Complex Vector Data (V2C Format)**

Interpolate complex vector data (e.g., harmonic constants for tidal currents):

```bash
mesh2mesh -i input_mesh.nc -o output_mesh.nc input.v2c
```

### **Custom Mask Value**

Use a custom mask value (e.g., `-999.0`) for invalid or missing data:

```bash
mesh2mesh -i input_mesh.nc -o output_mesh.nc -s -999.0 input.s2r
```

---

## Environment Variables

`mesh2mesh` does not rely on specific environment variables. However, ensure that:

- Input and output mesh files are **accessible** and in the correct format.
- The simulation file suffix (e.g., `.s2r`, `.v2c`) matches the expected data type.

---

## Notes

1. **Input File Formats:**
  - The tool **automatically detects** the format of the simulation file based on its suffix:
    - `.s2r`: Scalar real data (e.g., sea surface height).
    - `.s2c`: Scalar complex data (e.g., harmonic constants for elevation).
    - `.v2r`: Vector real data (e.g., velocity components).
    - `.v2c`: Vector complex data (e.g., harmonic constants for currents).
2. **Mask Handling:**
  - The `-s` option sets the value used for **masked or invalid data** in the output. Default is `999.9`.
  - If a point in the output mesh does not correspond to any valid point in the input mesh, it is assigned the mask value.
3. **Interpolation Method:**
  - Uses **nearest-neighbor interpolation** for simplicity and efficiency.
  - For points that fall within an element of the input mesh, **linear interpolation** (LGP1) is applied.
4. **Output Files:**
  - Output files are saved with a `.new.<suffix>` extension (e.g., `input.new.s2r`).
  - Metadata (comments) are preserved in the output file, including the original filename and a copyright notice.
5. **Error Handling:**
  - The tool exits with an error if:
    - Input or output mesh files are not specified.
    - The simulation file format is not recognized.
    - Interpolation fails for any reason.

---

## See Also

- [POC/Noveltis Tools](https://www.poc-ocean.fr/) (for related tools and documentation)
- [NetCDF Format](https://www.unidata.ucar.edu/software/netcdf/) (for input/output file formats)