Provided by: gmt_4.5.11-1build1_amd64 bug

NAME

       surface - adjustable tension continuous curvature surface gridding algorithm

SYNOPSIS

       surface     [     xyzfile     ]    -Goutputfile.grd    -Ixinc[unit][=|+][/yinc[unit][=|+]]
       -Rwest/east/south/north[r] [ -Aaspect_ratio ] [ -Cconvergence_limit ] [  -H[i][nrec]  ]  [
       -Lllower  ]  [  -Luupper  ]  [  -Nmax_iterations  ]  [  -Q  ]  [  -Ssearch_radius[m]  ]  [
       -Ttension_factor[i|b]  ]  [  -V[l]  ]  [  -Zover-relaxation_factor  ]  [   -:[i|o]   ]   [
       -bi[s|S|d|D[ncol]|c[var1/...]] ] [ -fcolinfo ]

DESCRIPTION

       surface  reads  randomly-spaced  (x,y,z)  triples  from  standard  input  [or xyzfile] and
       produces a binary grid file of gridded values z(x,y) by solving:

            (1 - T) * L (L (z)) + T * L (z) = 0

       where T is a tension factor between 0 and 1, and L indicates the Laplacian operator.  T  =
       0  gives  the  "minimum  curvature"  solution which is equivalent to SuperMISP and the ISM
       packages.  Minimum curvature can cause undesired oscillations and false  local  maxima  or
       minima  (See  Smith  and  Wessel,  1990),  and you may wish to use T > 0 to suppress these
       effects.  Experience suggests T ~ 0.25 usually looks good for potential field data  and  T
       should be larger (T ~ 0.35) for steep topography data.  T = 1 gives a harmonic surface (no
       maxima or minima are possible except at control data points).  It is recommended that  the
       user  pre-process  the  data  with  blockmean,  blockmedian, or blockmode to avoid spatial
       aliasing and eliminate redundant data.  You may impose lower and/or upper  bounds  on  the
       solution.   These  may  be  entered  in  the form of a fixed value, a grid with values, or
       simply be the minimum/maximum input data values.

       xyzfile
              3 column ASCII file [or binary, see -b] holding (x,y,z) data values.  If no file is
              specified, surface will read from standard input.

       -G     Output  file  name.  Output is a binary 2-D .grd file.  Note that the smallest grid
              dimension must be at least 4.

       -I     x_inc [and optionally y_inc] is the  grid  spacing.  Optionally,  append  a  suffix
              modifier.   Geographical (degrees) coordinates: Append m to indicate arc minutes or
              c to indicate arc seconds.  If one of the units e, k, i, or n is appended  instead,
              the  increment  is  assumed  to  be  given  in meter, km, miles, or nautical miles,
              respectively, and will be converted to the  equivalent  degrees  longitude  at  the
              middle  latitude of the region (the conversion depends on ELLIPSOID).  If /y_inc is
              given but set to 0 it will be reset equal to x_inc; otherwise it will be  converted
              to  degrees latitude.  All coordinates: If = is appended then the corresponding max
              x (east) or y (north) may be slightly adjusted to fit exactly the  given  increment
              [by  default  the  increment  may  be  adjusted  slightly to fit the given domain].
              Finally, instead of giving an increment you may specify the number of nodes desired
              by appending + to the supplied integer argument; the increment is then recalculated
              from the number of nodes and the domain.  The resulting increment value depends  on
              whether  you  have  selected  a  gridline-registered  or pixel-registered grid; see
              Appendix B for details.  Note: if -Rgrdfile is used then grid spacing  has  already
              been initialized; use -I to override the values.

       -R     xmin, xmax, ymin, and ymax specify the Region of interest.  For geographic regions,
              these limits correspond to west, east, south, and north and you may specify them in
              decimal  degrees  or in [+-]dd:mm[:ss.xxx][W|E|S|N] format.  Append r if lower left
              and upper right map coordinates are given instead of w/e/s/n.  The  two  shorthands
              -Rg and -Rd stand for global domain (0/360 and -180/+180 in longitude respectively,
              with -90/+90 in latitude).  Alternatively, specify the name  of  an  existing  grid
              file  and  the  -R  settings  (and grid spacing, if applicable) are copied from the
              grid.  For calendar  time  coordinates  you  may  either  give  (a)  relative  time
              (relative  to  the  selected  TIME_EPOCH and in the selected TIME_UNIT; append t to
              -JX|x), or (b) absolute time of the form [date]T[clock] (append T  to  -JX|x).   At
              least  one  of  date and clock must be present; the T is always required.  The date
              string must be of the form [-]yyyy[-mm[-dd]] (Gregorian calendar) or yyyy[-Www[-d]]
              (ISO  week  calendar),  while  the clock string must be of the form hh:mm:ss[.xxx].
              The use of delimiters and their type and positions must  be  exactly  as  indicated
              (however, input, output and plot formats are customizable; see gmtdefaults).

