Provided by: grass-doc_6.4.3-3_all bug

NAME

       v.surf.bspline  - Bicubic or bilinear spline interpolation with Tykhonov regularization.

KEYWORDS

       vector, interpolation

SYNOPSIS

       v.surf.bspline
       v.surf.bspline help
       v.surf.bspline    [-ce]    input=name    [sparse=name]     [output=name]     [raster=name]
       [sie=float]     [sin=float]     [method=string]      [lambda_i=float]      [layer=integer]
       [column=name]   [--overwrite]  [--verbose]  [--quiet]

   Flags:
       -c
           Find the best Tykhonov regularizing parameter using a "leave-one-out" cross validation
           method

       -e
           Estimate point density and distance
           Estimate point density and distance for the input vector  points  within  the  current
           region extends and quit

       --overwrite
           Allow output files to overwrite existing files

       --verbose
           Verbose module output

       --quiet
           Quiet module output

   Parameters:
       input=name
           Name of input vector map

       sparse=name
           Name of input vector map of sparse points

       output=name
           Name for output vector map

       raster=name
           Name for output raster map

       sie=float
           Length of each spline step in the east-west direction
           Default: 4

       sin=float
           Length of each spline step in the north-south direction
           Default: 4

       method=string
           Spline interpolation algorithm
           Options: bilinear,bicubic
           Default: bilinear

       lambda_i=float
           Tykhonov regularization parameter (affects smoothing)
           Default: 0.01

       layer=integer
           Layer number
           If set to 0, z coordinates are used. (3D vector only)
           Default: 0

       column=name
           Attribute table column with values to interpolate (if layer>0)

DESCRIPTION

       v.surf.bspline   performs   a   bilinear/bicubic   spline   interpolation   with  Tykhonov
       regularization. The input is a 2D or 3D vector points map. Values to  interpolate  can  be
       the  z values of 3D points or the values in a user-specified attribue column in a 2D or 3D
       map. Output can be a raster or vector map.  Optionally, a "sparse point" vector map can be
       input which indicates the location of output vector points.

       From  a theoretical perspective, the interpolating procedure takes place in two parts: the
       first is an estimate of the linear coefficients of a spline function is derived  from  the
       observation  points using a least squares regression; the second is the computation of the
       interpolated surface (or interpolated vector points). As used here,  the  splines  are  2D
       piece-wise  non-zero polynomial functions calculated within a limited, 2D area. The length
       of each spline step is defined by sie for the east-west direction and sin for  the  north-
       south direction. For optimum performance, the length of spline step should be no less than
       the distance between observation points. Each vector point observation  is  modeled  as  a
       linear  function  of  the  non-zero  splines in the area around the observation. The least
       squares  regression  predicts  the   the   coefficients   of   these   linear   functions.
       Regularization,  avoids  the need to have one one observation and one coefficient for each
       spline (in order to avoid instability).

       With regularly distributed data  points,  a  spline  step  corresponding  to  the  maximum
       distance between two points in both the east and north directions is sufficient. But often
       data points are  not  regularly  distributed  and  require  statistial  regularization  or
       estimation.  In  such  cases,  v.surf.bspline  will  attempt  to  minimize the gradient of
       bilinear splines or the curvature of bicubic splines in areas lacking point  observations.
       As  a  general  rule,  spline step length should be greater than the mean distance between
       observation points (twice the distance between points is a good starting point).  Separate
       east-west and north-south spline step length arguments allows the user to account for some
       degree of anisotropy  in  the  distribution  of  observation  points.  Short  spline  step
       lengths--especially   spline  step  lengths  that  are  less  than  the  distance  between
       observation points--can greatly increase processing time.

       Moreover, the maximum number of  splines  for  each  direction  at  each  time  is  fixed,
       regardless of the spline step length. As the total number of splines used increases (i.e.,
       with small  spline  step  lengths),  the  region  is  automatically  into  subregions  for
       interpolation. Each subregion can contain no more than 150x150 splines. To avoid subregion
       boundary problems, subregions are created to partially overlap each other. A weighted mean
       of observations, based on point locations, is calculated within each subregion.

       The  Tykhonov regularization parameter ("lambda_i") acts to smooth the interpolation. With
       a small lambda_i, the interpolated surface closely follows observation  points;  a  larger
       value will produce a smoother interpolation.

       The  input  can be a 2D pr 3D vector points map. If "layer =" 0 the z-value of a 3D map is
       used for interpolation. If layer > 0, the user must specify an attribute  column  to  used
       for interpolation using the "column=" argument (2D or 3D map).

       v.surf.bspline  can  produce a raster OR a vector output (NOT simultaneously).  However, a
       vector output cannot be obtained using the default GRASS DBF driver.

       If output is a vector points map and a "sparse=" vector points map is not  specified,  the
       output  vector  map will contain points at the same locations as observation points in the
       input map, but the values of the output points  are  interpolated  values.  If  instead  a
       "sparse=" vector points map is specified, the output vector map will contain points at the
       same locations as the  sparse  vector  map  points,  and  values  will  be  those  of  the
       interpolated raster surface at those points.

       A  cross validation "leave-one-out" analysis is available to help to determine the optimal
       lambda_i value that produces an interpolation that  best  fits  the  original  observation
       data.  The  more  points  used  for  cross-validation,  the  longer  the  time  needed for
       computation. Empirical testing indicates a  threshold  of  a  maximum  of  100  points  is
       recommended.  Note that cross validation can run very slowly if more than 100 observations
       are used. The cross-validation output reports mean and rms of the residuals from the  true
       point  value  and  the  estimated  from  the  interpolation for a fixed series of lambda_i
       values. No vector nor raster output will be created when cross-validation is selected.

