.TH v.surf.bspline 1grass "" "GRASS 7.2.0" "Grass User's Manual"
.SH NAME
\fI\fBv.surf.bspline\fR\fR  \- Performs bicubic or bilinear spline interpolation with Tykhonov regularization.
.SH KEYWORDS
vector, surface, interpolation, LIDAR
.SH SYNOPSIS
\fBv.surf.bspline\fR
.br
\fBv.surf.bspline \-\-help\fR
.br
\fBv.surf.bspline\fR [\-\fBce\fR] \fBinput\fR=\fIname\fR  [\fBlayer\fR=\fIstring\fR]   [\fBcolumn\fR=\fIname\fR]   [\fBsparse_input\fR=\fIname\fR]   [\fBoutput\fR=\fIname\fR]   [\fBraster_output\fR=\fIname\fR]   [\fBmask\fR=\fIname\fR]   [\fBew_step\fR=\fIfloat\fR]   [\fBns_step\fR=\fIfloat\fR]   [\fBmethod\fR=\fIstring\fR]   [\fBlambda_i\fR=\fIfloat\fR]   [\fBsolver\fR=\fIname\fR]   [\fBmaxit\fR=\fIinteger\fR]   [\fBerror\fR=\fIfloat\fR]   [\fBmemory\fR=\fIinteger\fR]   [\-\-\fBoverwrite\fR]  [\-\-\fBhelp\fR]  [\-\-\fBverbose\fR]  [\-\-\fBquiet\fR]  [\-\-\fBui\fR]
.SS Flags:
.IP "\fB\-c\fR" 4m
.br
Find the best Tykhonov regularizing parameter using a \(dqleave\-one\-out\(dq cross validation method
.IP "\fB\-e\fR" 4m
.br
Estimate point density and distance
.br
Estimate point density and distance for the input vector points within the current region extends and quit
.IP "\fB\-\-overwrite\fR" 4m
.br
Allow output files to overwrite existing files
.IP "\fB\-\-help\fR" 4m
.br
Print usage summary
.IP "\fB\-\-verbose\fR" 4m
.br
Verbose module output
.IP "\fB\-\-quiet\fR" 4m
.br
Quiet module output
.IP "\fB\-\-ui\fR" 4m
.br
Force launching GUI dialog
.SS Parameters:
.IP "\fBinput\fR=\fIname\fR \fB[required]\fR" 4m
.br
Name of input vector point map
.br
Or data source for direct OGR access
.IP "\fBlayer\fR=\fIstring\fR" 4m
.br
Layer number or name
.br
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.
.br
Default: \fI1\fR
.IP "\fBcolumn\fR=\fIname\fR" 4m
.br
Name of the attribute column with values to be used for approximation
.br
If not given and input is 3D vector map then z\-coordinates are used.
.IP "\fBsparse_input\fR=\fIname\fR" 4m
.br
Name of input vector map with sparse points
.br
Or data source for direct OGR access
.IP "\fBoutput\fR=\fIname\fR" 4m
.br
Name for output vector map
.IP "\fBraster_output\fR=\fIname\fR" 4m
.br
Name for output raster map
.IP "\fBmask\fR=\fIname\fR" 4m
.br
Raster map to use for masking (applies to raster output only)
.br
Only cells that are not NULL and not zero are interpolated
.IP "\fBew_step\fR=\fIfloat\fR" 4m
.br
Length of each spline step in the east\-west direction
.br
Default: \fI4\fR
.IP "\fBns_step\fR=\fIfloat\fR" 4m
.br
Length of each spline step in the north\-south direction
.br
Default: \fI4\fR
.IP "\fBmethod\fR=\fIstring\fR" 4m
.br
Spline interpolation algorithm
.br
Options: \fIbilinear, bicubic\fR
.br
Default: \fIbilinear\fR
.br
\fBbilinear\fR: Bilinear interpolation
.br
\fBbicubic\fR: Bicubic interpolation
.IP "\fBlambda_i\fR=\fIfloat\fR" 4m
.br
Tykhonov regularization parameter (affects smoothing)
.br
Default: \fI0.01\fR
.IP "\fBsolver\fR=\fIname\fR" 4m
.br
The type of solver which should solve the symmetric linear equation system
.br
Options: \fIcholesky, cg\fR
.br
Default: \fIcholesky\fR
.IP "\fBmaxit\fR=\fIinteger\fR" 4m
.br
Maximum number of iteration used to solve the linear equation system
.br
Default: \fI10000\fR
.IP "\fBerror\fR=\fIfloat\fR" 4m
.br
Error break criteria for iterative solver
.br
Default: \fI0.000001\fR
.IP "\fBmemory\fR=\fIinteger\fR" 4m
.br
Maximum memory to be used (in MB)
.br
Cache size for raster rows
.br
Default: \fI300\fR
.SH DESCRIPTION
\fIv.surf.bspline\fR performs a bilinear/bicubic spline
interpolation with Tykhonov regularization. The \fBinput\fR is a 2D
or 3D vector \fIpoints\fR 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
(\fBraster_output\fR) or vector (\fBoutput\fR) map.  Optionally, a
\(dqsparse point\(dq vector map can be input which indicates the location
of \fBoutput\fR vector points.
.SH NOTES
.PP
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 \fBew_step\fR for the east\-west direction and
\fBns_step\fR 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).
.PP
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.
.PP
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.
.PP
The Tykhonov regularization parameter (\fBlambda_i\fR) acts to
smooth the interpolation. With a small \fBlambda_i\fR, the
interpolated surface closely follows observation points; a larger
value will produce a smoother interpolation.
.PP
The input can be a 2D or 3D vector points map. If input is 3D
and \fBcolumn\fR is not given than z\-coordinates are used for
interpolation. Parameter \fBcolumn\fR is required when input is 2D
vector map.
.PP
\fIv.surf.bspline\fR can produce a \fBraster_output\fR OR
a \fBoutput\fR (but NOT simultaneously). Note that topology is not
build for output vector point map. The topology can be built if
required by \fIv.build\fR.
.PP
If output is a vector points map and a \fBsparse\fR 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 \fBsparse\fR 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.
.PP
A cross validation \(dqleave\-one\-out\(dq analysis is available to help to
determine the optimal \fBlambda_i\fR 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 \fImean\fR and \fIrms\fR of the residuals from the
true point value and the estimated from the interpolation for a fixed
series of \fBlambda_i\fR values. No vector nor raster output will be
created when cross\-validation is selected.
.SH EXAMPLES
.SS Basic interpolation
.br
.nf
\fC
v.surf.bspline input=point_vector output=interpolate_surface method=bicubic
\fR
.fi
A bicubic spline interpolation will be done and a vector points map
with estimated (i.e., interpolated) values will be created.
.SS Basic interpolation and raster output with a longer spline step
.br
.nf
\fC
v.surf.bspline input=point_vector raster=interpolate_surface ew_step=25 ns_step=25
\fR
.fi
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.
.SS Estimation of lambda_i parameter with a cross validation process
.br
.nf
\fC
v.surf.bspline \-c input=point_vector
\fR
.fi
.SS Estimation on sparse points
.br
.nf
\fC
v.surf.bspline input=point_vector sparse=sparse_points output=interpolate_surface
\fR
.fi
An output map of vector points will be created, corresponding to the
sparse vector map, with interpolated values.
.SS Using attribute values instead z\-coordinates
.br
.nf
\fC
v.surf.bspline input=point_vector raster=interpolate_surface layer=1 \(rs
  column=attrib_column
\fR
.fi
The interpolation will be done using the values
in \fIattrib_column\fR, in the table associated with layer 1.
.SS North carolina location example using z\-coordinates for interpolation
.br
.nf
\fC
g.region region=rural_1m res=2 \-p
v.surf.bspline input=elev_lid792_bepts raster=elev_lid792_rast \(rs
  ew_step=5 ns_step=5 method=bicubic lambda_i=0.1
\fR
.fi
.SH KNOWN ISSUES
Known issues:
.PP
In order to avoid RAM memory problems, an auxiliary table is needed
for recording some intermediate calculations. This requires
the \fIGROUP BY\fR SQL function is used, which is not supported by
the DBF driver. For this reason, vector map output
(\fBoutput\fR) is not permitted with the DBF driver. There are
no problems with the raster map output from the DBF driver.
.SH REFERENCES
.RS 4n
.IP \(bu 4n
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
.IP \(bu 4n
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
.IP \(bu 4n
Brovelli M. A e Longoni U.M., 2003, Software per il filtraggio di
dati LIDAR, Rivista dell\(cqAgenzia del Territorio, n. 3\-2003, pp. 11\-22
(ISSN 1593\-2192)
.IP \(bu 4n
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
.RE
.SH SEE ALSO
\fI
v.surf.idw,
v.surf.rst
\fR
.PP
Overview: Interpolation and Resampling in GRASS GIS
.SH AUTHORS
Original version (s.bspline.reg) in GRASS 5.4:
Maria Antonia Brovelli, Massimiliano Cannata, Ulisse Longoni, Mirko Reguzzoni
.br
Update for GRASS 6 and improvements: Roberto Antolin
.PP
\fILast changed: $Date: 2016\-08\-03 13:53:17 +0200 (Wed, 03 Aug 2016) $\fR
.SH SOURCE CODE
.PP
Available at: v.surf.bspline source code (history)
.PP
Main index |
Vector index |
Topics index |
Keywords index |
Graphical index |
Full index
.PP
© 2003\-2016
GRASS Development Team,
GRASS GIS 7.2.0 Reference Manual