## NAME

v.vol.rst - Interpolates vector point data to a G3D grid volume using regularized spline with tension (RST) algorithm

## SYNOPSIS

v.vol.rst
v.vol.rst help
v.vol.rst [-c] input=string [cellinp=string] [colnum=integer] [tension=float] [smatt=integer] [smooth=float] [devi=string] [cvdev=string] [maskmap=string] [segmax=integer] [dmin=float] [npmin=integer] [wmult=float] [zmult=float] [cellout=string] [elev=string] [gradient=string] [aspect1=string] [aspect2=string] [ncurv=string] [gcurv=string] [mcurv=string]

### Flags:

-c Perform a cross-validation procedure.

### Parameters:

input=string
  Name of the vector points file with input x,y,z,w
cellinp=string
  Name of the surface cell file
colnum=integer
  Column number of w attribute to use for calculation (counting only float type columns)
  Default: 1
tension=float
  Tension
  Default: 40.
smatt=integer
  Which fp point attribute to use for smoothing (or use smooth= for constant)
smooth=float
  Smoothing parameter
  Default: 0.1
devi=string
  Name of the output deviations vector file
cvdev=string
  Name of the output cross-validation vector file
maskmap=string
  Name of the raster file used as mask
segmax=integer
  Max number of points in segment (<=700)
  Default: 50
dmin=float
  Min distance between points (extra points ignored)
  Default: 50.000000
npmin=integer
  Min number of points for interpolation
  Default: 200
wmult=float
  Conversion factor for w-values
  Default: 1.0
zmult=float
  Conversion factor for z-values
  Default: 1.0
cellout=string
  Name of the crossection cell file
elev=string
  Elevation g3d-file
gradient=string
  Gradient magnitude g3d-file
aspect1=string
  G. horizontal angle g3d-file
aspect2=string
  G. vertical angle g3d-file
ncurv=string
  Change of gradient g3d-file
gcurv=string
  Gaussian curvature g3d-file
mcurv=string
  Mean curvature g3d-file

## DESCRIPTION

v.vol.rst interpolates values to a 3-dimensional grid 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 3-D grid g3d file 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 and then the output 2D grid file cellout contains crossection of interpolated volume with surface defined by cellinp 2D grid input file. 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 g3d files gradient, aspect1, aspect2, ncurv, gcurv, mcurv, respectively.

At first, data points are checked for identical points and points that are closer to each other than given dmin are removed. Parameters wmult and zmult allow 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).

Regularized spline with tension method is used in the interpolation. The tension parameter tunes the character of the resulting volume from thin plate to membrane. 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. Also, the user can use a spatially variable smoothing using smatt option by setting the parameter smatt to the value j for the j-th floating point attribute in the input vector point file, representing the smoothing parameter for each point. When smoothing is used, it is possible to output site file devi containing deviations of the resulting volume from the given data.

User can define a 2D raster file named maskmap, which will be used as a mask. The interpolation is skipped for 3-dimensional cells whose 2-dimensional projection has zero value in mask. Zero values will be assigned to these cells in all output g3d files.

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 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.

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.

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 changes its behavior to membrane( rubber sheet stretched over the data points resulting in a peak in each given point and everywhere else the volume goes rapidly to trend). With 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 site file is less then 400, segmax should be set to 400 so that segmentation is not performed when it is not necessary.

The program gives warning when user wants to interpolate outside the "box" given by minimum and maximum coordinates in site file, zoom into the area where the points are is suggested in this case.

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 g3.region before the program to set the region for interpolation.

### Flags:

-c Perform a cross-validation procedure.

### Parameters:

input
  Name of the vector file (format see NOTES below)
colnum
  decimal attribute to use for value w (1=first) options (1-100), default is 1.
cellinp
  Name of the surface cell file to use for crossection
tension
  Tension
  Default: 40
smatt
  Which fp point attribute to use for smoothing (or use smooth= for constant)
smooth
  Smoothing parameter
  Default: 0.1
devi
  Output deviations to a vector file (not yet working, see bugs)
cvdev
  Name of the output cross-validation vector file
maskmap
  Name of the raster file used as mask
segmax
  Max number of points in segment (=700)
  Default: 50
dmin
  Min distance between points (extra points ignored)
  Default: Default value is set to 0.5 cell size.
npmin
  Min number of points for interpolation
  Default: 200
wmult
  Conversion factor for w-values
  Default: 1.0
zmult
  Conversion factor for z-values
  Default: 1.0
cellout
  Name of the crossection cell file
elev
  Elevation g3d-file
gradient
  Gradient g3d-file
aspect1
  Aspect1 g3d-file
aspect2
  Aspect2 g3d-file
ncurv
  Change of gradient g3d-file
gcurv
  Gauss-Kronecker curvature g3d-file
mcurv
  Mean curvature g3d-file

## 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.

## BUGS

devi file is written as 2D and deviations are not written as attributes.

## SEE ALSO

g3.region, s.in.ascii, v.in.ascii, v.vol.idw, r3.mask, v.in.db v.surf.rst

## AUTHOR

Original version of program (in FORTRAN) and GRASS enhancements:
Lubos Mitas, NCSA, University of Illinois at Urbana-Champaign, Illinois, USA,lubos_mitas@ncsu.edu
Helena Mitasova, Department of Marine, Earth and Atmospheric Sciences, North Carolina State University, Raleigh, USA, 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, hofierka@fhpv.unipo.sk, http://www.geomodel.sk

## 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, 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): Multidimensional interpolation and visualization in GRASS GIS

Mitasova H. and Mitas L. 1993: Interpolation by Regularized Spline with Tension: I. Theory and Implementation, Mathematical Geology 25, 641-655.

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.

Last changed: $Date: 2004/12/13 10:04:03 $