EXAMPLES

   Basic interpolation

       v.surf.bspline input=point_vector output=interpolate_surface method=bicubic
        A bicubic spline interpolation will be done and a vector points map with estimated (i.e.,
       interpolated) values will be created.

   Basic interpolation and raster output with a longer spline step

       v.surf.bspline input=point_vector raster=interpolate_surface sie=25 sin=25
         A  bilinear spline interpolation will be done with a spline step length of 25 map units.
       An interpolated raster map will be created at the current region resolution.

   Estimation of lambda_i parameter with a cross validation proccess

       v.surf.bspline -c input=point_vector

   Estimation on sparse points

       v.surf.bspline input=point_vector sparse=sparse_points output=interpolate_surface
        An output map of vector points will be created, corresponding to the sparse  vector  map,
       with interpolated values.

   Using attribute values instead Z-coordinates

       v.surf.bspline input=point_vector raster=interpolate_surface layer=1 column=attrib_column
        The interpolation will be done using the values in attrib_column, in the table associated
       with layer 1.

BUGS

       Known issues:

       In order to avoid RAM memory problems, an auxiliary table is  needed  for  recording  some
       intermediate calculations. This requires the "GROUP BY" SQL function is used, which is not
       supported by the "dbf" driver. For  this  reason,  vector  map  output  "output="  is  not
       permitted  with  the DBF driver. There are no problems with the raster map output from the
       DBF driver.

SEE ALSO

        v.surf.idw, v.surf.rst

AUTHORS

       Original version in GRASS 5.4: (s.bspline.reg)
       Maria Antonia Brovelli, Massimiliano Cannata, Ulisse Longoni, Mirko Reguzzoni

       Update for GRASS 6.X and improvements:
       Roberto Antolin

REFERENCES

       Brovelli M. A., Cannata  M.,  and  Longoni  U.M.,  2004,  LIDAR  Data  Filtering  and  DTM
       Interpolation  Within  GRASS,  Transactions  in  GIS,  April  2004,  vol.  8,  iss. 2, pp.
       155-174(20), Blackwell Publishing Ltd

       Brovelli M. A. and Cannata M., 2004, Digital Terrain model reconstruction in  urban  areas
       from  airborne  laser scanning data: the method and an example for Pavia (Northern Italy).
       Computers and Geosciences 30, pp.325-331

       Brovelli M. A e Longoni U.M., 2003, Software per il  filtraggio  di  dati  LIDAR,  Rivista
       dell'Agenzia del Territorio, n. 3-2003, pp. 11-22 (ISSN 1593-2192)

       Antolin  R.  and  Brovelli  M.A.,  2007,  LiDAR  data  Filtering  with  GRASS  GIS for the
       Determination of Digital Terrain Models. Proceedings of Jornadas  de  SIG  Libre,  Girona,
       España. CD ISBN: 978-84-690-3886-9

       Last changed: $Date: 2012-12-27 09:22:59 -0800 (Thu, 27 Dec 2012) $

       Full index

       © 2003-2013 GRASS Development Team