Helios++
Helios software for LiDAR simulations
SurfaceInspector::maths::SingularContextComputer< T > Class Template Reference

Handle singular context descriptors computation. More...

#include <SingularContextComputer.hpp>

Inheritance diagram for SurfaceInspector::maths::SingularContextComputer< T >:
Collaboration diagram for SurfaceInspector::maths::SingularContextComputer< T >:

Public Member Functions

 SingularContextComputer ()
 Default constructor for singular context computer. More...
 
 SingularContextComputer (bool normalize, bool center)
 Non default constructor for singular context computer. More...
 
 SingularContextComputer (size_t aWorst, size_t aBest, size_t bWorst, size_t bBest)
 Non default constructor for singular context computer. More...
 
 SingularContextComputer (bool normalize, bool center, size_t aWorst, size_t aBest, size_t bWorst, size_t bBest)
 Non default constructor for singular context computer. More...
 
void init (bool normalize, bool center, size_t aWorst, size_t aBest, size_t bWorst, size_t bBest)
 Initialize the singular context computer. More...
 
SingularContextDescriptors< T > describe (Mat< T > &M) const
 Obtain singular context descriptors from given matrix. More...
 
vector< size_t > alpha (arma::vec const &v, size_t const a) const
 Extract indices for \(a\) minimum values of \(\vec{v}\). More...
 
vector< size_t > beta (arma::vec const &v, size_t const b) const
 Extract indices for \(b\) maximum values of \(\vec{v}\). More...
 
vector< T > extractComponents (arma::vec const &v, vector< size_t > indices) const
 Extract components of given vector \(\vec{v}\) corresponding to given indices. More...
 
void configureNorm (vector< T > const &a, vector< T > const &b)
 Configure normalization vectors from given ones. More...
 
void configureNorm (vector< vector< T >> const &X)
 Configure normalization vectors from given matrix. More...
 
void normalizeDefault (Mat< T > &M) const
 Normalize given matrix by default criteria. More...
 
void normalizeRGB (Mat< T > &M) const
 Normalize given matrix assuming each first 3 components are RGB so they must be inside \([0, 255]\) interval. More...
 
void normalizeHSO (Mat< T > &M) const
 Normalize given matrix assuming each first 3 components are HSO (Horizontality, Sum and Omnivariance). More...
 
void normalizeHLI (Mat< T > &M) const
 Normalize given matrix assuming each first 3 components are HLI (Horizontality, Linearity and Intensity). More...
 
void normalizeLP (Mat< T > &M) const
 Normalize given matrix assuming each first 2 components are LP (Linearity and Planarity) More...
 
void normalizeGdCd (Mat< T > &M) const
 Normalize given matrix assuming each first 2 components are GdCd (Ground-distance and Ceiling-distance) More...
 
