manpagez: man pages & more
man grdtrack(1)
Home | html | info | man
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
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.