NAME
surface - adjustable tension continuous curvature surface
gridding algorithm
SYNOPSIS
surface [ xyzfile ] -Goutputfile.grd
-Ix_inc[m|c][/y_inc[m|c]] -Rwest/east/south/north[r] [
-Aaspect_ratio ] [ -Cconvergence_limit ] [ -H[nrec] ] [
-Lllower ] [ -Luupper ] [ -Nmax_iterations ] [ -Q ] [
-Ssearch_radius[m] ] [ -Ttension_factor[ib] ] [ -V[l] ] [
-Zover-relaxation_factor ] [ -: ] [ -bi[s][n] ]
DESCRIPTION
surface reads randomly-spaced (x,y,z) triples from standard
input [or xyzfile] and produces a binary grdfile 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 pack-
ages. 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 spa-
tial 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 grdfile 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.
-I x_inc [and optionally y_inc] is the grid spacing.
Append m to indicate minutes or c to indicate seconds.
-R west, east, south, and north specify the Region of
interest. To specify boundaries in degrees and minutes
[and seconds], use the dd:mm[:ss] format. Append r if
lower left and upper right map coordinates are given
instead of wesn.
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 con-
verged 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). Number of header
records can be changed by editing your .gmtdefaults
file. If used, GMT default is 1 header record. Not
used with binary data.
-L Impose limits on the output solution. llower sets the
lower bound. lower can be the name of a grdfile 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 grdfile
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 itera-
tions 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 sug-
gested 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 flat-
ten 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 solu-
tion.]
-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 con-
vergence, 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/output. [Default is
(longitude,latitude)].
-bi Selects binary input. Append s for single precision
[Default is double]. Append n for the number of
columns in the binary file(s). [Default is 3 input
columns].
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 -R198/208/18/25 -I5m -Ghawaii_grd.grd
-T0.25 -C0.1 -VL
BUGS
surface will complain when more than one data point is found
for any node and suggest that you run blockmean, block-
median, or blockmode first. If you did run blockm* and
still get this message it usually means that your grid spac-
ing 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 .gmtdefaults file
prior to running blockm*, or choose binary input and/or out-
put using single or double precision storage.
SEE ALSO
blockmean(l), blockmedian(l), blockmode(l), gmt(l),
nearneighbor(l), triangulate(l)
REFERENCES
Smith, W. H. F, and P. Wessel, 1990, Gridding with continu-
ous curvature splines in tension, Geophysics, 55, 293-305.