grdconvert reads a grid file in one format and writes it out using another format. As an option the user may select a subset of the data to be written and to specify scaling, translation, and NaN-value.

The grid file to be read. Append format =id code if not a standard COARDS-compliant netCDF grid file. If =id is set (see below), you may optionally append any of +sscale, +ooffset, and +ninvalid. The first two options will scale the data and then offset them with the specified amounts after reading while the latter lets you supply a value that represents an invalid grid entry, i.e., ‘Not-a-Number’ (for floating-point grids this is unnecessary since the IEEE NaN is used; however integers need a value which means no data available). When id=gd, the file will be read using the GDAL library, which will take care to detect the format of the file being read. This mechanism is actually used automatically when the file format is not one of those that GMT recognize. However, sometimes the guessing may fail, so adding id=gd forces a read via GDAL. See Section grid-file-format of the GMT Technical Reference and Cookbook for more information.

The grid file to be written. Append format =id code if not a standard COARDS-compliant netCDF grid file. If =id is set (see below), you may optionally append any of +sscale, +ooffset, and +ninvalid. These modifiers are particularly practical when storing the data as integers, by first removing an offset and then scaling down the values. Since the scale and offset are applied in reverse order when reading, this does not affect the data values (except for round-offs). The +n modifier let you append a value that represents ‘Not-a-Number’ (for floating-point grids this is unnecessary since the IEEE NaN is used; however integers need a value which means no data available). You may specify +sa for auto-adjusting the scale and/or offset of packed integer grids (=id+sa is a shorthand for =id+sa+oa). When id=gd, the file will be saved using the GDAL library. Append the format :driver and optionally the output datatype. The driver names are those used by GDAL itself (e.g., netCDF, GTiFF, etc.), and the data type is one of u8|u16|i16|u32|i32|float32, where ‘i’ and ‘u’ denote signed and unsigned integers respectively. The default type is float32. Note also that both driver names and data types are case insensitive. See Section grid-file-format of the GMT Technical Reference and Cookbook for more information.

Consider setting IO_NC4_DEFLATION_LEVEL to reduce file size and to further increase read/write performance. Especially when working with subsets of global grids, masks, and grids with repeating grid values, the improvement is usually significant.

By default, grids will be written as floating point data stored in binary files using the netCDF format and meta-data structure. This format is conform the COARDS conventions. GMT versions prior to 4.1 produced netCDF files that did not conform to these conventions. Although these files are still supported, their use is deprecated. To write other than floating point COARDS-compliant netCDF files, append the =id suffix to the filename outgrdfile.

When reading files, grdconvert and other GMT programs will try to automatically recognize the type of the input grid file. If this fails you may append the =id suffix to the filename ingrdfile.

The standard format used for grdfiles is based on netCDF and conforms to the COARDS conventions. Files written in this format can be read by numerous third-party programs and are platform-independent. Some disk-space can be saved by storing the data as bytes or shorts in stead of integers. Use the scale and offset parameters to make this work without loss of data range or significance. For more details, see App-file-formats.

Multi-variable grid files

By default, GMT programs will read the first 2-dimensional grid contained in a COARDS-compliant netCDF file. Alternatively, use ingrdfile?varname (ahead of any optional suffix =id) to specify the requested variable varname. Since ? has special meaning as a wildcard, escape this meaning by placing the full filename and suffix between quotes.

Multi-dimensional grids

To extract one layer or level from a 3-dimensional grid stored in a COARDS-compliant netCDF file, append both the name of the variable and the index associated with the layer (starting at zero) in the form: ingrdfile?varname[layer]. Alternatively, specify the value associated with that layer using parentheses in stead of brackets: ingridfile?varname(layer).

In a similar way layers can be extracted from 4- or even 5-dimensional grids. For example, if a grid has the dimensions (parameter, time, depth, latitude, longitude), a map can be selected by using: ingridfile?varname(parameter,time,depth).

Since question marks, brackets and parentheses have special meanings on the command line, escape these meanings by placing the full filename and suffix between quotes.

For binary native GMT files the size of the GMT grid header block is hsize = 892 bytes, and the total size of the file is hsize + nx * ny * item_size, where item_size is the size in bytes of each element (1, 2, 4). Bit grids are stored using 4-byte integers, each holding 32 bits, so for these files the size equation is modified by using ceil (nx / 32) * 4 instead of nx. Note that these files are platform-dependent. Files written on Little Endian machines (e.g., PCs) can not be read on Big Endian machines (e.g., most workstations). Also note that it is not possible for GMT to determine uniquely if a 4-byte grid is float or int; in such cases it is best to use the =ID mechanism to specify the file format. In all cases a native grid is considered to be signed (i.e., there are no provision for unsigned short ints or unsigned bytes). For header and grid details, see App-file-formats.

Regardless of the precision of the input data, GMT programs that create grid files will internally hold the grids in 4-byte floating point arrays. This is done to conserve memory and furthermore most if not all real data can be stored using 4-byte floating point values. Data with higher precision (i.e., double precision values) will lose that precision once GMT operates on the grid or writes out new grids. To limit loss of precision when processing data you should always consider normalizing the data prior to processing.