1GRDREFORMAT(1) Generic Mapping Tools GRDREFORMAT(1)
2
6 grdreformat - Converting between different grid file formats.
7
9 grdreformat ingrdfile[=id[/scale/offset[/NaNvalue]]] outgrd‐
10 file[=id[/scale/offset[/NaNvalue]]] [ -N ] [ -Rwest/east/south/north[r]
11 ] [ -f[i|o]colinfo ] [ -V ]
12
14 grdreformat reads a grid file in one format and writes it out using
15 another format. As an option the user may select a subset of the data
16 to be written and to specify scaling, translation, and NaN-value.
17 ingrdfile
19 The grid file to be read. Append format =id code if not a stan‐
20 dard COARDS-compliant netCDF grid file. If =id is set (see
21 below), you may optionally append scale and offset. These
22 options will scale the data and then offset them with the speci‐
23 fied amounts after reading.
24 If scale and offset are supplied you may also append a value
25 that represents 'Not-a-Number' (for floating-point grids this is
26 unnecessary since the IEEE NaN is used; however integers need a
27 value which means no data available.)
28 outgrdfile
30 The grid file to be written. Append format =id code if not a
31 standard COARDS-compliant netCDF grid file. If =id is set (see
32 below), you may optionally append scale and offset. These
33 options are particularly practical when storing the data as
34 integers, first removing an offset and then scaling down the
35 values. Since the scale and offset are applied in reverse order
36 when reading, this does not affect the data values (except for
37 round-offs).
38 If scale and offset are supplied you may also append a value
39 that represents 'Not-a-Number' (for floating-point grids this is
40 unnecessary since the IEEE NaN is used; however integers need a
41 value which means no data available.)
42
44 -N Suppress the writing of the GMT header structure. This is use‐
45 ful when you want to write a native grid to be used by
46 grdraster. It only applies to native grids and is ignored for
47 netCDF output.
48 -R xmin, xmax, ymin, and ymax specify the Region of interest. For
50 geographic regions, these limits correspond to west, east,
51 south, and north and you may specify them in decimal degrees or
52 in [+-]dd:mm[:ss.xxx][W|E|S|N] format. Append r if lower left
53 and upper right map coordinates are given instead of w/e/s/n.
54 The two shorthands -Rg and -Rd stand for global domain (0/360
55 and -180/+180 in longitude respectively, with -90/+90 in lati‐
56 tude). For calendar time coordinates you may either give (a)
57 relative time (relative to the selected TIME_EPOCH and in the
58 selected TIME_UNIT; append t to -JX|x), or (b) absolute time of
59 the form [date]T[clock] (append T to -JX|x). At least one of
60 date and clock must be present; the T is always required. The
61 date string must be of the form [-]yyyy[-mm[-dd]] (Gregorian
62 calendar) or yyyy[-Www[-d]] (ISO week calendar), while the clock
63 string must be of the form hh:mm:ss[.xxx]. The use of delim‐
64 iters and their type and positions must be exactly as indicated
65 (however, input, output and plot formats are customizable; see
66 gmtdefaults).
67 -V Selects verbose mode, which will send progress reports to stderr
69 [Default runs "silently"].
70 -f Special formatting of input and/or output columns (time or geo‐
72 graphical data). Specify i or o to make this apply only to
73 input or output [Default applies to both]. Give one or more
74 columns (or column ranges) separated by commas. Append T (abso‐
75 lute calendar time), t (relative time in chosen TIME_UNIT since
76 TIME_EPOCH), x (longitude), y (latitude), or f (floating point)
77 to each column or column range item. Shorthand -f[i|o]g means
78 -f[i|o]0x,1y (geographic coordinates).
79
81 By default, grids will be written as floating point data stored in
82 binary files using the netCDF format and meta-data structure. This for‐
83 mat is conform the COARDS conventions. GMT versions prior to 4.1 pro‐
84 duced netCDF files that did not conform to these conventions. Although
85 these files are still supported, their use is depreciated. To write
86 other than floating point COARDS-compliant netCDF files, append the =id
87 suffix to the filename outgrdfile.
88 When reading files, grdreformat and other GMT programs will automati‐
89 cally recognize any type of netCDF grid file. These can be in either
90 COARDS-compliant or pre-4.1 format, and contain floating-point or inte‐
91 ger data. To read other types of grid files, append the =id suffix to
92 the filename ingrdfile.
93 id GMT 4 netCDF standard formats
95 nb GMT netCDF format (byte) (COARDS-compliant)
96 ns GMT netCDF format (short) (COARDS-compliant)
97 ni GMT netCDF format (integer) (COARDS-compliant)
98 nf GMT netCDF format (float) (COARDS-compliant)
99 nd GMT netCDF format (double) (COARDS-compliant)
100 id GMT 3 netCDF legacy formats
102 cb GMT netCDF format (byte) (depreciated)
103 cs GMT netCDF format (short) (depreciated)
104 ci GMT netCDF format (integer) (depreciated)
105 cf GMT netCDF format (float) (depreciated)
106 cd GMT netCDF format (double) (depreciated)
107 id GMT native binary formats
109 bm GMT native, C-binary format (bit-mask)
110 bb GMT native, C-binary format (byte)
111 bs GMT native, C-binary format (short)
112 bi GMT native, C-binary format (integer)
113 bf GMT native, C-binary format (float)
114 bd GMT native, C-binary format (double)
115 id Miscellaneous formats
117 rb SUN rasterfile format (8-bit standard)
118 rf GEODAS grid format GRD98 (NGDC)
119 sf Golden Software Surfer format 6 (float)
120 sd Golden Software Surfer format 7 (double, read-only)
121 af Atlantic Geoscience Center format AGC (float)
122
124 The standard format used for gdrfiles is based on netCDF and conforms
125 to the COARDS conventions. Files written in this format can be read by
126 numerous third-party programs and are platform-independent. Some disk-
127 space can be saved by storing the data as bytes or shorts in stead of
128 integers. Use the scale and offset parameters to make this work without
129 loss of data range or significance. For more details, see Appendix B.
130 Multi-variable grid files
132 By default, GMT programs will read the first 2-dimensional grid con‐
133 tained in a COARDS-compliant netCDF file. Alternatively, use ingrd‐
134 file?varname (ahead of any optional suffix =id) to specify the
135 requested variable varname. Since ? has special meaning as a wildcard,
136 escape this meaning by placing the full filename and suffix between
137 quotes.
138 Multi-dimensional grids
140 To extract one layer or level from a 3-dimensional grid stored in a
141 COARDS-compliant netCDF file, append both the name of the variable and
142 the index associated with the layer (starting at zero) in the form:
143 ingrdfile?varname[layer]. Alternatively, specify the value associated
144 with that layer using parentheses in stead of brackets: ingridfile?var‐
145 name(level).
146 In a similar way layers can be extracted from 4- or even 5-dimensional
147 grids. For example, if a grid has the dimensions (parameter, time,
148 depth, latitude, longitude), a map can be selected by using: ingrid‐
149 file?varname(parameter,time,depth).
150 Since question marks, brackets and parentheses have special meanings on
151 the command line, escape these meanings by placing the full filename
152 and suffix between quotes.
153
155 For binary native GMT files the size of the GMT grdheader block is
156 hsize = 892 bytes, and the total size of the file is hsize + nx * ny *
157 item_size, where item_size is the size in bytes of each element (1, 2,
158 4). Bit grids are stored using 4-byte integers, each holding 32 bits,
159 so for these files the size equation is modified by using ceil (nx /
160 32) * 4 instead of nx. Note that these files are platform-dependent.
161 Files written on Little Endian machines (e.g. PCs) can not be read on
162 Big Endian machines (e.g. most workstations). Also note that it is not
163 possible for GMT to determine uniquely if a 4-byte grid is float or
164 int; in such cases it is best to use the =ID mechanism to specify the
165 file format. For header and grid details, see Appendix B.
166
168 Regardless of the precision of the input data, GMT programs that create
169 gridded files will internally hold the grids in 4-byte floating point
170 arrays. This is done to conserve memory and futhermore most if not all
171 real data can be stored using 4-byte floating point values. Data with
172 higher precision (i.e., double precision values) will lose that preci‐
173 sion once GMT operates on the grid or writes out new grids. To limit
174 loss of precision when processing data you should always consider nor‐
175 malizing the data prior to processing.
176
178 To extract the second layer from a 3-dimensional grid named temp from a
179 COARDS-compliant netCDF file climate.grd:
180 grdreformat climate.grd?temp[1] temp.grd -V
182 To create a 4-byte native floating point grid from the COARDS-compliant
184 netCDF file data.grd:
185 grdreformat data.grd ras_data.b4=bf -V
187 To make a 2-byte short integer file, scale it by 10, subtract 32000,
189 setting NaNs to -9999, do
190 grdreformat values.grd shorts.i2=bs/10/-32000/-9999 -V
192 To create a Sun standard 8-bit rasterfile for a subset of the data file
194 image.grd, assuming the range in image.grd is 0-1 and we need 0-255,
195 run
196 grdreformat image.grd -R-60/-40/-40/-30 image.ras8=rb/255/0 -V
198 To convert etopo2.grd to etopo2.i2 that can be used by grdraster, try
200 grdreformat etopo2.grd etopo2.i2=bs -N -V
202
204 GMT(1), grdmath(1)
205GMT 4.3.1 15 May 2008 GRDREFORMAT(1)