1GRDCONVERT(1) GMT GRDCONVERT(1)
2
6 grdconvert - Convert between different grid formats
7
9 grdconvert ingrdfile[=id[+sscale][+ooffset][+ninvalid]]
10 -Goutgrdfile[=id[+sscale][+ooffset][+ninvalid]][:driver[/datatype]]] [
11 -N ] [ -Rregion ] [ -V[level] ] [ -fflags ]
12 Note: No space is allowed between the option flag and the associated
14 arguments.
15
17 grdconvert reads a grid file in one format and writes it out using
18 another format. As an option the user may select a subset of the data
19 to be written and to specify scaling, translation, and NaN-value.
20
22 ingrdfile
23 The grid file to be read. Append format =id code if not a stan‐
24 dard COARDS-compliant netCDF grid file. If =id is set (see
25 below), you may optionally append any of +sscale, +ooffset, and
26 +ninvalid. The first two options will scale the data and then
27 offset them with the specified amounts after reading while the
28 latter lets you supply a value that represents an invalid grid
29 entry, i.e., 'Not-a-Number' (for floating-point grids this is
30 unnecessary since the IEEE NaN is used; however integers need a
31 value which means no data available). When id=gd, the file will
32 be read using the GDAL library, which will take care to detect
33 the format of the file being read. This mechanism is actually
34 used automatically when the file format is not one of those that
35 GMT recognize. However, sometimes the guessing may fail, so
36 adding id=gd forces a read via GDAL. See Section grid-file-for‐
37 mat of the GMT Technical Reference and Cookbook for more infor‐
38 mation.
39 -Goutgrdfile
41 The grid file to be written. Append format =id code if not a
42 standard COARDS-compliant netCDF grid file. If =id is set (see
43 below), you may optionally append any of +sscale, +ooffset, and
44 +ninvalid. These modifiers are particularly practical when
45 storing the data as integers, by first removing an offset and
46 then scaling down the values. Since the scale and offset are
47 applied in reverse order when reading, this does not affect the
48 data values (except for round-offs). The +n modifier let you
49 append a value that represents 'Not-a-Number' (for float‐
50 ing-point grids this is unnecessary since the IEEE NaN is used;
51 however integers need a value which means no data available).
52 You may specify +sa for auto-adjusting the scale and/or offset
53 of packed integer grids (=id+sa is a shorthand for =id+sa+oa).
54 When id=gd, the file will be saved using the GDAL library.
55 Append the format :driver and optionally the output datatype.
56 The driver names are those used by GDAL itself (e.g., netCDF,
57 GTiFF, etc.), and the data type is one of
58 u8|u16|i16|u32|i32|float32, where 'i' and 'u' denote signed and
59 unsigned integers respectively. The default type is float32.
60 Note also that both driver names and data types are case insen‐
61 sitive. See Section grid-file-format of the GMT Technical Ref‐
62 erence and Cookbook for more information.
63 Consider setting IO_NC4_DEFLATION_LEVEL to reduce file size and
65 to further increase read/write performance. Especially when
66 working with subsets of global grids, masks, and grids with
67 repeating grid values, the improvement is usually significant.
68
70 -N Suppress the writing of the GMT header structure. This is useful
71 when you want to write a native grid to be used by grdraster. It
72 only applies to native grids and is ignored for netCDF output.
73 -Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
75 Specify the region of interest.
76 -V[level] (more ...)
78 Select verbosity level [c].
79 -f[i|o]colinfo (more ...)
81 Specify data types of input and/or output columns.
82 -^ or just -
84 Print a short message about the syntax of the command, then
85 exits (NOTE: on Windows just use -).
86 -+ or just +
88 Print an extensive usage (help) message, including the explana‐
89 tion of any module-specific option (but not the GMT common
90 options), then exits.
91 -? or no arguments
93 Print a complete usage (help) message, including the explanation
94 of all options, then exits.
95
97 By default, grids will be written as floating point data stored in
98 binary files using the netCDF format and meta-data structure. This for‐
99 mat is conform the COARDS conventions. GMT versions prior to 4.1 pro‐
100 duced netCDF files that did not conform to these conventions. Although
101 these files are still supported, their use is deprecated. To write
102 other than floating point COARDS-compliant netCDF files, append the =id
103 suffix to the filename outgrdfile.
104 When reading files, grdconvert and other GMT programs will try to auto‐
106 matically recognize the type of the input grid file. If this fails you
107 may append the =id suffix to the filename ingrdfile.
108 ┌───┬────────────────────────────┐
110 │ID │ Explanation │
111 ├───┼────────────────────────────┤
112 │nb │ GMT netCDF format (8-bit │
113 │ │ integer, COARDS, CF-1.5) │
114 ├───┼────────────────────────────┤
115 │ns │ GMT netCDF format (16-bit │
116 │ │ integer, COARDS, CF-1.5) │
117 ├───┼────────────────────────────┤
118 │ni │ GMT netCDF format (32-bit │
119 │ │ integer, COARDS, CF-1.5) │
120 ├───┼────────────────────────────┤
121 │nf │ GMT netCDF format (32-bit │
122 │ │ float, COARDS, CF-1.5) │
123 ├───┼────────────────────────────┤
124 │nd │ GMT netCDF format (64-bit │
125 │ │ float, COARDS, CF-1.5) │
126 ├───┼────────────────────────────┤
127 │cb │ GMT netCDF format (8-bit │
128 │ │ integer, deprecated) │
129 └───┴────────────────────────────┘
130 │cs │ GMT netCDF format (16-bit │
134 │ │ integer, deprecated) │
135 ├───┼────────────────────────────┤
136 │ci │ GMT netCDF format (32-bit │
137 │ │ integer, deprecated) │
138 ├───┼────────────────────────────┤
139 │cf │ GMT netCDF format (32-bit │
140 │ │ float, deprecated) │
141 ├───┼────────────────────────────┤
142 │cd │ GMT netCDF format (64-bit │
143 │ │ float, deprecated) │
144 ├───┼────────────────────────────┤
145 │bm │ GMT native, C-binary for‐ │
146 │ │ mat (bit-mask) │
147 ├───┼────────────────────────────┤
148 │bb │ GMT native, C-binary for‐ │
149 │ │ mat (8-bit integer) │
150 ├───┼────────────────────────────┤
151 │bs │ GMT native, C-binary for‐ │
152 │ │ mat (16-bit integer) │
153 ├───┼────────────────────────────┤
154 │bi │ GMT native, C-binary for‐ │
155 │ │ mat (32-bit integer) │
156 ├───┼────────────────────────────┤
157 │bf │ GMT native, C-binary for‐ │
158 │ │ mat (32-bit float) │
159 ├───┼────────────────────────────┤
160 │bd │ GMT native, C-binary for‐ │
161 │ │ mat (64-bit float) │
162 ├───┼────────────────────────────┤
163 │rb │ SUN rasterfile format │
164 │ │ (8-bit standard) │
165 ├───┼────────────────────────────┤
166 │rf │ GEODAS grid format GRD98 │
167 │ │ (NGDC) │
168 ├───┼────────────────────────────┤
169 │sf │ Golden Software Surfer │
170 │ │ format 6 (32-bit float) │
171 ├───┼────────────────────────────┤
172 │sd │ Golden Software Surfer │
173 │ │ format 7 (64-bit float, │
174 │ │ read-only) │
175 ├───┼────────────────────────────┤
176 │af │ Atlantic Geoscience Center │
177 │ │ format AGC (32-bit float) │
178 ├───┼────────────────────────────┤
179 │ei │ ESRI Arc/Info ASCII Grid │
180 │ │ Interchange format (ASCII │
181 │ │ integer) │
182 ├───┼────────────────────────────┤
183 │ef │ ESRI Arc/Info ASCII Grid │
184 │ │ Interchange format (ASCII │
185 │ │ float) │
186 ├───┼────────────────────────────┤
187 │gd │ Import/export through GDAL │
188 └───┴────────────────────────────┘
189
191 The standard format used for grdfiles is based on netCDF and conforms
192 to the COARDS conventions. Files written in this format can be read by
193 numerous third-party programs and are platform-independent. Some
194 disk-space can be saved by storing the data as bytes or shorts in stead
195 of integers. Use the scale and offset parameters to make this work
196 without loss of data range or significance. For more details, see
197 App-file-formats.
198 Multi-variable grid files
200 By default, GMT programs will read the first 2-dimensional grid con‐
202 tained in a COARDS-compliant netCDF file. Alternatively, use ingrd‐
203 file?varname (ahead of any optional suffix =id) to specify the
204 requested variable varname. Since ? has special meaning as a wildcard,
205 escape this meaning by placing the full filename and suffix between
206 quotes.
207 Multi-dimensional grids
209 To extract one layer or level from a 3-dimensional grid stored in a
211 COARDS-compliant netCDF file, append both the name of the variable and
212 the index associated with the layer (starting at zero) in the form:
213 ingrdfile?varname[layer]. Alternatively, specify the value associated
214 with that layer using parentheses in stead of brackets: ingridfile?var‐
215 name(layer).
216 In a similar way layers can be extracted from 4- or even 5-dimensional
218 grids. For example, if a grid has the dimensions (parameter, time,
219 depth, latitude, longitude), a map can be selected by using: ingrid‐
220 file?varname(parameter,time,depth).
221 Since question marks, brackets and parentheses have special meanings on
223 the command line, escape these meanings by placing the full filename
224 and suffix between quotes.
225
227 For binary native GMT files the size of the GMT grid header block is
228 hsize = 892 bytes, and the total size of the file is hsize + nx * ny *
229 item_size, where item_size is the size in bytes of each element (1, 2,
230 4). Bit grids are stored using 4-byte integers, each holding 32 bits,
231 so for these files the size equation is modified by using ceil (nx /
232 32) * 4 instead of nx. Note that these files are platform-dependent.
233 Files written on Little Endian machines (e.g., PCs) can not be read on
234 Big Endian machines (e.g., most workstations). Also note that it is not
235 possible for GMT to determine uniquely if a 4-byte grid is float or
236 int; in such cases it is best to use the =ID mechanism to specify the
237 file format. In all cases a native grid is considered to be signed
238 (i.e., there are no provision for unsigned short ints or unsigned
239 bytes). For header and grid details, see App-file-formats.
240
242 Regardless of the precision of the input data, GMT programs that create
243 grid files will internally hold the grids in 4-byte floating point
244 arrays. This is done to conserve memory and furthermore most if not all
245 real data can be stored using 4-byte floating point values. Data with
246 higher precision (i.e., double precision values) will lose that preci‐
247 sion once GMT operates on the grid or writes out new grids. To limit
248 loss of precision when processing data you should always consider nor‐
249 malizing the data prior to processing.
250
252 To extract the second layer from a 3-dimensional grid named temp from a
253 COARDS-compliant netCDF file climate.nc:
254 gmt grdconvert climate.nc?temp[1] -Gtemp.nc -V
256 To create a 4-byte native floating point grid from the COARDS-compliant
258 netCDF file data.nc:
259 gmt grdconvert data.nc -Gras_data.b4=bf -V
261 To make a 2-byte short integer file, scale it by 10, subtract 32000,
263 setting NaNs to -9999, do
264 gmt grdconvert values.nc -Gshorts.i2=bs+s10+o-32000+n-9999 -V
266 To create a Sun standard 8-bit rasterfile for a subset of the data file
268 image.nc, assuming the range in image.nc is 0-1 and we need 0-255, run
269 gmt grdconvert image.nc -R-60/-40/-40/-30 -Gimage.ras8=rb+s255 -V
271 To convert etopo2.nc to etopo2.i2 that can be used by grdraster, try
273 gmt grdconvert etopo2.nc -Getopo2.i2=bs -N -V
275
277 gmt.conf, gmt, grdmath, grdraster
278
280 2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
2815.4.5 Feb 24, 2019 GRDCONVERT(1)