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¶

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:

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:

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:

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:

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

Specify a Zone for Grid Generation¶

Generate a grid for a specific zone:

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

Create an Empty NetCDF File¶

Create an empty NetCDF file with the specified grid:

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

Convert to BMG Format¶

Convert an unstructured file to BMG format:

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

Convert Vector Data (V2R Format)¶

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

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:

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¶

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.

Output Formats:

Supported output formats: ascii, bmg, grd, netcdf.
If -f netcdf is used, discretization is mandatory.

Fill Values:

The default fill value for masked nodes is 999.9. Use -s to change it.

Notebook Files:

Notebook files (specified with -n) define the grid structure and are useful for custom grid configurations.

Zone Specification:

The -z option allows specifying a predefined zone or global resolution for grid generation.

Empty NetCDF Files:

The -c option creates an empty NetCDF file with the specified grid but does not populate it with data.