# gridit-surfref v3.2.3

**Mercurial revision 5770:c90c3015e72d | 2026-05-22**

---

## Description

`gridit-surfref` is a tool that **converts unstructured data files to structured grid formats**. It is designed to process input files (e.g., `.s2r`, `.s2c`, `.v2r`, `.v2c`) and generate structured outputs in various formats such as ASCII, BMG, GRD, or NetCDF.

---

## Usage

```bash
gridit-surfref input [OPTIONS] file
```

---

## Options


| Option                                | Description                                                                                       |
| ------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `-h`, `--help`                        | Display help and exit.                                                                            |
| `-scale <factor>`                     | Multiply the values by a **scale factor** (e.g., `-scale 2.5`).                                   |
| `-g <grid_file> <var1> [var2] [var3]` | Specify a **grid file** followed by up to 3 gridded variable names for elevation, `u`, and `v`.   |
| `-n <notebook_file>`                  | Use a **notebook file** to build the grid.                                                        |
| `-m <mesh_file>`                      | Specify a **mesh file** (required).                                                               |
| `-z <zone>`                           | Specify a **zone name** or **global resolution** for grid generation.                             |
| `-o <prefix>`                         | Set the **output rootname prefix** (default: `generic`).                                          |
| `-f <format>`                         | Specify the **input format** (default: `ascii`). If set to `netcdf`, discretization is mandatory. |
| `-s <fill_value>`                     | Set the **fill value** for masked nodes (default: `999.9`).                                       |
| `-c`                                  | Create an **empty output NetCDF file**.                                                           |


---

## Examples

### **Basic Conversion (Default ASCII Output)**

Convert an unstructured `.s2r` file to ASCII format:

```bash
gridit-surfref input.s2r -m mesh_file.nc
```

### **Convert to NetCDF with Custom Prefix**

Convert an unstructured file to NetCDF with a custom output prefix:

```bash
gridit-surfref input.s2r -m mesh_file.nc -f netcdf -o output_prefix
```

### **Apply Scale Factor**

Multiply values by a scale factor of `2.0`:

```bash
gridit-surfref input.s2r -m mesh_file.nc -scale 2.0
```

### **Use a Notebook File for Grid Definition**

Build the grid using a notebook file:

```bash
gridit-surfref input.s2r -m mesh_file.nc -n notebook.txt
```

### **Specify a Zone for Grid Generation**

Generate a grid for a specific zone:

```bash
gridit-surfref input.s2r -m mesh_file.nc -z "Europe"
```

### **Create an Empty NetCDF File**

Create an empty NetCDF file with the specified grid:

```bash
gridit-surfref input.s2r -m mesh_file.nc -c
```

### **Convert to BMG Format**

Convert an unstructured file to BMG format:

```bash
gridit-surfref input.s2r -m mesh_file.nc -f bmg
```

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

Convert a vector data file (`.v2r`) to NetCDF:

```bash
gridit-surfref input.v2r -m mesh_file.nc -f netcdf -o vector_output
```

### **Use a Grid File with Variables**

Specify a grid file with elevation, `u`, and `v` variables:

```bash
gridit-surfref input.s2r -g grid_file.nc elevation u v -m mesh_file.nc
```

---

## Environment Variables

`gridit-surfref` does not rely on specific environment variables for its core functionality. However, if used in a script or workflow, standard environment variables (e.g., `PATH`) may apply.

---

## Notes

1. **Input File Requirements:**
  - The input file must be in a supported format (e.g., `.s2r`, `.s2c`, `.v2r`, `.v2c`).
  - A **mesh file** (`-m`) is **required** for processing.
2. **Output Formats:**
  - Supported output formats: `ascii`, `bmg`, `grd`, `netcdf`.
  - If `-f netcdf` is used, discretization is **mandatory**.
3. **Fill Values:**
  - The default fill value for masked nodes is `999.9`. Use `-s` to change it.
4. **Notebook Files:**
  - Notebook files (specified with `-n`) define the grid structure and are useful for custom grid configurations.
5. **Zone Specification:**
  - The `-z` option allows specifying a predefined zone or global resolution for grid generation.
6. **Empty NetCDF Files:**
  - The `-c` option creates an empty NetCDF file with the specified grid but does not populate it with data.

---

## See Also

- [NetCDF Documentation](https://www.unidata.ucar.edu/software/netcdf/)
- [BMG Format Specification](https://www.ngdc.noaa.gov/mgg/gdas/gd_designagrid.html)
- [GRD Format Documentation](https://www.generic-mapping-tools.org/)