grdconvert(1) GMT grdconvert(1)
NAME
grdconvert - Convert between different grid formats
SYNOPSIS
grdconvert ingrdfile[=id[+sscale][+ooffset][+ninvalid]]
-Goutgrdfile[=id[+sscale][+ooffset][+ninvalid]][:driver[/datatype]]] [
-N ] [ -Rregion ] [ -V[level] ] [ -fflags ]
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
ingrdfile
The grid file to be read. Append format =id code if not a stan-
dard 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., aNot-a-Numbera (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-for-
mat of the GMT Technical Reference and Cookbook for more infor-
mation.
-Goutgrdfile
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 aNot-a-Numbera (for float-
ing-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 aia and aua denote signed and
unsigned integers respectively. The default type is float32.
Note also that both driver names and data types are case insen-
sitive. See Section grid-file-format of the GMT Technical Ref-
erence 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.
OPTIONAL ARGUMENTS
-N Suppress the writing of the GMT header structure. This is useful
when you want to write a native grid to be used by grdraster. It
only applies to native grids and is ignored for netCDF output.
-Rxmin/xmax/ymin/ymax[+r][+uunit] (more a|)
Specify the region of interest.
-V[level] (more a|)
Select verbosity level [c].
-f[i|o]colinfo (more a|)
Specify data types of input and/or output columns.
-^ or just -
Print a short message about the syntax of the command, then
exits (NOTE: on Windows just use -).
-+ or just +
Print an extensive usage (help) message, including the explana-
tion of any module-specific option (but not the GMT common
options), then exits.
-? or no arguments
Print a complete usage (help) message, including the explanation
of all options, then exits.
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 for-
mat is conform the COARDS conventions. GMT versions prior to 4.1 pro-
duced 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 auto-
matically recognize the type of the input grid file. If this fails you
may append the =id suffix to the filename ingrdfile.
+---+----------------------------+
|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 for- |
| | mat (bit-mask) |
+---+----------------------------+
|bb | GMT native, C-binary for- |
| | mat (8-bit integer) |
+---+----------------------------+
|bs | GMT native, C-binary for- |
| | mat (16-bit integer) |
+---+----------------------------+
|bi | GMT native, C-binary for- |
| | mat (32-bit integer) |
+---+----------------------------+
|bf | GMT native, C-binary for- |
| | mat (32-bit float) |
+---+----------------------------+
|bd | GMT native, C-binary for- |
| | mat (64-bit float) |
+---+----------------------------+
|rb | SUN rasterfile format |
| | (8-bit standard) |
+---+----------------------------+
|rf | GEODAS grid format GRD98 |
| | (NGDC) |
+---+----------------------------+
|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
App-file-formats.
Multi-variable grid files
By default, GMT programs will read the first 2-dimensional grid con-
tained in a COARDS-compliant netCDF file. Alternatively, use ingrd-
file?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?var-
name(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: ingrid-
file?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 App-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 preci-
sion once GMT operates on the grid or writes out new grids. To limit
loss of precision when processing data you should always consider nor-
malizing the data prior to processing.
EXAMPLES
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
netCDF file data.nc:
gmt grdconvert data.nc -Gras_data.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
To convert etopo2.nc to etopo2.i2 that can be used by grdraster, try
gmt grdconvert etopo2.nc -Getopo2.i2=bs -N -V
SEE ALSO
gmt.conf(5), gmt(1), grdmath(1), grdraster(1)
COPYRIGHT
2017, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
5.4.2 Jun 24, 2017 grdconvert(1)
gmt5 5.4.2 - Generated Wed Jun 28 18:16:33 CDT 2017