Provided by: gmt-common_5.2.1+dfsg-3build1_all 
NAME
grdtrack - Sample grids at specified (x,y) locations
SYNOPSIS
grdtrack [ xyfile ] grd1 grd2 ... [ f|p|m|r|R[+l] ] [ length[u]/ds[spacing][+a] ] [dfile
] [ line[,line,...][+aaz][+d][+iinc[u]][+llength[u]][+nnp][+oaz][+rradius[u] ] [ ] [
region ] [ method/modifiers ] [ [radius[u]][+e|p]] [ [level] ] [ ] [ -b<binary> ] [
-d<nodata> ] [ -f<flags> ] [ -g<gaps> ] [ -h<headers> ] [ -i<flags> ] [ -n<flags> ] [
-o<flags> ] [ -s<flags> ] [ -:[i|o] ]
Note: No space is allowed between the option flag and the associated arguments.
DESCRIPTION
grdtrack reads one or more grid files (or a Sandwell/Smith IMG files) and a table (from
file or standard input; but see -E for exception) with (x,y) [or (lon,lat)] positions in
the first two columns (more columns may be present). It interpolates the grid(s) at the
positions in the table and writes out the table with the interpolated values added as (one
or more) new columns. Alternatively (-C), the input is considered to be line-segments and
we create orthogonal cross-profiles at each data point or with an equidistant separation
and sample the grid(s) along these profiles. A bicubic [Default], bilinear, B-spline or
nearest-neighbor (see -n) interpolation is used, requiring boundary conditions at the
limits of the region (see -n; Default uses "natural" conditions (second partial derivative
normal to edge is zero) unless the grid is automatically recognized as periodic.)
REQUIRED ARGUMENTS
-Ggridfile
grdfile is a 2-D binary grid file with the function f(x,y). If the specified grid
is in Sandwell/Smith Mercator format you must append a comma-separated list of
arguments that includes a scale to multiply the data (usually 1 or 0.1), the mode
which stand for the following: (0) Img files with no constraint code, returns data
at all points, (1) Img file with constraints coded, return data at all points, (2)
Img file with constraints coded, return data only at constrained points and NaN
elsewhere, and (3) Img file with constraints coded, return 1 at constraints and 0
elsewhere, and optionally the max latitude in the IMG file [80.738]. You may repeat
-G as many times as you have grids you wish to sample. Alternatively, use -G+llist
to pass a list of file names. The grids are sampled and results are output in the
order given. (See GRID FILE FORMAT below.)
OPTIONAL ARGUMENTS
xyfile This is an ASCII (or binary, see -bi) file where the first 2 columns hold the (x,y)
positions where the user wants to sample the 2-D data set.
-Af|pm|r|R
For track resampling (if -C is set) we can select how this is to be performed.
Append f to keep original points, but add intermediate points if needed [Default],
m as f, but first follow meridian (along y) then parallel (along x), p as f, but
first follow parallel (along y) then meridian (along x), r to resample at
equidistant locations; input points are not necessarily included in the output, and
R as r, but adjust given spacing to fit the track length exactly. Finally, append
+l if distances should be measured along rhumb lines (loxodromes). Ignored unless
-C is used.
-Clength[u]/ds[spacing][+a]
Use input line segments to create an equidistant and (optionally) equally-spaced
set of crossing profiles along which we sample the grid(s) [Default simply samples
the grid(s) at the input locations]. Specify two length scales that control how
the sampling is done: length sets the full length of each cross-profile, while ds
is the sampling spacing along each cross-profile. Optionally, append /spacing for
an equidistant spacing between cross-profiles [Default erects cross-profiles at the
input coordinates]. By default, all cross-profiles have the same direction. Append
+a to alternate the direction of cross-profiles. Append suitable units to length;
it sets the unit used for ds [and spacing] (See UNITS below). The default unit for
geographic grids is meter while Cartesian grids implies the user unit. The output
columns will be lon, lat, dist, azimuth, z1, z2, ..., zn (The zi are the sampled
values for each of the n grids)
-Ddfile
In concert with -C we can save the (possibly resampled) original lines to the file
dfile [Default only saves the cross-profiles]. The columns will be lon, lat, dist,
azimuth, z1, z2, ... (sampled value for each grid)
-Eline[,line,...][+aaz][+d][+iinc[u]][+llength[u]][+nnp][+oaz][+rradius[u]
Instead of reading input track coordinates, specify profiles via coordinates and
modifiers. The format of each line is start/stop, where start or stop are either
lon/lat (x/y for Cartesian data) or a 2-character XY key that uses the
"pstext"-style justification format format to specify a point on the map as
[LCR][BMT]. In addition, you can use Z-, Z+ to mean the global minimum and maximum
locations in the grid (only available if only one grid is given). Instead of two
coordinates you can specify an origin and one of +a, +o, or +r. You may append
+iinc[u] to set the sampling interval; if not given then we default to half the
minimum grid interval. The +a sets the azimuth of a profile of given length
starting at the given origin, while +o centers the profile on the origin; both
require +l. For circular sampling specify +r to define a circle of given radius
centered on the origin; this option requires either +n or +i. The +nnp sets the
desired number of points, while +llength gives the total length of the profile.
Append +d to output the along-track distances after the coordinates. Note: No
track file will be read. Also note that only one distance unit can be chosen.
Giving different units will result in an error. If no units are specified we
default to great circle distances in km (if geographic). If working with
geographic data you can prepend - (Flat Earth) or + (Geodesic) to inc, length, or
radius to change the mode of distance calculation [Great Circle].
-N Do not skip points that fall outside the domain of the grid(s) [Default only output
points within grid domain].
-R[unit]xmin/xmax/ymin/ymax[r] (more ...)
Specify the region of interest.
-Smethod/modifiers
In conjunction with -C, compute a single stacked profile from all profiles across
each segment. Append how stacking should be computed: a = mean (average), m =
median, p = mode (maximum likelihood), l = lower, L = lower but only consider
positive values, u = upper, U = upper but only consider negative values [a]. The
modifiers control the output; choose one or more among these choices: +a : Append
stacked values to all cross-profiles. +d : Append stack deviations to all
cross-profiles. +d : Append data residuals (data - stack) to all cross-profiles.
+s[file] : Save stacked profile to file [grdtrack_stacked_profile.txt]. +cfact :
Compute envelope on stacked profile as +/- fact *deviation [2]. Notes: (1)
Deviations depend on method and are st.dev (a), L1 scale (m and p), or half-range
(upper-lower)/2. (2) The stacked profile file contains 1 plus groups of 4-6
columns, one group for each sampled grid. The first column holds cross distance,
while the first 4 in a group hold stacked value, deviation, min value, and max
value. If method is one of a|m|p then we also write the lower and upper confidence
bounds (see +c). When one or more of +a, +d, and +r are used then we append the
results to the end of each row for all cross-profiles. The order is always stacked
value (+a), followed by deviations (+d) and residuals (+r). When more than one
grid is sampled this sequence of 1-3 columns are repeated for each grid.
-T[radius[u]][+e|p]
To be used with normal grid sampling, and limited to a single, non-IMG grid. If
the nearest node to the input point is NaN, search outwards until we find the
nearest non-NaN node and report that value instead. Optionally specify a search
radius which limits the consideration to points within this distance from the input
point. To report the location of the nearest node and its distance from the input
point, append +e. To instead replace the input point with the coordinates of the
nearest node, append +p.
-V[level] (more ...)
Select verbosity level [c].
-Z Only write out the sampled z-values [Default writes all columns].
-: Toggles between (longitude,latitude) and (latitude,longitude) input/output.
[Default is (longitude,latitude)].
-bi[ncols][t] (more ...)
Select native binary input. [Default is 2 input columns].
-bo[ncols][type] (more ...)
Select native binary output. [Default is one more than input].
-d[i|o]nodata (more ...)
Replace input columns that equal nodata with NaN and do the reverse on output.
-f[i|o]colinfo (more ...)
Specify data types of input and/or output columns.
-g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] (more ...)
Determine data gaps and line breaks.
-h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
Skip or produce header record(s).
-icols[l][sscale][ooffset][,...] (more ...)
Select input columns (0 is first column).
-n[b|c|l|n][+a][+bBC][+c][+tthreshold] (more ...)
Select interpolation mode for grids.
-ocols[,...] (more ...)
Select output columns (0 is first column).
-s[cols][a|r] (more ...)
Set handling of NaN records.
-^ or just -
Print a short message about the syntax of the command, then exits (NOTE: on Windows
use just -).
-+ or just +
Print an extensive usage (help) message, including the explanation of any
module-specific option (but not the GMT common options), then exits.
-? or no arguments
Print a complete usage (help) message, including the explanation of options, then
exits.
--version
Print GMT version and exit.
--show-datadir
Print full path to GMT share directory and exit.
UNITS
For map distance unit, append unit d for arc degree, m for arc minute, and s for arc
second, or e for meter [Default], f for foot, k for km, M for statute mile, n for nautical
mile, and u for US survey foot. By default we compute such distances using a spherical
approximation with great circles. Prepend - to a distance (or the unit is no distance is
given) to perform "Flat Earth" calculations (quicker but less accurate) or prepend + to
perform exact geodesic calculations (slower but more accurate).
ASCII FORMAT PRECISION
The ASCII output formats of numerical data are controlled by parameters in your gmt.conf
file. Longitude and latitude are formatted according to FORMAT_GEO_OUT, whereas other
values are formatted according to FORMAT_FLOAT_OUT. Be aware that the format in effect can
lead to loss of precision in the output, which can lead to various problems downstream. If
you find the output is not written with enough precision, consider switching to binary
output (-bo if available) or specify more decimals using the FORMAT_FLOAT_OUT setting.
GRID FILE FORMATS
By default GMT writes out grid as single precision floats in a COARDS-complaint netCDF
file format. However, GMT is able to produce grid files in many other commonly used grid
file formats and also facilitates so called "packing" of grids, writing out floating point
data as 1- or 2-byte integers. To specify the precision, scale and offset, the user should
add the suffix =id[/scale/offset[/nan]], where id is a two-letter identifier of the grid
type and precision, and scale and offset are optional scale factor and offset to be
applied to all grid values, and nan is the value used to indicate missing data. In case
the two characters id is not provided, as in =/scale than a id=nf is assumed. When
reading grids, the format is generally automatically recognized. If not, the same suffix
can be added to input grid file names. See grdconvert and Section grid-file-format of the
GMT Technical Reference and Cookbook for more information.
When reading a netCDF file that contains multiple grids, GMT will read, by default, the
first 2-dimensional grid that can find in that file. To coax GMT into reading another
multi-dimensional variable in the grid file, append ?varname to the file name, where
varname is the name of the variable. Note that you may need to escape the special meaning
of ? in your shell program by putting a backslash in front of it, or by placing the
filename and suffix between quotes or double quotes. The ?varname suffix can also be used
for output grids to specify a variable name different from the default: "z". See
grdconvert and Sections modifiers-for-CF and grid-file-format of the GMT Technical
Reference and Cookbook for more information, particularly on how to read splices of 3-,
4-, or 5-dimensional grids.
CONSEQUENCES OF GRID RESAMPLING
Resample or sampling of grids will use various algorithms (see -n) that may lead to
possible distortions or unexpected results in the resampled values. One expected effect
of resampling with splines is the tendency for the new resampled values to slightly exceed
the global min/max limits of the original grid. If this is unacceptable, you can impose
clipping of the resampled values values so they do not exceed the input min/max values by
adding +c to your -n option.
HINTS
If an interpolation point is not on a node of the input grid, then a NaN at any node in
the neighborhood surrounding the point will yield an interpolated NaN. Bicubic
interpolation [default] yields continuous first derivatives but requires a neighborhood of
4 nodes by 4 nodes. Bilinear interpolation [-n] uses only a 2 by 2 neighborhood, but
yields only zeroth-order continuity. Use bicubic when smoothness is important. Use
bilinear to minimize the propagation of NaNs, or lower threshold.
EXAMPLES
To sample the file hawaii_topo.nc along the SEASAT track track_4.xyg (An ASCII table
containing longitude, latitude, and SEASAT-derived gravity, preceded by one header
record):
grdtrack track_4.xyg -Ghawaii_topo.nc -h > track_4.xygt
To sample the Sandwell/Smith IMG format file topo.8.2.img (2 minute predicted bathymetry
on a Mercator grid) and the Muller et al age grid age.3.2.nc along the lon,lat coordinates
given in the file cruise_track.xy, try
grdtrack cruise_track.xy -Gtopo.8.2.img,1,1 -Gage.3.2.nc > depths-age.d
To sample the Sandwell/Smith IMG format file grav.18.1.img (1 minute free-air anomalies on
a Mercator grid) along 100-km-long cross-profiles that are orthogonal to the line segment
given in the file track.xy, erecting cross-profiles every 25 km and sampling the grid
every 3 km, try
grdtrack track.xy -Ggrav.18.1.img,0.1,1 -C100k/3/25 -Ar > xprofiles.txt
To sample the grid data.nc along a line from the lower left to the upper right corner,
using a grid spacing of 1 km, and output distances as well, try
grdtrack -ELB/RT+i1k+d -Gdata.nc > profiles.txt
SEE ALSO
gmt, gmtconvert, sample1d, surface
COPYRIGHT
2015, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe