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., eleva-
       tions, 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, topographic parameters
       slope, aspect, profile curvature (measured in the direction of steepest
       slope), tangential curvature (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  respec-
       tively.	 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  interpola-
       tion 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 possi-
       ble to define either a constant smoothing parameter _s_m_o_o_t_h or  a  vari-
       able 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,	repre-
       senting the smoothing 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, segmented pro-
       cessing is used. The region is split into  rectangular  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 rect-
       angular	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 interpola-
       tion on each segment were taken. Anisotropic surfaces can  be  interpo-
       lated  setting  anisotropy  angle  _t_h_e_t_a and scaling factor _s_c_a_l_e_x. The
       program writes several 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-interac-
       tively.	The program will be run non-interactively if the  user	speci-
       fies  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 settings  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 parame-
       ter

       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 counterclockwise)
       to _v_a_l.


       ssccaalleexx = _v_a_l

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


       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  interpolation  from
       point data. Point data should be in a new site format , that means for-
       mat 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  auto-
       matically.

       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 seg-
       ments, 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  coun-
       terclockwise.  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 character.  For
       most landscape scale applications the default should work fine.The pro-
       gram  gives warning when significant overshoots appear in the resulting
       surface and higher tension or smoothing should be used.


       While it is possible to automatize the selection  of  suitable  _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 seg-
       mentation 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 relation  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	multi-
       plied  (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 experi-
       ments).


       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  applica-
       tions  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 direc-
       tion 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 perpendicular
       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 suggested to interpolate  the  log
       of the values rather than the original ones.

       The  program checks the numerical stability of the algorithm by comput-
       ing 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 performed using the  out-
       put deviations option and running s.univar on the site file with devia-
       tions.

       The program writes the values of parameters used  in  computation  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 coordinates 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://skagit.meas.ncsu.edu/~helena/gmslab/viz/


       and http://skagit.meas.ncsu.edu/~helena/gmslab/

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-Champaign,  Illi-
       nois, 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, Indiana, USA

RREEFFEERREENNCCEESS
       Hofierka  J.,  Parajka  J.,   Mitasova H., Mitas L., 2002, Multivariate
       Interpolation of Precipitation Using Regularized Spline	with  Tension.
       _T_r_a_n_s_a_c_t_i_o_n_s _i_n _G_I_S  6(2), 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. Kosinovsky, 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 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, _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  Approximation  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 mathematics, 59, SIAM,  Philadel-
       phia, 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_3_/_0_2_/_0_5 _1_2_:_4_6_:_0_3 _$



GRASS 5.0							 s.surf.rst(1)
