1GRDTRACK(1) GMT GRDTRACK(1)
2
6 grdtrack - Sample grids at specified (x,y) locations
7
9 grdtrack [ xyfile ] -Ggrd1 -Ggrd2 ... [ -Af|p|m|r|R[+l] ] [
10 -Clength[u]/ds[/spacing][+a][+v] ] [ -Ddfile ] [ -Eline ] [ -N ] [
11 -Rregion ] [ -Smethod/modifiers ] [ -T[radius[u]][+e|p]] [ -V[level]
12 ] [ -Z ] [ -bbinary ] [ -dnodata ] [ -eregexp ] [ -fflags ] [ -ggaps ]
13 [ -hheaders ] [ -iflags ] [ -nflags ] [ -oflags ] [ -sflags ] [ -:[i|o]
14 ]
15 Note: No space is allowed between the option flag and the associated
17 arguments.
18
20 grdtrack reads one or more grid files (or a Sandwell/Smith IMG files)
21 and a table (from file or standard input; but see -E for exception)
22 with (x,y) [or (lon,lat)] positions in the first two columns (more col‐
23 umns may be present). It interpolates the grid(s) at the positions in
24 the table and writes out the table with the interpolated values added
25 as (one or more) new columns. Alternatively (-C), the input is consid‐
26 ered to be line-segments and we create orthogonal cross-profiles at
27 each data point or with an equidistant separation and sample the
28 grid(s) along these profiles. A bicubic [Default], bilinear, B-spline
29 or nearest-neighbor (see -n) interpolation is used, requiring boundary
30 conditions at the limits of the region (see -n; Default uses "natural"
31 conditions (second partial derivative normal to edge is zero) unless
32 the grid is automatically recognized as periodic.)
33
35 -Ggridfile
36 grdfile is a 2-D binary grid file with the function f(x,y). If
37 the specified grid is in Sandwell/Smith Mercator format you must
38 append a comma-separated list of arguments that includes a scale
39 to multiply the data (usually 1 or 0.1), the mode which stand
40 for the following: (0) Img files with no constraint code,
41 returns data at all points, (1) Img file with constraints coded,
42 return data at all points, (2) Img file with constraints coded,
43 return data only at constrained points and NaN elsewhere, and
44 (3) Img file with constraints coded, return 1 at constraints and
45 0 elsewhere, and optionally the max latitude in the IMG file
46 [80.738]. You may repeat -G as many times as you have grids you
47 wish to sample. Alternatively, use -G+llist to pass a list of
48 file names. The grids are sampled and results are output in the
49 order given. (See GRID FILE FORMAT below.)
50
52 xyfile This is an ASCII (or binary, see -bi) file where the first 2
53 columns hold the (x,y) positions where the user wants to sample
54 the 2-D data set.
55 -Af|pm|r|R[+l]
57 For track resampling (if -C or -E are set) we can select how
58 this is to be performed. Append f to keep original points, but
59 add intermediate points if needed [Default], m as f, but first
60 follow meridian (along y) then parallel (along x), p as f, but
61 first follow parallel (along y) then meridian (along x), r to
62 resample at equidistant locations; input points are not neces‐
63 sarily included in the output, and R as r, but adjust given
64 spacing to fit the track length exactly. Finally, append +l if
65 distances should be measured along rhumb lines (loxodromes).
66 Ignored unless -C is used.
67 -Clength[u]/ds[/spacing][+a][+v]
69 Use input line segments to create an equidistant and (option‐
70 ally) equally-spaced set of crossing profiles along which we
71 sample the grid(s) [Default simply samples the grid(s) at the
72 input locations]. Specify two length scales that control how
73 the sampling is done: length sets the full length of each
74 cross-profile, while ds is the sampling spacing along each
75 cross-profile. Optionally, append /spacing for an equidistant
76 spacing between cross-profiles [Default erects cross-profiles at
77 the input coordinates]. By default, all cross-profiles have the
78 same direction (left to right as we look in the direction of the
79 input line segment). Append +a to alternate the direction of
80 cross-profiles, or v to enforce either a "west-to-east" or
81 "south-to-north" view. Append suitable units to length; it sets
82 the unit used for ds [and spacing] (See UNITS below). The
83 default unit for geographic grids is meter while Cartesian grids
84 implies the user unit. The output columns will be lon, lat,
85 dist, azimuth, z1, z2, ..., zn (The zi are the sampled values
86 for each of the n grids)
87 -Ddfile
89 In concert with -C we can save the (possibly resampled) original
90 lines to the file dfile [Default only saves the cross-profiles].
91 The columns will be lon, lat, dist, azimuth, z1, z2, ... (sam‐
92 pled value for each grid)
93 -Eline[,line,...][+aaz][+d][+iinc[u]][+llength[u]][+nnp][+oaz][+rra‐
95 dius[u]
96 Instead of reading input track coordinates, specify profiles via
97 coordinates and modifiers. The format of each line is
98 start/stop, where start or stop are either lon/lat (x/y for
99 Cartesian data) or a 2-character XY key that uses the
100 pstext-style justification format format to specify a point on
101 the map as [LCR][BMT]. In addition, you can use Z-, Z+ to mean
102 the global minimum and maximum locations in the grid (only
103 available if only one grid is given). Instead of two coordinates
104 you can specify an origin and one of +a, +o, or +r. You may
105 append +iinc[u] to set the sampling interval; if not given then
106 we default to half the minimum grid interval. The +a sets the
107 azimuth of a profile of given length starting at the given ori‐
108 gin, while +o centers the profile on the origin; both require
109 +l. For circular sampling specify +r to define a circle of given
110 radius centered on the origin; this option requires either +n or
111 +i. The +nnp sets the desired number of points, while +llength
112 gives the total length of the profile. Append +d to output the
113 along-track distances after the coordinates. Note: No track
114 file will be read. Also note that only one distance unit can be
115 chosen. Giving different units will result in an error. If no
116 units are specified we default to great circle distances in km
117 (if geographic). If working with geographic data you can
118 prepend - (Flat Earth) or + (Geodesic) to inc, length, or radius
119 to change the mode of distance calculation [Great Circle].
120 Note: If -C is set and spacing is given the that sampling scheme
121 overrules any modifier in -E.
122 -N Do not skip points that fall outside the domain of the grid(s)
124 [Default only output points within grid domain].
125 -Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
127 Specify the region of interest.
128 -Smethod/modifiers
130 In conjunction with -C, compute a single stacked profile from
131 all profiles across each segment. Append how stacking should be
132 computed: a = mean (average), m = median, p = mode (maximum
133 likelihood), l = lower, L = lower but only consider positive
134 values, u = upper, U = upper but only consider negative values
135 [a]. The modifiers control the output; choose one or more among
136 these choices: +a : Append stacked values to all cross-profiles.
137 +d : Append stack deviations to all cross-profiles. +r : Append
138 data residuals (data - stack) to all cross-profiles. +s[file] :
139 Save stacked profile to file [grdtrack_stacked_profile.txt].
140 +cfact : Compute envelope on stacked profile as +/- fact *devia‐
141 tion [2]. Notes: (1) Deviations depend on method and are st.dev
142 (a), L1 scale (m and p), or half-range (upper-lower)/2. (2) The
143 stacked profile file contains a leading column plus groups of
144 4-6 columns, with one group for each sampled grid. The leading
145 column holds cross distance, while the first four columns in a
146 group hold stacked value, deviation, min value, and max value,
147 respectively. If method is one of a|m|p then we also write the
148 lower and upper confidence bounds (see +c). When one or more of
149 +a, +d, and +r are used then we also append the stacking results
150 to the end of each row, for all cross-profiles. The order is
151 always stacked value (+a), followed by deviations (+d) and
152 finally residuals (+r). When more than one grid is sampled this
153 sequence of 1-3 columns is repeated for each grid.
154 -T[radius[u]][+e|p]
156 To be used with normal grid sampling, and limited to a single,
157 non-IMG grid. If the nearest node to the input point is NaN,
158 search outwards until we find the nearest non-NaN node and
159 report that value instead. Optionally specify a search radius
160 which limits the consideration to points within this distance
161 from the input point. To report the location of the nearest
162 node and its distance from the input point, append +e. To
163 instead replace the input point with the coordinates of the
164 nearest node, append +p.
165 -V[level] (more ...)
167 Select verbosity level [c].
168 -Z Only write out the sampled z-values [Default writes all col‐
170 umns].
171 -: Toggles between (longitude,latitude) and (latitude,longitude)
173 input/output. [Default is (longitude,latitude)].
174 -bi[ncols][t] (more ...)
176 Select native binary input. [Default is 2 input columns].
177 -bo[ncols][type] (more ...)
179 Select native binary output. [Default is one more than input].
180 -d[i|o]nodata (more ...)
182 Replace input columns that equal nodata with NaN and do the
183 reverse on output.
184 -e[~]"pattern" | -e[~]/regexp/[i] (more ...)
186 Only accept data records that match the given pattern.
187 -f[i|o]colinfo (more ...)
189 Specify data types of input and/or output columns.
190 -g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] (more ...)
192 Determine data gaps and line breaks.
193 -h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
195 Skip or produce header record(s).
196 -icols[+l][+sscale][+ooffset][,...] (more ...)
198 Select input columns and transformations (0 is first column).
199 -n[b|c|l|n][+a][+bBC][+c][+tthreshold] (more ...)
201 Select interpolation mode for grids.
202 -ocols[,...] (more ...)
204 Select output columns (0 is first column).
205 -s[cols][a|r] (more ...)
207 Set handling of NaN records.
208 -^ or just -
210 Print a short message about the syntax of the command, then
211 exits (NOTE: on Windows just use -).
212 -+ or just +
214 Print an extensive usage (help) message, including the explana‐
215 tion of any module-specific option (but not the GMT common
216 options), then exits.
217 -? or no arguments
219 Print a complete usage (help) message, including the explanation
220 of all options, then exits.
221
223 For map distance unit, append unit d for arc degree, m for arc minute,
224 and s for arc second, or e for meter [Default], f for foot, k for km, M
225 for statute mile, n for nautical mile, and u for US survey foot. By
226 default we compute such distances using a spherical approximation with
227 great circles. Prepend - to a distance (or the unit is no distance is
228 given) to perform "Flat Earth" calculations (quicker but less accurate)
229 or prepend + to perform exact geodesic calculations (slower but more
230 accurate).
231
233 The ASCII output formats of numerical data are controlled by parameters
234 in your gmt.conf file. Longitude and latitude are formatted according
235 to FORMAT_GEO_OUT, absolute time is under the control of FOR‐
236 MAT_DATE_OUT and FORMAT_CLOCK_OUT, whereas general floating point val‐
237 ues are formatted according to FORMAT_FLOAT_OUT. Be aware that the for‐
238 mat in effect can lead to loss of precision in ASCII output, which can
239 lead to various problems downstream. If you find the output is not
240 written with enough precision, consider switching to binary output (-bo
241 if available) or specify more decimals using the FORMAT_FLOAT_OUT set‐
242 ting.
243
245 By default GMT writes out grid as single precision floats in a
246 COARDS-complaint netCDF file format. However, GMT is able to produce
247 grid files in many other commonly used grid file formats and also
248 facilitates so called "packing" of grids, writing out floating point
249 data as 1- or 2-byte integers. (more ...)
250
252 Resample or sampling of grids will use various algorithms (see -n) that
253 may lead to possible distortions or unexpected results in the resampled
254 values. One expected effect of resampling with splines is the tendency
255 for the new resampled values to slightly exceed the global min/max lim‐
256 its of the original grid. If this is unacceptable, you can impose
257 clipping of the resampled values values so they do not exceed the input
258 min/max values by adding +c to your -n option.
259
261 If an interpolation point is not on a node of the input grid, then a
262 NaN at any node in the neighborhood surrounding the point will yield an
263 interpolated NaN. Bicubic interpolation [default] yields continuous
264 first derivatives but requires a neighborhood of 4 nodes by 4 nodes.
265 Bilinear interpolation [-n] uses only a 2 by 2 neighborhood, but yields
266 only zeroth-order continuity. Use bicubic when smoothness is important.
267 Use bilinear to minimize the propagation of NaNs, or lower threshold.
268
270 To sample the file hawaii_topo.nc along the SEASAT track track_4.xyg
271 (An ASCII table containing longitude, latitude, and SEASAT-derived
272 gravity, preceded by one header record):
273 grdtrack track_4.xyg -Ghawaii_topo.nc -h > track_4.xygt
275 To sample the Sandwell/Smith IMG format file topo.8.2.img (2 minute
277 predicted bathymetry on a Mercator grid) and the Muller et al age grid
278 age.3.2.nc along the lon,lat coordinates given in the file
279 cruise_track.xy, try
280 grdtrack cruise_track.xy -Gtopo.8.2.img,1,1 -Gage.3.2.nc > depths-age.d
282 To sample the Sandwell/Smith IMG format file grav.18.1.img (1 minute
284 free-air anomalies on a Mercator grid) along 100-km-long cross-profiles
285 that are orthogonal to the line segment given in the file track.xy,
286 erecting cross-profiles every 25 km and sampling the grid every 3 km,
287 try
288 grdtrack track.xy -Ggrav.18.1.img,0.1,1 -C100k/3/25 -Ar > xprofiles.txt
290 To sample the grid data.nc along a line from the lower left to the
292 upper right corner, using a grid spacing of 1 km, and output distances
293 as well, try
294 grdtrack -ELB/RT+i1k+d -Gdata.nc > profiles.txt
296
298 gmt, gmtconvert, pstext, sample1d, surface
299
301 2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
3025.4.5 Feb 24, 2019 GRDTRACK(1)