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 &S)

	SurfaceSpline (SurfaceSpline &&S)

	~SurfaceSpline () override

void	Clear ()

IsoString	CoreSerialization () const

void	DisablePolynomial (bool disable=true)

void	EnablePolynomial (bool enable=true)

vector	Evaluate (const vector &X, const vector &Y) const

void	Evaluate (scalar Z, const scalar X, const scalar *Y, size_type n) const

bool	HasFastVectorEvaluation () const

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 &S)

SurfaceSpline &	operator= (SurfaceSpline &&S)

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

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 358 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 389 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 366 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 372 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 378 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 383 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 > & S )

inline

Copy constructor.

Definition at line 400 of file SurfaceSpline.h.

◆ SurfaceSpline() [3/3]

template<typename T >

pcl::SurfaceSpline< T >::SurfaceSpline ( SurfaceSpline< T > && S )

inline

Move constructor.

Definition at line 423 of file SurfaceSpline.h.

◆ ~SurfaceSpline()

template<typename T >

pcl::SurfaceSpline< T >::~SurfaceSpline ( )

inlineoverride

Destroys a SurfaceSpline object.

Definition at line 447 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 932 of file SurfaceSpline.h.

◆ CoreSerialization()

template<typename T >

IsoString pcl::SurfaceSpline< T >::CoreSerialization ( ) const

inline

Returns a plain text serialization of the internal core surface spline structures.

If this object uses a core surface spline implementation (such as RadialBasisFunction::DDMThinPlateSpline) and has been correctly initialized, this function returns an implementation-specific plain text serialization. Otherwise, an empty string is returned.

The plain text serialization returned by this function can be used to recreate the internal core surface spline structures without requiring a reinitialization from data points.

Definition at line 956 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 706 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 693 of file SurfaceSpline.h.

◆ Evaluate() [1/2]

template<typename T >

vector pcl::SurfaceSpline< T >::Evaluate	(	const vector &	X,
		const vector &	Y
	)		const

inline

Evaluates the surface spline for a set of points in 2-D space specified as the X and Y vectors of coordinates, and returns the corresponding function values as a vector.

See Evaluate( const scalar*, const scalar*, int ) const for more information.

Definition at line 1141 of file SurfaceSpline.h.

◆ Evaluate() [2/2]

template<typename T >

void pcl::SurfaceSpline< T >::Evaluate	(	scalar *	Z,
		const scalar *	X,
		const scalar *	Y,
		size_type	n
	)		const

inline

Evaluates the surface spline for a set of points in 2-D space specified as the X and Y contiguous sequences of n coordinates, and stores the corresponding function values in the specified array Z.

For core DDM-RBF interpolation/approximation, this is a support function for fast multithreaded evaluation of the surface spline at large-scale sets of interpolation points. For PCL RBF implementations this function can be convenient, but it does not provide any significant performance improvement.

Note: This function provides compatibility with the GridInterpolation and PointGridInterpolation classes.

Definition at line 1118 of file SurfaceSpline.h.

◆ HasFastVectorEvaluation()

template<typename T >

bool pcl::SurfaceSpline< T >::HasFastVectorEvaluation ( ) const

inline

Returns true iff this object can be evaluated for vectors of points in 2-D space efficiently by calling the Evaluate() member functions. In current PCL versions, this member function only returns true for RBF interpolation/approximation algorithms with core implementations.

Note: This function provides compatibility with the GridInterpolation and PointGridInterpolation classes.

Definition at line 1162 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

x	X node coordinates.
y	Y node coordinates.
z	Node function values.
n	Number of nodes. Must be ≥ 3 (3 nodes * 2 coordinates = 6 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.

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 794 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 681 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 514 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 522 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 1099 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 972 of file SurfaceSpline.h.

◆ operator=() [1/2]

template<typename T >

SurfaceSpline& pcl::SurfaceSpline< T >::operator= ( const SurfaceSpline< T > & S )

inline

Copy assignment operator. Returns a reference to this object.

Definition at line 456 of file SurfaceSpline.h.

◆ operator=() [2/2]

template<typename T >

SurfaceSpline& pcl::SurfaceSpline< T >::operator= ( SurfaceSpline< T > && S )

inline

Move assignment operator. Returns a reference to this object.

Definition at line 484 of file SurfaceSpline.h.

◆ Order()

template<typename T >

int pcl::SurfaceSpline< T >::Order ( ) const

inline

Returns the derivability order of this surface spline.

Definition at line 638 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 581 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

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 is only 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, 3 and 4. Orders greater than 6 should not be used under normal conditions, as they are prone to generate ill-conditioned systems with unstable behavior.

Definition at line 666 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 594 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 628 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

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.

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 737 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 608 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 715 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 571 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 532 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 546 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 560 of file SurfaceSpline.h.

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

SurfaceSpline.h

Classes

Public Types

Public Member Functions

Detailed Description

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

Member Typedef Documentation

◆ rbf_type

◆ scalar

◆ vector

◆ weight

◆ weight_vector

Constructor & Destructor Documentation

◆ SurfaceSpline() [1/3]

◆ SurfaceSpline() [2/3]

◆ SurfaceSpline() [3/3]

◆ ~SurfaceSpline()

Member Function Documentation

◆ Clear()

◆ CoreSerialization()

◆ DisablePolynomial()

◆ EnablePolynomial()

◆ Evaluate() [1/2]

◆ Evaluate() [2/2]

◆ HasFastVectorEvaluation()

◆ Initialize()

◆ IsPolynomialEnabled()

◆ IsValid()

◆ Length()

◆ operator()() [1/2]

◆ operator()() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ Order()

◆ RBFType()

◆ SetOrder()

◆ SetRBFType()

◆ SetShapeParameter()

◆ SetSmoothing()

◆ ShapeParameter()

◆ Smoothing()

◆ Weights()

◆ X()

◆ Y()

◆ Z()

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