void normalizeGdCdI (Mat< T > &M) const
 Normalize given matrix assuming each first 3 components are GdCdI (Ground-distance, Ceiling-distance, Intensity. More...
 
void normalizeHV (Mat< T > &M) const
 Normalize given matrix assuming each first 2 components are HV (Horizontality and Verticality) More...
 
void normalizeSO (Mat< T > &M) const
 Normalize given matrix assuming each first 2 components are SO (Sum and Omnivariance) More...
 
void normalizeLC (Mat< T > &M) const
 Normalize given matrix assuming each first 2 components are LC (Linearity and Curvature) More...
 
void normalizeVC (Mat< T > &M) const
 Normalize given matrix assuming each first 2 components are VC (Verticality and Curvature) More...
 
void normalizePC (Mat< T > &M) const
 Normalize given matrix assuming each first 2 components are PC (Planarity and Curvature) More...
 
void normalizeVR (Mat< T > &M) const
 Normalize given matrix assuming each first 2 components are VR (Verticality and Roughness) More...
 
void normalizeCone (Mat< T > &M) const
 Normalize given matrix assuming (X,Y,Z) components for a cone. More...
 
void normalizeHyperbolicParaboloid (Mat< T > &M) const
 Normalize given matrix assuming (X,Y,Z) components for a hyperbolic paraboloid. More...
 
void centerDefault (Mat< T > &M) const
 Center given matrix by default criteria. More...
 

Public Attributes

bool normalizeFlag
 Flag which specifies if the singular context computer must normalize when computing descriptors (true) or not (false)
 
bool centerFlag
 Flag which specifies if the singular context computer must center when computing descriptors (true) or not (false)
 
size_t aWorst
 How many minimum values consider when computing the \(\alpha_a(v^{-})\) function for the worst fitting vector.
 
size_t aBest
 How many minimum values consider when computing the \(\alpha_a(v^{+})\) function for the best fitting vector.
 
size_t bWorst
 How many minimum values consider when computing the \(\beta_b(v^{-})\) function for the worst fitting vector.
 
size_t bBest
 How many maximum values consider when computing the \(\beta_b(v^{+})\) function for the best fitting vector.
 
bool absoluteComponents = false
 Specify if use absolute values of the singular vector components (true) or consider their signed version (false)
 
void(SingularContextComputer< T >::* normalize )(Mat< T > &M) const
 Function which normalizes the matrix if necessary. A default implementation is provided as the normalizeDefault function. More...
 
void(SingularContextComputer< T >::* center )(Mat< T > &M) const
 Function which centers the matrix if necessary. A default implementation is provided as the centerDefault function. More...
 
vector< T > aNorm
 The \(\vec{a}\) vector must contain the start of normalization interval if the normalization strategy requires it. More...
 
vector< T > bNorm
 The \(\vec{b}\) vector must contain the end of normalization interval if the normalization strategy requires it. More...
 
vector< T > deltaNorm
 

Detailed Description

template<typename T>
class SurfaceInspector::maths::SingularContextComputer< T >

Handle singular context descriptors computation.

Author
Alberto M. Esmoris Pena
Version
1.0

The singular context descriptors algorithm can be described as follows, for any input matrix \(P_{m \times n}\) where each i-th row is a point \(p_i = (x_{i1}, \ldots, x_{in})\) in \(\mathbb{R}^{n}\).

1. Normalize
Let \(\vec{x}_j\) be the vector containing the j-th component of each point in the matrix \(P\). Thus, \(\vec{x}_j = (x_{1j}, \ldots, x_{mj})\) is a column vector from \(P\).
Now, each value in \(P\) can be normalized as follows:

\[ \hat{x}_{ij} = \frac{x_{ij} - \min\left({\vec{x}_j}\right)} {\max\left({\vec{x}_j}\right) - \min\left(\vec{x}_j\right)} \]

NOTICE here exposed method is the default normalization strategy. Other normalization methods could be used.


2. Center
Let \(\mu_j\) be the mean of the j-th component for each normalized point. It is:

\[ \mu_j = \frac{1}{m} \sum_{i=1}^{m}{\hat{x}_{ij}} \]

Therefore, for each normalized \({\hat{x}_{ij}}\) its centered version can be defined as \(\overline{x}_{ij} = \hat{x}_{ij} - \mu_j\).

NOTICE here exposed method is the default centering strategy. Other centering methods could be used.


3. Factorize
After applying previous transformations, the matrix \({X}\) arises:

\[ X_{m \times n} = \left[\begin{array}{lll} \overline{x}_{11} & \ldots & \overline{x}_{1n} \\ \vdots & \ddots & \vdots \\ \overline{x}_{m1} & \ldots & \overline{x}_{mn} \end{array}\right] \]

This matrix can be factorized with singular value decomposition so:

\[ X_{m \times n } = U_{m \times r} \Sigma_{r \times r} V^{T}_{r \times n} \]

In consequence, singular values are obtained as \(\mathrm{diag}\left(\Sigma\right) = \vec{\sigma}\) while singular vectors are the rows from matrix \(V^{T}\).

Currently, armadillo library is being used to compute the singular values decomposition. This library returns \(V\) instead of \(V^{T}\). So, if the singular vectors come from rows of \(V^{T}\), when using armadillo they come from columns of \(V\).


4. Singular context descriptors
Let \(v^{-}\) and \(v^{+}\) be the singular vectors associated with minimum and maximum singular values, respectively. Also, let the functions \(\alpha_a(\vec{v})\) and \(\beta_b(\vec{v})\) be as described in this class.

Thus, sets \(\mathcal{S}^{-}\) and \(\mathcal{S}^{+}\) will be:

\[ \left.\begin{array}{l} \mathcal{S}^{-} = \left\{ (j, v_j^-) : j \in \alpha_a(v^-) \lor j \in \beta_b(v^-) \right\} \\ \mathcal{S}^{+} = \left\{ (j, v_j^+) : j \in \alpha_a(v^+) \lor j \in \beta_b(v^+) \right\} \end{array}\right. \]

Now understand \(\sigma^-\) and \(sigma^+\) as the minimum and maximum singular values respectively.

Finally, the singular context descriptors of \(X\) are:

\[ \mathrm{SCD}\left(X \right) = \left\{ \sigma^-, \sigma^+, \mathcal{S}^-, \mathcal{S}^+ \right\} \]

See also
SurfaceInspector::maths::SingularContextDescriptors
SingularContextComputer::alpha
SingularContextComputer::beta

Constructor & Destructor Documentation

◆ SingularContextComputer() [1/4]

Default constructor for singular context computer.

See also
SingularContextComputer::init

◆ SingularContextComputer() [2/4]

template<typename T >
SurfaceInspector::maths::SingularContextComputer< T >::SingularContextComputer ( bool  normalize,
bool  center 
)
inline

Non default constructor for singular context computer.

See also
SingularContextComputer::init

◆ SingularContextComputer() [3/4]

template<typename T >
SurfaceInspector::maths::SingularContextComputer< T >::SingularContextComputer ( size_t  aWorst,
size_t  aBest,
size_t  bWorst,
size_t  bBest 
)
inline

Non default constructor for singular context computer.

See also
SingularContextComputer::init

◆ SingularContextComputer() [4/4]

template<typename T >
SurfaceInspector::maths::SingularContextComputer< T >::SingularContextComputer ( bool  normalize,
bool  center,
size_t  aWorst,
size_t  aBest,
size_t  bWorst,
size_t  bBest 
)
inline

Non default constructor for singular context computer.

See also
SingularContextComputer::init

Member Function Documentation

◆ alpha()

template<typename T >
vector<size_t> SurfaceInspector::maths::SingularContextComputer< T >::alpha ( arma::vec const &  v,
size_t const  a 
) const

Extract indices for \(a\) minimum values of \(\vec{v}\).

Parameters
vVector to extract indices of \(a\) minimum values from
aHow many minimum values extract from vector \(\vec{v}\)
Returns
Indices of \(a\) minimum values from \(\vec{v}\)

◆ beta()

template<typename T >
vector<size_t> SurfaceInspector::maths::SingularContextComputer< T >::beta ( arma::vec const &  v,
size_t const  b 
) const

Extract indices for \(b\) maximum values of \(\vec{v}\).

Parameters
vVector to extract indices of \(b\) maximum values from
bHow many maximum values extract from vector \(\vec{v}\)
Returns
Indices of \(b\) maximum values from \(\vec{v}\)

◆ centerDefault()

template<typename T >
void SurfaceInspector::maths::SingularContextComputer< T >::centerDefault ( Mat< T > &  M) const

Center given matrix by default criteria.

Parameters
MMatrix to be centered

◆ configureNorm() [1/2]

template<typename T >
void SurfaceInspector::maths::SingularContextComputer< T >::configureNorm ( vector< T > const &  a,
vector< T > const &  b 
)

Configure normalization vectors from given ones.

Parameters
aThe \(\vec{a}\) vector for normalization start
bThe \(\vec{b}\) vector for normalization end
See also
SingularContextComputer::aNorm
SingularContextComputer::bNorm
SingularContextComputer::deltaNorm

◆ configureNorm() [2/2]

template<typename T >
void SurfaceInspector::maths::SingularContextComputer< T >::configureNorm ( vector< vector< T >> const &  X)

Configure normalization vectors from given matrix.

Parameters
XMatrix containing all values so X[i][j] is the j-th value of the i-th attribute. It is, X[i] is the vector containing all values for i-th attribute.

◆ describe()

template<typename T >
SingularContextDescriptors<T> SurfaceInspector::maths::SingularContextComputer< T >::describe ( Mat< T > &  M) const

Obtain singular context descriptors from given matrix.

NOTICE the describe function might modify given matrix

Parameters
MMatrix which singular context descriptors must be obtained
Returns
The singular context descriptors of given matrix
See also
SingularContextDescriptors

◆ extractComponents()

template<typename T >
vector<T> SurfaceInspector::maths::SingularContextComputer< T >::extractComponents ( arma::vec const &  v,
vector< size_t >  indices 
) const

Extract components of given vector \(\vec{v}\) corresponding to given indices.

Parameters
vVector to extract components from
indicesIndices of components to be extracted
Returns
Vector containing extracted components

◆ init()

template<typename T >
void SurfaceInspector::maths::SingularContextComputer< T >::init ( bool  normalize,
bool  center,
size_t  aWorst,
size_t  aBest,
size_t  bWorst,
size_t  bBest 
)

◆ normalizeCone()

template<typename T >
void SurfaceInspector::maths::SingularContextComputer< T >::normalizeCone ( Mat< T > &  M) const

Normalize given matrix assuming (X,Y,Z) components for a cone.

Parameters
MMatrix to be normalized

◆ normalizeDefault()

template<typename T >
void SurfaceInspector::maths::SingularContextComputer< T >::normalizeDefault ( Mat< T > &  M) const

Normalize given matrix by default criteria.

Parameters
MMatrix to be normalized

◆ normalizeGdCd()

template<typename T >
void SurfaceInspector::maths::SingularContextComputer< T >::normalizeGdCd ( Mat< T > &  M) const

Normalize given matrix assuming each first 2 components are GdCd (Ground-distance and Ceiling-distance)

Parameters
MMatrix to be normalized

◆ normalizeGdCdI()

template<typename T >
void SurfaceInspector::maths::SingularContextComputer< T >::normalizeGdCdI ( Mat< T > &  M) const

Normalize given matrix assuming each first 3 components are GdCdI (Ground-distance, Ceiling-distance, Intensity.

Parameters
MMatrix to be normalized

◆ normalizeHLI()

template<typename T >
void SurfaceInspector::maths::SingularContextComputer< T >::normalizeHLI ( Mat< T > &  M) const

Normalize given matrix assuming each first 3 components are HLI (Horizontality, Linearity and Intensity).

Parameters
MMatrix to be normalized

◆ normalizeHSO()

template<typename T >
void SurfaceInspector::maths::SingularContextComputer< T >::normalizeHSO ( Mat< T > &  M) const

Normalize given matrix assuming each first 3 components are HSO (Horizontality, Sum and Omnivariance).

Parameters
MMatrix to be normalized

◆ normalizeHV()

template<typename T >
void SurfaceInspector::maths::SingularContextComputer< T >::normalizeHV ( Mat< T > &  M) const

Normalize given matrix assuming each first 2 components are HV (Horizontality and Verticality)

Parameters
MMatrix to be normalized

◆ normalizeHyperbolicParaboloid()

template<typename T >
void SurfaceInspector::maths::SingularContextComputer< T >::normalizeHyperbolicParaboloid ( Mat< T > &  M) const

Normalize given matrix assuming (X,Y,Z) components for a hyperbolic paraboloid.

Parameters
MMatrix to be normalized

◆ normalizeLC()

template<typename T >
void SurfaceInspector::maths::SingularContextComputer< T >::normalizeLC ( Mat< T > &  M) const

Normalize given matrix assuming each first 2 components are LC (Linearity and Curvature)

Parameters
MMatrix to be normalized

◆ normalizeLP()

template<typename T >
void SurfaceInspector::maths::SingularContextComputer< T >::normalizeLP ( Mat< T > &  M) const

Normalize given matrix assuming each first 2 components are LP (Linearity and Planarity)

Parameters
MMatrix to be normalized

◆ normalizePC()

template<typename T >
void SurfaceInspector::maths::SingularContextComputer< T >::normalizePC ( Mat< T > &  M) const

Normalize given matrix assuming each first 2 components are PC (Planarity and Curvature)

Parameters
MMatrix to be normalized

◆ normalizeRGB()

template<typename T >
void SurfaceInspector::maths::SingularContextComputer< T >::normalizeRGB ( Mat< T > &  M) const

Normalize given matrix assuming each first 3 components are RGB so they must be inside \([0, 255]\) interval.

\[ \forall j \in \{1, 2, 3\}, \hat{x_ij} = \frac{x}{255} \]

Parameters
MMatrix to be normalized

◆ normalizeSO()

template<typename T >
void SurfaceInspector::maths::SingularContextComputer< T >::normalizeSO ( Mat< T > &  M) const

Normalize given matrix assuming each first 2 components are SO (Sum and Omnivariance)

Parameters
MMatrix to be normalized

◆ normalizeVC()

template<typename T >
void SurfaceInspector::maths::SingularContextComputer< T >::normalizeVC ( Mat< T > &  M) const

Normalize given matrix assuming each first 2 components are VC (Verticality and Curvature)

Parameters
MMatrix to be normalized

◆ normalizeVR()

template<typename T >
void SurfaceInspector::maths::SingularContextComputer< T >::normalizeVR ( Mat< T > &  M) const

Normalize given matrix assuming each first 2 components are VR (Verticality and Roughness)

Parameters
MMatrix to be normalized

Member Data Documentation

◆ aNorm

template<typename T >
vector<T> SurfaceInspector::maths::SingularContextComputer< T >::aNorm

The \(\vec{a}\) vector must contain the start of normalization interval if the normalization strategy requires it.

\(a_i\) is the start of normalization interval for i-th component

◆ bNorm

template<typename T >
vector<T> SurfaceInspector::maths::SingularContextComputer< T >::bNorm

The \(\vec{b}\) vector must contain the end of normalization interval if the normalization strategy requires it.

\(b_i\) is the end of normalization interval for i-th component

◆ center

template<typename T >
void(SingularContextComputer<T>::* SurfaceInspector::maths::SingularContextComputer< T >::center) (Mat< T > &M) const

Function which centers the matrix if necessary. A default implementation is provided as the centerDefault function.

Any valid centering function that is assigned to this attribute will be used by the singular context computer

See also
SingularContextComputer::centerDefault

◆ deltaNorm

template<typename T >
vector<T> SurfaceInspector::maths::SingularContextComputer< T >::deltaNorm

\[ \vec{\Delta} = \vec{b} - \vec{a} \]

◆ normalize

template<typename T >
void(SingularContextComputer<T>::* SurfaceInspector::maths::SingularContextComputer< T >::normalize) (Mat< T > &M) const

Function which normalizes the matrix if necessary. A default implementation is provided as the normalizeDefault function.

Any valid normalization function that is assigned to this attribute will be used by the singular context computer

See also
SingularContextComputer::normalizeDefault

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