v.surf.bspline(1)

📦
version 8.4.2 · 8 versions
, in fedora 44

✨ NAME ✨

v.surf.bspline — bestie, this one does bicubic or bilinear spline interpolation with Tykhonov regularization 💅 (yes it's a real thing, yes it's a lot, we'll get there).

🏷️ 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=memory in MB]
[--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]

🚩 Flags 🚩

  • -c — hunts down the best Tykhonov regularizing parameter for you, using a "leave-one-out" cross validation method 🔍
  • -e — estimates point density and distance 📏 in map units, for the input vector points inside the current region extents, and then just quits. That's it, that's the whole job.
  • --overwrite — lets output files overwrite existing files (chaotic but okay 💀)
  • --help — prints the usage summary
  • --verbose — verbose module output, the chatty mode 🗣️
  • --quiet — quiet module output, the silent-treatment mode 🤫
  • --ui — forces the GUI dialog to launch 🖥️

🎀 Parameters 🎀

  • input=name [required] — name of the input vector point map. Or, plot twist, a data source for direct OGR access.
  • layer=string — layer number or name. Vector features can have category values living in different layers, and this number decides which layer we're using. When you're doing direct OGR access, this is the layer name instead. Default: 1.
  • column=name — the name of the attribute column whose values get used for the approximation. If you don't give one and the input is a 3D vector map, the z-coordinates get used instead 📈.
  • sparse_input=name — name of the input vector map with sparse points. Or a data source for direct OGR access.
  • output=name — the name for the output vector map.
  • raster_output=name — the name for the output raster map.
  • mask=name — raster map to use for masking (this one only applies to raster output, fyi). Only cells that are not NULL and not zero get interpolated ✨.
  • ew_step=float — the length of each spline step in the east-west direction. Default: 4 * east-west resolution.
  • ns_step=float — the length of each spline step in the north-south direction. Default: 4 * north-south resolution.
  • method=string — the spline interpolation algorithm. Options: bilinear, bicubic. Default: bilinear.
    • bilinear: bilinear interpolation
    • bicubic: bicubic interpolation
  • lambda_i=float — the Tykhonov regularization parameter (this is the one that affects smoothing, lowkey the main character here). Default: 0.01.
  • solver=name — which type of solver should solve the symmetric linear equation system. Options: cholesky, cg. Default: cholesky.
  • maxit=integer — maximum number of iterations used to solve the linear equation system. Default: 10000.
  • error=float — the error break criteria for the iterative solver. Default: 0.000001.
  • memory=memory in MB — maximum memory to be used (in MB). It's the cache size for raster rows. Default: 300.

💖 DESCRIPTION 💖

okay so v.surf.bspline performs a bilinear/bicubic spline interpolation with Tykhonov regularization. The input is a 2D or 3D vector point layer, no cap.

What are we interpolating, exactly? Either the z values of 3D points, or the values sitting in a user-specified attribute column in a 2D or 3D vector layer. Your call bestie.

Output can be a raster (raster_output) or a vector (output) layer. And optionally, you can feed in a "sparse point" vector layer, which tells it where the output vector points should go 📍.

📝 NOTES 📝

From a theoretical perspective (yes we're going there, stay with me), the interpolating procedure happens in two parts:

  1. First, there's an estimate of the linear coefficients of a spline function, derived from the observation points using a least squares regression.
  2. Second, the computation of the interpolated surface, or the 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 the spline step should be no less than the distance between observation points 🫡.

Each vector point observation gets modeled as a linear function of the non-zero splines in the area around the observation. The least squares regression predicts the coefficients of these linear functions. Regularization avoids the need to have one observation and one coefficient for each spline — which you'd want, because that's how you avoid instability.

So, 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 🚨 data points are often not regularly distributed and require statistical 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: the spline step length should be greater than the mean distance between observation points (twice the distance between points is a good starting point). Having separate east-west and north-south spline step length arguments lets you account for some degree of anisotropy in how your observation points are distributed. And listen — short spline step lengths, especially spline step lengths that are less than the distance between observation points, can greatly increase the processing time. Like, greatly. 😭

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 increases (i.e., with small spline step lengths), the region gets automatically split into subregions for interpolation. Each subregion can contain no more than 150x150 splines. To avoid subregion boundary problems, the 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 point vector layer. If input is 3D and column is not given, then z-coordinates are used for interpolation. Parameter column is required when input is a 2D vector layer.

v.surf.bspline can produce raster (raster_output) OR vector output but NOT simultaneously. No multitasking, periodt. Also note that topology is not built for the output point vector layer. If you need it, the topology can be built using v.build.

If output is a point vector layer and sparse is not specified, the output vector layer will contain points at the same locations as the observation points in the input layer — but the values of the output points will be interpolated values. If a sparse point vector layer is specified, the output vector layer will contain points at the same locations as the sparse vector layer points, and the values will be those of the interpolated raster surface at those points.

A cross validation "leave-one-out" analysis is available to help 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 one 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 point vector layer with estimated (i.e., interpolated) values will be created. slay ✨

🌸 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 layer 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 layer of vector points will be created, corresponding to the sparse vector layer, 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 dataset 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 💀

bestie, listen up, this one actually matters.

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. This function is not supported by the DBF driver 😭. For this reason, vector output (output) is not permitted with the DBF driver. There are no problems with the raster map output from the DBF driver though, so that's fine 🫶.

📚 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

💜

✨ SOURCE CODE ✨

ok so bestie, you wanna see the actual source code?? of course you do, you're a main character who reads the code 💅

  • Available at: v.surf.bspline source code (history) — that's the link to the repo history, go peek, it's giving open source royalty 👑
  • Accessed: Saturday Jan 17 05:41:31 2026 — yeah, that's when this page got pulled, timestamps and everything, no cap ⏰

🧭 the index situation (iykyk)

you can bounce around the whole manual from here, pick your adventure:

  • Main index
  • Vector index
  • Topics index
  • Keywords index
  • Graphical index
  • Full index

like a lil mall directory but for Unix docs 🛍️ every door leads somewhere useful fr fr.

© 2003-2025 GRASS Development Team, GRASS GIS 8.4.2 Reference Manual

that's the copyright line, keep it sacred 🫶 it's been GRASS Development Team's baby since 2003 and they're still feeding it in 2025. iconic behaviour honestly 🌈

💀 reminder that this whole page is the GRASS GIS 8.4.2 reference manual version of v.surf.bspline(1) — so if you're on a different version, vibe check your own docs before you trust every single word, k?

and that's the page bestie!! 🎀 you read the whole thing, spline-interpolated your way to the end, and honestly? slay. ✨

GRASS 8.4.2 · v.surf.bspline(1) · pulled Saturday Jan 17 05:41:31 2026 — go smooth some vectors, you've earned it 💖🦋🌸

📦 where this page comes from