## NAME

v.surf.rst - interpolation and topographic analysis from given contour data in vector format to GRASS floating point raster format using regularized spline with tension
(GRASS Vector Program)

## SYNOPSIS

v.surf.rst
v.surf.rst help
v.surf.rst [-d] [-r] [-c] [-t] input = name elev = name [ slope = name] [ aspect = name] [ pcurv = name] [ tcurv = name] [ mcurv = name] [ maskmap = name] [ dmin = val] [ dmax = val] [ zmult = val] [ tension = val] [ smooth = val] [ segmax = val] [ npmin = val] [ theta = val ] [ scalex = val ] [ devi = name] [ treefile = name] [= name]

## DESCRIPTION

v.surf.rst
This program interpolates the z-values from vector data (e.g., contours, isolines) given in a vector file named input to grid cells in the output raster file elev 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 slope, aspect, pcurv, tcurv, mcurv 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. If the input data have time stamp, the program creates time stamp for all output files.

User can define a raster file named maskmap, 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 dmin are removed. Additional points are used for interpolation between each 2 points on a line if the distance between them is greater than specified dmax. Parameter zmult 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 tension parameter tunes the character of the resulting surface from thin plate to membrane. For noisy data, it is possible to define a smoothing parameter smooth. With the smoothing parameter set to zero (smooth=0) the resulting surface passes exactly through the data points. When smoothing parameter is used, it is possible to output site file devi containing deviations of the resulting surface from the given data.

If the number of given points is greater than segmax, segmented processing is used . The region is split into rectangular segments, each having less than segmax 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 rectangular window surrounding the given segment. The number of points taken for interpolation is controlled by npmin, the value of which must be larger than segmax . User can choose to output vector files treefile and overfile 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 theta and scaling factor scalex. The program writes several important values to history file of raster map elev.

## OPTIONS

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:

v.surf.rst [-d] [-r] [-c] [-t] input = name elev = name [ slope = name] [ aspect = name] [ pcurv = name] [ tcurv = name] [ mcurv = name] [ maskmap = name] [ dmin = val] [ dmax = val] [ zmult = val] [ tension = val] [ smooth = val] [ segmax = val] [ npmin = val] [ theta = val ] [ scalex = val ] [ devi = name] [ treefile = name] [= name]

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

Flags:

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

-t Use dnorm independent tension

-r Zero values in input file represent elevation.

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

Parameters

input = name
Use the existing vector file name as input.

elev = name
Output elevation values to raster file name.

slope = name
Output slope or dx values to raster file name.

aspect = name
Output aspect or dy values to raster file name.

pcurv = name
Output profile curvature or dxx values to raster file name.

tcurv = name
Output tangential curvature or dyy values to raster file name.

mcurv = name
Output mean curvature or dxy values to raster file name.

maskmap = name
Use the existing raster file name as a mask.

dmin = val
Set min distance between points to val. Default value is set to 0.5 grid cell size.

dmax = val
Maximum distance between points. Default value is 5 * dmin.

zmult = val
Convert z-values using conversion factor val. Default value is 1.

tension =val
Set tension to val. Default value is 40, appropriate for smooth surfaces.

smooth = val
Set smoothing parameter to val. Default value is 0.1.

segmax = val
Set max number of points per segment to val. Default value is 40.

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

theta = val
Set anisotropy angle in degrees (measured from East counterclockwise) to val.

scalex = val
Set anisotropy scaling factor to val. Values 0 and 1 give no anisotropy.

devi = name
Output deviations to a site file name.

treefile = name
Output quad tree used for segmentation to vector file name

overfile = name
Output overlapping neighborhoods used for segmentation to vector file name.

## NOTES

v.surf.rst 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 specified dmax. If dmax is small (less than cell size) the number of added data points can be vary large and slow down interpolation significantly. 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 respectively). 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 concave areas. Singular points with undefined curvatures have assigned zero values.

Tension and smoothing allow user to tune the surface character. For most landscape scale applications the default should work fine.The program 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 tension and smoothing, 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 tension works as a rescaling parameter (high tension "increases the distances between the points" and reduces the range of impact of each point, low tension "decreases the distance" and the points influence each other over longer range). Surface with tension 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 tension 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 tension can be applied in relation to dnorm (dnorm rescales the coordinates depending on the average data density so that the size of segments with segmax=40 points is around 1 - this ensures the numerical stability of the computation):

1. Default (used also in s.surf.rst): the given tension is applied to normalized data (x/dnorm..), that means that the distances are multiplied (rescaled) by tension/dnorm. If density of points is changed, e.g., by using higher dmin, the dnorm changes and tension needs to be changed too to get the same result. Because the tension 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 -t (experimental for s.surf.rst): The given tension is applied to un-normalized data (rescaled tension = tension*dnorm/1000 is applied to normalized data (x/dnorm) and therefore dnorm cancels out) so here tension 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 dnorm and rescaled tension=tension*dnorm/1000 at the beginning of the program run. This rescaled tension should be around 20-30. If it is lower or higher, the given tension 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 -t flag can be helpful.

Anisotropic data (e.g. geologic phenomena) can be interpolated using theta and scalex defining orientation and ratio of the perpendicular axes put on the longest/shortest side of the feature, respectively. Theta is measured in degrees from East, counterclockwise. Scalex is a ratio of axes sizes. Setting scalex in the range 0-1, you will get pattern prolonged in the direction defined by theta. Scalex value 0.5 means that your feature is approximatelly 2 times longer in the direction of theta than in the perpendicular direction. Scalex 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 computating the values in given points, and prints the root mean square deviation (rms) found into the history file of raster map elev. For computation with smoothing set to 0. 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 output deviations option.

The program writes the values of parameters used in computation into the comment part of history file elev 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 npmin 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 segmax 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 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.surf.rst.

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.

## SEE ALSO

s.surf.rst

## AUTHORS

Original version of program (in FORTRAN) and GRASS enhancements:
Lubos Mitas, NCSA, University of Illinois at Urbana Champaign, Illinois, USA
Helena Mitasova, Department of Geography, University of Illinois at Urbana-Champaign, USA

Modified program (translated to C, adapted for GRASS, new segmentation procedure):
Irina Kosinovsky, US Army CERL
Dave Gerdes, US Army CERL

Modifications for new sites format and timestamping:
Darrel McCauley, Purdue University

## REFERENCES

Hofierka J., Parajka J., Mitasova H., Mitas L., 2002, Multivariate Interpolation of Precipitation Using Regularized Spline with Tension. Transactions in GIS 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 Tension: 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 Analysis, 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, Philadelphia, Pennsylvania.

Last changed: $Date: 2003/02/05 12:46:04 $