/*!
\mainpage v.surf.rst

<h2>NAME</h2>

<b><i>v.surf.rst</i></b>- interpolation and topographic analysis from
given site data to GRASS floating point raster format using regularized
spline with tension (this program replaces <i>s.surf.tps</i>)
<br>

<i>(GRASS Site Program)</i>
<h2>
SYNOPSIS</h2>
<b>v.surf.rst</b><br>

<b>v.surf.rst help</b><br>

<b>v.surf.rst [-d] [-t]  input </b>= name [<b>elev </b>= name]
[<b>field</b>=val] [<b>slope </b>= name] [<b>aspect
</b>= name] [<b>pcurv
</b>=
name] [<b>tcurv </b>= name] [<b>mcurv </b>= name] [<b>maskmap</b> = name]
[<b>dmin </b>= val] [<b>zmult = </b>val] [<b>tension
</b>= val] [<b>smooth
</b>=
val] [<b>smatt=</b>val] [<b>segmax = </b>val] [<b>npmin
</b>= val] [<b>theta</b> = val] [<b>scalex</b> = val] [<b>devi
</b>=
name] [<b>treefile </b>= name] [<b>overfile </b>= name]
<br>

<h2>
DESCRIPTION</h2>
<i>v.surf.rst</i><br>

This program interpolates the z<sub><font size="-1">i</sub>-values
from point data (e.g., elevations, climatic stations, drill holes, etc.)
given in a sites file named <i>input</i> as x|y|%z<sub><font size="-2">1</sub>
%z<sub><font size="-2">2</sub> ...%z<sub><font size="-2">i</sub>...
to grid cells in the output raster file
<i>elev</i> representing a surface.
The user can select which floating point attribute will be interpolated
by setting the parameter <i>field</i> to the value i for the i-th floating
point attribute<b>.</b>
<p>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 <i>slope, aspect, pcurv, tcurv, mcurv</i> respectively.
If <i>-d</i> flag is set the program outputs partial derivatives f<sub>x</sub>,
f<sub>y</sub>, f<sub>xx</sub>, f<sub>yy</sub>, f<sub>xy</sub> instead of
slope, aspect, profile, tangential and mean curvatures respectively.
</p>
<p>User can define a raster file named <i>maskmap</i>, 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 <i>dmin</i> are removed. Parameter
<i>zmult</i>
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).
</p>

<p>Regularized spline with tension and smoothing is used for  interpolation
and approximation. The <i>tension</i> parameter tunes the character of
the resulting surface from thin plate to membrane. The experimental flag <i>-t </i>can
be set to use "dnorm independent tension", (see notes for more details
about the tension behavior). For noisy data, it is possible to define 
either a constant smoothing parameter <i>smooth</i> or a variable smoothing
parameter by  setting the parameter
<i>smatt</i> to the value j for
the j-th floating point attribute in the<i> input</i> site file, representing
the smoothing parameter for each point. When smoothing is used, it is possible
to output site file
<i>devi</i> containing deviations of the resulting
surface from the given data.
</p>
<p>If the number of given points is greater than <i>segmax</i>, segmented
processing is used. The region is split into rectangular segments, each
having less than
<i>segmax</i> 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 rectangular
window surrounding the given segment. The number of points taken for interpolation
is controlled by <i>npmin</i>, the value of which must be larger than <i>segmax</i>.
User can choose to output vector files <i>treefile</i> and <i>overfile</i>
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 <i>theta</i> and scaling factor <i>scalex</i>. The program writes several important values to history file of raster map
<i>elev</i>.
If the input data have time stamp, the program creates time stamp for all
output files.
</p>
<p>The user must run <i>g.region</i> before the program to set the region
and resolution for interpolation.
<br>
</p>
<h2>
OPTIONS</h2>

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:

<p><b>v.surf.rst [-d] [-t] input </b>= name <b>elev </b>= name [<b>field</b>=val]
[<b> slope </b>= name] [<b> aspect </b>= name] [<b> pcurv </b>= name] [<b>
tcurv </b>= name] [<b> mcurv </b>= name] [<b> maskmap</b> = name] [<b>
dmin </b>= val] [<b> zmult = </b>val] [<b> tension </b>= val] [<b> smooth
</b>=
val] [<b>smatt</b>=val] [<b> segmax = </b>val] [<b> npmin </b>= val] [ <b>theta</b> = val ] [ <b>scalex</b> = val ] [<b>
devi </b>= name] [<b> treefile </b>= name] [= name]
</p>
<p>Alternately, the user can simply type <b>v.surf.rst</b> 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<i> parser</i>.
</p>
<p><b>Flags</b></p>
<p><b>-d</b> Output partial derivatives instead of aspect, slope and curvatures.
<br>
<b>-t</b>  Use dnorm independent tension (experimental)
</p>
<p><b>Parameters:</b></p>
<p><b>input </b>= <i>name</i><br>
Use the existing site file name as input.
</p>
<p><b>elev </b>= <i>name</i><br>
Output elevation values to raster file <i>name</i>.
</p>
<p><b>field</b>=<i>val</i><br>
decimal attribute to use for elevation (1=first) options (1-100), default is 1.
</p>
<p><b>slope </b>= <i>name</i><br>
Output slope or dx values to raster file <i>name</i>.
</p>
<p><b>aspect </b>= <i>name</i><br>
Output aspect or dy values to raster file <i>name</i>.
</p>
<p><b>pcurv </b>= <i>name</i><br>
Output profile curvature or dxx values to raster file <i>name</i>.
</p>
<p><b>tcurv</b> = <i>name</i><br>
Output tangential curvature or dyy values to raster file <i>name</i>.
</p>
<p><b>mcurv</b> = <i>name</i><br>
Output mean curvature or dxy values to raster file <i>name</i>.
</p>
<p><b>maskmap</b> = <i>name</i><br>
Use the existing raster file <i>name</i> as a mask.
</p>
<p><b>dmin</b> = <i>val</i><br>
Set min distance between points to <i>val</i>. Default value is set
to 0.5 grid cell size.
</p>
<p><b>zmult</b> = <i>val</i><br>
Convert z-values using conversion factor <i>val</i>. Default value
is 1.
</p>
<p><b>tension</b> =<i>val</i><br>
Set tension to <i>val</i>. Default value is 40.
</p>
<p><b>smooth</b> = <i>val</i><br>
Set smoothing parameter to <i>val</i>. Default value is 0.1.
</p>
<p><b>smatt</b>=<i>val</i><br>
order of floating point attribute to use for variable smoothing parameter
</p>
<p><b>segmax</b> = <i>val</i><br>
Set max number of points per segment to <i>val</i>. Default value is
40.
</p>
<p><b>npmin</b> = <i>val</i><br>
Set min number of points for interpolation to <i>val</i>. Default value
is 200, for data with heterogeneous spatial distribution higher value is
suggested (see notes).</p>
<p><b>theta</b> =<i> val</i><i><br>
</i>Set anisotropy angle in degrees (measured from East counterclockwise) to <i>val</i>.<br></p>
<p><b>scalex</b> =<i> val</i><i><br>
</i>Set anisotropy scaling factor to <i>val</i>. Values 0 and 1 give no anisotropy.<br>
</p>
<p><b>devi</b> = <i>name</i><br>
Output deviations to a site file <i>name</i>.
</p>
<p><b>treefile</b> = <i>name</i><br>
Output quad tree used for segmentation to vector file <i>name</i></p>
<p><b>overfile</b> = name
<br>
Output overlapping neighborhoods used for segmentation to vector file
<i>name</i>.
<br>
</p>
<h2>
NOTES</h2>
<i>v.surf.rst</i>uses regularized spline with tensionfor interpolation
from point data. Point data should be in a <a href="../ascii_formats.html">new
site format </a>

, that means format x|y|%z<sub><font size="-2">1</sub>
%z<sub><font size="-2">2</sub> ...%z<sub><font size="-2">i</sub>...,
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 automatically.

<p>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 segments, to reduce
the potential for visibility of segmentens in areas with sparse data.
</p>
<p>Special color tables are created by the program for output raster files.
</p>
<p>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 <a href="http://www2.gis.uiuc.edu:2280/modviz/papers/lmg.rev1.ps">(Mitasova
and Hofierka 1993</a>
). 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.
</p>
<p><i>Tension</i> and <i>smooth</i>ing 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.
<br>
While it is possible to automatize the selection of suitable <i>tension</i>
and <i>smooth</i>ing, 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 <i>tension</i>
works as a rescaling parameter (high <i>tension</i> "increases the distances
between the points" and reduces the range of impact of each point, low<i>
tension</i> "decreases the distance" and the points influence each other
over longer range). Surface with  <i>tension</i> 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.
<br>
Surface with <i>tension</i> 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.
</p>
<p>There are two options how <i>tension</i> can be applied in relation
to <i>dnorm</i> (dnorm rescales the coordinates depending on the average
data density so that the size of segments with <i>segmax=</i>40 points
is around 1 - this ensures the numerical stability of the computation):
</p>
<p>1. Default (used also in s.surf.tps): the given <i>tension</i> 
is applied to normalized data (x/<i>dnorm</i>..),  that means that
the distances are multiplied (rescaled) by <i>tension/dnorm</i>. If density
of points is changed, e.g.,  by using higher <i>dmin</i>, the <i>dnorm</i>
changes and <i>tension</i> needs to be changed too to get the same result.
Because the <i>tension</i> 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).
<br>
2. Flag<b> -t </b>(experimental for v.surf.rst)<b>: </b>The given 
<i>tension</i> is applied to un-normalized data (rescaled tension = t<i>ension*dnorm</i>/1000
is applied to normalized data (x/<i>dnorm</i>) and therefore  <i>dnorm</i>
cancels out) so here <i>tension</i> truly works as a rescaling parameter.
For regional applications 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
<i>dnorm</i> and rescaled tension=<i>tension*dnorm</i>/1000 at the
beginning of the program run. This rescaled <i>tension</i> should be around
20-30.  If it is lower or higher, the given <i>tension</i> parameter
should be changed accordingly.
</p>
<p>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 <b>-t</b> flag can be helpful.</p>
<p>Anisotropic data (e.g. geologic phenomena) can be 
interpolated using <i>theta</i> 
and <i>scalex</i> defining orientation 
and ratio of the perpendicular axes put on the longest/shortest side of the feature, respectively.
<i>Theta</i> is measured in degrees from East, 
counterclockwise. <i>Scalex</i> is a ratio 
of axes sizes. 
Setting <i>scalex</i> in the range 0-1, you will get pattern prolonged in the
direction defined by <i>theta</i>. <i>Scalex</i> value 0.5 means that your feature is approximatelly
2 times longer in the direction of <i>theta</i> than in the perpendicular direction.
<i>Scalex</i> 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/).<br>
</p>
<p>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.
</p>
<p>The program checks the numerical stability of the algorithm by computing
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 <i>elev</i>. 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 output deviations option and running
s.univar on the site file with deviations.
</p>
<p>The program writes the values of parameters used in computation into
the comment part of history file <i>elev</i> 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.
</p>
<p>When the number of points in a site file is not too large (less than
800), the user can skip segmentation by setting <i>segmax</i> to the number
of data points or segmax=700.
</p>
<p>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.
</p>
<p>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 (e.g. using r.mask.points).
</p>
<p>For examples of applications see 
<a href="http://www2.gis.uiuc.edu:2280/modviz/viz/">http://www2.gis.uiuc.edu:2280/modviz/viz/</a>
 <br>
and
 <a href="http://www2.gis.uiuc.edu:2280/modviz/">http://www2.gis.uiuc.edu:2280/modviz/</a>
</p>
<h2>
SEE ALSO</h2>
<a href="r.slope.aspect.html">r.slope.aspect,</a>

<a href="r.surf.idw.html">r.surf.idw</a>

,
<a href="r.surf.idw2.html">r.surf.idw2</a>

,
<a href="r.surf.contour.html">r.surf.contour</a>

,
<a href="s.surf.idw.html">s.surf.idw</a>

,
<a href="v.to.sites.html">v.to.sites</a>

,
<a href="g.region.html">g.region</a>

,
<a href="r.mask.html">r.mask</a>

,
<a href="v.surf.rst.html">v.surf.rst</a>

,
<a href="r.resamp.rst.html">r.resamp.rst</a>

<h2>
Formula</h2>

The function is a sum of a <i>trend function</i> and a <i>radial basis
function</i> with an explicit form which depends on the choice of the
measure of smoothness, for more details see Mitasova 1993, Mitasova 1995,
Neteler and Mitasova 2002:

\f$
z({\bf r})=T({\bf r})+\sum_{j=1}^N \lambda_j R({\bf r},{\bf r}^{[j]})\, .
\f$

The trend function \f$T({\bf r})\f$ is given by

\f$
T({\bf r})=\sum_{l=1}^M a_l f_l ({\bf r})
\f$

where \f$\{f_l ({\bf r})\}\f$ is a set of linearly independent functions
(monomials) which have zero smooth seminorm.  \f$R({\bf r},{\bf r}^{[j]})\f$
is a radial basis function with an explicit form which depends on
the choice of weights for partial derivatives in the smooth seminorm.
See Mitasova 1993, Mitasova 1995 for the RST smoothness seminorm,
which includes derivatives of all orders with their weights decreasing
with the increasing derivative order.

RST can be generalized to an arbitrary dimension and the corresponding
\f$d\f$-variate formula for the radial basis function is given by

\f$
R_d({\bf r, r}_j) = R_d(|{\bf r} - {\bf r}_j|)=
R_d(r) =   \varrho ^{-\delta}\;
\gamma\left(\delta, \varrho \right) -{1 \over \delta}
\f$

where \f$r=|{\bf r} - {\bf r}_j|\f$, \f$\delta=(d-2)/2\f$, and 
\f$\varrho = (\varphi r/2)^2\f$.  Further, \f$\varphi\f$ is a generalized tension parameter,
and \f$\gamma(\delta,\varrho)\f$ is the incomplete gamma function, not to be
confused with semivariogram (Abramowitz 1964).
<p>
[see more in Neteler and Mitasova 2002]

<h2>
AUTHORS</h2>
<i>Original version of program (in FORTRAN) and GRASS enhancements:</i><br>

Lubos Mitas, NCSA, University of Illinois at Urbana-Champaign, Illinois,
USA
<br>

Helena Mitasova, Department of Geography, University of Illinois at
Urbana-Champaign, Champaign, Illinois, USA

<p><i>Modified program (translated to C, adapted for GRASS, new segmentation
procedure):</i><br>
Irina Kosinovsky, US Army CERL, Champaign, Illinois, USA
<br>
Dave Gerdes, US Army CERL, Champaign, Illinois, USA
</p>
<p><i>Modifications for new sites format and timestamping:</i><br>
Darrel McCauley, Purdue University, West Laffayette, Indiana, USA

</p>
<h2>
REFERENCES</h2>

Hofierka J., Parajka J.,  Mitasova H., Mitas L., 2002,
Multivariate Interpolation of Precipitation Using Regularized Spline with Tension.
<i>Transactions in GIS</i>&nbsp; 6(2), pp. 135-150.
<p>

Mitas, L., Mitasova, H., 1999, Spatial Interpolation. In: P.Longley, M.F.
Goodchild, D.J. Maguire, D.W.Rhind (Eds.), <i>Geographical Information
Systems: Principles, Techniques, Management and Applications</i>, Wiley,
pp.481-492

<p>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>International Journal of GIS</i>,
9 (4), special issue on Integrating GIS and Environmental modeling, 433-446.
</p>
<p><a href="http://www2.gis.uiuc.edu:2280/modviz/papers/lmg.rev1.ps">Mitasova
H. and Mitas L. 1993</a>
: Interpolation by Regularized Spline with Tension:
I. Theory and Implementation, <i>Mathematical Geology</i> 25, 641-655.
</p>
<p><a href="http://www2.gis.uiuc.edu:2280/modviz/papers/hmg.rev1.ps">Mitasova
H. and Hofierka J. 1993</a>
: Interpolation by Regularized Spline with Tension:
II. Application to Terrain Modeling and Surface Geometry Analysis, <i>Mathematical
Geology</i> 25, 657-667.
</p>
<p>Mitasova, H., 1992 : New capabilities for interpolation and topographic
analysis in GRASS, <i>GRASSclippings </i>6, No.2 (summer), p.13.
</p>
<p>Mitas, L., Mitasova H., 1988 : General variational approach to the interpolation
problem, <i>Computers and Mathematics with Applications </i>16, p. 983
</p>
<p><a href=http://mpa.itc.it/grassbook/>M. Neteler and H. Mitasova, 2002:</a>
Open Source GIS: A GRASS GIS Approach. The
Kluwer international series in Engineering and Computer Science (SECS):
Volume 689. Kluwer Academic Publishers, Boston, Dordrecht, London, 2002.
ISBN: 1-4020-7088-8
</p>
<p>Talmi, A. and Gilat, G., 1977 : Method for Smooth Approximation of Data,
<i>Journal
of Computational Physics</i>, 23, p.93-123.
</p>
<p>Wahba, G., 1990, : Spline Models for Observational Data, CNMS-NSF Regional
Conference series in applied mathematics, 59, SIAM, Philadelphia, Pennsylvania.
<br>
</p>
<p>Updated April 2, 2002 by Jaro Hofierka and Helena Mitasova
</p>
<p><i>Last changed: $Date: 2003/03/10 09:48:43 $</i></p>
</body></html>

*/
