Visual Servoing Platform  version 3.6.1 under development (2024-03-28)
vpRobust Class Reference

#include <visp3/core/vpRobust.h>

Public Types

enum  vpRobustEstimatorType { TUKEY , CAUCHY , HUBER }
 

Public Member Functions

 vpRobust ()
 
 vpRobust (const vpRobust &other)
 
virtual ~vpRobust ()
 
double getMedianAbsoluteDeviation ()
 
double getMinMedianAbsoluteDeviation ()
 
void MEstimator (const vpRobustEstimatorType method, const vpColVector &residues, vpColVector &weights)
 
vpRobustoperator= (const vpRobust &other)
 
vpRobustoperator= (const vpRobust &&other)
 
void setMinMedianAbsoluteDeviation (double mad_min)
 

Deprecated functions

vp_deprecated vpRobust (unsigned int n_data)
 
void MEstimator (const vpRobustEstimatorType method, const vpColVector &residues, const vpColVector &all_residues, vpColVector &weights)
 
vp_deprecated void setIteration (unsigned int iter)
 
vp_deprecated void setThreshold (double mad_min)
 
vp_deprecated vpColVector simultMEstimator (vpColVector &residues)
 

Detailed Description

Contains an M-estimator and various influence function.

This class implements an M-estimator with Tukey, Cauchy or Huber influence function [9] which allow uncertain measures to be less likely considered and in some cases completely rejected, thus inferring that the data is not normally distributed.

When using a robust estimate of the mean, it is usual to normalize the distribution to center the data around zero. In the case of a median operator, the normalized residue is given by:

$\overline{r_i} = r_i - {Med}(r_i) $ where ${Med}(r_i)$ is the median value of the residue vector $r$.

The Median Absolute Deviation (MAD) representing one standard deviation of the normal distribution is given by:

\[ \sigma = 1.48 \; {Med}(|\overline{r_i}|) \]

This class allows to set the minimum value of $ \sigma $ using setMinMedianAbsoluteDeviation().

This estimated standard deviation $\sigma$ can accordingly be used with a tuning variable for different influence functions.

