GRDREFORMAT(1) Generic Mapping Tools GRDREFORMAT(1)NAMEgrdreformat - Converting between different grid file formats.
SYNOPSISgrdreformat ingrdfile[=id[/scale/offset[/NaNvalue]]] outgrd‐
file[=id[/scale/offset[/NaNvalue]]] [ -N ] [ -Rwest/east/south/north[r]
] [ -f[i|o]colinfo ] [ -V ]
DESCRIPTIONgrdreformat 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.
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 scale and offset. These
options will scale the data and then offset them with the speci‐
fied amounts after reading.
If scale and offset are supplied you may also 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.)
outgrdfile
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 scale and offset. These
options are particularly practical when storing the data as
integers, 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).
If scale and offset are supplied you may also 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.)
OPTIONS-N Suppress the writing of the GMT header structure. This is use‐
ful 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.
-R xmin, xmax, ymin, and ymax specify the Region of interest. For
geographic regions, these limits correspond to west, east,
south, and north and you may specify them in decimal degrees or
in [+-]dd:mm[:ss.xxx][W|E|S|N] format. Append r if lower left
and upper right map coordinates are given instead of w/e/s/n.
The two shorthands -Rg and -Rd stand for global domain (0/360
and -180/+180 in longitude respectively, with -90/+90 in lati‐
tude). Alternatively, specify the name of an existing grid file
and the -R settings (and grid spacing, if applicable) are copied
from the grid. For calendar time coordinates you may either
give (a) relative time (relative to the selected TIME_EPOCH and
in the selected TIME_UNIT; append t to -JX|x), or (b) absolute
time of the form [date]T[clock] (append T to -JX|x). At least
one of date and clock must be present; the T is always required.
The date string must be of the form [-]yyyy[-mm[-dd]] (Gregorian
calendar) or yyyy[-Www[-d]] (ISO week calendar), while the clock
string must be of the form hh:mm:ss[.xxx]. The use of delim‐
iters and their type and positions must be exactly as indicated
(however, input, output and plot formats are customizable; see
gmtdefaults).
-V Selects verbose mode, which will send progress reports to stderr
[Default runs "silently"].
-f Special formatting of input and/or output columns (time or geo‐
graphical data). Specify i or o to make this apply only to
input or output [Default applies to both]. Give one or more
columns (or column ranges) separated by commas. Append T (abso‐
lute calendar time), t (relative time in chosen TIME_UNIT since
TIME_EPOCH), x (longitude), y (latitude), or f (floating point)
to each column or column range item. Shorthand -f[i|o]g means
-f[i|o]0x,1y (geographic coordinates).
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, grdreformat and other GMT programs will automati‐
cally recognize any type of netCDF grid file. These can be in either
COARDS-compliant or pre-4.1 format, and contain floating-point or inte‐
ger data. To read other types of grid files, append the =id suffix to
the filename ingrdfile.
id GMT 3 netCDF legacy formats
cb GMT netCDF format (byte) (deprecated)
cs GMT netCDF format (short) (deprecated)
ci GMT netCDF format (int) (deprecated)
cf GMT netCDF format (float) (deprecated)
cd GMT netCDF format (double) (deprecated)
id GMT native binary formats
bm GMT native, C-binary format (bit-mask)
bb GMT native, C-binary format (byte)
bs GMT native, C-binary format (short)
bi GMT native, C-binary format (int)
bf GMT native, C-binary format (float)
bd GMT native, C-binary format (double)
id GMT 4 netCDF standard
nb GMT netCDF format (byte) (COARDS-compliant)
ns GMT netCDF format (short) (COARDS-compliant)
ni GMT netCDF format (int) (COARDS-compliant)
nf GMT netCDF format (float) (COARDS-compliant) [DEFAULT]
nd GMT netCDF format (double) (COARDS-compliant)
id Misc formats
rb SUN rasterfile format (8-bit standard)
rf GEODAS grid format GRD98 (NGDC)
sf Golden Software Surfer format 6 (float)
sd Golden Software Surfer format 7 (double, read-only)
af Atlantic Geoscience Center format AGC (float)
gd Import through GDAL (convert to float) -- NON-STANDARD
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 Appendix B.
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(level).
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 grdheader 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 Appendix B.
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
To extract the second layer from a 3-dimensional grid named temp from a
COARDS-compliant netCDF file climate.grd:
grdreformat climate.grd?temp[1] temp.grd -V
To create a 4-byte native floating point grid from the COARDS-compliant
netCDF file data.grd:
grdreformat data.grd ras_data.b4=bf -V
To make a 2-byte short integer file, scale it by 10, subtract 32000,
setting NaNs to -9999, do
grdreformat values.grd shorts.i2=bs/10/-32000/-9999 -V
To create a Sun standard 8-bit rasterfile for a subset of the data file
image.grd, assuming the range in image.grd is 0-1 and we need 0-255,
run
grdreformat image.grd -R-60/-40/-40/-30 image.ras8=rb/255/0 -V
To convert etopo2.grd to etopo2.i2 that can be used by grdraster, try
grdreformat etopo2.grd etopo2.i2=bs -N -V
SEE ALSOGMT(1), grdmath(1)GMT 4.5.14 1 Nov 2015 GRDREFORMAT(1)
