PCL
|
Two-dimensional interpolating/approximating surface spline. More...
#include <SurfaceSpline.h>
Classes | |
struct | NodeData |
Auxiliary structure for data sanitization. More... | |
Public Types | |
using | rbf_type = SurfaceSplineBase::rbf_type |
using | scalar = T |
using | vector = GenericVector< scalar > |
using | weight = float |
using | weight_vector = GenericVector< weight > |
Public Member Functions | |
SurfaceSpline ()=default | |
SurfaceSpline (const SurfaceSpline &)=default | |
SurfaceSpline (SurfaceSpline &&)=default | |
~SurfaceSpline () override | |
void | Clear () |
void | DisablePolynomial (bool disable=true) |
void | EnablePolynomial (bool enable=true) |
void | Initialize (const scalar *x, const scalar *y, const scalar *z, int n, const weight *w=nullptr) |
bool | IsPolynomialEnabled () const |
bool | IsValid () const |
int | Length () const |
template<typename Tp > | |
scalar | operator() (const GenericPoint< Tp > &p) const |
scalar | operator() (double x, double y) const |
SurfaceSpline & | operator= (const SurfaceSpline &)=default |
SurfaceSpline & | operator= (SurfaceSpline &&)=default |
int | Order () const |
rbf_type | RBFType () const |
void | SetOrder (int order) |
void | SetRBFType (rbf_type rbf) |
void | SetShapeParameter (double eps) |
void | SetSmoothing (float s) |
double | ShapeParameter () const |
float | Smoothing () const |
const weight_vector & | Weights () const |
vector | X () const |
vector | Y () const |
const vector & | Z () const |
SurfaceSpline implements interpolating or smoothing surface splines for arbitrarily distributed input nodes in two dimensions using radial basis functions (RBFs).
The most distinctive property of surface splines is their high adaptability to local variations, which makes them ideal to model complex two dimensional functions with high accuracy. These interpolation properties largely depend on the employed radial basis functions. The well-known thin plate spline function is the default RBF used by this implementation. A thin plate spline describes the minimal-energy bending of a thin sheet of metal passing through a set of interpolation points in three-dimensional space. This physical justification gives thin plate splines accuracy and adaptability properties that we have been applying successfully to many critical data modeling tasks, including very especially image registration and astrometric solutions with arbitrary distortion corrections.
Other RBFs supported by this class include a variable order function that allows imposing the derivability order of the interpolation/approximation spline, as well as less globally dependent functions such as Gaussian and multiquadric RBFs. See the RadialBasisFunction namespace for the complete list of supported RBFs.
An important advantage of our implementation is the possibility to control adaptability with approximating (or smoothing) surface splines, as opposed to interpolating splines, and the possibility to control adaptability both as a global property of the modeling device, or on a point-by-point basis.
The main drawback of surface splines is that they are computationally expensive, especially for large data sets. Generation of surface splines usually requires solving dense linear systems, which involves the use of algorithms with O(N^3) complexity (such as the Bunch-Kaufman diagonal pivoting method). This limits the applicability of this implementation to data sets of no more than about 2000-3000 interpolation nodes using current hardware. See the RecursivePointSurfaceSpline class for a more efficient implementation to generate local subsplines based on quadtrees.
For fast evaluation of surface splines in massive problems, see the GridInterpolation and PointGridInterpolation classes for highly efficient discretized implementations.
Definition at line 267 of file SurfaceSpline.h.
using pcl::SurfaceSpline< T >::rbf_type = SurfaceSplineBase::rbf_type |
Represents a radial basis function (RBF) supported by this surface spline implementation.
Definition at line 298 of file SurfaceSpline.h.
using pcl::SurfaceSpline< T >::scalar = T |
The numeric type used to represent coordinates, function values and spline coefficients.
Definition at line 275 of file SurfaceSpline.h.
using pcl::SurfaceSpline< T >::vector = GenericVector<scalar> |
Represents a vector of coordinates, function values or spline coefficients.
Definition at line 281 of file SurfaceSpline.h.
using pcl::SurfaceSpline< T >::weight = float |
The numeric type used to represent the interpolation strength of a surface interpolation node.
Definition at line 287 of file SurfaceSpline.h.
using pcl::SurfaceSpline< T >::weight_vector = GenericVector<weight> |
Represents a vector of interpolation node weights.
Definition at line 292 of file SurfaceSpline.h.
|
default |
Default constructor. Constructs an empty, two-dimensional interpolating surface spline of second order.
|
default |
Copy constructor.
|
default |
Move constructor.
|
inlineoverride |
Destroys a SurfaceSpline object.
Definition at line 319 of file SurfaceSpline.h.
|
inline |
Resets this surface spline interpolation, deallocating all internal working structures.
Definition at line 752 of file SurfaceSpline.h.
|
inline |
Disables the use of a stabilizing first-degree polynomial added to the RBF interpolation/approximation function.
Calling this member function implicitly resets this SurfaceSpline object and destroys all internal working structures.
Definition at line 527 of file SurfaceSpline.h.
|
inline |
Enables the use of a stabilizing first-degree polynomial added to the RBF interpolation/approximation function.
Calling this member function implicitly resets this SurfaceSpline object and destroys all internal working structures.
Definition at line 514 of file SurfaceSpline.h.
|
inline |
Generation of a two-dimensional surface spline (thin plate).
x | X node coordinates. |
y | Y node coordinates. |
z | Node function values. |
n | Number of nodes. Must be ≥ 3 (3 nodes * 2 coordinates = six degrees of freedom). |
w | When the smoothing factor of this spline is > 0, this is a vector of positive weights > 0 corresponding to the specified input nodes. If this parameter is nullptr , unit weights are assumed for all input nodes. When the smoothing factor is zero (interpolating spline), this parameter is ignored. |
The input nodes can be arbitrarily distributed, and they don't need to follow any specific order. However, all nodes should be distinct with respect to the machine epsilon for the floating point type T.
This initialization function includes a sanitization routine. If there are duplicate points in the specified set of input nodes, only the first occurrence of each duplicate will be kept to build the surface spline, and the rest of duplicate points will be ignored. Two points are considered equal if their coordinates don't differ more than the machine epsilon for the floating point type T.
For an interpolating surface spline (when smoothness = 0), all node function values will be reproduced exactly at their respective coordinates. In this case the vector w of node weights will be ignored.
For an approximating surface spline (smoothness > 0), if a vector w of node weights is specified, it will be used to assign a different interpolation strength to each interpolation node. In this case the vector w must have at least n values greater than zero. A node weight larger than one will reduce the smoothness of the interpolating surface at the corresponding node coordinates, or in other words, it will give more prominence to the corresponding data point. A node weight of one will apply the current surface smoothness at its node position. A node weight smaller than one will increase the interpolation smoothness.
Definition at line 615 of file SurfaceSpline.h.
|
inline |
Returns true iff this surface spline adds a stabilizing first-degree polynomial to the RBF interpolation/approximation function.
A polynomial part is always enabled by default. Disabling it can generate some stability issues, especially for data sets with highly varying node values.
Definition at line 502 of file SurfaceSpline.h.
|
inline |
Returns true iff this surface spline is valid. A valid surface spline has been initialized with three or more interpolation nodes.
Definition at line 337 of file SurfaceSpline.h.
|
inline |
Returns the number of nodes used by this surface spline interpolation.
Definition at line 345 of file SurfaceSpline.h.
|
inline |
Returns an interpolated/approximated function value at the specified p.x and p.y point coordinates. See operator()( double, double ) for more information.
Definition at line 891 of file SurfaceSpline.h.
References pcl::GenericPoint< T >::x, and pcl::GenericPoint< T >::y.
|
inline |
Two-dimensional surface spline interpolation/approximation. Returns an approximated or interpolated function value at the specified x and y coordinates.
Before calling this function, a valid surface spline must be generated by calling Initialize(). If called fon an uninitialized object, this member function invokes undefined behavior.
Definition at line 770 of file SurfaceSpline.h.
|
default |
Copy assignment operator. Returns a reference to this object.
|
default |
Move assignment operator. Returns a reference to this object.
|
inline |
Returns the derivability order of this surface spline.
Definition at line 461 of file SurfaceSpline.h.
|
inline |
Returns the type of radial basis function (RBF) used by this surface spline. See the RadialBasisFunction namespace for the list of supported RBFs in the current implementation.
Definition at line 404 of file SurfaceSpline.h.
|
inline |
Sets the derivability order of this surface spline.
order | Derivability order. Must be ≥ 2. |
Calling this member function implicitly resets this SurfaceSpline object and destroys all internal working structures.
Specifying a derivability order ≥ 2 is really useful for variable order radial basis functions (RadialBasisFunction::VariableOrder). Other RBFs are implicitly of second order, so when they are selected the order specified by calling this function will only change the polynomial part of the surface spline.
Only when a variable order RBF is selected, the surface spline will be continuously differentiable up to the specified order after a subsequent initialization. If the order is too high, an ill-conditioned linear system may result even for a set of valid interpolation nodes.
The default order is 2. Recommended values are 2 and 3.
Definition at line 487 of file SurfaceSpline.h.
|
inline |
Sets the radial basis function that will be used by this surface spline.
Calling this member function implicitly resets this SurfaceSpline object and destroys all internal working structures. If the specified RBF is not of a variable order type, the derivability order of this surface spline will be reset to second order.
Definition at line 417 of file SurfaceSpline.h.
|
inline |
Sets the shape parameter applied to scale the radial basis function used by this surface spline.
If the specified value eps is zero, an optimal shape parameter value will be computed automatically during initialization of spline functions. See the Initialize() member function for more information.
Calling this member function implicitly resets this SurfaceSpline object and destroys all internal working structures.
The shape parameter is only used by decreasing RBFs, i.e., it is not used by the variable order and thin plate spline RBFs, which are parameter-free.
Definition at line 451 of file SurfaceSpline.h.
|
inline |
Sets the smoothing factor of this surface spline.
s | Smoothing factor. Must be ≥ 0. |
For s = 0, an interpolating surface spline will be generated: all node values will be reproduced exactly at their respective coordinates.
For s > 0, a smoothing (or approximating) surface spline will be generated: increasing s values will generate splines closer to the reference plane of the input node set.
Definition at line 558 of file SurfaceSpline.h.
|
inline |
Returns the shape parameter applied to scale the radial basis function used by this surface spline.
The shape parameter is only used by decreasing RBFs, i.e., it is not used by the variable order and thin plate spline RBFs, which are parameter-free.
Definition at line 431 of file SurfaceSpline.h.
References pcl::Sqrt().
|
inline |
Returns the smoothing factor of this surface spline. See SetSmoothing() for more information.
Definition at line 536 of file SurfaceSpline.h.
|
inline |
Returns the vector of node weights used to initialize this surface spline. If this object has not been initialized, or if no node weights were specified or used for initialization, this function returns an empty vector.
Definition at line 394 of file SurfaceSpline.h.
|
inline |
Returns a vector with the X node coordinates used to initialize this surface spline. If this object has not been initialized, this function returns an empty vector.
Definition at line 355 of file SurfaceSpline.h.
|
inline |
Returns a vector with the Y node coordinates used to initialize this surface spline. If this object has not been initialized, this function returns an empty vector.
Definition at line 369 of file SurfaceSpline.h.
|
inline |
Returns a vector with the node function values (Z-axis values) used to initialize this surface spline. If this object has not been initialized, this function returns an empty vector.
Definition at line 383 of file SurfaceSpline.h.