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



NNAAMMEE
       s.vol.rst  -  Interpolates  point data to a G3D grid volume using regu-
       larised splines with tension (RST) algorithm

       _(_G_R_A_S_S _3_D _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       s.vol.rst  input=_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]]	  [[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.vol.rst 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 cceelllliinnpp and cceelllloouutt are specified
       then the output raster file cceelllloouutt contains  crossection  of  interpo-
       lated  volume  with  surface defined by input cell file cceelllliinnpp.  As an
       option, simultaneously with interpolation, geometric parameters	magni-
       tude  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 respectively.

       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.

       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 400, 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 400. This limit of 400
       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

       mmaasskkmmaapp
	   Name of the raster file used as mask

       sseeggmmaaxx
	   Max number of points in segment (=400) 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:

	  x|y|z|#n %w1 %w2 %w3

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

SSEEEE AALLSSOO
       _g_3_._r_e_g_i_o_n_, _s_._i_n_._a_s_c_i_i_, _s_._v_o_l_._i_d_w_, _r_3_._m_a_s_k

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:

       Jaro  Hofierka,	GeoModel s.r.o., Bratislava, Slovakia, http://www.geo-
       model.sk


RREEFFEERREENNCCEESS
       Hofierka J., J. Parajka, H.  Mitasova, and L. Mitas, 2002.   Multivari-
       ate  Interpolation  of Precipitation Using Regularized Spline with Ten-
       sion.  Transactions in GIS, March 2002, vol. 6, no. 2, pp. 135-150

       Mitas, L., Mitasova, H., 1999, Spatial  Interpolation.  In:  P.Longley,
       M.F.  Goodchild,  D.J. Maguire, D.W.Rhind (Eds.), Geographical Informa-
       tion 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.


       Helena  Mitasova,  Lubos  Mitas,  Bill  Brown,  Irina Kosinovsky, Terry
       Baker, Dave Gerdes (1994): Multidimensional interpolation  and  visual-
       ization in GRASS GIS

       Mitasova  H.   and  Mitas  L. 1993: Interpolation by Regularized Spline
       with Tension: 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 Tension: 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, Philadel-
       phia, 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_2_/_0_5 _1_2_:_4_6_:_0_3 _$



GRASS 5.0							  s.vol.rst(1)
