grdtrack(1) GMT grdtrack(1)
NAME
grdtrack - Sample grids at specified (x,y) locations
SYNOPSIS
grdtrack [ xyfile ] -Ggrd1 -Ggrd2 a| [ -Af|p|m|r|R[+l] ] [
-Clength[u]/ds[/spacing][+a][+v] ] [ -Ddfile ] [ -Eline ] [ -N ] [
-Rregion ] [ -Smethod/modifiers ] [ -T[radius[u]][+e|p]] [ -V[level]
] [ -Z ] [ -bbinary ] [ -dnodata ] [ -eregexp ] [ -fflags ] [ -ggaps ]
[ -hheaders ] [ -iflags ] [ -nflags ] [ -oflags ] [ -sflags ] [ -:[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 col-
umns 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 consid-
ered 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 anaturala
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[+l]
For track resampling (if -C or -E are 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 neces-
sarily 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][+v]
Use input line segments to create an equidistant and (option-
ally) 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 (left to right as we look in the direction of the
input line segment). Append +a to alternate the direction of
cross-profiles, or v to enforce either a awest-to-easta or
asouth-to-northa view. 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, a|, 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, a| (sampled
value for each grid)
-Eline[,line,a|][+aaz][+d][+iinc[u]][+llength[u]][+nnp][+oaz][+rra-
dius[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 ori-
gin, 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].
Note: If -C is set and spacing is given the that sampling scheme
overrules any modifier in -E.
-N Do not skip points that fall outside the domain of the grid(s)
[Default only output points within grid domain].
-Rxmin/xmax/ymin/ymax[+r][+uunit] (more a|)
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. +r : 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 *devia-
tion [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 a leading column plus groups of
4-6 columns, with one group for each sampled grid. The leading
column holds cross distance, while the first four columns in a
group hold stacked value, deviation, min value, and max value,
respectively. 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 also append the stacking results
to the end of each row, for all cross-profiles. The order is
always stacked value (+a), followed by deviations (+d) and
finally residuals (+r). When more than one grid is sampled this
sequence of 1-3 columns is 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 a|)
Select verbosity level [c].
-Z Only write out the sampled z-values [Default writes all col-
umns].
-: Toggles between (longitude,latitude) and (latitude,longitude)
input/output. [Default is (longitude,latitude)].
-bi[ncols][t] (more a|)
Select native binary input. [Default is 2 input columns].
-bo[ncols][type] (more a|)
Select native binary output. [Default is one more than input].
-d[i|o]nodata (more a|)
Replace input columns that equal nodata with NaN and do the
reverse on output.
-e[~]^<i>apattern^<i>a | -e[~]/regexp/[i] (more a|)
Only accept data records that match the given pattern.
-f[i|o]colinfo (more a|)
Specify data types of input and/or output columns.
-g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] (more a|)
Determine data gaps and line breaks.
-h[i|o][n][+c][+d][+rremark][+rtitle] (more a|)
Skip or produce header record(s).
-icols[+l][+sscale][+ooffset][,^<i>a|] (more a|)
Select input columns and transformations (0 is first column).
-n[b|c|l|n][+a][+bBC][+c][+tthreshold] (more a|)
Select interpolation mode for grids.
-ocols[,a|] (more a|)
Select output columns (0 is first column).
-s[cols][a|r] (more a|)
Set handling of NaN records.
-^ or just -
Print a short message about the syntax of the command, then
exits (NOTE: on Windows just use -).
-+ or just +
Print an extensive usage (help) message, including the explana-
tion 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 all options, then exits.
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 aFlat Eartha 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, absolute time is under the control of FOR-
MAT_DATE_OUT and FORMAT_CLOCK_OUT, whereas general floating point val-
ues are formatted according to FORMAT_FLOAT_OUT. Be aware that the for-
mat in effect can lead to loss of precision in ASCII 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 set-
ting.
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 apackinga of grids, writing out floating point
data as 1- or 2-byte integers. (more a|)
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 lim-
its 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(1), gmtconvert(1), pstext(1), sample1d(1), surface(1)
COPYRIGHT
2017, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
5.4.2 Jun 24, 2017 grdtrack(1)
gmt5 5.4.2 - Generated Thu Jun 29 08:30:16 CDT 2017