Provided by: gmt-common_5.4.5+dfsg-1_all bug

NAME

       grdtrack - Sample grids at specified (x,y) locations

SYNOPSIS

       grdtrack    [    xyfile    ]     -Ggrd1     -Ggrd2    ...     [    -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 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[+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 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][+v]
              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 (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  "west-to-east"
              or  "south-to-north"  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, ..., 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].   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 ...)
              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  *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 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 ...)
              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.

       -e[~]"pattern" | -e[~]/regexp/[i] (more ...)
              Only accept data records that match the given pattern.

       -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 and transformations (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
              just use -).

       -+ 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  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  "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, absolute time is
       under the control of FORMAT_DATE_OUT and FORMAT_CLOCK_OUT, whereas general floating  point
       values are formatted according to FORMAT_FLOAT_OUT. Be aware that the format 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 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. (more ...)

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, pstext, sample1d, surface

COPYRIGHT

       2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe