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 regularised 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]]  [[tteenn--
       ssiioonn==_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 interpolated volume with surface defined by input  cell
       file  cceelllliinnpp.  As an option, simultaneously with interpo-
       lation, geometric parameters magnitude of  gradient,  both
       aspects, change of gradient, Gauss-Kronecker curvature, or
       mean curvature are computed and saved as g3d file as spec-
       ified  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 interpola-
       tion.  The  _t_e_n_s_i_o_n  parameter  tunes the character of the
       resulting volume from thin plate to membrane. Higher  val-
       ues  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 smoothing parameter,
       _s_m_o_o_t_h.	 With  the  smoothing  parameter  set	to   zero
       (_s_m_o_o_t_h_=_0) the resulting volume 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,  seg-
       mented  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 inter-
       polation from point data (as  described	in  Mitasova  and
       Mitas, 1993). The implementation has an improved segmenta-
       tion procedure based on Oct-trees which enhances the effi-
       ciency 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 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 _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 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 sug-
       gested to zoom into a smaller representative area and test
       whether	the  parameters chosen (e.g. defaults) are appro-
       priate.

       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 num-
       ber) 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-Cham-
       paign, Illinois, 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.geomodel.sk


RREEFFEERREENNCCEESS
       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.else-
       vier.nl/locate/cgvis)

       Mitasova H., Mitas L.,  Brown W.M.,  D.P. Gerdes, I. Kosi-
       novsky, 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 Kosi-
       novsky, Terry Baker, Dave Gerdes (1994):  Multidimensional
       interpolation and visualization in GRASS GIS

       Mitasova  H.  and Mitas L. 1993: Interpolation by Regular-
       ized 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 Regu-
       larized 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 mathemat-
       ics, 59, SIAM, Philadelphia, Pennsylvania.

       Mitas,  L.,  Mitasova  H.,  1988  :  General   variational
       approach to the interpolation problem, Computers and Math-
       ematics with Applications 16, p. 983

       Talmi, A. and Gilat, G., 1977 : Method for Smooth Approxi-
       mation  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_2_/_0_3_/_0_1 _0_0_:_2_7_:_4_5 _$



GRASS 5.0					     s.vol.rst(1)
