Provided by: grass-doc_7.6.0-1_all bug

NAME

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

KEYWORDS

       vector, surface, interpolation, LIDAR

SYNOPSIS

       v.surf.bspline
       v.surf.bspline --help
       v.surf.bspline  [-ce]  input=name   [layer=string]    [column=name]    [sparse_input=name]
       [output=name]    [raster_output=name]    [mask=name]    [ew_step=float]    [ns_step=float]
       [method=string]    [lambda_i=float]    [solver=name]     [maxit=integer]     [error=float]
       [memory=integer]   [--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]

   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 in map units for the input  vector  points  within
           the current region extents and quit

       --overwrite
           Allow output files to overwrite existing files

       --help
           Print usage summary

       --verbose
           Verbose module output

       --quiet
           Quiet module output

       --ui
           Force launching GUI dialog

   Parameters:
       input=name [required]
           Name of input vector point map
           Or data source for direct OGR access

       layer=string
           Layer number or name
           Vector  features  can have category values in different layers. This number determines
           which layer to use. When used with direct OGR access this is the layer name.
           Default: 1

       column=name
           Name of the attribute column with values to be used for approximation
           If not given and input is 3D vector map then z-coordinates are used.

       sparse_input=name
           Name of input vector map with sparse points
           Or data source for direct OGR access

       output=name
           Name for output vector map

       raster_output=name
           Name for output raster map

       mask=name
           Raster map to use for masking (applies to raster output only)
           Only cells that are not NULL and not zero are interpolated

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

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

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

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

       solver=name
           The type of solver which should solve the symmetric linear equation system
           Options: cholesky, cg
           Default: cholesky

       maxit=integer
           Maximum number of iteration used to solve the linear equation system
           Default: 10000

       error=float
           Error break criteria for iterative solver
           Default: 0.000001

       memory=integer
           Maximum memory to be used (in MB)
           Cache size for raster rows
           Default: 300

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 attribute column in a 2D or 3D
       vector  map. Output can be a raster (raster_output) or vector (output) map.  Optionally, a
       "sparse point" vector map can be input which  indicates  the  location  of  output  vector
       points.

NOTES

       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
       (in mapping units) of each spline step is defined by ew_step for the  east-west  direction
       and  ns_step  for the north-south direction. For optimal 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 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 the 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  split  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 or 3D vector points map. If input is 3D and column is not given than
       z-coordinates are used for interpolation. Parameter column is required when  input  is  2D
       vector map.

       v.surf.bspline can produce a raster_output OR a output (but NOT simultaneously). Note that
       topology is not build for output vector point map. The topology can be built  if  required
       by v.build.

       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 ew_step=25 ns_step=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 process
       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.

   North carolina location example using z-coordinates for interpolation
       g.region region=rural_1m res=2 -p
       v.surf.bspline input=elev_lid792_bepts raster=elev_lid792_rast \
         ew_step=5 ns_step=5 method=bicubic lambda_i=0.1

KNOWN ISSUES

       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.

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

SEE ALSO

        v.surf.idw, v.surf.rst

       Overview: Interpolation and Resampling in GRASS GIS

AUTHORS

       Original  version  (s.bspline.reg)  in  GRASS  5.4:  Maria  Antonia Brovelli, Massimiliano
       Cannata, Ulisse Longoni, Mirko Reguzzoni
       Update for GRASS 6 and improvements: Roberto Antolin

       Last changed: $Date: 2017-07-24 23:59:39 +0200 (Mon, 24 Jul 2017) $

SOURCE CODE

       Available at: v.surf.bspline source code (history)

       Main index | Vector index | Topics index | Keywords index | Graphical index | Full index

       © 2003-2019 GRASS Development Team, GRASS GIS 7.6.0 Reference Manual