OPTIONS

       -A     Aspect  ratio.   If  desired, grid anisotropy can be added to the equations.  Enter
              aspect_ratio, where dy = dx / aspect_ratio relates the grid dimensions.  [Default =
              1 assumes isotropic grid.]

       -C     Convergence  limit.   Iteration  is  assumed  to  have  converged  when the maximum
              absolute change in any grid value is less than convergence_limit.  (Units  same  as
              data  z  units).   [Default  is  scaled to 0.1 percent of typical gradient in input
              data.]

       -H     Input file(s) has header record(s).  If used, the default number of header  records
              is  N_HEADER_RECS.   Use -Hi if only input data should have header records [Default
              will write out header records if the input data have them]. Blank lines  and  lines
              starting with # are always skipped.  Not used with binary data.

       -L     Impose  limits  on the output solution.  llower sets the lower bound.  lower can be
              the name of a grid file with lower bound values, a fixed value, d to set to minimum
              input value, or u for unconstrained [Default].  uupper sets the upper bound and can
              be the name of a grid file with upper bound values, a fixed  value,  d  to  set  to
              maximum input value, or u for unconstrained [Default].

       -N     Number  of  iterations.   Iteration will cease when convergence_limit is reached or
              when number of iterations reaches max_iterations. [Default is 250.]

       -Q     Suggest grid dimensions which have a highly composite greatest common factor.  This
              allows  surface  to use several intermediate steps in the solution, yielding faster
              run times and better results. The sizes suggested by -Q can be achieved by altering
              -R  and/or  -I.  You can recover the -R and -I you want later by using grdsample or
              grdcut on the output of surface.

       -S     Search radius.  Enter search_radius in same units as x,y data; append m to indicate
              minutes.  This is used to initialize the grid before the first iteration; it is not
              worth the time unless the grid lattice is prime and cannot  have  regional  stages.
              [Default = 0.0 and no search is made.]

       -T     Tension  factor[s].   These  must  be  between 0 and 1.  Tension may be used in the
              interior solution (above equation, where it suppresses spurious  oscillations)  and
              in  the boundary conditions (where it tends to flatten the solution approaching the
              edges).  Using zero for both values results in a  minimum  curvature  surface  with
              free  edges, i.e., a natural bicubic spline.  Use -Ttension_factori to set interior
              tension, and -Ttension_factorb to set boundary tension.  If you do not append i  or
              b,  both  will  be  set  to  the  same  value.  [Default = 0 for both gives minimum
              curvature solution.]

       -V     Selects verbose mode, which will send progress  reports  to  stderr  [Default  runs
              "silently"].  -Vl will report the convergence after each iteration;  -V will report
              only after each regional grid is converged.

       -Z     Over-relaxation factor.  This parameter is used to accelerate the  convergence;  it
              is a number between 1 and 2.  A value of 1 iterates the equations exactly, and will
              always assure stable  convergence.   Larger  values  overestimate  the  incremental
              changes  during  convergence, and will reach a solution more rapidly but may become
              unstable.  If you use a large value for this factor, it is a good idea  to  monitor
              each iteration with the -Vl option.  [Default = 1.4 converges quickly and is almost
              always stable.]

       -:     Toggles between (longitude,latitude) and (latitude,longitude) input and/or  output.
              [Default  is  (longitude,latitude)].   Append i to select input only or o to select
              output only.  [Default affects both].

       -bi    Selects binary input.  Append s for  single  precision  [Default  is  d  (double)].
              Uppercase  S or D will force byte-swapping.  Optionally, append ncol, the number of
              columns in your binary input file if it exceeds the columns needed by the  program.
              Or  append  c  if  the  input  file  is netCDF. Optionally, append var1/var2/... to
              specify the variables to be read.  [Default is 3 input columns].

       -f     Special formatting of input and/or output  columns  (time  or  geographical  data).
              Specify  i  or  o  to  make  this apply only to input or output [Default applies to
              both].  Give one or more columns (or column ranges) separated by commas.  Append  T
              (absolute calendar time), t (relative time in chosen TIME_UNIT since TIME_EPOCH), x
              (longitude), y (latitude), or f (floating point) to each  column  or  column  range
              item.  Shorthand -f[i|o]g means -f[i|o]0x,1y (geographic coordinates).

GRID VALUES PRECISION

       Regardless  of  the  precision of the input data, GMT programs that create grid files will
       internally hold the grids in 4-byte floating point  arrays.   This  is  done  to  conserve
       memory and furthermore most if not all real data can be stored using 4-byte floating point
       values.  Data with higher  precision  (i.e.,  double  precision  values)  will  lose  that
       precision  once  GMT  operates  on  the  grid  or  writes out new grids.  To limit loss of
       precision when processing data you should always consider normalizing the  data  prior  to
       processing.

EXAMPLES

       To  grid  5 by 5 minute gravity block means from the ASCII data in hawaii_5x5.xyg, using a
       tension_factor = 0.25, a convergence_limit = 0.1 milligal, writing the result  to  a  file
       called hawaii_grd.grd, and monitoring each iteration, try:

       surface hawaii_5x5.xyg -R 198/208/18/25 -I 5m -G hawaii_grd.grd -T 0.25 -C 0.1 -Vl

BUGS

       surface will complain when more than one data point is found for any node and suggest that
       you run blockmean, blockmedian, or blockmode first.  If you did run blockm* and still  get
       this  message  it  usually  means  that  your  grid spacing is so small that you need more
       decimals in the output format used by blockm*.  You may specify  more  decimal  places  by
       editing  the  parameter  D_FORMAT  in your .gmtdefaults4 file prior to running blockm*, or
       choose binary input and/or output using single or double precision storage.
       Note that only gridline registration is possible with  surface.   If  you  need  a  pixel-
       registered grid you can resample a gridline registered grid using grdsample -T.

SEE ALSO

       blockmean(1), blockmedian(1), blockmode(1), GMT(1), nearneighbor(1), triangulate(1)

REFERENCES

       Smith,  W.  H.  F,  and  P.  Wessel,  1990,  Gridding with continuous curvature splines in
       tension, Geophysics, 55, 293-305.