NAME¶
grdreformat - Converting between different grid file formats.
SYNOPSIS¶
grdreformat
ingrdfile[
=id[
/scale/offset[
/NaNvalue]]]
outgrdfile[
=id[
/scale/offset[
/NaNvalue]]] [
-N ] [
-Rwest/
east/
south/
north[
r] ] [
-f[
i|
o]
colinfo ] [
-V ]
DESCRIPTION¶
grdreformat 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 standard
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 specified 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 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.
- -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 latitude).
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 delimiters 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 geographical
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 (absolute 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).
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,
grdreformat and other
GMT programs will
automatically recognize any type of netCDF grid file. These can be in either
COARDS-compliant or pre-4.1 format, and contain floating-point or integer
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 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(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:
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 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 ALSO¶
GMT(1),
grdmath(1)