Visual Servoing Platform  version 3.5.0 under development (2022-02-15)
Public Types | Public Member Functions | List of all members
vpRobust Class Reference
core: Core module » Mathematics » Robust estimation

#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)
 
vpRobust & operator= (const vpRobust &other)
 
vpRobust & operator= (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:
testTukeyEstimator.cpp.

Definition at line 88 of file vpRobust.h.

Member Enumeration Documentation

◆ vpRobustEstimatorType

enum vpRobust::vpRobustEstimatorType

Enumeration of influence functions.

Enumerator
TUKEY 

Tukey influence function.

CAUCHY 

Cauchy influence function.

HUBER 

Huber influence function.

Definition at line 92 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 71 of file vpRobust.cpp.

◆ ~vpRobust()

virtual vpRobust::~vpRobust ( )
inlinevirtual

Destructor.

Definition at line 124 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 135 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 mimimal value of $\sigma$ computed in MEstimator().

See also
setMinMedianAbsoluteDeviation()

Definition at line 143 of file vpRobust.h.

◆ MEstimator() [1/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:
testTukeyEstimator.cpp.

Definition at line 137 of file vpRobust.cpp.

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

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

◆ MEstimator() [2/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 >::data, vpArray2D< Type >::getRows(), HUBER, vpColVector::resize(), TUKEY, and vpCDEBUG.

◆ operator=() [1/2]

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

Copy operator.

Definition at line 76 of file vpRobust.cpp.

◆ operator=() [2/2]

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

Move operator.

Definition at line 95 of file vpRobust.cpp.

References vpColVector::resize().

◆ 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 176 of file vpRobust.h.

◆ setMinMedianAbsoluteDeviation()

void vpRobust::setMinMedianAbsoluteDeviation ( double  mad_min)
inline

Set minimal median absolute deviation (MAD) value corresponding to the mimimal 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:
testTukeyEstimator.cpp.

Definition at line 161 of file vpRobust.h.

Referenced by vpPoseFeatures::computePose(), vpMbEdgeKltTracker::computeVVS(), vpMbDepthNormalTracker::computeVVSInit(), vpMbKltTracker::computeVVSInit(), vpMbEdgeTracker::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 185 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 CAUCHY, vpArray2D< Type >::getRows(), HUBER, vpMath::sqr(), and TUKEY.