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 regularized 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.,  contours,  isolines)  given in a vector file named
       _i_n_p_u_t to grid cells in the output raster file _e_l_e_v  repre-
       senting	a  surface.  As  an  option,  simultaneously with
       interpolation, topographic parameters slope, aspect,  pro-
       file  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 respectively. If _-_d flag is
       set    the    program	outputs    partial    derivatives
       fx,fy,fxx,fyy,fxy  instead of slope, aspect, profile, tan-
       gential 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 output 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 interpola-
       tion. 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, 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 the smooth connection of segments the interpola-
       tion 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 which represent the quad tree used for segmen-
       tation 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 pro-
       gram 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-
       interactively.  The program will be run	non-interactively
       if  the user specifies 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 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

       --rr Zero values in input file represent elevation.

       --cc Category data is used instead of attribute as an eleva-
       tion

       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 surfaces.

       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 distri-
       bution 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 = _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  inter-
       polation  from vector data. Additional points are used for
       interpolation between each 2 points on a line if the  dis-
       tance between them is greater than specified _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 sig-
       nificantly.  The implementation has a segmentation  proce-
       dure  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 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.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 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 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  ten-
       sion=_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 interpo-
       lated  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/short-
       est  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  per-
       pendicular  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  behav-
       ior  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 algo-
       rithm by computating  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
       smoothing effects can be performed using the output devia-
       tions option.

       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.

       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  ten-
       sion.

       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 coordi-
       nates  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://www2.gis.uiuc.edu:2280/modviz/.

       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  Cham-
       paign, Illinois, 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 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.

       H. Mitasova, L. Mitas, B.M. Brown, D.P. Gerdes,	I.  Kosi-
       novsky,	1995,  Modeling  spatially  and  temporally  dis-
       tributed 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 Tension: I. Theory and Implementation, Mathe-
       matical Geology ,25, 641-655.

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

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

       Talmi, A. and Gilat, G., 1977 : Method for Smooth Approxi-
       mation 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	mathemat-
       ics, 59, SIAM, Philadelphia, Pennsylvania.

       _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					    v.surf.rst(1)
