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



NNAAMMEE
       _s_._s_u_r_f_._r_s_t-  interpolation  and	topographic analysis from
       given site data to  GRASS  floating  point  raster  format
       using   regularized  spline  with  tension  (this  program
       replaces _s_._s_u_r_f_._t_p_s)


       _(_G_R_A_S_S _S_i_t_e _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       ss..ssuurrff..rrsstt

       ss..ssuurrff..rrsstt hheellpp

       ss..ssuurrff..rrsstt  [[--dd]]  [[--tt]]	iinnppuutt  =  name	[eelleevv	=   name]
       [ffiieelldd=val]  [ssllooppee = name] [aassppeecctt = name] [ppccuurrvv = name]
       [ttccuurrvv = name] [mmccuurrvv = name] [mmaasskkmmaapp  =  name]  [ddmmiinn	=
       val]  [zzmmuulltt  ==	val]  [tteennssiioonn	=  val]  [ssmmooootthh  =  val]
       [ssmmaatttt==val] [sseeggmmaaxx == val] [nnppmmiinn =  val]  [tthheettaa  =  val]
       [ssccaalleexx = val] [ddeevvii = name] [ttrreeeeffiillee = name] [oovveerrffiillee =
       name]

DDEESSCCRRIIPPTTIIOONN
       _s_._s_u_r_f_._r_s_t

       This program interpolates the zi-values	from  point  data
       (e.g.,  elevations,  climatic stations, drill holes, etc.)
       given in a sites file named _i_n_p_u_t as x|y|%z1 %z2 ...%zi...
       to  grid cells in the output raster file _e_l_e_v representing
       a surface.  The	user  can  select  which  floating  point
       attribute  will	be  interpolated by setting the parameter
       _f_i_e_l_d  to  the  value  i  for  the  i-th  floating   point
       attribute..

       As  an  option,	simultaneously	with interpolation, topo-
       graphic parameters slope, aspect, profile curvature  (mea-
       sured in the direction of steepest slope), tangential cur-
       vature (measured in the direction of a tangent to  contour
       line)  or  mean curvature are computed and saved as raster
       files specified	by  the  options  _s_l_o_p_e_,  _a_s_p_e_c_t_,  _p_c_u_r_v_,
       _t_c_u_r_v_,  _m_c_u_r_v respectively.  If _-_d flag is set the program
       outputs partial derivatives fx, fy, fxx, fyy, fxy  instead
       of  slope, aspect, profile, tangential and mean curvatures
       respectively.

       User can define a raster file named _m_a_s_k_m_a_p, which will be
       used  as  a  mask.  The interpolation is skipped for cells
       which have zero or NULL value in  mask.	Data  points  are
       checked	for  identical	points	and  the  points that are
       closer to each other than  the  given  _d_m_i_n  are  removed.
       Parameter  _z_m_u_l_t  allows  user to rescale the z-values for
       sites (useful e.g. for transformation of elevations  given
       in feet to meters, so that the proper values of slopes and
       curvatures can be computed).

       Regularized spline with tension and smoothing is used  for
       interpolation  and  approximation.  The	_t_e_n_s_i_o_n parameter
       tunes the character of the  resulting  surface  from  thin
       plate  to membrane. The experimental flag _-_t can be set to
       use "dnorm  independent	tension",  (see  notes	for  more
       details about the tension behavior). For noisy data, it is
       possible to define either a constant  smoothing	parameter
       _s_m_o_o_t_h  or  a variable smoothing parameter by  setting the
       parameter _s_m_a_t_t to the value j for the j-th floating point
       attribute in the _i_n_p_u_t site file, representing the smooth-
       ing parameter for each point. When smoothing is	used,  it
       is possible to output site file _d_e_v_i containing deviations
       of the resulting surface from the given data.

       If the number of given points is greater than _s_e_g_m_a_x, seg-
       mented  processing is used. The region is split into rect-
       angular segments, each having less than _s_e_g_m_a_x points  and
       interpolation  is performed on each segment of the region.
       To ensure smooth connection of segments the  interpolation
       function  for each segment is computed using the points in
       given segment and the points in its neighborhood which are
       in  the	rectangular window surrounding the given segment.
       The 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.
       User can choose to output vector files _t_r_e_e_f_i_l_e and  _o_v_e_r_-
       _f_i_l_e  which  represent the quad tree used for segmentation
       and overlapping neighborhoods from which additional points
       for  interpolation on each segment were taken. Anisotropic
       surfaces can  be  interpolated  setting	anisotropy  angle
       _t_h_e_t_a  and  scaling factor _s_c_a_l_e_x. The program writes sev-
       eral important values to history file of raster map  _e_l_e_v.
       If  the	input  data  have time stamp, the program creates
       time stamp for all output files.

       The user must run _g_._r_e_g_i_o_n before the program to  set  the
       region and resolution for interpolation.



OOPPTTIIOONNSS
       The user can run this program either interactively or non-
       interactively.  The program will be run	non-interactively
       if  the user specifies program arguments and flag settings
       on the command line using the form:

       ss..ssuurrff..rrsstt [[--dd]] [[--tt]] iinnppuutt = name eelleevv = name  [ffiieelldd=val]
       [ ssllooppee = name] [ aassppeecctt = name] [ ppccuurrvv = name] [ ttccuurrvv =
       name] [ mmccuurrvv = name] [ mmaasskkmmaapp = name] [ ddmmiinn  =  val]	[
       zzmmuulltt  == val] [ tteennssiioonn = val] [ ssmmooootthh = val] [ssmmaatttt=val]
       [ sseeggmmaaxx == val] [ nnppmmiinn = val] [ tthheettaa = val ] [ ssccaalleexx	=
       val ] [ ddeevvii = name] [ ttrreeeeffiillee = name] [= name]

       Alternately,  the  user	can simply type ss..ssuurrff..rrsstt on the
       command line without program arguments. In this case,  the
       user  will  be prompted for parameter values and flag set-
       tings using the standard GRASS parser interface	described
       in the manual entry for _p_a_r_s_e_r.

       FFllaaggss

       --dd Output partial derivatives instead of aspect, slope and
       curvatures.


       --tt  Use dnorm independent tension (experimental)

       PPaarraammeetteerrss::

       iinnppuutt = _n_a_m_e

       Use the existing site file name as input.

       eelleevv = _n_a_m_e

       Output elevation values to raster file _n_a_m_e.

       ffiieelldd=_v_a_l

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

       ssllooppee = _n_a_m_e

       Output slope or dx values to raster file _n_a_m_e.

       aassppeecctt = _n_a_m_e

       Output aspect or dy values to raster file _n_a_m_e.

       ppccuurrvv = _n_a_m_e

       Output  profile	curvature  or  dxx  values to raster file
       _n_a_m_e.

       ttccuurrvv = _n_a_m_e

       Output tangential curvature or dyy values to  raster  file
       _n_a_m_e.

       mmccuurrvv = _n_a_m_e

       Output mean curvature or dxy values to raster file _n_a_m_e.

       mmaasskkmmaapp = _n_a_m_e

       Use the existing raster file _n_a_m_e as a mask.

       ddmmiinn = _v_a_l

       Set  min  distance between points to _v_a_l. Default value is
       set to 0.5 grid cell size.

       zzmmuulltt = _v_a_l

       Convert z-values  using	conversion  factor  _v_a_l.  Default
       value is 1.

       tteennssiioonn =_v_a_l

       Set tension to _v_a_l. Default value is 40.

       ssmmooootthh = _v_a_l

       Set smoothing parameter to _v_a_l. Default value is 0.1.

       ssmmaatttt=_v_a_l

       order  of  floating  point  attribute  to use for variable
       smoothing parameter

       sseeggmmaaxx = _v_a_l

       Set max number of points per segment to _v_a_l. Default value
       is 40.

       nnppmmiinn = _v_a_l

       Set min number of points for interpolation to _v_a_l. Default
       value  is  200,	for  data  with   heterogeneous   spatial
       distribution higher value is suggested (see notes).

       tthheettaa = _v_a_l

       Set  anisotropy angle in degrees (measured from East coun-
       terclockwise) to _v_a_l.


       ssccaalleexx = _v_a_l

       Set anisotropy scaling factor to _v_a_l. Values 0 and 1  give
       no anisotropy.


       ddeevvii = _n_a_m_e

       Output deviations to a site file _n_a_m_e.

       ttrreeeeffiillee = _n_a_m_e

       Output quad tree used for segmentation to vector file _n_a_m_e

       oovveerrffiillee = name


       Output overlapping neighborhoods used for segmentation  to
       vector file _n_a_m_e.



NNOOTTEESS
       _s_._s_u_r_f_._r_s_tuses regularized spline with tensionfor interpo-
       lation from point data. Point data should be in a new site
       format  , that means format x|y|%z1 %z2 ...%zi..., instead
       of the old format which confused  categories  with  values
       (x|y|#z).  If program detects the old format it will allow
       users to have the site file  rewritten  to  a  new  format
       automatically.

       The  implementation  has a segmentation procedure based on
       quadtrees which enhances the  efficiency  for  large  data
       sets. The GRASS5.0 version has enhanced segmentation which
       takes more points for the large segments,  to  reduce  the
       potential  for  visibility  of  segmentens  in  areas with
       sparse data.

       Special color tables are created by the program for output
       raster files.

       Topographic  parameters	are  computed  directly  from the
       interpolation function so that the important relationships
       between	these parameters are preserved. The equations for
       computation of these parameters and  their  interpretation
       are described in (Mitasova and Hofierka 1993 ). Slopes and
       aspect are computed in degrees  (0-90  and  1-360  respec-
       tively).  The  aspect  raster file has value 0 assigned to
       flat areas (with slope less than  0.1%)	and  to  singular
       points  with undefined aspect. Aspect points downslope and
       is 90 to the North, 180 to the West, 270 to the South  and
       360  to	the  East,  the values increase counterclockwise.
       Curvatures are positive for convex and negative	for  con-
       cave areas. Singular points with undefined curvatures have
       assigned zero values.

       _T_e_n_s_i_o_n and _s_m_o_o_t_hing allow user to tune the surface char-
       acter.	For most landscape scale applications the default
       should work fine.The program gives warning  when  signifi-
       cant overshoots appear in the resulting surface and higher
       tension or smoothing should be used.


       While it is possible to automatize the selection of  suit-
       able  _t_e_n_s_i_o_n  and _s_m_o_o_t_hing, it has not been done yet, so
       here are some hints which may help to  choose  the  proper
       parameters  if  the results look "weird".  It is useful to
       know that the method is scale dependent	and  the  _t_e_n_s_i_o_n
       works  as  a  rescaling parameter (high _t_e_n_s_i_o_n "increases
       the distances between the points" and reduces the range of
       impact of each point, low _t_e_n_s_i_o_n "decreases the distance"
       and the points influence each other  over  longer  range).
       Surface with  _t_e_n_s_i_o_n set too high behaves like a membrane
       (rubber sheet stretched over the data points) with peak or
       pit ("crater") in each given point and everywhere else the
       surface goes rapidly to trend. If digitized  contours  are
       used  as  input	data,  high  tension can cause artificial
       waves along contours. Lower tension and	higher	smoothing
       is suggested for such a case.


       Surface	with  _t_e_n_s_i_o_n  set  too  low behaves like a stiff
       steel plate and overshoots can appear in areas with  rapid
       change  of  gradient  and  segmentation	can  be  visible.
       Increase tension should solve the problems.

       There are two options how _t_e_n_s_i_o_n can be applied in  rela-
       tion to _d_n_o_r_m (dnorm rescales the coordinates depending on
       the average data density so that the size of segments with
       _s_e_g_m_a_x_=40  points is around 1 - this ensures the numerical
       stability of the computation):

       1. Default (used also in s.surf.tps): the given _t_e_n_s_i_o_n is
       applied	to  normalized data (x/_d_n_o_r_m..),  that means that
       the distances are multiplied (rescaled) by  _t_e_n_s_i_o_n_/_d_n_o_r_m.
       If  density  of	points is changed, e.g.,  by using higher
       _d_m_i_n, the _d_n_o_r_m changes and _t_e_n_s_i_o_n needs  to  be  changed
       too  to	get  the  same	result.   Because  the _t_e_n_s_i_o_n is
       applied to normalized data its suitable value  is  usually
       within  the 10-100 range and does not depend on the actual
       scale (distances) of the original data (which  can  be  km
       for regional applications or cm for field experiments).


       2.  Flag  --tt (experimental for s.surf.rst):: The given _t_e_n_-
       _s_i_o_n is applied to un-normalized data (rescaled tension	=
       t_e_n_s_i_o_n_*_d_n_o_r_m/1000 is applied to normalized data (x/_d_n_o_r_m)
       and therefore  _d_n_o_r_m cancels out) so  here  _t_e_n_s_i_o_n  truly
       works as a rescaling parameter.	For regional applications
       with distances between points in km the	suitable  tension
       can  be	0.1 or smaller, for detailed field scale analysis
       with distances in cm it can be 500 or more. To help select
       how  much  the data need to be rescaled the program writes
       _d_n_o_r_m  and  rescaled  tension=_t_e_n_s_i_o_n_*_d_n_o_r_m/1000  at   the
       beginning of the program run. This rescaled _t_e_n_s_i_o_n should
       be around 20-30.  If it is lower or higher, the given _t_e_n_-
       _s_i_o_n parameter should be changed accordingly.

       The  default  is  a  recommended  choice,  however for the
       applications where the user needs  to  change  density  of
       data  and preserve the interpolation character the --tt flag
       can be helpful.

       Anisotropic  data  (e.g.  geologic   phenomena)	 can   be
       interpolated  using  _t_h_e_t_a and _s_c_a_l_e_x defining orientation
       and  ratio  of  the  perpendicular   axes   put	 on   the
       longest/shortest side of the feature, respectively.  _T_h_e_t_a
       is measured in degrees from East, counterclockwise. _S_c_a_l_e_x
       is  a  ratio  of  axes sizes.  Setting _s_c_a_l_e_x in the range
       0-1, you will  get  pattern  prolonged  in  the	direction
       defined by _t_h_e_t_a. _S_c_a_l_e_x value 0.5 means that your feature
       is approximatelly 2 times longer in the direction of _t_h_e_t_a
       than in the perpendicular direction.  _S_c_a_l_e_x value 2 means
       that axes ratio is reverse and you will get  pattern  per-
       pendicular  to  the  previous  example.	Please	note that
       anisotropy option has not been extensively tested and  may
       include	bugs  -  if  there are problems, please report to
       GRASS bugtracker (accessible from http://grass.itc.it/).


       For data with  values  changing	over  several  magnitudes
       (sometimes  the	concentration or density data) it is sug-
       gested to interpolate the log of the  values  rather  than
       the original ones.

       The  program  checks  the numerical stability of the algo-
       rithm by computing the values in given  points.	The  root
       mean square deviation (rms) between interpolated and given
       values is written into the  history  file  of  raster  map
       _e_l_e_v.  For  computation	with  smoothing set to 0. the rms
       should be 0. Significant increase in tension is	suggested
       if  the	rms  is  unexpectedly  high  for  this case. With
       smoothing parameter greater than zero the surface will not
       pass  exactly  through  the data points and the higher the
       parameter the closer the surface will be to the trend. The
       rms then represents a measure of smoothing effect on data.
       More detailed analysis of smoothing effects  can  be  per-
       formed  using  the  output  deviations  option and running
       s.univar on the site file with deviations.

       The program writes the values of parameters used in compu-
       tation  into the comment part of history file _e_l_e_v as well
       as the following values which help to evaluate the results
       and  choose the suitable parameters: minimum and maximum z
       values in the data file (zmin_data, zmax_data) and in  the
       interpolated  raster  map  (zmin_int, zmax_int), rescaling
       parameter used for normalization (dnorm), which influences
       the tension.

       When  the number of points in a site file is not too large
       (less than 800), the user can skip segmentation by setting
       _s_e_g_m_a_x to the number of data points or segmax=700.

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

       When a mask is used, the program takes all points  in  the
       given  region  for  interpolation,  including those in the
       area which is masked out, to ensure  proper  interpolation
       along  the  border of the mask. It therefore does not mask
       out the data points, if this is desirable, it must be done
       outside s.surf.rst (e.g. using r.mask.points).

       For	  examples	  of	   applications       see
       http://www2.gis.uiuc.edu:2280/modviz/viz/


       and http://www2.gis.uiuc.edu:2280/modviz/

SSEEEE AALLSSOO
       r.slope.aspect, r.surf.idw , r.surf.idw2 ,  r.surf.contour
       , s.surf.idw , v.to.sites , g.region , r.mask , v.surf.rst
       , r.resamp.rst

AAUUTTHHOORRSS
       _O_r_i_g_i_n_a_l  _v_e_r_s_i_o_n  _o_f  _p_r_o_g_r_a_m  _(_i_n  _F_O_R_T_R_A_N_)  _a_n_d   _G_R_A_S_S
       _e_n_h_a_n_c_e_m_e_n_t_s_:

       Lubos  Mitas, NCSA, University of Illinois at Urbana-Cham-
       paign, Illinois, USA


       Helena Mitasova, Department of  Geography,  University  of
       Illinois at Urbana-Champaign, Champaign, Illinois, USA

       _M_o_d_i_f_i_e_d  _p_r_o_g_r_a_m _(_t_r_a_n_s_l_a_t_e_d _t_o _C_, _a_d_a_p_t_e_d _f_o_r _G_R_A_S_S_, _n_e_w
       _s_e_g_m_e_n_t_a_t_i_o_n _p_r_o_c_e_d_u_r_e_)_:

       Irina Kosinovsky, US Army CERL, Champaign, Illinois, USA


       Dave Gerdes, US Army CERL, Champaign, Illinois, USA

       _M_o_d_i_f_i_c_a_t_i_o_n_s _f_o_r _n_e_w _s_i_t_e_s _f_o_r_m_a_t _a_n_d _t_i_m_e_s_t_a_m_p_i_n_g_:

       Darrel McCauley, Purdue University, West Laffayette, Indi-
       ana, USA

RREEFFEERREENNCCEESS
       Hofierka  J.,  Parajka  J.,   Mitasova H., Mitas L., 2002,
       Multivariate Interpolation of Precipitation Using Regular-
       ized  Spline  with  Tension.   _T_r_a_n_s_a_c_t_i_o_n_s _i_n _G_I_S  6, pp.
       135-150.

       Mitas, L., Mitasova, H., 1999, Spatial Interpolation.  In:
       P.Longley,   M.F.    Goodchild,	D.J.  Maguire,	D.W.Rhind
       (Eds.),	_G_e_o_g_r_a_p_h_i_c_a_l  _I_n_f_o_r_m_a_t_i_o_n  _S_y_s_t_e_m_s_:   _P_r_i_n_c_i_p_l_e_s_,
       _T_e_c_h_n_i_q_u_e_s_, _M_a_n_a_g_e_m_e_n_t _a_n_d _A_p_p_l_i_c_a_t_i_o_n_s, Wiley, pp.481-492

       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. _I_n_t_e_r_n_a_t_i_o_n_a_l _J_o_u_r_n_a_l _o_f _G_I_S, 9 (4), special issue on
       Integrating GIS and Environmental modeling, 433-446.

       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, _G_R_A_S_S_c_l_i_p_p_i_n_g_s 6,  No.2
       (summer), p.13.

       Mitas,	L.,  Mitasova  H.,  1988  :  General  variational
       approach to the interpolation problem, _C_o_m_p_u_t_e_r_s _a_n_d _M_a_t_h_-
       _e_m_a_t_i_c_s _w_i_t_h _A_p_p_l_i_c_a_t_i_o_n_s 16, p. 983

       Talmi, A. and Gilat, G., 1977 : Method for Smooth Approxi-
       mation of Data,	_J_o_u_r_n_a_l  _o_f  _C_o_m_p_u_t_a_t_i_o_n_a_l  _P_h_y_s_i_c_s,  23,
       p.93-123.

       Wahba,  G.,  1990, : Spline Models for Observational Data,
       CNMS-NSF Regional Conference series in  applied	mathemat-
       ics, 59, SIAM, Philadelphia, Pennsylvania.



       Updated April 2, 2002 by Jaro Hofierka and Helena Mitasova

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_4_/_1_6 _1_4_:_5_9_:_2_0 _$



GRASS 5.0					    s.surf.rst(1)
