**-c**- Perform a cross-validation procedure without volume interpolation
**--overwrite**- Force overwrite of output files

**input**=*string*- Name of the vector file with input x,y,z,w
**cellinp**=*string*- Name of the surface cell file for cross-section
**wcolumn**=*string*- Name of the column containing w attribute to interpolate
- Default:
*flt1* **scolumn**=*string*- Name of the column with smoothing parameters
**tension**=*float*- Tension parameter
- Default:
*40.* **smooth**=*float*- Smoothing parameter
- Default:
*0.1* **devi**=*string*- Output deviations vector point file
**cvdev**=*string*- Output cross-validation vector file
**maskmap**=*string*- Name of the raster file used as mask
**segmax**=*integer*- Maximum number of points in a segment
- Default:
*50* **dmin**=*float*- Minimum distance between points (to remove almost identical points)
- Default:
*0.500000* **npmin**=*integer*- Minimum number of points for approximation in a segment (>segmax)
- Default:
*200* **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 cell file
**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

*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 vector map *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.

*Example
( Slovakia3d dataset):*

v.info -c precip3d v.vol.rst -c input=precip3d wcolumn=precip segmax=700 cvdev=cvdevmap tension=10 v.db.select cvdevmap v.univar cvdevmap col=flt1 type=point

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*. Usually *tension*=10...20
provide best results. But the user should always check the
result by visual inspection, sometimes CV does not provide the best
results, especially when the density of data are insufficient. Then
the optimal result found by CV is an oversmoothed surface.

*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 vector map 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 vector map, 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 *g.region* before the program to set the
3D region for interpolation.

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

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: 2006/06/16 12:12:37 $*