grdconvert

Convert between different grid formats

Synopsis

gmt grdconvert ingrid -Goutgrid [ -Cb|c|n|p ] [ -N ] [ -Rregion ] [ -V[level] ] [ -Z[+sfactor][+ooffset] ] [ -fflags ] [ --PAR=value ]

Note: No space is allowed between the option flag and the associated arguments.

Description

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.

Required Arguments

ingrid[=ID|?varname][+bband][+ddivisor][+ninvalid][+ooffset][+sscale]

2-D gridded data set to be read. Optionally, append =ID for reading a specific file format [Default is =nf] or ?varname for a specific netCDF variable [Default is the first 2-D grid found by GMT] (See full description). The following modifiers are supported:

  • +b - Select a band (for images only) [Default is 0].

  • +d - Divide data values by the given divisor [Default is 1].

  • +n - Replace data values matching invalid with NaN.

  • +o - Offset data values by the given offset [Default is 0].

  • +s - Scale data values by the given scale [Default is 1].

Note: Any offset is added after any scaling.

-Goutgrid[=ID][+ddivisor][+ninvalid][+ooffset|a][+sscale|a][:driver[dataType][+coptions]]

Give the name of the output converted grid file. Optionally, append =ID for writing a specific file format (See full description). The following modifiers are supported:

  • +d - Divide data values by given divisor [Default is 1].

  • +n - Replace data values matching invalid with a NaN.

  • +o - Offset data values by the given offset, or append a for automatic range offset to preserve precision for integer grids [Default is 0].

  • +s - Scale data values by the given scale, or append a for automatic scaling to preserve precision for integer grids [Default is 1].

Note: Any offset is added before any scaling. +sa also sets +oa (unless overridden). To write specific formats via GDAL, use =gd and supply driver (and optionally dataType) and/or one or more concatenated GDAL -co options using +c. See the “Writing grids and images” cookbook section for more details.

Optional Arguments

-Cb|c|n|p

Normally, output grids store the current module’s command-line history. Use -C to specify what the output grid’s command history should be: Append directive b to write both the previous and the current module’s command histories, c to only write the current module’s command history, n to save no history whatsoever [Default], or select p to instead save only the previous command history.

-N

Suppress the writing of the GMT header structure. This is useful when you want to write a native grid to be used by external tools that do not recognize GMT headers. It only applies to native grids and is ignored for netCDF output.

-Rxmin/xmax/ymin/ymax[+r][+uunit]

Specify the region of interest. (See full description) (See cookbook information).

-V[level]

Select verbosity level [w]. (See full description) (See cookbook information).

-Z[+sfactor][+ooffset]

Use to subtract offset from the data and then multiply the results by factor before writing the output file [1/0]. Note: This changes the values in the grid. In contrast, while options to supply a scale and offset via the +s and +o modifiers in a file name also adjust the data accordingly they also set the scale and offset in the metadata, so upon reading the new file you recover the original range. Typically, those options are used to enable packing of data via the use of an integer format (see table).

-f[i|o]colinfo (more …)

Specify data types of input and/or output columns.

-^ or just -

Print a short message about the syntax of the command, then exit (Note: on Windows just use -).

-+ or just +

Print an extensive usage (help) message, including the explanation of any module-specific option (but not the GMT common options), then exit.

-? or no arguments

Print a complete usage (help) message, including the explanation of all options, then exit.

--PAR=value

Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.

Format Identifier

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 outgrid.

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 ingrid.

ID

Explanation

nb

GMT netCDF format (8-bit integer, COARDS, CF-1.5)

ns

GMT netCDF format (16-bit integer, COARDS, CF-1.5)

ni

GMT netCDF format (32-bit integer, COARDS, CF-1.5)

nf

GMT netCDF format (32-bit float, COARDS, CF-1.5)

nd

GMT netCDF format (64-bit float, COARDS, CF-1.5)

cb

GMT netCDF format (8-bit integer, deprecated)

cs

GMT netCDF format (16-bit integer, deprecated)

ci

GMT netCDF format (32-bit integer, deprecated)

cf

GMT netCDF format (32-bit float, deprecated)

cd

GMT netCDF format (64-bit float, deprecated)

bm

GMT native, C-binary format (bit-mask)

bb

GMT native, C-binary format (8-bit integer)

bs

GMT native, C-binary format (16-bit integer)

bi

GMT native, C-binary format (32-bit integer)

bf

GMT native, C-binary format (32-bit float)

bd

GMT native, C-binary format (64-bit float)

rb

SUN rasterfile format (8-bit standard)

rf

GEODAS grid format GRD98 (NCEI)

sf

Golden Software Surfer format 6 (32-bit float)

sd

Golden Software Surfer format 7 (64-bit float, read-only)

af

Atlantic Geoscience Center format AGC (32-bit float)

ei

ESRI Arc/Info ASCII Grid Interchange format (ASCII integer)

ef

ESRI Arc/Info ASCII Grid Interchange format (ASCII float)

gd

Import/export through GDAL

GMT Standard Netcdf Files

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 GMT File Formats and Writing grids and images.

Multi-variable grid files

By default, GMT programs will read the first 2-dimensional grid contained in a COARDS-compliant netCDF file. Alternatively, use ingrid?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: ingrid?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.

Native Binary Files

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 GMT File Formats.

Grid Values Precision

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.

Examples

Note: Below are some examples of valid syntax for this module. The examples that use remote files (file names starting with @) can be cut and pasted into your terminal for testing. Other commands requiring input files are just dummy examples of the types of uses that are common but cannot be run verbatim as written.

To extract the second layer from a 3-dimensional grid named temp from a COARDS-compliant netCDF file climate.nc:

gmt grdconvert climate.nc?temp[1] -Gtemp.nc -V

To create a 4-byte native floating point grid from the COARDS-compliant remote netCDF file AFR.nc:

gmt grdconvert @AFR.nc -GAFR_bin.b4=bf -V

To make a 2-byte short integer file, scale it by 10, subtract 32000, setting NaNs to -9999, do

gmt grdconvert values.nc -Gshorts.i2=bs+s10+o-32000+n-9999 -V

To create a Sun standard 8-bit rasterfile for a subset of the data file image.nc, assuming the range in image.nc is 0-1 and we need 0-255, run

gmt grdconvert image.nc -R-60/-40/-40/-30 -Gimage.ras8=rb+s255 -V

See Also

gmt.conf, gmt, grdmath