s.vol.rst(1)		      Grass User's Manual		  s.vol.rst(1)



NNAAMMEE
       _s_._v_o_l_._r_s_t - Interpolates point data to a G3D grid volume using regular-
       ized spline with tension (RST) algorithm

       _(_G_R_A_S_S _3_D _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       ss..vvooll..rrsstt  iinnppuutt==_n_a_m_e  [[cceelllliinnpp==_n_a_m_e]]   [[ffiieelldd==_v_a_l_u_e]]   [[tteennssiioonn==_v_a_l_u_e]]
       [[ssmmooootthh==_v_a_l_u_e]]  [[ddeevvii=_n_a_m_e]] [[mmaasskkmmaapp== _n_a_m_e]] [[sseeggmmaaxx==_v_a_l_u_e]] [[ddmmiinn==_v_a_l_u_e]]
       [[nnppmmiinn==_v_a_l_u_e]] [[wwmmuulltt==_v_a_l_u_e]]  [[zzmmuulltt==_v_a_l_u_e]]  [[cceelllloouutt==_n_a_m_e]]  [[eelleevv==_n_a_m_e]]
       [[ggrraaddiieenntt==_n_a_m_e]] [[aassppeecctt11==_n_a_m_e]] [[aassppeecctt22==_n_a_m_e]] [[nnccuurrvv==_n_a_m_e]] [[ggccuurrvv==_n_a_m_e]]
       [[mmccuurrvv==_n_a_m_e]]

DDEESSCCRRIIPPTTIIOONN
       _s_._v_o_l_._r_s_t interpolates the values to 3-dimensional grid from point data
       (climatic  stations,  drill  holes etc.) given in a 3D sites file named
       _i_n_p_u_t.  Output g3d file is _e_l_e_v. The 3-dimensional grid is given by the
       current	3D  region.  If  the options _c_e_l_l_i_n_p and _c_e_l_l_o_u_t are specified
       then the output raster file _c_e_l_l_o_u_t contains  crossection  of  interpo-
       lated  volume  with surface defined by input cell file .  As an option,
       simultaneously with interpolation, geometric  parameters  magnitude  of
       gradient,  both aspects, change of gradient, Gauss-Kronecker curvature,
       or mean curvature are computed and saved as g3d file  as  specified  by
       the  options  _g_r_a_d_i_e_n_t_,	_a_s_p_e_c_t_1_,  _a_s_p_e_c_t_2_, _n_c_u_r_v_, _g_c_u_r_v_, _m_c_u_r_v respec-
       tively.

       At first, data points are checked for identical points and points  that
       are  closer to each other than given _d_m_i_n are removed. Parameters _w_m_u_l_t
       and _z_m_u_l_t allow user to re-scale the w-values and  z-values  for  sites
       (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 is used for the interpolation. The _t_e_n_-
       _s_i_o_n parameter tunes the character of the resulting  volume  from  thin
       plate  to membrane. Higher values of tension parameter reduce the over-
       shoots that can	appear in volumes with rapid change of	gradient.  For
       noisy  data,  it  is possible  to define a smoothing parameter, _s_m_o_o_t_h.
       With the smoothing parameter  set to zero (_s_m_o_o_t_h_=_0) the resulting vol-
       ume passes exactly through  the data points. When smoothing is used, it
       is  possible to output site file  _d_e_v_i  containing  deviations  of  the
       resulting volume from the given data.

       User can define a 2D raster file named _m_a_s_k_m_a_p, 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 _s_e_g_m_a_x 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 _n_p_m_i_n ,  the  value
       of  which  must be larger than _s_e_g_m_a_x  and less than 700. This limit of
       700 was selected to ensure the numerical  stability and	efficiency  of
       the algorithm.

       _s_._v_o_l_._r_s_t  uses	regularized spline with tension for interpolation from
       point data (as described in Mitasova and Mitas, 1993). The  implementa-
       tion  has  an  improved segmentation procedure based on Oct-trees which
       enhances the efficiency for large data sets.

       Geometric parameters - magnitude  of  gradient  (_g_r_a_d_i_e_n_t),  horizontal
       (_a_s_p_e_c_t_1)  and  vertical (_a_s_p_e_c_t_2_) aspects, change of gradient (_n_c_u_r_v),
       Gauss-Kronecker	(_g_c_u_r_v)  and  mean  curvatures	(_m_c_u_r_v)  are  computed
       directly  from  the  interpolation function so that the important rela-
       tionships 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  _n_p_m_i_n  to get more points from the neighborhood of
       given segment.

       If the number of points in a site file is less then 400, _s_e_g_m_a_x	should
       be set to 400 so that segmentation is not performed when it is not nec-
       essary.

       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 cho-
       sen (e.g. defaults) are appropriate.

       The user must run _g_3_._r_e_g_i_o_n before the program to set  the  region  for
       interpolation.

   PPaarraammeetteerrss::
       iinnppuutt
	   Name of the site file (format see NOTES below)

       field
	   decimal  attribute  to  use	for value w (1=first) options (1-100),
	   default is 1.

       cceelllliinnpp
	   Name of the surface cell file to use for crossection

       tteennssiioonn
	   Tension Default: 40

       ssmmooootthh
	   Smoothing parameter Default: 0.1

       ddeevvii
	   Output deviations to a site file

       mmaasskkmmaapp
	   Name of the raster file used as mask

       sseeggmmaaxx
	   Max number of points in segment (=700) Default: 50

       ddmmiinn
	   Min distance between points (extra points ignored) Default: Default
	   value is set to 0.5 cell size.

       nnppmmiinn
	   Min number of points for interpolation Default: 200

       wwmmuulltt
	   Conversion factor for w-values Default: 1.0

       zzmmuulltt
	   Conversion factor for z-values Default: 1.0

       cceelllloouutt
	   Name of the crossection cell file

       eelleevv
	   Elevation g3d-file

       ggrraaddiieenntt
	   Gradient g3d-file

       aassppeecctt11
	   Aspect1 g3d-file

       aassppeecctt22
	   Aspect2 g3d-file

       nnccuurrvv
	   Change of gradient g3d-file

       ggccuurrvv
	   Gauss-Kronecker curvature g3d-file

       mmccuurrvv
	   Mean curvature g3d-file


NNOOTTEESS
       The sites volume format is as follows:


	   with x,y,z (spatial coordinates), n (optional integer number) and w
       (data
	values).


SSEEEE AALLSSOO
       g3.region,
       s.in.ascii,
       s.vol.idw,
       r3.mask,
       s.surf.rst


AAUUTTHHOORR
       Original version of program (in FORTRAN) and GRASS enhancements:

	  Lubos Mitas, NCSA, University of Illinois at Urbana-Champaign, Illi-
       nois,
	USA,lubos_mitas@ncsu.edu

	  Helena  Mitasova, Department of Geography, University of Illinois at
       Urbana-Champaign,
	Champaign, Illinois, 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, deviations:

	  Jaro Hofierka, GeoModel s.r.o., Bratislava, Slovakia, <a
	href="MAILTO:hofierka@geomodel.sk">hofierka@geomodel.sk, <a
	href="http://www.geomodel.sk">http://www.geomodel.sk




RREEFFEERREENNCCEESS
       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, Tech-
       niques,
	Management and Applications, Wiley, pp.481-492


       Mitas L., Brown W. M., Mitasova H., 1997, <a
	href="http://skagit.meas.ncsu.edu/~helena/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 phenom-
       ena:
       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 Ten-
       sion:
	I. Theory and Implementation, _M_a_t_h_e_m_a_t_i_c_a_l _G_e_o_l_o_g_y 25, 641-655.


       Mitasova
	H. and Hofierka J. 1993: Interpolation by Regularized Spline with Ten-
       sion:
	II.  Application  to  Terrain  Modeling and Surface Geometry Analysis,
       _M_a_t_h_e_m_a_t_i_c_a_l
	_G_e_o_l_o_g_y 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.


       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_3_/_0_8_/_2_0 _0_8_:_1_0_:_1_3 _$








GRASS 5.0							  s.vol.rst(1)
