PCL
pcl::SurfaceSpline< T > Class Template Reference

Two-dimensional interpolating/approximating surface spline. More...

#include <SurfaceSpline.h>

+ Inheritance diagram for pcl::SurfaceSpline< T >:

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
 
SurfaceSplineoperator= (const SurfaceSpline &)=default
 
SurfaceSplineoperator= (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_vectorWeights () const
 
vector X () const
 
vector Y () const
 
const vectorZ () const
 

Detailed Description

template<typename T>
class pcl::SurfaceSpline< T >

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.

See also
PointSurfaceSpline, RecursivePointSurfaceSpline, GridInterpolation, PointGridInterpolation, ShepardInterpolation, SurfacePolynomial

Definition at line 267 of file SurfaceSpline.h.

Member Typedef Documentation

◆ rbf_type

template<typename T >
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.

◆ scalar

template<typename T >
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.

◆ vector

template<typename T >
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.

◆ weight

template<typename T >
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.

◆ weight_vector

template<typename T >
using pcl::SurfaceSpline< T >::weight_vector = GenericVector<weight>

Represents a vector of interpolation node weights.

Definition at line 292 of file SurfaceSpline.h.

Constructor & Destructor Documentation

◆ SurfaceSpline() [1/3]

template<typename T >
pcl::SurfaceSpline< T >::SurfaceSpline ( )
default

Default constructor. Constructs an empty, two-dimensional interpolating surface spline of second order.

◆ SurfaceSpline() [2/3]

template<typename T >
pcl::SurfaceSpline< T >::SurfaceSpline ( const SurfaceSpline< T > &  )
default

Copy constructor.

◆ SurfaceSpline() [3/3]

template<typename T >
pcl::SurfaceSpline< T >::SurfaceSpline ( SurfaceSpline< T > &&  )
default

Move constructor.

◆ ~SurfaceSpline()

template<typename T >
pcl::SurfaceSpline< T >::~SurfaceSpline ( )
inlineoverride

Destroys a SurfaceSpline object.

Definition at line 319 of file SurfaceSpline.h.

Member Function Documentation

◆ Clear()

template<typename T >
void pcl::SurfaceSpline< T >::Clear ( )
inline

Resets this surface spline interpolation, deallocating all internal working structures.

Definition at line 752 of file SurfaceSpline.h.

◆ DisablePolynomial()

template<typename T >
void pcl::SurfaceSpline< T >::DisablePolynomial ( bool  disable = true)
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.

◆ EnablePolynomial()

template<typename T >
void pcl::SurfaceSpline< T >::EnablePolynomial ( bool  enable = true)
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.

◆ Initialize()

template<typename T >
void pcl::SurfaceSpline< T >::Initialize ( const scalar x,
const scalar y,
const scalar z,
int  n,
const weight w = nullptr 
)
inline

Generation of a two-dimensional surface spline (thin plate).

Parameters
xX node coordinates.
yY node coordinates.
zNode function values.
nNumber of nodes. Must be ≥ 3 (3 nodes * 2 coordinates = six degrees of freedom).
wWhen 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.

Note
The smoothing factor and the w parameter are only used for the thin plate spline and variable order spline radial basis functions. For other RBFs only interpolation surface splines can be generated with this implementation, and hence the w parameter is always ignored.

Definition at line 615 of file SurfaceSpline.h.

◆ IsPolynomialEnabled()

template<typename T >
bool pcl::SurfaceSpline< T >::IsPolynomialEnabled ( ) const
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.

◆ IsValid()

template<typename T >
bool pcl::SurfaceSpline< T >::IsValid ( ) const
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.

◆ Length()

template<typename T >
int pcl::SurfaceSpline< T >::Length ( ) const
inline

Returns the number of nodes used by this surface spline interpolation.

Definition at line 345 of file SurfaceSpline.h.

◆ operator()() [1/2]

template<typename T >
template<typename Tp >
scalar pcl::SurfaceSpline< T >::operator() ( const GenericPoint< Tp > &  p) const
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.

◆ operator()() [2/2]

template<typename T >
scalar pcl::SurfaceSpline< T >::operator() ( double  x,
double  y 
) const
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.

◆ operator=() [1/2]

template<typename T >
SurfaceSpline& pcl::SurfaceSpline< T >::operator= ( const SurfaceSpline< T > &  )
default

Copy assignment operator. Returns a reference to this object.

◆ operator=() [2/2]

template<typename T >
SurfaceSpline& pcl::SurfaceSpline< T >::operator= ( SurfaceSpline< T > &&  )
default

Move assignment operator. Returns a reference to this object.

◆ Order()

template<typename T >
int pcl::SurfaceSpline< T >::Order ( ) const
inline

Returns the derivability order of this surface spline.

Definition at line 461 of file SurfaceSpline.h.

◆ RBFType()

template<typename T >
rbf_type pcl::SurfaceSpline< T >::RBFType ( ) const
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.

◆ SetOrder()

template<typename T >
void pcl::SurfaceSpline< T >::SetOrder ( int  order)
inline

Sets the derivability order of this surface spline.

Parameters
orderDerivability 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.

◆ SetRBFType()

template<typename T >
void pcl::SurfaceSpline< T >::SetRBFType ( rbf_type  rbf)
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.

◆ SetShapeParameter()

template<typename T >
void pcl::SurfaceSpline< T >::SetShapeParameter ( double  eps)
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.

◆ SetSmoothing()

template<typename T >
void pcl::SurfaceSpline< T >::SetSmoothing ( float  s)
inline

Sets the smoothing factor of this surface spline.

Parameters
sSmoothing 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.

Note
This parameter is only used for the thin plate spline and variable order spline radial basis functions. For other RBFs only interpolation surface splines can be generated with this implementation, and hence this parameter is always ignored.

Definition at line 558 of file SurfaceSpline.h.

◆ ShapeParameter()

template<typename T >
double pcl::SurfaceSpline< T >::ShapeParameter ( ) const
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().

◆ Smoothing()

template<typename T >
float pcl::SurfaceSpline< T >::Smoothing ( ) const
inline

Returns the smoothing factor of this surface spline. See SetSmoothing() for more information.

Definition at line 536 of file SurfaceSpline.h.

◆ Weights()

template<typename T >
const weight_vector& pcl::SurfaceSpline< T >::Weights ( ) const
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.

◆ X()

template<typename T >
vector pcl::SurfaceSpline< T >::X ( ) const
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.

◆ Y()

template<typename T >
vector pcl::SurfaceSpline< T >::Y ( ) const
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.

◆ Z()

template<typename T >
const vector& pcl::SurfaceSpline< T >::Z ( ) const
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.


The documentation for this class was generated from the following file: