Procedure that compute and decompose the covariance matrix of the neighbors positions. More...

#include <covariance.h>

Inheritance diagram for Ponca::CovarianceBase< DataPoint, _NFilter, T >:

Collaboration diagram for Ponca::CovarianceBase< DataPoint, _NFilter, T >:

Public Types
using	Scalar = typename DataPoint::Scalar
	Alias to scalar type.

using	VectorType = typename Base::VectorType
	Alias to vector type.

using	NeighborFilter = typename Base::NeighborFilter
	Alias to the filter applied on the neighbors.

using	MatrixType = typename DataPoint::MatrixType
	Alias to matrix type.

using	Solver = Eigen::SelfAdjointEigenSolver< MatrixType >
	Solver used to analyse the covariance matrix.

Public Member Functions
CovarianceBase< DataPoint, _NFilter, T > &	covarianceBase ()
	Explicit conversion to CovarianceBase , to access methods potentially hidden by heritage.

const CovarianceBase< DataPoint, _NFilter, T > &	covarianceBase () const
	Explicit conversion to CovarianceBase , to access methods potentially hidden by heritage.

void	init ()
	Set the evaluation position and reset the internal states.

void	addLocalNeighbor (Scalar w, const VectorType &localQ, const DataPoint &attributes)
	Add a neighbor to perform the fit.

FIT_RESULT	finalize ()
	Finalize the procedure.

Scalar	surfaceVariation () const
	Implements [15] surface variation.

Scalar	planarity () const
	Implements the planarity [9] .

Scalar	linearity () const
	Implements the linearity [9] .

Scalar	sphericity () const
	Implements the sphericity [9] .

Scalar	anisotropy () const
	Implements the anisotropy [9] .

Scalar	eigenentropy () const
	Implements the eigenentropy [9] .

Scalar	lambda_0 () const
	The minimum eigenvalue \( \lambda_0 \).

Scalar	lambda_1 () const
	The second eigenvalue \( \lambda_1 \).

Scalar	lambda_2 () const
	The maximum eigenvalue \( \lambda_2 \).

const Solver &	solver () const
	Reading access to the Solver used to analyze the covariance matrix.

Protected Types
using	Base = T
	Base class of the procedure.

Protected Attributes
MatrixType	m_cov {MatrixType::Zero()}
	Covariance matrix.

Solver	m_solver
	Solver used to analyse the covariance matrix.

Detailed Description

template<class DataPoint, class _NFilter, typename T>
requires ProvidesMeanPosition<T>
class Ponca::CovarianceBase< DataPoint, _NFilter, T >

Procedure that compute and decompose the covariance matrix of the neighbors positions.

This process is commonly used for plane fitting and local variance analysis. It is often called Principal Component Analysis (PCA) of the neighborhood, and used in Geometry Processing and Computer Vision.

See also: CovariancePlaneFit which use a similar approach for Plane estimation

Computation details

Standard PCA algorithm involves a two-steps process where the barycenter \(\mathbf{b}\) is first computed, and then the covariance matrix \(\text{C}\) (in the following, the weights are ignored for clarity but without loss of generality):

\begin{align} \mathbf{b} &= \frac{1}{n}\sum_i\mathbf{p}_i \\ \text{C} &= \frac{1}{n}\sum_i(\mathbf{p}_i-\mathbf{b})(\mathbf{p}_i-\mathbf{b})^T \end{align}

This class implements a single-pass version, where the first formulation is re-expressed as follows:

\begin{align} \text{C} &= \frac{1}{n}\sum_i (\mathbf{p}_i\mathbf{p}_i^T - \mathbf{b}\mathbf{p}_i^T - \mathbf{p}_i\mathbf{b}^T + \mathbf{b}\mathbf{b}^T) \\ &= \frac{1}{n}\sum_i (\mathbf{p}_i\mathbf{p}_i^T) - \frac{1}{n}\sum_i(\mathbf{b}\mathbf{p}_i^T) - \frac{1}{n}\sum_i(\mathbf{p}_i\mathbf{b}^T) + \frac{1}{n}\sum_i (\mathbf{b}\mathbf{b}^T) \\ &= \frac{1}{n}\sum_i (\mathbf{p}_i\mathbf{p}_i^T) - \mathbf{b}\frac{1}{n}\sum_i(\mathbf{p}_i^T) - \frac{1}{n}\sum_i(\mathbf{p}_i)\mathbf{b}^T + \frac{1}{n}\sum_i(1) \mathbf{b}\mathbf{b}^T \\ &= \frac{1}{n}\sum_i (\mathbf{p}_i\mathbf{p}_i^T) - \mathbf{b}\mathbf{b}^T - \mathbf{b}\mathbf{b}^T + \mathbf{b}\mathbf{b}^T \end{align}

Leading to a single pass where \(\text{C}\) is express by subtracting two terms that can be computed independently in one run:

\[ \text{C} = \frac{1}{n}\sum_i (\mathbf{p}_i\mathbf{p}_i^T) - \mathbf{b}\mathbf{b}^T \]

All the computed features are defined for the 3 eigenvalues \( 0 < \lambda_0 \leq \lambda_1 \leq \lambda_2 \).

Warning: This class is valid for any dimensions, however some statistics can only be computed in 3d.

Definition at line 65 of file covariance.h.

Member Typedef Documentation

◆ Base

template<class DataPoint , class _NFilter , typename T >

using Ponca::CovarianceBase< DataPoint, _NFilter, T >::Base = T

protected

Base class of the procedure.

Definition at line 67 of file covariance.h.

◆ MatrixType

template<class DataPoint , class _NFilter , typename T >

using Ponca::CovarianceBase< DataPoint, _NFilter, T >::MatrixType = typename DataPoint::MatrixType

Alias to matrix type.

Definition at line 69 of file covariance.h.

◆ NeighborFilter

template<class DataPoint , class _NFilter , typename T >

using Ponca::CovarianceBase< DataPoint, _NFilter, T >::NeighborFilter = typename Base::NeighborFilter

Alias to the filter applied on the neighbors.

Definition at line 67 of file covariance.h.

◆ Scalar

template<class DataPoint , class _NFilter , typename T >

using Ponca::CovarianceBase< DataPoint, _NFilter, T >::Scalar = typename DataPoint::Scalar

Alias to scalar type.

Definition at line 67 of file covariance.h.

◆ Solver

template<class DataPoint , class _NFilter , typename T >

using Ponca::CovarianceBase< DataPoint, _NFilter, T >::Solver = Eigen::SelfAdjointEigenSolver<MatrixType>

Solver used to analyse the covariance matrix.

Definition at line 71 of file covariance.h.

◆ VectorType

template<class DataPoint , class _NFilter , typename T >

using Ponca::CovarianceBase< DataPoint, _NFilter, T >::VectorType = typename Base::VectorType

Alias to vector type.

Definition at line 67 of file covariance.h.

Member Function Documentation

◆ addLocalNeighbor()

template<class DataPoint , class _NFilter , typename T >

void CovarianceBase::addLocalNeighbor	(	Scalar	w,
		const VectorType &	localQ,
		const DataPoint &	attributes
	)

inline

Add a neighbor to perform the fit.

Definition at line 20 of file covariance.hpp.

◆ anisotropy()

template<class DataPoint , class _NFilter , typename T >

CovarianceBase< DataPoint, _WFunctor, T >::Scalar CovarianceBase::anisotropy ( ) const

inline

Implements the anisotropy [9] .

Anisotropy is defined as:

\[ \frac{\lambda_2 - \lambda_0}{\lambda_2} \]

Note: Valid in any dimension, but not sure what it means out of 3d

Definition at line 85 of file covariance.hpp.

◆ covarianceBase() [1/2]

template<class DataPoint , class _NFilter , typename T >

CovarianceBase< DataPoint, _NFilter, T > & Ponca::CovarianceBase< DataPoint, _NFilter, T >::covarianceBase ( )

inline

Explicit conversion to CovarianceBase , to access methods potentially hidden by heritage.

Definition at line 79 of file covariance.h.

◆ covarianceBase() [2/2]

template<class DataPoint , class _NFilter , typename T >

const CovarianceBase< DataPoint, _NFilter, T > & Ponca::CovarianceBase< DataPoint, _NFilter, T >::covarianceBase ( ) const

inline

Explicit conversion to CovarianceBase , to access methods potentially hidden by heritage.

Definition at line 79 of file covariance.h.

◆ eigenentropy()

template<class DataPoint , class _NFilter , typename T >

CovarianceBase< DataPoint, _WFunctor, T >::Scalar CovarianceBase::eigenentropy ( ) const

inline

Implements the eigenentropy [9] .

Eigenentropy is defined as:

\[ - \sum_i (\lambda_i * \ln{\lambda_i}) \]

Definition at line 92 of file covariance.hpp.

◆ finalize()

template<class DataPoint , class _NFilter , typename T >

FIT_RESULT CovarianceBase::finalize ( )

inline

Finalize the procedure.

