1GRD2XYZ(1) Generic Mapping Tools GRD2XYZ(1)
2
6 grd2xyz - Converting grid file(s) to ASCII or binary data
7
9 grd2xyz grdfiles [ -E[f][nodata] ] [ -H[i][nrec] ] [ -Nnodata ] [
10 -Rwest/east/south/north[r] ] [ -S[r] ] [ -V ] [ -W[weight] ] [
11 -Z[flags] ] [ -bo[s|S|d|D[ncol]|c[var1/...]] ] [ -fcolinfo ]
12
14 grd2xyz reads one or more binary 2-D grid files and writes out xyz-
15 triplets in ASCII [or binary] format to standard output. Modify the
16 precision of the ASCII output format by editing the D_FORMAT parameter
17 in your .gmtdefaults4 file or use --D_FORMAT=value on the command line,
18 or choose binary output using single or double precision storage. As
19 an option you may output z-values without the (x,y) in a number of for‐
20 mats, see -E or -Z below.
21 grdfiles
23 Names of 2-D binary grid files to be converted. (See GRID FILE
24 FORMATS below.)
25
27 -E Output an ESRI ArcInfo ASCII interchange grid format file.
28 Append f for float output [Default is integer]. Append nodata
29 which will be used wherever the grid value equals NaN [-9999].
30 -H Output 1 header record based on information in the first grid
32 file header. Ignored if binary output is selected. [Default is
33 no header].
34 -N Output this z-value where the latter equals NaN [Default writes
36 NaN].
37 -R xmin, xmax, ymin, and ymax specify the Region of interest. For
39 geographic regions, these limits correspond to west, east,
40 south, and north and you may specify them in decimal degrees or
41 in [+-]dd:mm[:ss.xxx][W|E|S|N] format. Append r if lower left
42 and upper right map coordinates are given instead of w/e/s/n.
43 The two shorthands -Rg and -Rd stand for global domain (0/360
44 and -180/+180 in longitude respectively, with -90/+90 in lati‐
45 tude). Alternatively, specify the name of an existing grid file
46 and the -R settings (and grid spacing, if applicable) are copied
47 from the grid. For calendar time coordinates you may either
48 give (a) relative time (relative to the selected TIME_EPOCH and
49 in the selected TIME_UNIT; append t to -JX|x), or (b) absolute
50 time of the form [date]T[clock] (append T to -JX|x). At least
51 one of date and clock must be present; the T is always required.
52 The date string must be of the form [-]yyyy[-mm[-dd]] (Gregorian
53 calendar) or yyyy[-Www[-d]] (ISO week calendar), while the clock
54 string must be of the form hh:mm:ss[.xxx]. The use of delim‐
55 iters and their type and positions must be exactly as indicated
56 (however, input, output and plot formats are customizable; see
57 gmtdefaults). Using the -R option will select a subsection of
58 the grid. If this subsection exceeds the boundaries of the grid,
59 only the common region will be output.
60 -S Suppress output for nodes whose z-value equals NaN [Default out‐
62 puts all nodes]. Append r to reverse the suppression, i.e.,
63 only output the nodes whose z-value equals NaN.
64 -V Selects verbose mode, which will send progress reports to stderr
66 [Default runs "silently"].
67 -W Write out x,y,z,w, where w is the supplied weight (or 1 if not
69 supplied) [Default writes x,y,z only].
70 -Z Write a 1-column ASCII [or binary] table. Output will be orga‐
72 nized according to the specified ordering convention contained
73 in flags. If data should be written by rows, make flags start
74 with T(op) if first row is y = ymax or B(ottom) if first row is
75 y = ymin. Then, append L or R to indicate that first element
76 should start at left or right end of row. Likewise for column
77 formats: start with L or R to position first column, and then
78 append T or B to position first element in a row. For gridline
79 registered grids: If grid is periodic in x but the outcoming
80 data should not contain the (redundant) column at x = xmax,
81 append x. For grid periodic in y, skip writing the redundant
82 row at y = ymax by appending y. If the byte-order needs to be
83 swapped, append w. Select one of several data types (all binary
84 except a):
85 a ASCII representation
87 c signed 1-byte character
88 u unsigned 1-byte character
89 h short 2-byte integer
90 i 4-byte integer
91 l long (4- or 8-byte) integer [architecture-dependent!]
92 f 4-byte floating point single precision
93 d 8-byte floating point double precision
94 Default format is scanline orientation of ASCII numbers: -ZTLa.
96 Note that -Z only applies to 1-column output.
97 -bo Selects binary output. Append s for single precision [Default
99 is d (double)]. Uppercase S or D will force byte-swapping.
100 Optionally, append ncol, the number of desired columns in your
101 binary output file. [Default is 3]. This option only applies
102 to xyz output; see -Z for z table output.
103 -f Special formatting of input and/or output columns (time or geo‐
105 graphical data). Specify i or o to make this apply only to
106 input or output [Default applies to both]. Give one or more
107 columns (or column ranges) separated by commas. Append T (abso‐
108 lute calendar time), t (relative time in chosen TIME_UNIT since
109 TIME_EPOCH), x (longitude), y (latitude), or f (floating point)
110 to each column or column range item. Shorthand -f[i|o]g means
111 -f[i|o]0x,1y (geographic coordinates). See also TIME COORDI‐
112 NATES below.
113
115 The ASCII output formats of numerical data are controlled by parameters
116 in your .gmtdefaults4 file. Longitude and latitude are formatted
117 according to OUTPUT_DEGREE_FORMAT, whereas other values are formatted
118 according to D_FORMAT. Be aware that the format in effect can lead to
119 loss of precision in the output, which can lead to various problems
120 downstream. If you find the output is not written with enough preci‐
121 sion, consider switching to binary output (-bo if available) or specify
122 more decimals using the D_FORMAT setting.
123
125 GMT is able to recognize many of the commonly used grid file formats,
126 as well as the precision, scale and offset of the values contained in
127 the grid file. When GMT needs a little help with that, you can add the
128 suffix =id[/scale/offset[/nan]], where id is a two-letter identifier of
129 the grid type and precision, and scale and offset are optional scale
130 factor and offset to be applied to all grid values, and nan is the
131 value used to indicate missing data. See grdreformat(1) and Section
132 4.17 of the GMT Technical Reference and Cookbook for more information.
133 When reading a netCDF file that contains multiple grids, GMT will read,
135 by default, the first 2-dimensional grid that can find in that file. To
136 coax GMT into reading another multi-dimensional variable in the grid
137 file, append ?varname to the file name, where varname is the name of
138 the variable. Note that you may need to escape the special meaning of ?
139 in your shell program by putting a backslash in front of it, or by
140 placing the filename and suffix between quotes or double quotes. See
141 grdreformat(1) and Section 4.18 of the GMT Technical Reference and
142 Cookbook for more information, particularly on how to read splices of
143 3-, 4-, or 5-dimensional grids.
144
146 Time coordinates in netCDF grids, be it the x, y, or z coordinate, will
147 be recognized as such. The variable's unit attribute is parsed to
148 determine the unit and epoch of the time coordinate in the grid. Val‐
149 ues are then converted to the internal time system specified by
150 TIME_UNIT and TIME_EPOCH in the .gmtdefaults file or on the command
151 line. The default output is relative time in that time system, or
152 absolute time when using the option -f0T, -f1T, or -f2T for x, y, or z
153 coordinate, respectively.
154
156 To edit individual values in the 5' by 5' hawaii_grv.grd file, dump the
157 .grd to ASCII:
158 grd2xyz hawaii_grv.grd > hawaii_grv.xyz
160 To write a single precision binary file without the x,y positions from
162 the file raw_data.grd file, using scanline orientation, run
163 grd2xyz raw_data.grd -ZTLf > hawaii_grv.b
165
167 gmtdefaults(1), GMT(1), grdedit(1), xyz2grd(1)
168GMT 4.5.6 10 Mar 2011 GRD2XYZ(1)