1SURFACE(1) GMT SURFACE(1)
2
6 surface - Grid table data using adjustable tension continuous curvature
7 splines
8
10 surface [ table ] -Goutputfile.nc
11 -Iincrement
12 -Rregion [ -Aaspect_ratio ] [ -Cconvergence_limit[%] ] [ -Lllower ]
13 [ -Luupper ] [ -Nmax_iterations ] [ -Q ] [ -Ssearch_radius[m|s] ] [
14 -T[i|b]tension_factor ] [ -V[level] ] [ -Zover-relaxation_factor ] [
15 -aflags ] [ -bibinary ] [ -dinodata ] [ -eregexp ] [ -fflags ] [
16 -hheaders ] [ -iflags ] [ -r ] [ -:[i|o] ]
17 Note: No space is allowed between the option flag and the associated
19 arguments.
20
22 surface reads randomly-spaced (x,y,z) triples from standard input [or
23 table] and produces a binary grid file of gridded values z(x,y) by
24 solving:
25 (1 - T) * L (L (z)) + T * L (z) = 0
26 where T is a tension factor between 0 and 1, and L indicates the Lapla‐
28 cian operator. T = 0 gives the "minimum curvature" solution which is
29 equivalent to SuperMISP and the ISM packages. Minimum curvature can
30 cause undesired oscillations and false local maxima or minima (See
31 Smith and Wessel, 1990), and you may wish to use T > 0 to suppress
32 these effects. Experience suggests T ~ 0.25 usually looks good for
33 potential field data and T should be larger (T ~ 0.35) for steep topog‐
34 raphy data. T = 1 gives a harmonic surface (no maxima or minima are
35 possible except at control data points). It is recommended that the
36 user pre-process the data with blockmean, blockmedian, or blockmode to
37 avoid spatial aliasing and eliminate redundant data. You may impose
38 lower and/or upper bounds on the solution. These may be entered in the
39 form of a fixed value, a grid with values, or simply be the mini‐
40 mum/maximum input data values. Natural boundary conditions are applied
41 at the edges, except for geographic data with 360-degree range where we
42 apply periodic boundary conditions in the longitude direction.
43
45 -Goutputfile.nc
46 Output file name. Output is a binary 2-D .nc file. Note that the
47 smallest grid dimension must be at least 4.
48 -Ixinc[unit][+e|n][/yinc[unit][+e|n]]
50 x_inc [and optionally y_inc] is the grid spacing. Optionally,
51 append a suffix modifier. Geographical (degrees) coordinates:
52 Append m to indicate arc minutes or s to indicate arc seconds.
53 If one of the units e, f, k, M, n or u is appended instead, the
54 increment is assumed to be given in meter, foot, km, Mile, nau‐
55 tical mile or US survey foot, respectively, and will be con‐
56 verted to the equivalent degrees longitude at the middle lati‐
57 tude of the region (the conversion depends on PROJ_ELLIPSOID).
58 If y_inc is given but set to 0 it will be reset equal to x_inc;
59 otherwise it will be converted to degrees latitude. All coordi‐
60 nates: If +e is appended then the corresponding max x (east) or
61 y (north) may be slightly adjusted to fit exactly the given
62 increment [by default the increment may be adjusted slightly to
63 fit the given domain]. Finally, instead of giving an increment
64 you may specify the number of nodes desired by appending +n to
65 the supplied integer argument; the increment is then recalcu‐
66 lated from the number of nodes and the domain. The resulting
67 increment value depends on whether you have selected a grid‐
68 line-registered or pixel-registered grid; see App-file-formats
69 for details. Note: if -Rgrdfile is used then the grid spacing
70 has already been initialized; use -I to override the values.
71 -Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
73 Specify the region of interest.
74
76 table One or more ASCII (or binary, see -bi[ncols][type]) data table
77 file(s) holding a number of data columns. If no tables are given
78 then we read from standard input.
79 -Aaspect_ratio
81 Aspect ratio. If desired, grid anisotropy can be added to the
82 equations. Enter aspect_ratio, where dy = dx / aspect_ratio
83 relates the grid dimensions. [Default = 1 assumes isotropic
84 grid.]
85 -Cconvergence_limit[%]
87 Convergence limit. Iteration is assumed to have converged when
88 the maximum absolute change in any grid value is less than con‐
89 vergence_limit. (Units same as data z units). Alternatively,
90 give limit in percentage of rms deviation by appending %.
91 [Default is scaled to 1e-4 of the root-mean-square deviation of
92 the data from a best-fit (least-squares) plane.]. This is the
93 final convergence limit at the desired grid spacing; for inter‐
94 mediate (coarser) grids the effective convergence limit is
95 divided by the grid spacing multiplier.
96 -Lllower and -Luupper
98 Impose limits on the output solution. llower sets the lower
99 bound. lower can be the name of a grid file with lower bound
100 values, a fixed value, d to set to minimum input value, or u for
101 unconstrained [Default]. uupper sets the upper bound and can be
102 the name of a grid file with upper bound values, a fixed value,
103 d to set to maximum input value, or u for unconstrained
104 [Default]. Grid files used to set the limits may contain NaNs.
105 In the presence of NaNs, the limit of a node masked with NaN is
106 unconstrained.
107 -Nmax_iterations
109 Number of iterations. Iteration will cease when conver‐
110 gence_limit is reached or when number of iterations reaches
111 max_iterations. This is the final iteration limit at the
112 desired grid spacing; for intermediate (coarser) grids the
113 effective iteration limit is scaled by the grid spacing multi‐
114 plier. [Default is 500.]
115 -Q Suggest grid dimensions which have a highly composite greatest
117 common factor. This allows surface to use several intermediate
118 steps in the solution, yielding faster run times and better
119 results. The sizes suggested by -Q can be achieved by altering
120 -R and/or -I. You can recover the -R and -I you want later by
121 using grdsample or grdcut on the output of surface.
122 -Ssearch_radius[m|s]
124 Search radius. Enter search_radius in same units as x,y data;
125 append m to indicate arc minutes or s for arc seconds. This is
126 used to initialize the grid before the first iteration; it is
127 not worth the time unless the grid lattice is prime and cannot
128 have regional stages. [Default = 0.0 and no search is made.]
129 -T[i|b]tension_factor
131 Tension factor[s]. These must be between 0 and 1. Tension may be
132 used in the interior solution (above equation, where it sup‐
133 presses spurious oscillations) and in the boundary conditions
134 (where it tends to flatten the solution approaching the edges).
135 Using zero for both values results in a minimum curvature sur‐
136 face with free edges, i.e., a natural bicubic spline. Use
137 -Titension_factor to set interior tension, and -Tbtension_factor
138 to set boundary tension. If you do not prepend i or b, both will
139 be set to the same value. [Default = 0 for both gives minimum
140 curvature solution.]
141 -V[level] (more ...)
143 Select verbosity level [c]. -V3 will report the convergence
144 after each iteration; -V will report only after each regional
145 grid is converged.
146 -Zover-relaxation_factor
148 Over-relaxation factor. This parameter is used to accelerate the
149 convergence; it is a number between 1 and 2. A value of 1 iter‐
150 ates the equations exactly, and will always assure stable con‐
151 vergence. Larger values overestimate the incremental changes
152 during convergence, and will reach a solution more rapidly but
153 may become unstable. If you use a large value for this factor,
154 it is a good idea to monitor each iteration with the -Vl option.
155 [Default = 1.4 converges quickly and is almost always stable.]
156 -acol=name[...] (more ...)
158 Set aspatial column associations col=name.
159 -bi[ncols][t] (more ...)
161 Select native binary input. [Default is 3 input columns].
162 -dinodata (more ...)
164 Replace input columns that equal nodata with NaN.
165 -e[~]"pattern" | -e[~]/regexp/[i] (more ...)
167 Only accept data records that match the given pattern.
168 -f[i|o]colinfo (more ...)
170 Specify data types of input and/or output columns.
171 -h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
173 Skip or produce header record(s). Not used with binary data.
174 -icols[+l][+sscale][+ooffset][,...] (more ...)
176 Select input columns and transformations (0 is first column).
177 -r (more ...)
179 Set pixel node registration [gridline].
180 -:[i|o] (more ...)
182 Swap 1st and 2nd column on input and/or output.
183 -^ or just -
185 Print a short message about the syntax of the command, then
186 exits (NOTE: on Windows just use -).
187 -+ or just +
189 Print an extensive usage (help) message, including the explana‐
190 tion of any module-specific option (but not the GMT common
191 options), then exits.
192 -? or no arguments
194 Print a complete usage (help) message, including the explanation
195 of all options, then exits.
196
198 Regardless of the precision of the input data, GMT programs that create
199 grid files will internally hold the grids in 4-byte floating point
200 arrays. This is done to conserve memory and furthermore most if not all
201 real data can be stored using 4-byte floating point values. Data with
202 higher precision (i.e., double precision values) will lose that preci‐
203 sion once GMT operates on the grid or writes out new grids. To limit
204 loss of precision when processing data you should always consider nor‐
205 malizing the data prior to processing.
206
208 To grid 5 by 5 minute gravity block means from the ASCII data in
209 hawaii_5x5.xyg, using a tension_factor = 0.25, a convergence_limit =
210 0.1 milligal, writing the result to a file called hawaii_grd.nc, and
211 monitoring each iteration, try:
212 gmt surface hawaii_5x5.xyg -R198/208/18/25 -I5m -Ghawaii_grd.nc -T0.25 -C0.1 -Vl
214
216 surface will complain when more than one data point is found for any
217 node and suggest that you run blockmean, blockmedian, or blockmode
218 first. If you did run these decimators and still get this message it
219 usually means that your grid spacing is so small that you need more
220 decimals in the output format used. You may specify more decimal places
221 by editing the parameter FORMAT_FLOAT_OUT in your gmt.conf file prior
222 to running the decimators or choose binary input and/or output using
223 single or double precision storage.
224 Note that only gridline registration is possible with surface. If you
226 need a pixel-registered grid you can resample a gridline registered
227 grid using grdsample -T.
228
230 blockmean, blockmedian, blockmode, gmt, grdcut, grdsample, greenspline,
231 nearneighbor, triangulate, sphtriangulate
232
234 Smith, W. H. F, and P. Wessel, 1990, Gridding with continuous curvature
235 splines in tension, Geophysics, 55, 293-305.
236
238 2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
2395.4.5 Feb 24, 2019 SURFACE(1)