# regular2node v3.2.3

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

---

## Description

`regular2node` is a tool for **interpolating data from a regular grid onto a finite element (FE) grid** (currently only supports ASCII output format). It is designed to transform structured grid data into unstructured grid data, such as those used in surface reference (surfref) models.

---

## Usage

```bash
regular2node [OPTIONS] file
```

---

## Options


| Option         | Description                                                                                                               |
| -------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `-h`, `--help` | Display this help message and exit.                                                                                       |
| `-iF <format>` | **Input format**: Specify the format of the input file. Supported formats: `xyz`, `ascii`, `grd`, `bmg`, `cst`, `netcdf`. |
| `-append`      | Append the interpolated variable to an existing output file.                                                              |
| `-n <file>`    | **Node file**: Path to the node file of the FE grid for interpolation.                                                    |
| `-m <file>`    | **Mesh file**: Path to the mesh file of the FE grid for interpolation.                                                    |
| `-s <value>`   | **Mask value**: Value used to represent masked data in the input file. Default: `999.9`.                                  |
| `-o <file>`    | **Output file**: Name of the output file. If not specified, the output filename is derived from the input filename.       |


---

## Examples

### **Basic Interpolation**

Interpolate data from a `xyz` file to a FE grid using a node file:

```bash
regular2node -iF xyz -n nodes.txt -o output.surfref input.xyz
```

### **Interpolate with a Mesh File**

Interpolate data using a mesh file instead of a node file:

```bash
regular2node -iF ascii -m mesh.txt -o output.surfref input.asc
```

### **Append to an Existing File**

Append the interpolated data to an existing output file:

```bash
regular2node -iF grd -n nodes.txt -append -o output.surfref input.grd
```

### **Custom Mask Value**

Specify a custom mask value (e.g., `-999`):

```bash
regular2node -iF netcdf -s -999 -n nodes.txt -o output.surfref input.nc
```

### **Interpolate BMG Format**

Interpolate data from a `bmg` file:

```bash
regular2node -iF bmg -n nodes.txt -o output.surfref input.bmg
```

### **Interpolate CST Format**

Interpolate data from a `cst` file:

```bash
regular2node -iF cst -m mesh.txt -o output.surfref input.cst
```

---

## Environment Variables

`regular2node` does not use any specific environment variables. However, ensure that your system has sufficient resources (memory, disk space) for large interpolations.

---

## Notes

1. **Input Formats**:
  - Supported input formats: `xyz`, `ascii`, `grd`, `bmg`, `cst`, `netcdf`.
  - The tool automatically detects the format if `-iF` is not specified (defaults to `xyz`).
2. **Output Formats**:
  - Currently, only **ASCII** output format is supported for the interpolated data.
3. **Mask Handling**:
  - The default mask value is `999.9`. Use `-s` to specify a different mask value.
  - Masked values in the input file will be preserved in the output.
4. **Node and Mesh Files**:
  - Either a **node file** (`-n`) or a **mesh file** (`-m`) must be provided for interpolation.
  - The node file should contain the coordinates of the FE grid nodes.
  - The mesh file should describe the connectivity of the FE grid.
5. **Performance**:
  - For large datasets, ensure that the input and output files are stored on a **fast storage device** (e.g., SSD) to optimize performance.
6. **Deprecated Options**:
  - The `-z` option (pre-set zone to limit the area) is **deprecated** and no longer supported.

---

## See Also

- [SurfRef FE Grid Format](https://www.comodo-ocean.fr/) (for node and mesh file specifications)
- [NetCDF Format](https://www.unidata.ucar.edu/software/netcdf/) (for input file specifications)