.TH s.surf.tps
.SH NAME
\fIs.surf.tps\fR \-interpolation and topographic analysis from given site data to GRASS raster format using spline with tension

.br
\fI(GRASS Raster Program)\fR
.SH SYNOPSIS
.B s.surf.tps
.br
\fBs.surf.tps help\fR
.br
\fBs.surf.tps \fR \fBinput = name\fR \fBelev = name\fR
 [\fBslope = name\fR] [\fBaspect = name\fR]   
 [\fBpcurv = name\fR] [\fBtcurv = name\fR] [\fBmcurv = name\fR] 
 [\fBdmin1 = val\fR] [\fBzmult = val\fR] 
 [\fBtension = val\fR] [\fBsmooth = val\fR]
 [\fBsegmax = val\fR] [\fBnpmin = val\fR]

.SH DESCRIPTION
\fIs.surf.tps\fR

.br
\fIs.surf.tps\fR interpolates the values to grid cells from point data
(digitized contours, climatic stations, drill holes etc.)
given in a sites file named \fIinput\fR. Output  raster file
is \fIelev\fR.
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 as specificied by the 
options \fIslope, aspect, pcurv, tcurv, mcurv\fR respectively.
.LP
At first, data points are checked for identical points and points that are
closer to each other than given \fIdmin1\fR are removed (this is necessary
especially for digitized contours).
Parameter \fIzmult\fR 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).
.LP
Regularized spline with tension is used for the interpolation.
The \fItension\fR parameter tunes the character of the resulting surface
from thin plate to membrane.  Higher values of tension parameter 
reduce the overshoots that can appear in surfaces with
rapid change of gradient (see suggested values for different types
of surfaces given in notes).
For noisy data, it is possible to define a smoothing parameter, \fIsmooth\fR.
With the smoothing parameter set to zero (\fIsmooth=0\fR) the resulting
surface passes exactly through the data points. 
.LP
If the number of given points is
greater than 400, segmented processing is  used.
The region is split into rectangular segments, each having less than
\fIsegmax\fR 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. The minimum
number of points taken for interpolation is controlled by 
\fInpmin\fR , the value of which must be larger than \fIsegmax\fR and less
than 400.  This limit of 400 was selected
to ensure the numerical stability and efficiency of the algorithm.

.SH 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:
.LP
.RS
\fBs.surf.tps \fR \fBinput = name\fR \fBelev = name\fR
 [\fBslope = name\fR] [\fBaspect = name\fR]   
 [\fBpcurv = name\fR] [\fBtcurv = name\fR] [\fBmcurv = name\fR] 
 [\fBdmin1 = val\fR] [\fBzmult = val\fR] 
 [\fBtension = val\fR] [\fBsmooth = val\fR]
 [\fBsegmax = val\fR] [\fBnpmin = val\fR]

.RE
.LP
Alternately, the user can simply type \fBs.surf.tps\fR 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 \fIparser\fR.

.LP
\fBParameters:\fR
.IP \fBinput\*=\fIname\fR 18 
Use the existing site file \fIname\fR as input.
.IP \fBelev\*=\fIname\fR 18 
Output elevation values to raster file named  \fIname\fR.
.IP \fBslope\*=\fIname\fR 18 
Output slope values to raster file named  \fIname\fR.
.IP \fBaspect\*=\fIname\fR 18 
Output aspect values to raster file named  \fIname\fR.
.IP \fBpcurv\*=\fIname\fR 18 
Output profile curvature values to raster file named  \fIname\fR.
.IP \fBtcurv\*=\fIname\fR 18 
Output tangential curvature values to raster file named  \fIname\fR.
.IP \fBmcurv\*=\fIname\fR 18 
Output mean curvature values to raster file named  \fIname\fR.
.IP \fBdmin1\*=\fIval\fR 18 
Set min distance between points to \fIval\fR.
Default value is set to 0.5grid cell size.
.IP \fBzmult\*=\fIval\fR 18 
Convert z-values using conversion factor \fIval\fR.
Default value is 1.
.IP \fBtension\*=\fIval\fR 18 
Set tension to \fIval\fR .
Default value is 40, appropriate for smooth surfaces.
.IP \fBsmooth\*=\fIval\fR 18
Set smoothing parameter to \fIval\fR .
Default value is 0, no smoothing is performed.
.IP \fBsegmax\*=\fIval\fR 18 
Set max number of points per segment to \fIval\fR.
Default value is 50.
.IP \fBnpmin\*=\fIval\fR 18 
Set min number of points for interpolation to \fIval\fR.
Default value is 100, for data with heterogeneous spatial
distribution higher value is suggested (see notes).

