1v.vol.rst(1) GRASS GIS User's Manual v.vol.rst(1)
2
6 v.vol.rst - Interpolates point data to a 3D raster map using regular‐
7 ized spline with tension (RST) algorithm.
8
10 vector, voxel, surface, interpolation, RST, 3D, no-data filling
11
13 v.vol.rst
14 v.vol.rst --help
15 v.vol.rst [-c] input=name [cross_input=name] [wcolumn=name] [ten‐
16 sion=float] [smooth=float] [smooth_column=name] [where=sql_query]
17 [deviations=name] [cvdev=name] [maskmap=name] [segmax=integer]
18 [npmin=integer] [npmax=integer] [dmin=float] [wscale=float]
19 [zscale=float] [cross_output=name] [elevation=name] [gradi‐
20 ent=name] [aspect_horizontal=name] [aspect_vertical=name] [ncur‐
21 vature=name] [gcurvature=name] [mcurvature=name] [--overwrite]
22 [--help] [--verbose] [--quiet] [--ui]
23 Flags:
25 -c
26 Perform a cross-validation procedure without volume interpolation
27 --overwrite
29 Allow output files to overwrite existing files
30 --help
32 Print usage summary
33 --verbose
35 Verbose module output
36 --quiet
38 Quiet module output
39 --ui
41 Force launching GUI dialog
42 Parameters:
44 input=name [required]
45 Name of input 3D vector points map
46 cross_input=name
48 Name of input surface raster map for cross-section
49 wcolumn=name
51 Name of column containing w-values attribute to interpolate
52 tension=float
54 Tension parameter
55 Default: 40.
56 smooth=float
58 Smoothing parameter
59 Default: 0.1
60 smooth_column=name
62 Name of column with smoothing parameters
63 where=sql_query
65 WHERE conditions of SQL statement without ’where’ keyword
66 Example: income < 1000 and population >= 10000
67 deviations=name
69 Name for output deviations vector point map
70 cvdev=name
72 Name for output cross-validation errors vector point map
73 maskmap=name
75 Name of input raster map used as mask
76 segmax=integer
78 Maximum number of points in a segment
79 Default: 50
80 npmin=integer
82 Minimum number of points for approximation in a segment (>segmax)
83 Default: 200
84 npmax=integer
86 Maximum number of points for approximation in a segment (>npmin)
87 Default: 700
88 dmin=float
90 Minimum distance between points (to remove almost identical points)
91 wscale=float
93 Conversion factor for w-values used for interpolation
94 Default: 1.0
95 zscale=float
97 Conversion factor for z-values
98 Default: 1.0
99 cross_output=name
101 Name for output cross-section raster map
102 elevation=name
104 Name for output elevation 3D raster map
105 gradient=name
107 Name for output gradient magnitude 3D raster map
108 aspect_horizontal=name
110 Name for output gradient horizontal angle 3D raster map
111 aspect_vertical=name
113 Name for output gradient vertical angle 3D raster map
114 ncurvature=name
116 Name for output change of gradient 3D raster map
117 gcurvature=name
119 Name for output Gaussian curvature 3D raster map
120 mcurvature=name
122 Name for output mean curvature 3D raster map
123
125 v.vol.rst interpolates values to a 3-dimensional raster map from 3-di‐
126 mensional point data (e.g. temperature, rainfall data from climatic
127 stations, concentrations from drill holes etc.) given in a 3-D vector
128 point file named input. The size of the output 3D raster map eleva‐
129 tion is given by the current 3D region. Sometimes, the user may want to
130 get a 2-D map showing a modelled phenomenon at a crossection surface.
131 In that case, cross_input and cross_output options must be specified,
132 with the output 2D raster map cross_output containing the crossection
133 of the interpolated volume with a surface defined by cross_input 2D
134 raster map. As an option, simultaneously with interpolation, geometric
135 parameters of the interpolated phenomenon can be computed (magnitude of
136 gradient, direction of gradient defined by horizontal and vertical an‐
137 gles), change of gradient, Gauss-Kronecker curvature, or mean curva‐
138 ture). These geometric parameteres are saved as 3D raster maps gradi‐
139 ent, aspect_horizontal, aspect_vertical, ncurvature, gcurvature, mcur‐
140 vature, respectively. Maps aspect_horizontal and aspect_vertical are in
141 degrees.
142 At first, data points are checked for identical positions and points
144 that are closer to each other than given dmin are removed. Parameters
145 wscale and zscale allow the user to re-scale the w-values and z-coordi‐
146 nates of the point data (useful e.g. for transformation of elevations
147 given in feet to meters, so that the proper values of gradient and cur‐
148 vatures can be computed). Rescaling of z-coordinates (zscale) is also
149 needed when the distances in vertical direction are much smaller than
150 the horizontal distances; if that is the case, the value of zscale
151 should be selected so that the vertical and horizontal distances have
152 about the same magnitude.
153 Regularized spline with tension method is used in the interpolation.
155 The tension parameter controls the distance over which each given point
156 influences the resulting volume (with very high tension, each point in‐
157 fluences only its close neighborhood and the volume goes rapidly to
158 trend between the points). Higher values of tension parameter reduce
159 the overshoots that can appear in volumes with rapid change of gradi‐
160 ent. For noisy data, it is possible to define a global smoothing param‐
161 eter, smooth. With the smoothing parameter set to zero (smooth=0) the
162 resulting volume passes exactly through the data points. When smooth‐
163 ing is used, it is possible to output a vector map deviations contain‐
164 ing deviations of the resulting volume from the given data.
165 The user can define a 2D raster map named maskmap, which will be used
167 as a mask. The interpolation is skipped for 3-dimensional cells whose
168 2-dimensional projection has a zero value in the mask. Zero values will
169 be assigned to these cells in all output 3D raster maps.
170 If the number of given points is greater than 700, segmented processing
172 is used. The region is split into 3-dimensional "box" segments, each
173 having less than segmax points and interpolation is performed on each
174 segment of the region. To ensure the smooth connection of segments, the
175 interpolation function for each segment is computed using the points in
176 the given segment and the points in its neighborhood. The minimum num‐
177 ber of points taken for interpolation is controlled by npmin , the
178 value of which must be larger than segmax and less than 700. This limit
179 of 700 was selected to ensure the numerical stability and efficiency of
180 the algorithm.
181 SQL support
183 Using the where parameter, the interpolation can be limited to use only
184 a subset of the input vectors.
185 # preparation as in above example
186 v.vol.rst elevrand_3d wcol=soilrange elevation=soilrange zscale=100 where="soilrange > 3"
187 Cross validation procedure
189 Sometimes it can be difficult to figure out the proper values of inter‐
190 polation parameters. In this case, the user can use a crossvalidation
191 procedure using -c flag (a.k.a. "jack-knife" method) to find optimal
192 parameters for given data. In this method, every point in the input
193 point file is temporarily excluded from the computation and interpola‐
194 tion error for this point location is computed. During this procedure
195 no output grid files can be simultanuously computed. The procedure for
196 larger datasets may take a very long time, so it might be worth to use
197 just a sample data representing the whole dataset.
198 Example (based on Slovakia3d dataset):
200 v.info -c precip3d
202 g.region n=5530000 s=5275000 w=4186000 e=4631000 res=500 -p
203 v.vol.rst -c input=precip3d wcolumn=precip zscale=50 segmax=700 cvdev=cvdevmap tension=10
204 v.db.select cvdevmap
205 v.univar cvdevmap col=flt1 type=point
206 Based on these results, the parameters will have to be optimized. It is
207 recommended to plot the CV error as curve while modifying the parame‐
208 ters.
209 The best approach is to start with tension, smooth and zscale with
211 rough steps, or to set zscale to a constant somewhere between 30-60.
212 This helps to find minimal RMSE values while then finer steps can be
213 used in all parameters. The reasonable range is tension=10...100,
214 smooth=0.1...1.0, zscale=10...100.
215 In v.vol.rst the tension parameter is much more sensitive to changes
217 than in v.surf.rst, therefore the user should always check the result
218 by visual inspection. Minimizing CV does not always provide the best
219 result, especially when the density of data are insufficient. Then the
220 optimal result found by CV is an oversmoothed surface.
221
223 The vector points map must be a 3D vector map (x, y, z as geometry).
224 The module v.in.db can be used to generate a 3D vector map from a table
225 containing x,y,z columns. Also, the input data should be in a pro‐
226 jected coordinate system, such as Universal Transverse Mercator. The
227 module does not appear to have support for geographic (Lat/Long) coor‐
228 dinates as of May 2009.
229 v.vol.rst uses regularized spline with tension for interpolation from
231 point data (as described in Mitasova and Mitas, 1993). The implementa‐
232 tion has an improved segmentation procedure based on Oct-trees which
233 enhances the efficiency for large data sets.
234 Geometric parameters - magnitude of gradient (gradient), horizontal
236 (aspect_horizontal) and vertical (aspect_vertical)aspects, change of
237 gradient (ncurvature), Gauss-Kronecker (gcurvature) and mean curvatures
238 (mcurvature) are computed directly from the interpolation function so
239 that the important relationships between these parameters are pre‐
240 served. More information on these parameters can be found in Mitasova
241 et al., 1995 or Thorpe, 1979.
242 The program gives warning when significant overshoots appear and higher
244 tension should be used. However, with tension too high the resulting
245 volume will have local maximum in each given point and everywhere else
246 the volume goes rapidly to trend. With a smoothing parameter greater
247 than zero, the volume will not pass through the data points and the
248 higher the parameter the closer the volume will be to the trend. For
249 theory on smoothing with splines see Talmi and Gilat, 1977 or Wahba,
250 1990.
251 If a visible connection of segments appears, the program should be re‐
253 run with higher npmin to get more points from the neighborhood of given
254 segment.
255 If the number of points in a vector map is less than 400, segmax should
257 be set to 400 so that segmentation is not performed when it is not nec‐
258 essary.
259 The program gives a warning when the user wants to interpolate outside
261 the "box" given by minimum and maximum coordinates in the input vector
262 map. To remedy this, zoom into the area encompassing the input vector
263 data points.
264 For large data sets (thousands of data points), it is suggested to zoom
266 into a smaller representative area and test whether the parameters cho‐
267 sen (e.g. defaults) are appropriate.
268 The user must run g.region before the program to set the 3D region for
270 interpolation.
271
273 Spearfish example (we first simulate 3D soil range data):
274 g.region -dp
275 # define volume
276 g.region res=100 tbres=100 res3=100 b=0 t=1500 -ap3
277 ### First part: generate synthetic 3D data (true 3D soil data preferred)
278 # generate random positions from elevation map (2D)
279 r.random elevation.10m vector_output=elevrand n=200
280 # generate synthetic values
281 v.db.addcolumn elevrand col="x double precision, y double precision"
282 v.to.db elevrand option=coor col=x,y
283 v.db.select elevrand
284 # create new 3D map
285 v.in.db elevrand out=elevrand_3d x=x y=y z=value key=cat
286 v.info -c elevrand_3d
287 v.info -t elevrand_3d
288 # remove the now superfluous ’x’, ’y’ and ’value’ (z) columns
289 v.db.dropcolumn elevrand_3d col=x
290 v.db.dropcolumn elevrand_3d col=y
291 v.db.dropcolumn elevrand_3d col=value
292 # add attribute to have data available for 3D interpolation
293 # (Soil range types taken from the USDA Soil Survey)
294 d.mon wx0
295 d.rast soils.range
296 d.vect elevrand_3d
297 v.db.addcolumn elevrand_3d col="soilrange integer"
298 v.what.rast elevrand_3d col=soilrange rast=soils.range
299 # fix 0 (no data in raster map) to NULL:
300 v.db.update elevrand_3d col=soilrange value=NULL where="soilrange=0"
301 v.db.select elevrand_3d
302 # optionally: check 3D points in Paraview
303 v.out.vtk input=elevrand_3d output=elevrand_3d.vtk type=point dp=2
304 paraview --data=elevrand_3d.vtk
305 ### Second part: 3D interpolation from 3D point data
306 # interpolate volume to "soilrange" voxel map
307 v.vol.rst input=elevrand_3d wcol=soilrange elevation=soilrange zscale=100
308 # visualize I: in GRASS GIS wxGUI
309 g.gui
310 # load: 2D raster map: elevation.10m
311 # 3D raster map: soilrange
312 # visualize II: export to Paraview
313 r.mapcalc "bottom = 0.0"
314 r3.out.vtk -s input=soilrange top=elevation.10m bottom=bottom dp=2 output=volume.vtk
315 paraview --data=volume.vtk
316
318 deviations file is written as 2D and deviations are not written as at‐
319 tributes.
320
322 Hofierka J., Parajka J., Mitasova H., Mitas L., 2002, Multivariate In‐
323 terpolation of Precipitation Using Regularized Spline with Tension.
324 Transactions in GISÂ 6, pp. 135-150.
325 Mitas, L., Mitasova, H., 1999, Spatial Interpolation. In: P.Longley,
327 M.F. Goodchild, D.J. Maguire, D.W.Rhind (Eds.), Geographical Informa‐
328 tion Systems: Principles, Techniques, Management and Applications, Wi‐
329 ley, pp.481-492
330 Mitas L., Brown W. M., Mitasova H., 1997, Role of dynamic cartography
332 in simulations of landscape processes based on multi-variate fields.
333 Computers and Geosciences, Vol. 23, No. 4, pp. 437-446 (includes CDROM
334 and WWW: www.elsevier.nl/locate/cgvis)
335 Mitasova H., Mitas L., Brown W.M., D.P. Gerdes, I. Kosinovsky,
337 Baker, T.1995, Modeling spatially and temporally distributed phenomena:
338 New methods and tools for GRASS GIS. International Journal of GIS, 9
339 (4), special issue on Integrating GIS and Environmental modeling,
340 433-446.
341 Mitasova, H., Mitas, L., Brown, B., Kosinovsky, I., Baker, T., Gerdes,
343 D. (1994): Multidimensional interpolation and visualization in GRASS
344 GIS
345 Mitasova H. and Mitas L. 1993: Interpolation by Regularized Spline with
347 Tension: I. Theory and Implementation, Mathematical Geology 25,
348 641-655.
349 Mitasova H. and Hofierka J. 1993: Interpolation by Regularized Spline
351 with Tension: II. Application to Terrain Modeling and Surface Geometry
352 Analysis, Mathematical Geology 25, 657-667.
353 Mitasova, H., 1992 : New capabilities for interpolation and topographic
355 analysis in GRASS, GRASSclippings 6, No.2 (summer), p.13.
356 Wahba, G., 1990 : Spline Models for Observational Data, CNMS-NSF Re‐
358 gional Conference series in applied mathematics, 59, SIAM, Philadel‐
359 phia, Pennsylvania.
360 Mitas, L., Mitasova H., 1988 : General variational approach to the in‐
362 terpolation problem, Computers and Mathematics with Applications 16, p.
363 983
364 Talmi, A. and Gilat, G., 1977 : Method for Smooth Approximation of
366 Data, Journal of Computational Physics, 23, p.93-123.
367 Thorpe, J. A. (1979): Elementary Topics in Differential Geometry.
369 Springer-Verlag, New York, pp. 6-94.
370
372 g.region, v.in.ascii, r3.mask, v.in.db, v.surf.rst, v.univar
373
375 Original version of program (in FORTRAN) and GRASS enhancements:
376 Lubos Mitas, NCSA, University of Illinois at Urbana-Champaign, Illi‐
377 nois, USA, since 2000 at Department of Physics, North Carolina State
378 University, Raleigh, USA lubos_mitas@ncsu.edu
379 Helena Mitasova, Department of Marine, Earth and Atmospheric Sciences,
380 North Carolina State University, Raleigh, USA, hmitaso@unity.ncsu.edu
381 Modified program (translated to C, adapted for GRASS, new segmentation
383 procedure):
384 Irina Kosinovsky, US Army CERL, Champaign, Illinois, USA
385 Dave Gerdes, US Army CERL, Champaign, Illinois, USA
386 Modifications for g3d library, geometric parameters, cross-validation,
388 deviations:
389 Jaro Hofierka, Department of Geography and Regional Development, Uni‐
390 versity of Presov, Presov, Slovakia, hofierka@fhpv.unipo.sk,
391 http://www.geomodel.sk
392
394 Available at: v.vol.rst source code (history)
395 Accessed: Saturday Jan 21 21:16:29 2023
397 Main index | Vector index | Topics index | Keywords index | Graphical
399 index | Full index
400 © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
402GRASS 8.2.1 v.vol.rst(1)