Provided by: grass-doc_6.4.3-3_all 
NAME
v.vol.rst - Interpolates point data to a 3D raster map using regularized spline with
tension (RST) algorithm.
KEYWORDS
vector, interpolation
SYNOPSIS
v.vol.rst
v.vol.rst help
v.vol.rst [-c] input=string [cellinp=string] [wcolumn=string] [tension=float]
[smooth=float] [scolumn=string] [where=sql_query] [devi=string] [cvdev=string]
[maskmap=string] [segmax=integer] [npmin=integer] [npmax=integer] [dmin=float]
[wmult=float] [zmult=float] [cellout=string] [elev=string] [gradient=string]
[aspect1=string] [aspect2=string] [ncurv=string] [gcurv=string] [mcurv=string]
[--overwrite] [--verbose] [--quiet]
Flags:
-c
Perform a cross-validation procedure without volume interpolation
--overwrite
Allow output files to overwrite existing files
--verbose
Verbose module output
--quiet
Quiet module output
Parameters:
input=string
Name of the vector map with input x,y,z,w
cellinp=string
Name of the surface raster map for cross-section
wcolumn=string
Name of the column containing w attribute to interpolate
Default: flt1
tension=float
Tension parameter
Default: 40.
smooth=float
Smoothing parameter
Default: 0.1
scolumn=string
Name of the column with smoothing parameters
where=sql_query
WHERE conditions of SQL statement without 'where' keyword
Example: income = 10000
devi=string
Output deviations vector point file
cvdev=string
Output cross-validation vector map
maskmap=string
Name of the raster map used as mask
segmax=integer
Maximum number of points in a segment
Default: 50
npmin=integer
Minimum number of points for approximation in a segment (>segmax)
Default: 200
npmax=integer
Maximum number of points for approximation in a segment (>npmin)
Default: 700
dmin=float
Minimum distance between points (to remove almost identical points)
Default: 0.500000
wmult=float
Conversion factor for w-values used for interpolation
Default: 1.0
zmult=float
Conversion factor for z-values
Default: 1.0
cellout=string
Output cross-section raster map
elev=string
Output elevation g3d-file
gradient=string
Output gradient magnitude g3d-file
aspect1=string
Output gradient horizontal angle g3d-file
aspect2=string
Output gradient vertical angle g3d-file
ncurv=string
Output change of gradient g3d-file
gcurv=string
Output gaussian curvature g3d-file
mcurv=string
Output mean curvature g3d-file
DESCRIPTION
v.vol.rst interpolates values to a 3-dimensional raster map from 3-dimensional point data
(e.g. temperature, rainfall data from climatic stations, concentrations from drill holes
etc.) given in a 3-D vector point file named input. The size of the output 3d raster map
elev is given by the current 3D region. Sometimes, the user may want to get a 2-D map
showing a modelled phenomenon at a crossection surface. In that case, cellinp and cellout
options must be specified, with the output 2D raster map cellout containing the
crossection of the interpolated volume with a surface defined by cellinp 2D raster map. As
an option, simultaneously with interpolation, geometric parameters of the interpolated
phenomenon can be computed (magnitude of gradient, direction of gradient defined by
horizontal and vertical angles), change of gradient, Gauss-Kronecker curvature, or mean
curvature). These geometric parameteres are saved as 3d raster maps gradient, aspect1,
aspect2, ncurv, gcurv, mcurv, respectively.
At first, data points are checked for identical positions and points that are closer to
each other than given dmin are removed. Parameters wmult and zmult allow the user to re-
scale the w-values and z-coordinates of the point data (useful e.g. for transformation of
elevations given in feet to meters, so that the proper values of gradient and curvatures
can be computed). Rescaling of z-coordinates (zmult) is also needed when the distances in
vertical direction are much smaller than the horizontal distances; if that is the case,
the value of zmult should be selected so that the vertical and horizontal distances have
about the same magnitude.
Regularized spline with tension method is used in the interpolation. The tension
parameter controls the distance over which each given point influences the resulting
volume (with very high tension, each point influences only its close neighborhood and the
volume goes rapidly to trend between the points). Higher values of tension parameter
reduce the overshoots that can appear in volumes with rapid change of gradient. For noisy
data, it is possible to define a global smoothing parameter, smooth. With the smoothing
parameter set to zero (smooth=0) the resulting volume passes exactly through the data
points. When smoothing is used, it is possible to output a vector map devi containing
deviations of the resulting volume from the given data.
The user can define a 2D raster map named maskmap, which will be used as a mask. The
interpolation is skipped for 3-dimensional cells whose 2-dimensional projection has a zero
value in the mask. Zero values will be assigned to these cells in all output 3d raster
maps.
If the number of given points is greater than 700, segmented processing is used. The
region is split into 3-dimensional "box" segments, each having less than segmax points and
interpolation is performed on each segment of the region. To ensure the smooth connection
of segments, the interpolation function for each segment is computed using the points in
the given segment and the points in its neighborhood. The minimum number of points taken
for interpolation is controlled by npmin , the value of which must be larger than segmax
and less than 700. This limit of 700 was selected to ensure the numerical stability and
efficiency of the algorithm.
EXAMPLES
Spearfish example (we simulate 3D soil range data):
g.region -dp
# define volume
g.region res=50 tbres=50 b=0 t=1500 -ap3
# random elevation extraction (2D)
r.random elevation.10m vector_output=elevrand n=200
# conversion to 3D
v.db.addcol elevrand col="x double precision, y double precision"
v.to.db elevrand option=coor col=x,y
v.db.select elevrand
# create new 3D map
v.in.db elevrand out=elevrand_3d x=x y=y z=value key=cat
v.info -c elevrand_3d
v.info -t elevrand_3d
# remove the now superfluous 'x', 'y' and 'value' (z) columns
v.db.dropcol elevrand_3d col=x
v.db.dropcol elevrand_3d col=y
v.db.dropcol elevrand_3d col=value
# add attribute to interpolate
# (Soil range types taken from the USDA Soil Survey)
d.rast soils.range
d.vect elevrand_3d
v.db.addcol elevrand_3d col="soilrange integer"
v.what.rast elevrand_3d col=soilrange rast=soils.range
# fix 0 (no data in raster map) to NULL:
v.db.update elevrand_3d col=soilrange value=NULL where="soilrange=0"
v.db.select elevrand_3d
# interpolate volume
v.vol.rst elevrand_3d wcol=soilrange elev=soilrange zmult=100
# visualize
nviz elevation.10m vol=soilrange
# export to Paraview
r.out.vtk elevation.10m out=elev.vtk
r3.out.vtk elevrand_3d out=volume.vtk
paraview
SQL support
Using the where parameter, the interpolation can be limited to use only a subset of the
input vectors.
# preparation as in above example
v.vol.rst elevrand_3d wcol=soilrange elev=soilrange zmult=100 where="soilrange > 3"
Cross validation procedure
Sometimes it can be difficult to figure out the proper values of interpolation parameters.
In this case, the user can use a crossvalidation procedure using -c flag (a.k.a. "jack-
knife" method) to find optimal parameters for given data. In this method, every point in
the input point file is temporarily excluded from the computation and interpolation error
for this point location is computed. During this procedure no output grid files can be
simultanuously computed. The procedure for larger datasets may take a very long time, so
it might be worth to use just a sample data representing the whole dataset.
Example (based on Slovakia3d dataset):
v.info -c precip3d
v.vol.rst -c input=precip3d wcolumn=precip zmult=50 segmax=700 cvdev=cvdevmap tension=10
v.db.select cvdevmap
v.univar cvdevmap col=flt1 type=point
Based on these results, the parameters will have to be optimized. It is recommended to
plot the CV error as curve while modifying the parameters.
The best approach is to start with tension, smooth and zmult with rough steps, or to set
zmult to a constant somewhere between 30-60. This helps to find minimal RMSE values while
then finer steps can be used in all parameters. The reasonable range is tension=10...100,
smooth=0.1...1.0, zmult=10...100.
In v.vol.rst the tension parameter is much more sensitive to changes than in v.surf.rst,
therefore the user should always check the result by visual inspection. Minimizing CV does
not always provide the best result, especially when the density of data are insufficient.
Then the optimal result found by CV is an oversmoothed surface.
NOTES
The vector points map must be a 3D vector map (x, y, z as geometry). The module v.in.db
can be used to generate a 3D vector map from a table containing x,y,z columns. Also, the
input data should be in a projected coodinate system, such as Univeral Transverse
Mercator. The module does not appear to have support for geographic (Lat/Long) coordinates
as of May 2009.
v.vol.rst uses regularized spline with tension for interpolation from point data (as
described in Mitasova and Mitas, 1993). The implementation has an improved segmentation
procedure based on Oct-trees which enhances the efficiency for large data sets.
Geometric parameters - magnitude of gradient (gradient), horizontal (aspect1) and vertical
(aspect2) aspects, change of gradient (ncurv), Gauss-Kronecker (gcurv) and mean curvatures
(mcurv) are computed directly from the interpolation function so that the important
relationships between these parameters are preserved. More information on these parameters
can be found in Mitasova et al., 1995 or Thorpe, 1979.
The program gives warning when significant overshoots appear and higher tension should be
used. However, with tension too high the resulting volume will have local maximum in each
given point and everywhere else the volume goes rapidly to trend. With a smoothing
parameter greater than zero, the volume will not pass through the data points and the
higher the parameter the closer the volume will be to the trend. For theory on smoothing
with splines see Talmi and Gilat, 1977 or Wahba, 1990.
If a visible connection of segments appears, the program should be rerun with higher npmin
to get more points from the neighborhood of given segment.
If the number of points in a vector map is less than 400, segmax should be set to 400 so
that segmentation is not performed when it is not necessary.
The program gives a warning when the user wants to interpolate outside the "box" given by
minimum and maximum coordinates in the input vector map. To remedy this, zoom into the
area encompassing the input vector data points.
For large data sets (thousands of data points), it is suggested to zoom into a smaller
representative area and test whether the parameters chosen (e.g. defaults) are
appropriate.
The user must run g.region before the program to set the 3D region for interpolation.
BUGS
devi file is written as 2D and deviations are not written as attributes.
REFERENCES
Hofierka J., Parajka J., Mitasova H., Mitas L., 2002, Multivariate Interpolation of
Precipitation Using Regularized Spline with Tension. Transactions in GIS 6, pp. 135-150.
Mitas, L., Mitasova, H., 1999, Spatial Interpolation. In: P.Longley, M.F. Goodchild, D.J.
Maguire, D.W.Rhind (Eds.), Geographical Information Systems: Principles, Techniques,
Management and Applications, Wiley, pp.481-492
Mitas L., Brown W. M., Mitasova H., 1997, <a
href="http://skagit.meas.ncsu.edu/%7Ehelena/gmslab/lcgfin/cg-mitas.html">Role of dynamic
cartography in simulations of landscape processes based on multi-variate fields. Computers
and Geosciences, Vol. 23, No. 4, pp. 437-446 (includes CDROM and WWW:
www.elsevier.nl/locate/cgvis)
Mitasova H., Mitas L., Brown W.M., D.P. Gerdes, I. Kosinovsky, Baker, T.1995, Modeling
spatially and temporally distributed phenomena: New methods and tools for GRASS GIS.
International Journal of GIS, 9 (4), special issue on Integrating GIS and Environmental
modeling, 433-446.
Mitasova, H., Mitas, L., Brown, B., Kosinovsky, I., Baker, T., Gerdes, D. (1994): <a
href="http://skagit.meas.ncsu.edu/%7Ehelena/gmslab/viz/ches.html">Multidimensional
interpolation and visualization in GRASS GIS
<a href="http://skagit.meas.ncsu.edu/%7Ehelena/gmslab/papers/lmg.rev1.ps">Mitasova H. and
Mitas L. 1993: Interpolation by Regularized Spline with Tension: I. Theory and
Implementation, Mathematical Geology 25, 641-655.
<a href="http://skagit.meas.ncsu.edu/%7Ehelena/gmslab/papers/hmg.rev1.ps">Mitasova H. and
Hofierka J. 1993: Interpolation by Regularized Spline with Tension: II. Application to
Terrain Modeling and Surface Geometry Analysis, Mathematical Geology 25, 657-667.
Mitasova, H., 1992 : New capabilities for interpolation and topographic analysis in GRASS,
GRASSclippings 6, No.2 (summer), p.13.
Wahba, G., 1990 : Spline Models for Observational Data, CNMS-NSF Regional Conference
series in applied mathematics, 59, SIAM, Philadelphia, Pennsylvania.
Mitas, L., Mitasova H., 1988 : General variational approach to the interpolation problem,
Computers and Mathematics with Applications 16, p. 983
Talmi, A. and Gilat, G., 1977 : Method for Smooth Approximation of Data, Journal of
Computational Physics, 23, p.93-123.
Thorpe, J. A. (1979): Elementary Topics in Differential Geometry. Springer-Verlag, New
York, pp. 6-94.
SEE ALSO
g.region, v.in.ascii, r3.mask, v.in.db, v.surf.rst, v.univar
AUTHOR
Original version of program (in FORTRAN) and GRASS enhancements:
Lubos Mitas, NCSA, University of Illinois at Urbana-Champaign, Illinois, USA, since 2000
at Department of Physics, North Carolina State University, Raleigh, USA
lubos_mitas@ncsu.edu
Helena Mitasova, Department of Marine, Earth and Atmospheric Sciences, North Carolina
State University, Raleigh, USA, <a
href="mailto:hmitaso@unity.ncsu.edu">hmitaso@unity.ncsu.edu
Modified program (translated to C, adapted for GRASS, new segmentation procedure):
Irina Kosinovsky, US Army CERL, Champaign, Illinois, USA
Dave Gerdes, US Army CERL, Champaign, Illinois, USA
Modifications for g3d library, geometric parameters, cross-validation, deviations:
Jaro Hofierka, Department of Geography and Regional Development, University of Presov,
Presov, Slovakia, <a href="MAILTO:hofierka@fhpv.unipo.sk">hofierka@fhpv.unipo.sk, <a
href="http://www.geomodel.sk">http://www.geomodel.sk
Last changed: $Date: 2011-11-08 03:29:50 -0800 (Tue, 08 Nov 2011) $
Full index
© 2003-2013 GRASS Development Team