1v.surf.rst(1) Grass User's Manual v.surf.rst(1)
2
6 v.surf.rst - Spatial approximation and topographic analysis from given
7 point or isoline data in vector format to floating point raster format
8 using regularized spline with tension.
9
11 vector
12
14 v.surf.rst
15 v.surf.rst help
16 v.surf.rst [-dtc] input=string [layer=integer] [zcolumn=string]
17 [scolumn=string] [dmax=float] [dmin=float] [devi=string]
18 [cvdev=string] [elev=string] [slope=string] [aspect=string]
19 [pcurv=string] [tcurv=string] [mcurv=string] [maskmap=string]
20 [zmult=float] [tension=float] [smooth=float] [segmax=integer]
21 [npmin=integer] [theta=float] [scalex=float] [treefile=string]
22 [overfile=string] [--overwrite]
23 Flags:
25 -d Output partial derivatives instead of topographic parameters
26 -t Use scale dependent tension
28 -c Perform cross-validation procedure without raster approximation
30 --overwrite
32 Parameters:
34 input=string
35 Name of the vector file with input data
36 layer=integer
38 Field value. If set to 0, z coordinates are used. (3D vector only)
39 Default: 1
40 zcolumn=string
42 Name of the attribute column with values to be used for approxima‐
43 tion (if layer>0)
44 scolumn=string
46 Name of the attribute column with smoothing parameters
47 dmax=float
49 Maximum distance between points on isoline (to insert additional
50 points) Default: 2.500000
51 dmin=float
53 Minimum distance between points (to remove almost identical points)
54 Default: 0.500000
55 devi=string
57 Output deviations vector point file
58 cvdev=string
60 Output cross-validation errors vector point file
61 elev=string
63 Output surface raster file (elevation)
64 slope=string
66 Output slope raster file
67 aspect=string
69 Output aspect raster file
70 pcurv=string
72 Output profile curvature raster file
73 tcurv=string
75 Output tangential curvature raster file
76 mcurv=string
78 Output mean curvature raster file
79 maskmap=string
81 Name of the raster file used as mask
82 zmult=float
84 Conversion factor for values used for approximation Default: 1.0
85 tension=float
87 Tension parameter Default: 40.
88 smooth=float
90 Smoothing parameter
91 segmax=integer
93 Maximum number of points in a segment Default: 40
94 npmin=integer
96 Minimum number of points for approximation in a segment (>segmax)
97 Default: 300
98 theta=float
100 Anisotropy angle (in degrees counterclockwise from East)
101 scalex=float
103 Anisotropy scaling factor
104 treefile=string
106 Output vector file showing quadtree segmentation
107 overfile=string
109 Output vector file showing overlapping windows
110
112 v.surf.rst
113 This program performs spatial approximation based on z-values or
114 attributes of point or isoline data given in a vector file named input
115 to grid cells in the output raster file elev representing a surface. As
116 an option, simultaneously with approximation, topographic parameters
117 slope, aspect, profile curvature (measured in the direction of the
118 steepest slope), tangential curvature (measured in the direction of a
119 tangent to contour line) or mean curvature are computed and saved as
120 raster files specified by the options slope, aspect, pcurv, tcurv,
121 mcurv respectively. If -d flag is set, the program outputs partial de‐
122 rivatives fx,fy,fxx, fyy,fxy instead of slope, aspect, profile, tangen‐
123 tial and mean curvatures respectively. If the input data have time
124 stamp, the program creates time stamp for all output files.
125 User can define a raster file named maskmap, which will be used as a
127 mask. The approximation is skipped for cells which have zero or NULL
128 value in mask. NULL values will be assigned to these cells in all out‐
129 put raster files. Data points are checked for identical points and
130 points that are closer to each other than the given dmin are removed.
131 If sparsely digitized contours or isolines are used as input, addi‐
132 tional points are computed between each 2 points on a line if the dis‐
133 tance between them is greater than specified dmax. Parameter zmult
134 allows user to rescale the values used for approximation (useful e.g.
135 for transformation of elevations given in feet to meters, so that the
136 proper values of slopes and curvatures can be computed).
137 Regularized spline with tension is used for the approximation. The ten‐
139 sion parameter tunes the character of the resulting surface from thin
140 plate to membrane. Smoothing parameter smooth controls the deviation
141 between the given points and the resulting surface and it can be very
142 effective in smoothing noisy data while preserving the geometrical
143 properties of the surface. With the smoothing parameter set to zero
144 (smooth=0) the resulting surface passes exactly through the data points
145 (spatial interpolation is performed). When smoothing parameter is used,
146 it is also possible to output a vector point file devi containing devi‐
147 ations of the resulting surface from the given data.
148 If the number of given points is greater than segmax, segmented pro‐
150 cessing is used . The region is split into quadtree-based rectangular
151 segments, each having less than segmax points and approximation is per‐
152 formed on each segment of the region. To ensure smooth connection of
153 segments the approximation function for each segment is computed using
154 the points in the given segment and the points in its neighborhood
155 which are in the rectangular window surrounding the given segment. The
156 number of points taken for approximation is controlled by npmin, the
157 value of which must be larger than segmax. User can choose to output
158 vector files treefile and overfile which represent the quad tree used
159 for segmentation and overlapping neighborhoods from which additional
160 points for approximation on each segment were taken.
161 Predictive error of surface approximation for given parameters can be
163 computed using the -c flag. A crossvalidation procedure is then per‐
164 formed using the data given in the vector file input and the estimated
165 predictive errors are stored in the vector point file cvdev. When using
166 this flag, no raster output files are computed. Anisotropic surfaces
167 can be interpolated by setting anisotropy angle theta and scaling fac‐
168 tor scalex. The program writes values of selected input and internally
169 computed parameters to the history file of raster map elev.
170
172 v.surf.rst uses regularized spline with tension for approximation from
173 vector data. The module does not require input data with topology,
174 therefore both level1 (no topology) and level2 (with topology) vector
175 point data are supported. Additional points are used for approximation
176 between each 2 points on a line if the distance between them is greater
177 than specified dmax. If dmax is small (less than cell size) the number
178 of added data points can be vary large and slow down approximation sig‐
179 nificantly. The implementation has a segmentation procedure based on
180 quadtrees which enhances the efficiency for large data sets. Special
181 color tables are created by the program for output raster files.
182 Topographic parameters are computed directly from the approximation
184 function so that the important relationships between these parameters
185 are preserved. The equations for computation of these parameters and
186 their interpretation is described in Mitasova and Hofierka, 1993 or
187 Neteler and Mitasova, 2004). Slopes and aspect are computed in degrees
188 (0-90 and 1-360 respectively). The aspect raster file has value 0
189 assigned to flat areas (with slope less than 0.1%) and to singular
190 points with undefined aspect. Aspect points downslope and is 90 to the
191 North, 180 to the West, 270 to the South and 360 to the East, the val‐
192 ues increase counterclockwise. Curvatures are positive for convex and
193 negative for concave areas. Singular points with undefined curvatures
194 have assigned zero values.
195 Tension and smoothing allow user to tune the surface character. For
197 most landscape scale applications the default values should provide
198 adequate results. The program gives warning when significant over‐
199 shoots appear in the resulting surface and higher tension or smoothing
200 should be used. To select parameters that will produce a surface with
201 desired properties, it is useful to know that the method is scale
202 dependent and the tension works as a rescaling parameter (high tension
203 "increases the distances between the points" and reduces the range of
204 impact of each point, low tension "decreases the distance" and the
205 points influence each other over longer range). Surface with tension
206 set too high behaves like a membrane (rubber sheet stretched over the
207 data points) with peak or pit ("crater") in each given point and every‐
208 where else the surface goes rapidly to trend. If digitized contours are
209 used as input data, high tension can cause artificial waves along con‐
210 tours. Lower tension and higher smoothing is suggested for such a case.
211 Surface with tension set too low behaves like a stiff steel plate and
212 overshoots can appear in areas with rapid change of gradient and seg‐
213 mentation can be visible. Increase in tension should solve the prob‐
214 lems.
215 There are two options how tension can be applied in relation to dnorm
216 (dnorm rescales the coordinates depending on the average data density
217 so that the size of segments with segmax=40 points is around 1 - this
218 ensures the numerical stability of the computation):
219 1. Default: the given tension is applied to normalized data
221 (x/dnorm..), that means that the distances are multiplied (rescaled) by
222 tension/dnorm. If density of points is changed, e.g., by using higher
223 dmin, the dnorm changes and tension needs to be changed too to get the
224 same result. Because the tension is applied to normalized data its
225 suitable value is usually within the 10-100 range and does not depend
226 on the actual scale (distances) of the original data (which can be km
227 for regional applications or cm for field experiments).
228 2. Flag -t : The given tension is applied to un-normalized data
229 (rescaled tension = tension*dnorm/1000 is applied to normalized data
230 (x/dnorm) and therefore dnorm cancels out) so here tension truly works
231 as a rescaling parameter. For regional applications with distances
232 between points in km. the suitable tension can be 500 or higher, for
233 detailed field scale analysis it can be 0.1. To help select how much
234 the data need to be rescaled the program writes dnorm and rescaled ten‐
235 sion fi=tension*dnorm/1000 at the beginning of the program run. This
236 rescaled tension should be around 20-30. If it is lower or higher, the
237 given tension parameter should be changed accordingly.
238 The default is a recommended choice, however for the applications where
240 the user needs to change density of data and preserve the approximation
241 character the -t flag can be helpful.
242 Anisotropic data (e.g. geologic phenomena) can be interpolated using
244 theta and scalex defining orientation and ratio of the perpendicular
245 axes put on the longest/shortest side of the feature, respectively.
246 Theta is measured in degrees from East, counterclockwise. Scalex is a
247 ratio of axes sizes. Setting scalex in the range 0-1, results in a
248 pattern prolonged in the direction defined by theta. Scalex value 0.5
249 means that modeled feature is approximately 2 times longer in the
250 direction of theta than in the perpendicular direction. Scalex value 2
251 means that axes ratio is reverse resulting in a pattern perpendicular
252 to the previous example. Please note that anisotropy option has not
253 been extensively tested and may include bugs (for example , topographic
254 parameters may not be computed correctly) - if there are problems,
255 please report to GRASS bugtracker (accessible from
256 http://grass.itc.it/).
257 For data with values changing over several magnitudes (sometimes the
259 concentration or density data) it is suggested to interpolate the log
260 of the values rather than the original ones.
261 The program checks the numerical stability of the algorithm by comput‐
263 ing the values in given points, and prints the root mean square devia‐
264 tion (rms) found into the history file of raster map elev. For computa‐
265 tion with smoothing set to 0. rms should be 0. Significant increase in
266 tension is suggested if the rms is unexpectedly high for this case.
267 With smoothing parameter greater than zero the surface will not pass
268 exactly through the data points and the higher the parameter the closer
269 the surface will be to the trend. The rms then represents a measure of
270 smoothing effect on data. More detailed analysis of smoothing effects
271 can be performed using the output deviations option.
272 Cross validation procedure
274 The "optimal" approximation parameters for given data can be found
275 using a cross-validation (CV) procedure (-c flag). The CV procedure is
276 based on removing one input data point at a time, performing the
277 approximation for the location of the removed point using the remaining
278 data points and calculating the difference between the actual and
279 approximated value for the removed data point. The procedure is
280 repeated until every data point has been, in turn, removed. This form
281 of CV is also known as the "leave-one-out" or "jack-knife" method
282 (Hofierka et al., 2002; Hofierka, 2005). The differences (residuals)
283 are then stored in the cvdev output vector file. Please note that dur‐
284 ing the CV procedure no other output files can be set, the approxima‐
285 tion is performed only for locations defined by input data. To find
286 "optimal parameters", the CV procedure must be iteratively performed
287 for all reasonable combinations of the approximation parameters with
288 small incremental steps (e.g. tension, smoothing) in order to find a
289 combination with minimal statistical error (also called predictive
290 error) defined by root mean squared error (RMSE), mean absolute error
291 (MAE) or other error characteristics. A script with loops for tested
292 RST parameters can do the job, necessary statistics can be calculated
293 using e.g. v.univar. It should be noted that crossvalidation is a time-
294 consuming procedure, usually reasonable for up to several thousands of
295 points. For larger data sets, CV should be applied to a representative
296 subset of the data. The cross-validation procedure works well only for
297 well-sampled phenomena and when minimizing the predictive error is the
298 goal. The parameters found by minimizing the predictive (CV) error may
299 not not be the best for for poorly sampled phenomena (result could be
300 strongly smoothed with lost details and fluctuations) or when signifi‐
301 cant noise is present that needs to be smoothed out.
302 The program writes the values of parameters used in computation into
304 the comment part of history file elev as well as the following values
305 which help to evaluate the results and choose the suitable parameters:
306 minimum and maximum z values in the data file (zmin_data, zmax_data)
307 and in the interpolated raster map (zmin_int, zmax_int), rescaling
308 parameter used for normalization (dnorm), which influences the tension.
309 If visible connection of segments appears, the program should be rerun
311 with higher npmin to get more points from the neighborhood of given
312 segment and/or with higher tension.
313 When the number of points in a vector map is not too large (less than
315 800), the user can skip segmentation by setting segmax to the number of
316 data points or segmax=700.
317 The program gives warning when user wants to interpolate outside the
319 rectangle given by minimum and maximum coordinates in the vector file,
320 zoom into the area where the given data are is suggested in this case.
321 When a mask is used, the program takes all points in the given region
323 for approximation, including those in the area which is masked out, to
324 ensure proper approximation along the border of the mask. It therefore
325 does not mask out the data points, if this is desirable, it must be
326 done outside v.surf.rst.
327 For examples of applications see GRASS4 implementation and GRASS5 and
329 GRASS6 implementation
330 The user must run g.region before the program to set the region and
332 resolution for approximation.
333
335 v.vol.rst
336
338 Original version of program (in FORTRAN) and GRASS enhancements:
339 Lubos Mitas, NCSA, University of Illinois at Urbana Champaign, Illi‐
340 nois, USA (1990-2000); Department of Physics, North Carolina State Uni‐
341 versity, Raleigh
342 Helena Mitasova, USA CERL, Department of Geography, University of Illi‐
343 nois at Urbana-Champaign, USA (1990-2001); MEAS, North Carolina State
344 University, Raleigh
345 Modified program (translated to C, adapted for GRASS, new segmentation
347 procedure):
348 Irina Kosinovsky, US Army CERL, Dave Gerdes, US Army CERL
349 Modifications for new sites format and timestamping:
351 Darrel McCauley, Purdue University, Bill Brown, US Army CERL
352 Update for GRASS5.7, GRASS6 and addition of crossvalidation: Jaroslav
354 Hofierka, University of Presov; Radim Blazek, ITC-irst
355
357 Mitasova, H., Mitas, L. and Harmon, R.S., 2005, Simultaneous spline
358 approximation and topographic analysis for lidar elevation data in open
359 source GIS, IEEE GRSL 2 (4), 375- 379.
360 Hofierka, J., 2005, Interpolation of Radioactivity Data Using Regular‐
362 ized Spline with Tension. Applied GIS, Vol. 1, No. 2, pp. 16-01 to
363 16-13. DOI: 10.2104/ag050016
364 Hofierka J., Parajka J., Mitasova H., Mitas L., 2002, Multivariate
366 Interpolation of Precipitation Using Regularized Spline with Tension.
367 Transactions in GIS 6(2), pp. 135-150.
368 H. Mitasova, L. Mitas, B.M. Brown, D.P. Gerdes, I. Kosinovsky, 1995,
370 Modeling spatially and temporally distributed phenomena: New methods
371 and tools for GRASS GIS. International Journal of GIS, 9 (4), special
372 issue on Integrating GIS and Environmental modeling, 433-446.
373 Mitasova, H. and Mitas, L., 1993: Interpolation by Regularized Spline
375 with Tension: I. Theory and Implementation, Mathematical Geology ,25,
376 641-655.
377 Mitasova, H. and Hofierka, J., 1993: Interpolation by Regularized
379 Spline with Tension: II. Application to Terrain Modeling and Surface
380 Geometry Analysis, Mathematical Geology 25, 657-667.
381 Mitas, L., and Mitasova H., 1988, General variational approach to the
383 approximation problem, Computers and Mathematics with Applications,
384 v.16, p. 983-992.
385 Neteler, M. and Mitasova, H., 2004, Open Source GIS: A GRASS GIS
387 Approach, Second Edition, Kluwer International Series in Engineering
388 and Computer Science, 773, Kluwer Academic Press / Springer, Boston,
389 Dordrecht, 424 pages.
390 Talmi, A. and Gilat, G., 1977 : Method for Smooth Approximation of
392 Data, Journal of Computational Physics, 23, p.93-123.
393 Wahba, G., 1990, : Spline Models for Observational Data, CNMS-NSF
395 Regional Conference series in applied mathematics, 59, SIAM, Philadel‐
396 phia, Pennsylvania.
397 Last changed: $Date: 2006/11/17 16:23:27 $
399 Full index
401GRASS 6.2.2 v.surf.rst(1)