.SH NOTES
.I s.surf.tps
uses regularized spline with tension for interpolation from point
data (as described in Mitasova and Mitas, submitted to Mathematical
Geology.). The implementation
has an improved 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.
.LP
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, (submitted to Mathematical Geology.)
Slopes and aspect are computed in degrees (0-90 and 0-360 respectively).
The aspect raster file has code 365 for flat areas 
(areas with slope less than 0.5%) and in singular points
with undefined aspect. Aspect is 0 to the east, points upslope 
 and the values increase counterclockwise.
Curvatures are negative for convex and positive
for concave areas.
Original values of curvatures are multiplied by 100000, to conform with
GRASS integer raster files. Therefore any curvature lower than
0.00001 will be zero.  Flat areas have zero curvatures and singular points
have codes  1000000, 2000000, 3000000 for peak, pit and saddle respectively.
We suggest to use these codes only to distinguish areas(grid cells) with
undefined curvature as  the codes are assigned using the theorems from
differential geometry but have never been tested.
.LP
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 in each given point and everywhere else the surface goes 
rapidly to trend).
For data with values changing over several magnitudes
(sometimes the concentration data) it is suggested to interpolate the log
of the values rather than the original ones.
With smoothing parameter greater than zero the surface will not pass
through the data points and the higher the parameter the closer the
surface will be to the trend. For theory on smoothing with splines
see Talmi and Gilat, 1977 or  Wahba, 1990.
.LP
If a visible connection of segments appears, the program should be rerun with
higher \fInpmin\fR to get more points from the neighborhood of given segment.
.LP
If the number of points in a site file is less then 400, 
\fIsegmax\fR should be set to 400 so that segmentation is not performed 
when it is not necessary.
.LP
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.
.LP
For large data sets (thousands of data points) it 
is suggested to zoom into a smaller representative area
and test whether the parameters chosen (e.g. defaults) are appropriate.

The program was used for various applications with the following
parameters :
.IP
.B "interpolation of DEM from digitized contours"
.TS
center;
l l.
tension	40. - 80.
smoothing	0.
segmax	35
npmin	150 - 300
.TE
.B "interpolation of precipitation from climatic stations"
.TS
center;
l l.
tension	150. - 300.
smoothing	0. - 1.
segmax	40
npmin	150
.TE
.B "interpolation of concentration of chemicals"
.TS
center;
l l.
tension	100.  -  200.
smoothing	0. - 5.
.TE
.LP
The user must run \fIg.region\fR before the program to set the region for interpolation. 
.SH "SEE ALSO"
.I "v.out.point, g.region, r.surf.contour, r.surf.idw, r.surf.idw2, r.surf.sor, s.surf.idw"
.SH "AUTHOR"
\fIOriginal version of program (in FORTRAN)\fR:
.br
Helena Mitasova,
Illinois Natural history Survey and US Army CERL, Champaign, Illinois
 Comenius University, Bratislava, Czechoslovakia,
.br
Lubos Mitas, Department of Physics, University of Illinois at Urbana
Champaign, Illinois 
Institute of Physics, Bratislava, Czechoslovakia
.LP
\fIModified program (translated to C, adapted for GRASS , segmentation procedure)\fR:
.br
Irina Kosinovsky, US Army CERL
.br
Dave Gerdes, US Army CERL
.br
.SH "REFERENCES"
Mitasova, H. and Mitas, L. : Interpolation by Regularized Spline with
Tension: I. Theory and Implementation, submitted to Mathematical Geology
.br
Mitasova, H. and Hofierka, L. : Interpolation by Regularized Spline with
Tension: II. Aplication to Terrain Modeling and Surface Geometry Analysis,
submitted to Mathemtical Geology.
.br
Talmi, A. and Gilat, G. : Method for Smooth Approximation of Data,
Journal of Computational Physics, 23, 1977, p.93-123.
.br
Wahba, G. : Spline Models for Observational Data, CNMS-NSF Regional
Conference series in applied mathematics, 59, SIAM, Philadelphia,
Pennsylvania, 1990.
