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



NNAAMMEE
       _v_._s_u_r_f_._r_s_t  - interpolation and topographic analysis from given contour
       data in vector format to GRASS floating point raster format using regu-
       larized spline with tension

       (_G_R_A_S_S _V_e_c_t_o_r _P_r_o_g_r_a_m)



SSYYNNOOPPSSIISS
       vv..ssuurrff..rrsstt

       vv..ssuurrff..rrsstt hheellpp

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



DDEESSCCRRIIPPTTIIOONN
       _v_._s_u_r_f_._r_s_t

       This  program  interpolates  the  z-values from vector data (e.g., con-
       tours, isolines) given in a vector file named _i_n_p_u_t to  grid  cells  in
       the  output  raster  file  _e_l_e_v	representing  a surface. 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.	If the input data have time stamp, the
       program creates time stamp for all output files.

       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. NULL values will be assigned to these cells in all  out-
       put  raster  files.  Data  points  are checked for identical points and
       points that are closer to each other than the given _d_m_i_n  are  removed.
       Additional points are used for interpolation between each 2 points on a
       line if the distance between  them  is  greater	than  specified  _d_m_a_x.
       Parameter  _z_m_u_l_t  allows  user to rescale the z-values (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 is used for the interpolation. The _t_e_n_-
       _s_i_o_n parameter tunes the character of the resulting surface  from  thin
       plate to membrane. 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  surface	passes	exactly  through the data points. When
       smoothing parameter 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 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 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 which represent the quad tree used for segmenta-
       tion 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 several important values to history file of raster
       map _e_l_e_v.



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:

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

       Alternately,  the  user	can simply type v..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

       --rr Zero values in input file represent elevation.

       --cc Category data is used instead of attribute as an elevation

       PPaarraammeetteerrss

       iinnppuutt = _n_a_m_e

       Use the existing vector file name as input.

       eelleevv = _n_a_m_e

       Output elevation values to raster file _n_a_m_e.

       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.

       ddmmaaxx = _v_a_l

	Maximum distance between points. Default value is 5 * ddmmiinn..

       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, appropriate  for  smooth  sur-
       faces.

       ssmmooootthh = _v_a_l

       Set smoothing parameter to _v_a_l. Default value is 0.1.

       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 = _n_a_m_e

       Output  overlapping  neighborhoods used for segmentation to vector file
       _n_a_m_e.



NNOOTTEESS
       _v_._s_u_r_f_._r_s_t uses regularized spline with tensionfor  interpolation  from
       vector  data. Additional points are used for interpolation between each
       2 points on a line if the distance between them is greater than	speci-
       fied  _d_m_a_x.  If _d_m_a_x is small (less than cell size) the number of added
       data points can be vary large  and  slow  down  interpolation  signifi-
       cantly.	 The  implementation  has  a  segmentation  procedure based on
       quadtrees which enhances the efficiency	for  large  data  sets.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 is 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.rst): 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
       500 or higher, for detailed field scale analysis it can be 0.1. 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/).


       The program gives warning when significant overshoots appear and higher
       tension should be used. However, with tension too  high	the  resulting
       surface	changes  its behavior to membrane (rubber sheet stretched over
       the data points resulting in a peak or pit  in  each  given  point  and
       everywhere  else the surface goes rapidly to trend). Also smoothing can
       be used to reduce the overshoots.

       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	compu-
       tating  the  values  in	given  points, and prints the root mean square
       deviation (rms) found into the history file of  raster  map  _e_l_e_v.  For
       computation  with  smoothing  set  to  0.  rms should be 0. Significant
       increase in _t_e_n_s_i_o_n 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  smooth-
       ing effects can be performed using the output deviations option.

       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.

       If  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 and/or with higher 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 _s_e_g_m_a_x_=_7_0_0.

       The  program  gives  warning when user wants to interpolate outside the
       rectangle given by minimum and maximum coordinates in the vector  file,
       zoom  into the area where the given data 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 _v_._s_u_r_f_._r_s_t_.

       For	    examples	       of	    applications	   see
       http://skagit.meas.ncsu.edu/~helena/gmslab/.

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



SSEEEE AALLSSOO
       s.surf.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, 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

       Dave Gerdes, US Army CERL

       _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



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.

       H.  Mitasova,  L.  Mitas, B.M. Brown, D.P. Gerdes, I. Kosinovsky, 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.

       Mitasova and Mitas 1993: Interpolation by Regularized Spline with  Ten-
       sion:  I. Theory and Implementation, Mathematical Geology ,25, 641-655.

       Mitasova and Hofierka 1993: Interpolation by  Regularized  Spline  with
       Tension: II. Application to Terrain Modeling and Surface Geometry Anal-
       ysis, Mathematical Geology 25, 657-667.

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

       Talmi, A. and Gilat, G., 1977 :	Method	for  Smooth  Approximation  of
       Data, Journal of Computational Physics, 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.

       _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_4 _$



GRASS 5.0							 v.surf.rst(1)