Let us consider the weight function $w(r)$ with $r$ the residual vector of the parameters to estimate.

  • Using Huber influence function, with $a$ a constant such as $a=1.21 \; \sigma $ we have

    \[ w(r_i) = \left\{ \begin{array}{ll} 1 & \mbox{if } |r_i| \leq a \\ \frac{a}{|r_i|} & \mbox{else} \end{array} \right. \]

  • Using Tukey influence function, with $b$ a constant such as $b=4.68 \; \sigma $ we have

    \[ w(r_i) = \left\{ \begin{array}{ll} {\left(1 - {\left(\frac{r_i}{b}\right)}^2 \right)}^2 & \mbox{if } |r_i| \leq b \\ 0 & \mbox{else} \end{array} \right. \]

  • Using Cauchy influence function, with $c$ a constant such as $c=2.38 \; \sigma $ we have

    \[ w(r_i) = \frac{1}{(1 + {(r_i/c)}^2)} \]

Given the influence function and the residual vector, the weights are updated in MEstimator().

Examples
ClassUsingPclViewer.cpp, and testTukeyEstimator.cpp.

Definition at line 82 of file vpRobust.h.

Member Enumeration Documentation

◆ vpRobustEstimatorType

Enumeration of influence functions.

Enumerator
TUKEY 

Tukey influence function.

CAUCHY 

Cauchy influence function.

HUBER 

Huber influence function.

Definition at line 86 of file vpRobust.h.

Constructor & Destructor Documentation

◆ vpRobust() [1/3]

vpRobust::vpRobust ( )

Default constructor.

Definition at line 59 of file vpRobust.cpp.

◆ vpRobust() [2/3]

vpRobust::vpRobust ( const vpRobust other)

Copy constructor.

Definition at line 70 of file vpRobust.cpp.

◆ ~vpRobust()

virtual vpRobust::~vpRobust ( )
inlinevirtual

Destructor.

Definition at line 119 of file vpRobust.h.

◆ vpRobust() [3/3]

vpRobust::vpRobust ( unsigned int  n_data)
explicit
Deprecated:
You should rather use the default constructor.
Parameters
n_data: Size of the data vector.

Definition at line 312 of file vpRobust.cpp.

References vpColVector::resize(), and vpCDEBUG.

Member Function Documentation

◆ getMedianAbsoluteDeviation()

double vpRobust::getMedianAbsoluteDeviation ( )
inline

Return residual vector Median Absolute Deviation (MAD). This value is updated after a call to MEstimator(). It corresponds to value of $ \sigma = 1.48{Med}(|r_i - {Med}(r_i)|) $. This value cannot be lower than the min value returned by getMinMedianAbsoluteDeviation() or set with setMinMedianAbsoluteDeviation().

See also
setMinMedianAbsoluteDeviation()

Definition at line 130 of file vpRobust.h.

◆ getMinMedianAbsoluteDeviation()

double vpRobust::getMinMedianAbsoluteDeviation ( )
inline

Return the min value used to threshold residual vector Median Absolute Deviation (MAD). This value corresponds to the minimal value of $\sigma$ computed in MEstimator().

See also
setMinMedianAbsoluteDeviation()

Definition at line 138 of file vpRobust.h.

◆ MEstimator() [1/2]

void vpRobust::MEstimator ( const vpRobustEstimatorType  method,
const vpColVector residues,
const vpColVector all_residues,
vpColVector weights 
)

Compute the weights according a residue vector and a PsiFunction.

Definition at line 327 of file vpRobust.cpp.

References CAUCHY, vpArray2D< Type >::getRows(), HUBER, TUKEY, and vpCDEBUG.

◆ MEstimator() [2/2]

void vpRobust::MEstimator ( const vpRobustEstimatorType  method,
const vpColVector residues,
vpColVector weights 
)

Calculate an M-estimate given a particular influence function using MAD (Median Absolute Deviation) as a scale estimate at each iteration.

Parameters
[in]method: Type of influence function.
[in]residues: Vector of residues $ r $ of the parameters to estimate.
[out]weights: Vector of weights $w(r)$. Values are in [0, 1]. A value near zero means that the data is an outlier.
Examples
ClassUsingPclViewer.cpp, and testTukeyEstimator.cpp.

Definition at line 136 of file vpRobust.cpp.

References CAUCHY, vpArray2D< Type >::getRows(), HUBER, vpColVector::resize(), and TUKEY.

Referenced by vpMbEdgeKltTracker::computeVVS(), vpMbEdgeTracker::computeVVSWeights(), vpMbTracker::computeVVSWeights(), vpMeLine::leastSquare(), vpMeEllipse::leastSquareRobust(), vpPose::poseVirtualVSrobust(), and vpHomography::robust().

◆ operator=() [1/2]

vpRobust & vpRobust::operator= ( const vpRobust &&  other)

Move operator.

Definition at line 94 of file vpRobust.cpp.

◆ operator=() [2/2]

vpRobust & vpRobust::operator= ( const vpRobust other)

Copy operator.

Definition at line 75 of file vpRobust.cpp.

◆ setIteration()

vp_deprecated void vpRobust::setIteration ( unsigned int  iter)
inline
Deprecated:
Set iteration. This function is to call before simultMEstimator().
Parameters
iter: The first call iter should be set to 0.

Definition at line 171 of file vpRobust.h.

◆ setMinMedianAbsoluteDeviation()

void vpRobust::setMinMedianAbsoluteDeviation ( double  mad_min)
inline

Set minimal median absolute deviation (MAD) value corresponding to the minimal value of $\sigma$ computed in MEstimator() with $ \sigma = 1.48{Med}(|r_i - {Med}(r_i)|) $.

Parameters
mad_min: Minimal Median Absolute Deviation value. Default value is set to 0.0017 in the default constructor.
See also
getMinMedianAbsoluteDeviation()
Examples
ClassUsingPclViewer.cpp, and testTukeyEstimator.cpp.

Definition at line 156 of file vpRobust.h.

Referenced by vpMbEdgeKltTracker::computeVVS(), vpMbDepthNormalTracker::computeVVSInit(), vpMbEdgeTracker::computeVVSInit(), vpMbKltTracker::computeVVSInit(), vpMeLine::leastSquare(), vpMeEllipse::leastSquareRobust(), and vpPose::poseVirtualVSrobust().

◆ setThreshold()

vp_deprecated void vpRobust::setThreshold ( double  mad_min)
inline
Deprecated:
You should rather use setMinMedianAbsoluteDeviation(). Set minimal median absolute deviation (MAD) value. Given the input vector or residual, when MAD(residual) < mad_min we set MAD(residual) = mad_min.
Parameters
mad_min: Minimal Median Absolute Deviation value. Default value is set to 0.0017 in the default constructor.

Definition at line 180 of file vpRobust.h.

◆ simultMEstimator()

vpColVector vpRobust::simultMEstimator ( vpColVector residues)
Deprecated:
This function is useless. Calculate an Mestimate with a simultaneous scale estimate using HUBER's influence function
Parameters
[in]residues: Vector of residues. The content of the vector is changed.
Returns
Returns a vector of weights associated to each residue.

Definition at line 421 of file vpRobust.cpp.

References vpArray2D< Type >::getRows().