# gridit-cls v3.2.3

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

---

## Description

`gridit-cls` is a tool that **converts unstructured data to structured files**. It processes input files (such as mesh or notebook files) and generates structured grid outputs for further analysis or visualization.

---

## Usage

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

---

## Options


| Option                               | Description                                                                                                    |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `--help`, `-h`                       | Display help and exit.                                                                                         |
| `-g <gridfile> <var1> [var2] [var3]` | Path to the **grid file**, followed by up to 3 variable names for elevation, u, and v (empty-terminated list). |
| `-n <notebook>`                      | Path to the **notebook file**.                                                                                 |
| `-m <meshfile>`                      | Path to the **mesh file**.                                                                                     |
| `-z <zone>`                          | **Zone name** or **global resolution** for grid generation.                                                    |
| `-o <output>`                        | Root name for the **output files** (default: `generic`).                                                       |
| `-a <number>`                        | Suffix number for this trial.                                                                                  |
| `-s <value>`                         | Fill value for **masked nodes**.                                                                               |
| `-p <path>`                          | Path for **output files**.                                                                                     |


---

### Deprecated Options

> ⚠️ **These options are deprecated and may not be supported in future versions.**


| Option           | Description                  |
| ---------------- | ---------------------------- |
| `-d <depthfile>` | Path to the **depth file**.  |
| `-u <ugridfile>` | Path to the **u grid file**. |
| `-v <vgridfile>` | Path to the **v grid file**. |


---

## Examples

### **Basic Conversion Using a Mesh File**

Convert unstructured data to a structured grid using a mesh file:

```bash
gridit-cls input.nc -m mesh_file.nc -o output_root -p /path/to/output
```

### **Conversion Using a Grid File and Variables**

Convert using a grid file and specify variables for elevation, u, and v:

```bash
gridit-cls input.nc -g grid_file.nc elevation u v -o output_root
```

### **Conversion Using a Notebook File**

Convert using a notebook file:

```bash
gridit-cls input.nc -n notebook_file.txt -o output_root
```

### **Specify Zone and Output Path**

Convert data for a specific zone and save outputs to a custom path:

```bash
gridit-cls input.nc -z zone_name -p /custom/output/path -o my_output
```

### **Handle Masked Nodes**

Specify a fill value for masked nodes:

```bash
gridit-cls input.nc -m mesh_file.nc -s -9999 -o output_root
```

### **Trial Number Suffix**

Add a trial number suffix to the output:

```bash
gridit-cls input.nc -m mesh_file.nc -a 1 -o output_root
```

---

## Environment Variables

`gridit-cls` does not explicitly rely on environment variables for its core functionality. However, if it interacts with external libraries or tools (e.g., NetCDF, OpenMP), ensure that the relevant environment variables for those dependencies are set correctly.

---

## Notes

1. **Input Requirements**:
  - At least **one** of the following must be provided: `--zone`, `--gridfile`, `--notebook`, or `--meshfile`.
  - If `--meshfile` is not provided, the tool will **fail** with an error.
2. **Output Files**:
  - Output files are saved in the directory specified by `-p`. If not provided, the current directory is used.
  - The output root name (`-o`) is used as a prefix for generated files. If not specified, the default `generic` is used.
3. **Masked Nodes**:
  - Use `-s` to define a fill value for masked nodes (e.g., `-9999`).
4. **Deprecated Options**:
  - Avoid using `-d`, `-u`, and `-v` as they are deprecated and may be removed in future versions.
5. **Error Handling**:
  - If an error occurs (e.g., missing files, invalid inputs), the tool will display an error message and exit.

---

## See Also

- [NetCDF Documentation](https://www.unidata.ucar.edu/software/netcdf/)
- [Mesh File Formats](https://www.comodo-ocean.fr/)