1XYZ2GRD(1) GMT XYZ2GRD(1)
2
6 xyz2grd - Convert data table to a grid file
7
9 xyz2grd [ table ] -Ggrdfile
10 -Iincrement
11 -Rregion [ -A[d|f|l|m|n|r|S|s|u|z] ] [
12 -D[+xxname][+yyname][+zzname][+sscale][+ooffset][+ninvalid][+tti‐
13 tle][+rremark] ] [ -Jparameters ] [ -S[zfile] ] [ -V[level] ] [
14 -Z[flags] ] [ -bibinary ] [ -dinodata ] [ -eregexp ] [ -fflags ] [
15 -hheaders ] [ -iflags ] [ -r ] [ -:[i|o] ]
16 Note: No space is allowed between the option flag and the associated
18 arguments.
19
21 xyz2grd reads one or more z or xyz tables and creates a binary grid
22 file. xyz2grd will report if some of the nodes are not filled in with
23 data. Such unconstrained nodes are set to a value specified by the user
24 [Default is NaN]. Nodes with more than one value will be set to the
25 mean value. As an option (using -Z), a 1-column z-table may be read
26 assuming all nodes are present (z-tables can be in organized in a num‐
27 ber of formats, see -Z below.) Note: xyz2grd does not grid the data,
28 it simply reformats existing data to a grid structure. For gridding,
29 see surface, greenspline, nearneighbor, or triangulate.
30
32 -Ggrdfile
33 grdfile is the name of the binary output grid file. (See GRID
34 FILE FORMAT below.)
35 -Ixinc[unit][+e|n][/yinc[unit][+e|n]]
37 x_inc [and optionally y_inc] is the grid spacing. Optionally,
38 append a suffix modifier. Geographical (degrees) coordinates:
39 Append m to indicate arc minutes or s to indicate arc seconds.
40 If one of the units e, f, k, M, n or u is appended instead, the
41 increment is assumed to be given in meter, foot, km, Mile, nau‐
42 tical mile or US survey foot, respectively, and will be con‐
43 verted to the equivalent degrees longitude at the middle lati‐
44 tude of the region (the conversion depends on PROJ_ELLIPSOID).
45 If y_inc is given but set to 0 it will be reset equal to x_inc;
46 otherwise it will be converted to degrees latitude. All coordi‐
47 nates: If +e is appended then the corresponding max x (east) or
48 y (north) may be slightly adjusted to fit exactly the given
49 increment [by default the increment may be adjusted slightly to
50 fit the given domain]. Finally, instead of giving an increment
51 you may specify the number of nodes desired by appending +n to
52 the supplied integer argument; the increment is then recalcu‐
53 lated from the number of nodes and the domain. The resulting
54 increment value depends on whether you have selected a grid‐
55 line-registered or pixel-registered grid; see App-file-formats
56 for details. Note: if -Rgrdfile is used then the grid spacing
57 has already been initialized; use -I to override the values.
58 -Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
60 Specify the region of interest.
61
63 table One or more ASCII [or binary, see -bi] files holding z or
64 (x,y,z) values. The xyz triplets do not have to be sorted.
65 One-column z tables must be sorted and the -Z must be set.
66 -A[d|f|l|m|n|r|S|s|u|z]
68 By default we will calculate mean values if multiple entries
69 fall on the same node. Use -A to change this behavior, except it
70 is ignored if -Z is given. Append f or s to simply keep the
71 first or last data point that was assigned to each node. Append
72 l or u or d to find the lowest (minimum) or upper (maximum)
73 value or the difference between the maximum and miminum value at
74 each node, respectively. Append m or r or S to compute mean or
75 RMS value or standard deviation at each node, respectively.
76 Append n to simply count the number of data points that were
77 assigned to each node (this only requires two input columns x
78 and y as z is not consulted). Append z to sum multiple values
79 that belong to the same node.
80 -D[+xxname][+yyname][+zzname][+sscale][+ooffset][+ninvalid][+tti‐
82 tle][+rremark]
83 Give one or more combinations for values xname, yname, zname
84 (give the names of those variables and in square bracket their
85 units, e.g., "distance [km]"), scale (to multiply grid values
86 after read [normally 1]), offset (to add to grid after scaling
87 [normally 0]), invalid (a value to represent missing data
88 [NaN]), title (anything you like), and remark (anything you
89 like). Items not listed will remain untouched. Give a blank
90 name to completely reset a particular string. Use quotes to
91 group texts with more than one word. Note that for geographic
92 grids (-fg) xname and yname are set automatically.
93 -Jparameters (more ...)
95 Select map projection. Use the -J syntax to save the georefer‐
96 encing info as CF-1 compliant metadata in netCDF grids. This
97 metadata will be recognized by GDAL.
98 -S[zfile]
100 Swap the byte-order of the input only. No grid file is produced.
101 You must also supply the -Z option. The output is written to
102 zfile (or stdout if not supplied).
103 -V[level] (more ...)
105 Select verbosity level [c].
106 -Z[flags]
108 Read a 1-column ASCII [or binary] table. This assumes that all
109 the nodes are present and sorted according to specified ordering
110 convention contained in flags. If incoming data represents rows,
111 make flags start with T(op) if first row is y = ymax or B(ottom)
112 if first row is y = ymin. Then, append L or R to indicate that
113 first element is at left or right end of row. Likewise for col‐
114 umn formats: start with L or R to position first column, and
115 then append T or B to position first element in a row. Note:
116 These two row/column indicators are only required for grids; for
117 other tables they do not apply. For gridline registered grids:
118 If data are periodic in x but the incoming data do not contain
119 the (redundant) column at x = xmax, append x. For data periodic
120 in y without redundant row at y = ymax, append y. Append sn to
121 skip the first n number of bytes (probably a header). If the
122 byte-order or the words needs to be swapped, append w. Select
123 one of several data types (all binary except a):
124 A ASCII representation of one or more floating point values per
126 record
127 a ASCII representation of a single item per record
129 c int8_t, signed 1-byte character
131 u uint8_t, unsigned 1-byte character
133 h int16_t, signed 2-byte integer
135 H uint16_t, unsigned 2-byte integer
137 i int32_t, signed 4-byte integer
139 I uint32_t, unsigned 4-byte integer
141 l int64_t, long (8-byte) integer
143 L uint64_t, unsigned long (8-byte) integer
145 f 4-byte floating point single precision
147 d 8-byte floating point double precision
149 Default format is scanline orientation of ASCII numbers: -ZTLa.
151 Note that -Z only applies to 1-column input. The difference
152 between A and a is that the latter can decode both dateTclock
153 and ddd:mm:ss[.xx] formats while the former is strictly for reg‐
154 ular floating point values.
155 -bi[ncols][t] (more ...)
157 Select native binary input. [Default is 3 input columns]. This
158 option only applies to xyz input files; see -Z for z tables.
159 -dinodata (more ...)
161 Replace input columns that equal nodata with NaN. Also sets
162 nodes with no input xyz triplet to this value [Default is NaN].
163 -e[~]"pattern" | -e[~]/regexp/[i] (more ...)
165 Only accept data records that match the given pattern.
166 -f[i|o]colinfo (more ...)
168 Specify data types of input and/or output columns.
169 -h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
171 Skip or produce header record(s). Not used with binary data.
172 -icols[+l][+sscale][+ooffset][,...] (more ...)
174 Select input columns and transformations (0 is first column).
175 -r (more ...)
177 Set pixel node registration [gridline].
178 -:[i|o] (more ...)
180 Swap 1st and 2nd column on input and/or output.
181 -^ or just -
183 Print a short message about the syntax of the command, then
184 exits (NOTE: on Windows just use -).
185 -+ or just +
187 Print an extensive usage (help) message, including the explana‐
188 tion of any module-specific option (but not the GMT common
189 options), then exits.
190 -? or no arguments
192 Print a complete usage (help) message, including the explanation
193 of all options, then exits.
194
196 Regardless of the precision of the input data, GMT programs that create
197 grid files will internally hold the grids in 4-byte floating point
198 arrays. This is done to conserve memory and furthermore most if not all
199 real data can be stored using 4-byte floating point values. Data with
200 higher precision (i.e., double precision values) will lose that preci‐
201 sion once GMT operates on the grid or writes out new grids. To limit
202 loss of precision when processing data you should always consider nor‐
203 malizing the data prior to processing.
204
206 By default GMT writes out grid as single precision floats in a
207 COARDS-complaint netCDF file format. However, GMT is able to produce
208 grid files in many other commonly used grid file formats and also
209 facilitates so called "packing" of grids, writing out floating point
210 data as 1- or 2-byte integers. To specify the precision, scale and off‐
211 set, the user should add the suffix =ID[+sscale][+ooffset][+ninvalid],
212 where ID is a two-letter identifier of the grid type and precision, and
213 scale and offset are optional scale factor and offset to be applied to
214 all grid values, and invalid is the value used to indicate missing
215 data. See grdconvert and Section grid-file-format of the GMT Technical
216 Reference and Cookbook for more information.
217 When writing a netCDF file, the grid is stored by default with the
219 variable name "z". To specify another variable name varname, append
220 ?varname to the file name. Note that you may need to escape the special
221 meaning of ? in your shell program by putting a backslash in front of
222 it, or by placing the filename and suffix between quotes or double
223 quotes.
224
226 When the output grid type is netCDF, the coordinates will be labeled
227 "longitude", "latitude", or "time" based on the attributes of the input
228 data or grid (if any) or on the -f or -R options. For example, both
229 -f0x -f1t and -R90w/90e/0t/3t will result in a longitude/time grid.
230 When the x, y, or z coordinate is time, it will be stored in the grid
231 as relative time since epoch as specified by TIME_UNIT and TIME_EPOCH
232 in the gmt.conf file or on the command line. In addition, the unit
233 attribute of the time variable will indicate both this unit and epoch.
234
236 All data types can be read, even 64-bit integers, but internally grids
237 are stored using floats. Hence, integer values exceeding the float
238 type's 23-bit mantissa may not be represented exactly. When -S is used
239 no grids are implied and we read data into an intermediate double con‐
240 tainer. This means all but 64-bit integers can be represented using the
241 double type's 53-bit mantissa.
242
244 To create a grid file from the ASCII data in hawaii_grv.xyz, use
245 gmt xyz2grd hawaii_grv.xyz -D+xdegree+ydegree+zGal+t"Hawaiian Grav‐
247 ity"+r"GRS-80 Ellipsoid used"
248 -Ghawaii_grv_new.nc -R198/208/18/25 -I5m -V
249 To create a grid file from the raw binary (3-column, single-precision
251 scanline-oriented data raw.b, use
252 gmt xyz2grd raw.b -D+xm+ym+zm -Graw.nc -R0/100/0/100 -I1 -V -Z -bi3f
253 To make a grid file from the raw binary USGS DEM (short integer scan‐
255 line-oriented data topo30.b on the NGDC global relief Data CD-ROM, with
256 values of -9999 indicate missing data, one must on some machine reverse
257 the byte-order. On such machines (like Sun), use
258 gmt xyz2grd topo30.b -D+xm+ym+zm -Gustopo.nc -R234/294/24/50 -I30s
259 -di-9999 -ZTLhw
260 Say you have received a binary file with 4-byte floating points that
262 were written on a machine of different byte-order than yours. You can
263 swap the byte-order with
264 gmt xyz2grd floats.bin -Snew_floats.bin -V -Zf
265
267 gmt, grd2xyz, grdedit, grdconvert, greenspline, nearneighbor, surface,
268 triangulate
269
271 2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
2725.4.5 Feb 24, 2019 XYZ2GRD(1)