Returns: Fitting Status

Warning: Must be called be for any use of the fitting output

Definition at line 29 of file covariance.hpp.

◆ init()

template<class DataPoint , class _NFilter , typename T >

void CovarianceBase::init ( )

inline

Set the evaluation position and reset the internal states.

Warning: Must be called be for any computation (but * after #setNeighborFilter)

Definition at line 12 of file covariance.hpp.

◆ lambda_0()

template<class DataPoint , class _NFilter , typename T >

CovarianceBase< DataPoint, _WFunctor, T >::Scalar CovarianceBase::lambda_0 ( ) const

inline

The minimum eigenvalue \( \lambda_0 \).

Definition at line 99 of file covariance.hpp.

◆ lambda_1()

template<class DataPoint , class _NFilter , typename T >

CovarianceBase< DataPoint, _WFunctor, T >::Scalar CovarianceBase::lambda_1 ( ) const

inline

The second eigenvalue \( \lambda_1 \).

Definition at line 106 of file covariance.hpp.

◆ lambda_2()

template<class DataPoint , class _NFilter , typename T >

CovarianceBase< DataPoint, _WFunctor, T >::Scalar CovarianceBase::lambda_2 ( ) const

inline

The maximum eigenvalue \( \lambda_2 \).

Definition at line 113 of file covariance.hpp.

◆ linearity()

template<class DataPoint , class _NFilter , typename T >

CovarianceBase< DataPoint, _WFunctor, T >::Scalar CovarianceBase::linearity ( ) const

inline

Implements the linearity [9] .

Linearity is defined as:

\[ \frac{\lambda_2 - \lambda_1}{\lambda_2} \]

Warning: Valid only in 3d

Definition at line 69 of file covariance.hpp.

◆ planarity()

template<class DataPoint , class _NFilter , typename T >

CovarianceBase< DataPoint, _WFunctor, T >::Scalar CovarianceBase::planarity ( ) const

inline

Implements the planarity [9] .

Planarity is defined as:

\[ \frac{\lambda_1 - \lambda_0}{\lambda_2} \]

Warning: Valid only in 3d

Definition at line 61 of file covariance.hpp.

◆ solver()

template<class DataPoint , class _NFilter , typename T >

const Solver & Ponca::CovarianceBase< DataPoint, _NFilter, T >::solver ( ) const

inline

Reading access to the Solver used to analyze the covariance matrix.

Definition at line 136 of file covariance.h.

◆ sphericity()

template<class DataPoint , class _NFilter , typename T >

CovarianceBase< DataPoint, _WFunctor, T >::Scalar CovarianceBase::sphericity ( ) const

inline

Implements the sphericity [9] .

Sphericity is defined as:

\[ \frac{\lambda_0}{\lambda_2} \]

Warning: Valid only in 3d

Definition at line 77 of file covariance.hpp.

◆ surfaceVariation()

template<class DataPoint , class _NFilter , typename T >

CovarianceBase< DataPoint, _NFilter, T >::Scalar CovarianceBase::surfaceVariation ( ) const

inline

Implements [15] surface variation.

It computes the ratio \( d \frac{\lambda_0}{\sum_i \lambda_i} \) with d the dimension of the ambient space.

Returns: 0 for invalid fits

Definition at line 54 of file covariance.hpp.

Member Data Documentation

◆ m_cov

template<class DataPoint , class _NFilter , typename T >

MatrixType Ponca::CovarianceBase< DataPoint, _NFilter, T >::m_cov {MatrixType::Zero()}

protected

Covariance matrix.

Definition at line 75 of file covariance.h.

◆ m_solver

template<class DataPoint , class _NFilter , typename T >

Solver Ponca::CovarianceBase< DataPoint, _NFilter, T >::m_solver

protected

Solver used to analyse the covariance matrix.

Definition at line 76 of file covariance.h.

Public Types

Public Member Functions

Protected Types

Protected Attributes

Detailed Description

Computation details

Member Typedef Documentation

◆ Base

◆ MatrixType

◆ NeighborFilter

◆ Scalar

◆ Solver

◆ VectorType

Member Function Documentation

◆ addLocalNeighbor()

◆ anisotropy()

◆ covarianceBase() [1/2]

◆ covarianceBase() [2/2]

◆ eigenentropy()

◆ finalize()

◆ init()

◆ lambda_0()

◆ lambda_1()

◆ lambda_2()

◆ linearity()

◆ planarity()

◆ solver()

◆ sphericity()

◆ surfaceVariation()

Member Data Documentation

◆ m_cov

◆ m_solver